You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tuscany.apache.org by haleh mahbod <hm...@gmail.com> on 2006/04/12 22:07:10 UTC
What are some good samples for Tuscany?
Hi,
What are the categories of samples that we need to consider for Tuscany?
I see two potential categories.
1) Business samples - Focused on showing how Tuscany solves certain business
problems.
2) Technology samples - Focused on showing developers how to use
Tuscanyfeatures such as Transaction.
Does this look right?
If yes, what are some good samples that we can consider for each category?
What should our approach to Samples be? Start with one sample and expand it
to show additional functionality; or
create distinct samples?
Haleh
Re: What are some good samples for Tuscany?
Posted by Jean-Sebastien Delfino <js...@apache.org>.
ant elder wrote:
> Here are some specific ideas to kick around:
>
> 1) how about calling business samples 'demos' and technology samples just
> 'samples'
>
>
Yes, +1
> 2) restructure the current samples folder to be something like:
> samples
> - demos
> - bigbank
> - petstore
> - ...
> - das
> - ...
> - sdo
> - ...
> - sca
> - bindings
> - jsonrpc
> - ws
> - ...
> - componentTypes
> - java
> - javascript
>
+1 we should just rename componentTypes to containers to be consistent
with the rest of the runtime.
> - ...
>
> 3) There should be a consistent set of samples within bindings,
> componentTypes etc so its easy to copy things to create new samples and add
> new function
>
> 4) samples are like functional tests so we should add a sample for every bit
> of existing and new function
>
> 5) Fix the testing/tomcat stuff so all the samples doing functional testing
> get run as part of a regular build
>
>
+1 to all of this. I would like to add a new sample showing the SCA
async PM, created JIRA issue 188 for this. I think we also need a simple
technology sample that shows wiring of two moduleComponents in a
subsystem. This is an important part of the SCA assembly programming
model and we have no sample showing this except bigbank.
The cpp subproject has different samples (Calculator instead of
HelloWorld), I think it would be good to show common samples across
languages, i.e. at least port HelloWorld to the cpp project, or port
Calculator to the java project. Longer term, most samples should exist
in both cpp and java forms.
> In more detail:
>
> Right now we have a samples folder which has things like the bigbank,
> helloworld, javascript and various other stuff in it. The bigbank sample
> shows a complete SCA application that does something useful and real world
> like, the helloworld samples on the other hand are very simplistic and
> really just help a developer getting started with SCA. I think Bigbank fits
> into what you describe as business samples and the helloworld samples are
> technology samples, but to make this clearer how about calling business
> samples 'demos' and technology samples just 'samples'?
>
> Samples to me could be a lot like functional tests, for every bit of new
> function we add we should add a sample showing how to use it. Samples would
> show just one bit of function so its obvious whats required without getting
> confused by unrelated code and xml. I've started trying to use this approach
> for the JavaScript samples:
> http://svn.apache.org/repos/asf/incubator/tuscany/java/samples/JavaScript/
>
> If we go that way it has to be really easy to create a new sample, the
> helloworld samples aren't so easy to copy but after a few different attempts
> with the JavaScript ones its now relatively easy to just copy an existing
> JavaScript sample to a new project and do a global edit to change the sample
> number. The most difficult part is updating the readme.htm file with all the
> ascii art directory structure pictures etc, I think its probably better to
> use plain txt readme files with simple content for samples and only have
> fancy html readme's for the demos (and gif's instead of ascii art?). Another
> minor problem with the JavaScript ones is the name is javascript-sampleX but
> it may be better to have sample-javascriptX so then all samples would get
> grouped together in your IDE.
>
> Another aspect is it should be easy and obvious what samples are required
> when creating something new like a new componentType. Most componentTypes
> are going to require similar samples like a helloworld component, injecting
> properties and references, initialization and scoping etc. If we get a good
> set of these for the Java componentType then when creating a new
> componentType you can just copy all the Java ones and update as required and
> its obvious what needs to get done. This probably all also applies for
> bindings and maybe theres a set of samples required for Tuscany core
> function as well (showing module fragments, subsystmes etc?). This way we'd
> also end up with a consistent set of samples, so if you've learnt how to use
> one componentType then picking up a new one the samples would be familiar.
> This would also all work across the different language impls so Java, C++,
> and PHP SCA impls could all have a similar set of samples.
>
> Right now some of the binding functional testing is done with existing
> samples but these don't actually get run as part of the main build so they
> do get broken. If the functional testing is going to be done in samples then
> we need to sort out the testing/tomcat stuff so its easy to do and so the
> samples get properly run as part of the regular build process.
>
> I think samples should expand on each other, for example they'd be a basic
> helloworld componentType sample, then a WS entryPoint sample exposes
> helloworld as a WS, then a WS-Security sample secures the WS entryPoint
> sample. I think Demo's on the other hand should be complete and self
> contained applications. There could be tutorials that show how each demo was
> developed.
>
> For the demos, we already have bigbank so we might as well keep it but it
> needs to be made more obvious what it does and how to use it. Right now I
> can't find any readme's or doc describing it, there used to be a pdf about
> it, where's that gone (and from what I remember that was like a 40 page doc
> which is way more than most people will have time to read)? Someone
> mentioned petstore and I think that could be a worthwhile demo as well - its
> so well known so people can grok whats going on without needing to read a 40
> page document. I think I heard that the PHP SCA impl have their own demo app
> which isn't bigbank, it may be worth looking at what they have and also
> adding it as a demo for the Java impl. I think the demo documentation needs
> to make clearer why SCA is a good thing, its not real obvious right now from
> the existing doc why this is better than using something like J2EE or just
> wiring up a bunch of POJOs with Spring.
>
> It would be good to have some more cool technology demo's, but right now the
> only function Tuscany supports is fairly mainstream. I think the E4X support
> in JavaScript could make some interesting WS mediation samples, but the
> function isn't quite there yet. The json-rpc/ajax stuff could be really cool
> but its also not ready yet. Maybe as this first milestone release is
> targeting getting new contributors rather than business users then just
> sorting out the functional samples and cleaning up the bigbank demo would be
> enough.
> ...ant
>
>
+1 unless somebody finds time to come up with, implement and document a
nice new business scenario demo (or enough time to implement PetStore...
but I'm not sure if PetStore is a good SOA sample and would illustrate
the capabilities of SCA/SDO better than Bigbank), for the May release we
should at least get bigbank working and well documented. Maybe the only
thing we can add to Bigbank is an Ajax front-end? What do people think?
Another question,
> On 4/12/06, haleh mahbod < hmahbod@gmail.com> wrote:
>
>> Hi,
>>
>>
>> What are the categories of samples that we need to consider for Tuscany?
>>
>> I see two potential categories.
>>
>>
>>
>> 1) Business samples - Focused on showing how Tuscany solves certain
>> business
>> problems.
>>
>> 2) Technology samples - Focused on showing developers how to use
>> Tuscanyfeatures such as Transaction.
>>
>>
>>
>> Does this look right?
>>
>>
>>
>> If yes, what are some good samples that we can consider for each category?
>>
>>
>>
>>
>> What should our approach to Samples be? Start with one sample and expand
>> it
>> to show additional functionality; or
>>
>> create distinct samples?
>>
>>
>>
>> Haleh
>>
>>
>>
>
>
--
Jean-Sebastien
Re: What are some good samples for Tuscany?
Posted by Simon Nash <na...@hursley.ibm.com>.
Ant,
See comments inline below.
Simon
ant elder wrote:
> Here are some specific ideas to kick around:
>
> 1) how about calling business samples 'demos' and technology samples just
> 'samples'
>
> 2) restructure the current samples folder to be something like:
> samples
> - demos
> - bigbank
> - petstore
> - ...
> - das
> - ...
> - sdo
> - ...
> - sca
> - bindings
> - jsonrpc
> - ws
> - ...
> - componentTypes
> - java
> - javascript
> - ...
>
> 3) There should be a consistent set of samples within bindings,
> componentTypes etc so its easy to copy things to create new samples and add
> new function
>
> 4) samples are like functional tests so we should add a sample for every bit
> of existing and new function
>
> 5) Fix the testing/tomcat stuff so all the samples doing functional testing
> get run as part of a regular build
>
> In more detail:
>
> Right now we have a samples folder which has things like the bigbank,
> helloworld, javascript and various other stuff in it. The bigbank sample
> shows a complete SCA application that does something useful and real world
> like, the helloworld samples on the other hand are very simplistic and
> really just help a developer getting started with SCA. I think Bigbank fits
> into what you describe as business samples and the helloworld samples are
> technology samples, but to make this clearer how about calling business
> samples 'demos' and technology samples just 'samples'?
>
Demos sound a bit different to me. I think demos are shown to an audience
and need to put an emphasis on visual impact. Business samples are more
for the purpose of reading the code to understand what it does. They don't
need to produce impressive output as long as the design principles are
clear. I think we need demos as well, but I don't think they are necessarily
the same as our business samples.
> Samples to me could be a lot like functional tests, for every bit of new
> function we add we should add a sample showing how to use it. Samples would
> show just one bit of function so its obvious whats required without getting
> confused by unrelated code and xml. I've started trying to use this approach
> for the JavaScript samples:
> http://svn.apache.org/repos/asf/incubator/tuscany/java/samples/JavaScript/
>
This sounds like a good idea but I wonder if it would lead to a very
large number of technology samples, almost at the level of our unit tests.
This might become a little unmanageable and confusing for the users.
> If we go that way it has to be really easy to create a new sample, the
> helloworld samples aren't so easy to copy but after a few different attempts
> with the JavaScript ones its now relatively easy to just copy an existing
> JavaScript sample to a new project and do a global edit to change the sample
> number. The most difficult part is updating the readme.htm file with all the
> ascii art directory structure pictures etc, I think its probably better to
> use plain txt readme files with simple content for samples and only have
> fancy html readme's for the demos (and gif's instead of ascii art?). Another
> minor problem with the JavaScript ones is the name is javascript-sampleX but
> it may be better to have sample-javascriptX so then all samples would get
> grouped together in your IDE.
>
> Another aspect is it should be easy and obvious what samples are required
> when creating something new like a new componentType. Most componentTypes
> are going to require similar samples like a helloworld component, injecting
> properties and references, initialization and scoping etc. If we get a good
> set of these for the Java componentType then when creating a new
> componentType you can just copy all the Java ones and update as required and
> its obvious what needs to get done. This probably all also applies for
> bindings and maybe theres a set of samples required for Tuscany core
> function as well (showing module fragments, subsystmes etc?). This way we'd
> also end up with a consistent set of samples, so if you've learnt how to use
> one componentType then picking up a new one the samples would be familiar.
> This would also all work across the different language impls so Java, C++,
> and PHP SCA impls could all have a similar set of samples.
>
> Right now some of the binding functional testing is done with existing
> samples but these don't actually get run as part of the main build so they
> do get broken. If the functional testing is going to be done in samples then
> we need to sort out the testing/tomcat stuff so its easy to do and so the
> samples get properly run as part of the regular build process.
>
> I think samples should expand on each other, for example they'd be a basic
> helloworld componentType sample, then a WS entryPoint sample exposes
> helloworld as a WS, then a WS-Security sample secures the WS entryPoint
> sample. I think Demo's on the other hand should be complete and self
> contained applications. There could be tutorials that show how each demo was
> developed.
>
All the above sounds fine.
> For the demos, we already have bigbank so we might as well keep it but it
> needs to be made more obvious what it does and how to use it. Right now I
> can't find any readme's or doc describing it, there used to be a pdf about
> it, where's that gone (and from what I remember that was like a 40 page doc
> which is way more than most people will have time to read)? Someone
> mentioned petstore and I think that could be a worthwhile demo as well - its
> so well known so people can grok whats going on without needing to read a 40
> page document. I think I heard that the PHP SCA impl have their own demo app
> which isn't bigbank, it may be worth looking at what they have and also
> adding it as a demo for the Java impl. I think the demo documentation needs
> to make clearer why SCA is a good thing, its not real obvious right now from
> the existing doc why this is better than using something like J2EE or just
> wiring up a bunch of POJOs with Spring.
>
We probably have to keep it to stay in sync with the SCA spec, but we don't
necessarily need to feature it as a business sample. Let's evaluate it
against our criteria for business samples and see how well it stacks up.
> It would be good to have some more cool technology demo's, but right now the
> only function Tuscany supports is fairly mainstream. I think the E4X support
> in JavaScript could make some interesting WS mediation samples, but the
> function isn't quite there yet. The json-rpc/ajax stuff could be really cool
> but its also not ready yet. Maybe as this first milestone release is
> targeting getting new contributors rather than business users then just
> sorting out the functional samples and cleaning up the bigbank demo would be
> enough.
> ...ant
>
I was hoping we might get a few business users as well :-)
Simon
Re: What are some good samples for Tuscany?
Posted by Jim Marino <jm...@myromatours.com>.
On Apr 13, 2006, at 7:18 PM, Jeremy Boynes wrote:
> ant elder wrote:
>
>> Here are some specific ideas to kick around:
>>
>> 1) how about calling business samples 'demos' and technology
>> samples just
>> 'samples'
>>
>>
>
> I tend to agree with Simon that there could be a perception that
> "demos"
> are just mockups with no substance. I do think thought that there is a
> difference though between business and technology samples.
>
> In J2EE days the business samples were called "blueprints" so
> perhaps we
> could call them that as well - would be a natural place for a
> petstore :-)
>
>
>> 2) restructure the current samples folder to be something like:
>> samples
>> - demos
>> - bigbank
>> - petstore
>> - ...
>> - das
>> - ...
>> - sdo
>> - ...
>> - sca
>> - bindings
>> - jsonrpc
>> - ws
>> - ...
>> - componentTypes
>> - java
>> - javascript
>> - ...
>>
>
> I'm a little concerned about the depth of the tree here but the idea
> looks good.
>
>
>>
>> 3) There should be a consistent set of samples within bindings,
>> componentTypes etc so its easy to copy things to create new
>> samples and add
>> new function
>>
>>
>
> +1
>
>
>> 4) samples are like functional tests so we should add a sample for
>> every bit
>> of existing and new function
>>
>>
>
> -1
> Business samples illustrate business application and should focus on
> that. Technology samples illustrate how to use the technology and
> should
> focus on that.
>
> Functional tests test function and should focus on that. If possible
> they should run as part of the build using the maven test framework.
>
>
>> 5) Fix the testing/tomcat stuff so all the samples doing
>> functional testing
>> get run as part of a regular build
>>
>>
>
> -1
> Fix the functional/integration tests so that they are an integrated
> part
> of the build rather than a bolt-on using different infrastructure. As
> Jim said we have been here before.
>
> I will point out that there are huge areas of the code where we do not
> even have unit test coverage even though that is trivial to add to the
> build. We need to stop building samples for testing and put some
> effort
> into real testing and samples that clearly illustrate key technology
> and/or business application.
>
> I'll plead guilty here as there are very few unit tests for the loader
> framework. So right now I'm committing to go back and add tests there.
> How about if everyone volunteers to go write unit and/or integration
> tests for some part of the code they worked on?
>
> Let's go further - given we're all supposed to be reviewing
> commits, how
> about we start to -1 changes that don't have tests associated with
> them?
>
I think this would actually be a good policy as long as we say it
applies for most changes (e.g.. performance changes maybe not but
definitely for bug fixes) .
Thoughts?
> --
> Jeremy
>
Re: What are some good samples for Tuscany?
Posted by Jeremy Boynes <jb...@apache.org>.
ant elder wrote:
> Here are some specific ideas to kick around:
>
> 1) how about calling business samples 'demos' and technology samples just
> 'samples'
>
I tend to agree with Simon that there could be a perception that "demos"
are just mockups with no substance. I do think thought that there is a
difference though between business and technology samples.
In J2EE days the business samples were called "blueprints" so perhaps we
could call them that as well - would be a natural place for a petstore :-)
> 2) restructure the current samples folder to be something like:
> samples
> - demos
> - bigbank
> - petstore
> - ...
> - das
> - ...
> - sdo
> - ...
> - sca
> - bindings
> - jsonrpc
> - ws
> - ...
> - componentTypes
> - java
> - javascript
> - ...
I'm a little concerned about the depth of the tree here but the idea
looks good.
>
> 3) There should be a consistent set of samples within bindings,
> componentTypes etc so its easy to copy things to create new samples and add
> new function
>
+1
> 4) samples are like functional tests so we should add a sample for every bit
> of existing and new function
>
-1
Business samples illustrate business application and should focus on
that. Technology samples illustrate how to use the technology and should
focus on that.
Functional tests test function and should focus on that. If possible
they should run as part of the build using the maven test framework.
> 5) Fix the testing/tomcat stuff so all the samples doing functional testing
> get run as part of a regular build
>
-1
Fix the functional/integration tests so that they are an integrated part
of the build rather than a bolt-on using different infrastructure. As
Jim said we have been here before.
I will point out that there are huge areas of the code where we do not
even have unit test coverage even though that is trivial to add to the
build. We need to stop building samples for testing and put some effort
into real testing and samples that clearly illustrate key technology
and/or business application.
I'll plead guilty here as there are very few unit tests for the loader
framework. So right now I'm committing to go back and add tests there.
How about if everyone volunteers to go write unit and/or integration
tests for some part of the code they worked on?
Let's go further - given we're all supposed to be reviewing commits, how
about we start to -1 changes that don't have tests associated with them?
--
Jeremy
Fwd: What are some good samples for Tuscany?
Posted by Jim Marino <jm...@bea.com>.
In case this didn't go through again...
Begin forwarded message:
> From: Jim Marino <ji...@gmail.com>
> Date: April 13, 2006 9:47:07 AM PDT
> To: tuscany-dev@ws.apache.org
> Subject: Re: What are some good samples for Tuscany?
>
>
> A couple of comments:
>
> - I like the "demos" vs. "samples" since that kind of describes the
> target audience (i.e. "business users" are probably not going to
> download Tuscany but a developer would in order to show it to
> someone).
>
> - This is rehashing old ground but I think testcases such as unit
> and integration tests should run as part of the main checkin build
> but not the samples. We should not rely on samples for proper test
> coverage (e.g. ensuring that public APIs are not broken) since, by
> their nature, they cannot reasonably provide it. Rather, we should
> have extensive unit and integration test coverage. I agree that we
> need to have a way to guarantee samples work so perhaps a build can
> be tagged as "stable" if upstream "samples" tests pass that are not
> run as part of the checkin process?
>
> For example, Jeremy has included integration testing for Tomcat in
> the main build where an embedded Tomcat server is started and
> exercised. This type of integration testing should guarantee the
> integrity of the host API. To guarantee the samples work, we could
> have a separate battery of tests run periodically (not by a
> developer prior to check in) that can mark a particular build as
> "stable".
>
> I believe this provides us with a way to have more test coverage
> than what is possible by the code paths taken in the samples as
> well as scale better when we add more host environments. Also, imo,
> this approach promotes good design (most classes should be testable
> in isolation and, although there are exceptions, if they are not I
> assume it is a problem in my design).
>
> Sorry to get on my soapbox about testing but I think this is one of
> the areas where we really fall short at the moment.
>
> Jim
>
> On Apr 13, 2006, at 4:14 AM, ant elder wrote:
>
>
>> Here are some specific ideas to kick around:
>>
>> 1) how about calling business samples 'demos' and technology
>> samples just
>> 'samples'
>>
>> 2) restructure the current samples folder to be something like:
>> samples
>> - demos
>> - bigbank
>> - petstore
>> - ...
>> - das
>> - ...
>> - sdo
>> - ...
>> - sca
>> - bindings
>> - jsonrpc
>> - ws
>> - ...
>> - componentTypes
>> - java
>> - javascript
>> - ...
>>
>> 3) There should be a consistent set of samples within bindings,
>> componentTypes etc so its easy to copy things to create new
>> samples and add
>> new function
>>
>> 4) samples are like functional tests so we should add a sample for
>> every bit
>> of existing and new function
>>
>> 5) Fix the testing/tomcat stuff so all the samples doing
>> functional testing
>> get run as part of a regular build
>>
>> In more detail:
>>
>> Right now we have a samples folder which has things like the bigbank,
>> helloworld, javascript and various other stuff in it. The bigbank
>> sample
>> shows a complete SCA application that does something useful and
>> real world
>> like, the helloworld samples on the other hand are very simplistic
>> and
>> really just help a developer getting started with SCA. I think
>> Bigbank fits
>> into what you describe as business samples and the helloworld
>> samples are
>> technology samples, but to make this clearer how about calling
>> business
>> samples 'demos' and technology samples just 'samples'?
>>
>> Samples to me could be a lot like functional tests, for every bit
>> of new
>> function we add we should add a sample showing how to use it.
>> Samples would
>> show just one bit of function so its obvious whats required
>> without getting
>> confused by unrelated code and xml. I've started trying to use
>> this approach
>> for the JavaScript samples:
>> http://svn.apache.org/repos/asf/incubator/tuscany/java/samples/
>> JavaScript/
>>
>> If we go that way it has to be really easy to create a new sample,
>> the
>> helloworld samples aren't so easy to copy but after a few
>> different attempts
>> with the JavaScript ones its now relatively easy to just copy an
>> existing
>> JavaScript sample to a new project and do a global edit to change
>> the sample
>> number. The most difficult part is updating the readme.htm file
>> with all the
>> ascii art directory structure pictures etc, I think its probably
>> better to
>> use plain txt readme files with simple content for samples and
>> only have
>> fancy html readme's for the demos (and gif's instead of ascii
>> art?). Another
>> minor problem with the JavaScript ones is the name is javascript-
>> sampleX but
>> it may be better to have sample-javascriptX so then all samples
>> would get
>> grouped together in your IDE.
>>
>> Another aspect is it should be easy and obvious what samples are
>> required
>> when creating something new like a new componentType. Most
>> componentTypes
>> are going to require similar samples like a helloworld component,
>> injecting
>> properties and references, initialization and scoping etc. If we
>> get a good
>> set of these for the Java componentType then when creating a new
>> componentType you can just copy all the Java ones and update as
>> required and
>> its obvious what needs to get done. This probably all also applies
>> for
>> bindings and maybe theres a set of samples required for Tuscany core
>> function as well (showing module fragments, subsystmes etc?). This
>> way we'd
>> also end up with a consistent set of samples, so if you've learnt
>> how to use
>> one componentType then picking up a new one the samples would be
>> familiar.
>> This would also all work across the different language impls so
>> Java, C++,
>> and PHP SCA impls could all have a similar set of samples.
>>
>> Right now some of the binding functional testing is done with
>> existing
>> samples but these don't actually get run as part of the main build
>> so they
>> do get broken. If the functional testing is going to be done in
>> samples then
>> we need to sort out the testing/tomcat stuff so its easy to do and
>> so the
>> samples get properly run as part of the regular build process.
>>
>> I think samples should expand on each other, for example they'd be
>> a basic
>> helloworld componentType sample, then a WS entryPoint sample exposes
>> helloworld as a WS, then a WS-Security sample secures the WS
>> entryPoint
>> sample. I think Demo's on the other hand should be complete and self
>> contained applications. There could be tutorials that show how
>> each demo was
>> developed.
>>
>> For the demos, we already have bigbank so we might as well keep it
>> but it
>> needs to be made more obvious what it does and how to use it.
>> Right now I
>> can't find any readme's or doc describing it, there used to be a
>> pdf about
>> it, where's that gone (and from what I remember that was like a 40
>> page doc
>> which is way more than most people will have time to read)? Someone
>> mentioned petstore and I think that could be a worthwhile demo as
>> well - its
>> so well known so people can grok whats going on without needing to
>> read a 40
>> page document. I think I heard that the PHP SCA impl have their
>> own demo app
>> which isn't bigbank, it may be worth looking at what they have and
>> also
>> adding it as a demo for the Java impl. I think the demo
>> documentation needs
>> to make clearer why SCA is a good thing, its not real obvious
>> right now from
>> the existing doc why this is better than using something like J2EE
>> or just
>> wiring up a bunch of POJOs with Spring.
>>
>> It would be good to have some more cool technology demo's, but
>> right now the
>> only function Tuscany supports is fairly mainstream. I think the
>> E4X support
>> in JavaScript could make some interesting WS mediation samples,
>> but the
>> function isn't quite there yet. The json-rpc/ajax stuff could be
>> really cool
>> but its also not ready yet. Maybe as this first milestone release is
>> targeting getting new contributors rather than business users then
>> just
>> sorting out the functional samples and cleaning up the bigbank
>> demo would be
>> enough.
>> ...ant
>>
>> On 4/12/06, haleh mahbod < hmahbod@gmail.com> wrote:
>>
>>
>>>
>>> Hi,
>>>
>>>
>>> What are the categories of samples that we need to consider for
>>> Tuscany?
>>>
>>> I see two potential categories.
>>>
>>>
>>>
>>> 1) Business samples - Focused on showing how Tuscany solves certain
>>> business
>>> problems.
>>>
>>> 2) Technology samples - Focused on showing developers how to use
>>> Tuscanyfeatures such as Transaction.
>>>
>>>
>>>
>>> Does this look right?
>>>
>>>
>>>
>>> If yes, what are some good samples that we can consider for each
>>> category?
>>>
>>>
>>>
>>>
>>> What should our approach to Samples be? Start with one sample and
>>> expand
>>> it
>>> to show additional functionality; or
>>>
>>> create distinct samples?
>>>
>>>
>>>
>>> Haleh
>>>
>>>
>>>
>>
>>
>
>
Re: What are some good samples for Tuscany?
Posted by Jim Marino <ji...@gmail.com>.
A couple of comments:
- I like the "demos" vs. "samples" since that kind of describes the
target audience (i.e. "business users" are probably not going to
download Tuscany but a developer would in order to show it to someone).
- This is rehashing old ground but I think testcases such as unit and
integration tests should run as part of the main checkin build but
not the samples. We should not rely on samples for proper test
coverage (e.g. ensuring that public APIs are not broken) since, by
their nature, they cannot reasonably provide it. Rather, we should
have extensive unit and integration test coverage. I agree that we
need to have a way to guarantee samples work so perhaps a build can
be tagged as "stable" if upstream "samples" tests pass that are not
run as part of the checkin process?
For example, Jeremy has included integration testing for Tomcat in
the main build where an embedded Tomcat server is started and
exercised. This type of integration testing should guarantee the
integrity of the host API. To guarantee the samples work, we could
have a separate battery of tests run periodically (not by a developer
prior to check in) that can mark a particular build as "stable".
I believe this provides us with a way to have more test coverage than
what is possible by the code paths taken in the samples as well as
scale better when we add more host environments. Also, imo, this
approach promotes good design (most classes should be testable in
isolation and, although there are exceptions, if they are not I
assume it is a problem in my design).
Sorry to get on my soapbox about testing but I think this is one of
the areas where we really fall short at the moment.
Jim
On Apr 13, 2006, at 4:14 AM, ant elder wrote:
> Here are some specific ideas to kick around:
>
> 1) how about calling business samples 'demos' and technology
> samples just
> 'samples'
>
> 2) restructure the current samples folder to be something like:
> samples
> - demos
> - bigbank
> - petstore
> - ...
> - das
> - ...
> - sdo
> - ...
> - sca
> - bindings
> - jsonrpc
> - ws
> - ...
> - componentTypes
> - java
> - javascript
> - ...
>
> 3) There should be a consistent set of samples within bindings,
> componentTypes etc so its easy to copy things to create new samples
> and add
> new function
>
> 4) samples are like functional tests so we should add a sample for
> every bit
> of existing and new function
>
> 5) Fix the testing/tomcat stuff so all the samples doing functional
> testing
> get run as part of a regular build
>
> In more detail:
>
> Right now we have a samples folder which has things like the bigbank,
> helloworld, javascript and various other stuff in it. The bigbank
> sample
> shows a complete SCA application that does something useful and
> real world
> like, the helloworld samples on the other hand are very simplistic and
> really just help a developer getting started with SCA. I think
> Bigbank fits
> into what you describe as business samples and the helloworld
> samples are
> technology samples, but to make this clearer how about calling
> business
> samples 'demos' and technology samples just 'samples'?
>
> Samples to me could be a lot like functional tests, for every bit
> of new
> function we add we should add a sample showing how to use it.
> Samples would
> show just one bit of function so its obvious whats required without
> getting
> confused by unrelated code and xml. I've started trying to use this
> approach
> for the JavaScript samples:
> http://svn.apache.org/repos/asf/incubator/tuscany/java/samples/
> JavaScript/
>
> If we go that way it has to be really easy to create a new sample, the
> helloworld samples aren't so easy to copy but after a few different
> attempts
> with the JavaScript ones its now relatively easy to just copy an
> existing
> JavaScript sample to a new project and do a global edit to change
> the sample
> number. The most difficult part is updating the readme.htm file
> with all the
> ascii art directory structure pictures etc, I think its probably
> better to
> use plain txt readme files with simple content for samples and only
> have
> fancy html readme's for the demos (and gif's instead of ascii
> art?). Another
> minor problem with the JavaScript ones is the name is javascript-
> sampleX but
> it may be better to have sample-javascriptX so then all samples
> would get
> grouped together in your IDE.
>
> Another aspect is it should be easy and obvious what samples are
> required
> when creating something new like a new componentType. Most
> componentTypes
> are going to require similar samples like a helloworld component,
> injecting
> properties and references, initialization and scoping etc. If we
> get a good
> set of these for the Java componentType then when creating a new
> componentType you can just copy all the Java ones and update as
> required and
> its obvious what needs to get done. This probably all also applies for
> bindings and maybe theres a set of samples required for Tuscany core
> function as well (showing module fragments, subsystmes etc?). This
> way we'd
> also end up with a consistent set of samples, so if you've learnt
> how to use
> one componentType then picking up a new one the samples would be
> familiar.
> This would also all work across the different language impls so
> Java, C++,
> and PHP SCA impls could all have a similar set of samples.
>
> Right now some of the binding functional testing is done with existing
> samples but these don't actually get run as part of the main build
> so they
> do get broken. If the functional testing is going to be done in
> samples then
> we need to sort out the testing/tomcat stuff so its easy to do and
> so the
> samples get properly run as part of the regular build process.
>
> I think samples should expand on each other, for example they'd be
> a basic
> helloworld componentType sample, then a WS entryPoint sample exposes
> helloworld as a WS, then a WS-Security sample secures the WS
> entryPoint
> sample. I think Demo's on the other hand should be complete and self
> contained applications. There could be tutorials that show how each
> demo was
> developed.
>
> For the demos, we already have bigbank so we might as well keep it
> but it
> needs to be made more obvious what it does and how to use it. Right
> now I
> can't find any readme's or doc describing it, there used to be a
> pdf about
> it, where's that gone (and from what I remember that was like a 40
> page doc
> which is way more than most people will have time to read)? Someone
> mentioned petstore and I think that could be a worthwhile demo as
> well - its
> so well known so people can grok whats going on without needing to
> read a 40
> page document. I think I heard that the PHP SCA impl have their own
> demo app
> which isn't bigbank, it may be worth looking at what they have and
> also
> adding it as a demo for the Java impl. I think the demo
> documentation needs
> to make clearer why SCA is a good thing, its not real obvious right
> now from
> the existing doc why this is better than using something like J2EE
> or just
> wiring up a bunch of POJOs with Spring.
>
> It would be good to have some more cool technology demo's, but
> right now the
> only function Tuscany supports is fairly mainstream. I think the
> E4X support
> in JavaScript could make some interesting WS mediation samples, but
> the
> function isn't quite there yet. The json-rpc/ajax stuff could be
> really cool
> but its also not ready yet. Maybe as this first milestone release is
> targeting getting new contributors rather than business users then
> just
> sorting out the functional samples and cleaning up the bigbank demo
> would be
> enough.
> ...ant
>
> On 4/12/06, haleh mahbod < hmahbod@gmail.com> wrote:
>
>>
>> Hi,
>>
>>
>> What are the categories of samples that we need to consider for
>> Tuscany?
>>
>> I see two potential categories.
>>
>>
>>
>> 1) Business samples - Focused on showing how Tuscany solves certain
>> business
>> problems.
>>
>> 2) Technology samples - Focused on showing developers how to use
>> Tuscanyfeatures such as Transaction.
>>
>>
>>
>> Does this look right?
>>
>>
>>
>> If yes, what are some good samples that we can consider for each
>> category?
>>
>>
>>
>>
>> What should our approach to Samples be? Start with one sample and
>> expand
>> it
>> to show additional functionality; or
>>
>> create distinct samples?
>>
>>
>>
>> Haleh
>>
>>
>
Re: What are some good samples for Tuscany?
Posted by ant elder <an...@gmail.com>.
Here are some specific ideas to kick around:
1) how about calling business samples 'demos' and technology samples just
'samples'
2) restructure the current samples folder to be something like:
samples
- demos
- bigbank
- petstore
- ...
- das
- ...
- sdo
- ...
- sca
- bindings
- jsonrpc
- ws
- ...
- componentTypes
- java
- javascript
- ...
3) There should be a consistent set of samples within bindings,
componentTypes etc so its easy to copy things to create new samples and add
new function
4) samples are like functional tests so we should add a sample for every bit
of existing and new function
5) Fix the testing/tomcat stuff so all the samples doing functional testing
get run as part of a regular build
In more detail:
Right now we have a samples folder which has things like the bigbank,
helloworld, javascript and various other stuff in it. The bigbank sample
shows a complete SCA application that does something useful and real world
like, the helloworld samples on the other hand are very simplistic and
really just help a developer getting started with SCA. I think Bigbank fits
into what you describe as business samples and the helloworld samples are
technology samples, but to make this clearer how about calling business
samples 'demos' and technology samples just 'samples'?
Samples to me could be a lot like functional tests, for every bit of new
function we add we should add a sample showing how to use it. Samples would
show just one bit of function so its obvious whats required without getting
confused by unrelated code and xml. I've started trying to use this approach
for the JavaScript samples:
http://svn.apache.org/repos/asf/incubator/tuscany/java/samples/JavaScript/
If we go that way it has to be really easy to create a new sample, the
helloworld samples aren't so easy to copy but after a few different attempts
with the JavaScript ones its now relatively easy to just copy an existing
JavaScript sample to a new project and do a global edit to change the sample
number. The most difficult part is updating the readme.htm file with all the
ascii art directory structure pictures etc, I think its probably better to
use plain txt readme files with simple content for samples and only have
fancy html readme's for the demos (and gif's instead of ascii art?). Another
minor problem with the JavaScript ones is the name is javascript-sampleX but
it may be better to have sample-javascriptX so then all samples would get
grouped together in your IDE.
Another aspect is it should be easy and obvious what samples are required
when creating something new like a new componentType. Most componentTypes
are going to require similar samples like a helloworld component, injecting
properties and references, initialization and scoping etc. If we get a good
set of these for the Java componentType then when creating a new
componentType you can just copy all the Java ones and update as required and
its obvious what needs to get done. This probably all also applies for
bindings and maybe theres a set of samples required for Tuscany core
function as well (showing module fragments, subsystmes etc?). This way we'd
also end up with a consistent set of samples, so if you've learnt how to use
one componentType then picking up a new one the samples would be familiar.
This would also all work across the different language impls so Java, C++,
and PHP SCA impls could all have a similar set of samples.
Right now some of the binding functional testing is done with existing
samples but these don't actually get run as part of the main build so they
do get broken. If the functional testing is going to be done in samples then
we need to sort out the testing/tomcat stuff so its easy to do and so the
samples get properly run as part of the regular build process.
I think samples should expand on each other, for example they'd be a basic
helloworld componentType sample, then a WS entryPoint sample exposes
helloworld as a WS, then a WS-Security sample secures the WS entryPoint
sample. I think Demo's on the other hand should be complete and self
contained applications. There could be tutorials that show how each demo was
developed.
For the demos, we already have bigbank so we might as well keep it but it
needs to be made more obvious what it does and how to use it. Right now I
can't find any readme's or doc describing it, there used to be a pdf about
it, where's that gone (and from what I remember that was like a 40 page doc
which is way more than most people will have time to read)? Someone
mentioned petstore and I think that could be a worthwhile demo as well - its
so well known so people can grok whats going on without needing to read a 40
page document. I think I heard that the PHP SCA impl have their own demo app
which isn't bigbank, it may be worth looking at what they have and also
adding it as a demo for the Java impl. I think the demo documentation needs
to make clearer why SCA is a good thing, its not real obvious right now from
the existing doc why this is better than using something like J2EE or just
wiring up a bunch of POJOs with Spring.
It would be good to have some more cool technology demo's, but right now the
only function Tuscany supports is fairly mainstream. I think the E4X support
in JavaScript could make some interesting WS mediation samples, but the
function isn't quite there yet. The json-rpc/ajax stuff could be really cool
but its also not ready yet. Maybe as this first milestone release is
targeting getting new contributors rather than business users then just
sorting out the functional samples and cleaning up the bigbank demo would be
enough.
...ant
On 4/12/06, haleh mahbod < hmahbod@gmail.com> wrote:
>
> Hi,
>
>
> What are the categories of samples that we need to consider for Tuscany?
>
> I see two potential categories.
>
>
>
> 1) Business samples - Focused on showing how Tuscany solves certain
> business
> problems.
>
> 2) Technology samples - Focused on showing developers how to use
> Tuscanyfeatures such as Transaction.
>
>
>
> Does this look right?
>
>
>
> If yes, what are some good samples that we can consider for each category?
>
>
>
>
> What should our approach to Samples be? Start with one sample and expand
> it
> to show additional functionality; or
>
> create distinct samples?
>
>
>
> Haleh
>
>
Re: What are some good samples for Tuscany?
Posted by Simon Nash <na...@hursley.ibm.com>.
haleh mahbod wrote:
> Hi,
>
>
> What are the categories of samples that we need to consider for Tuscany?
>
> I see two potential categories.
>
>
>
> 1) Business samples - Focused on showing how Tuscany solves certain business
> problems.
>
> 2) Technology samples - Focused on showing developers how to use
> Tuscanyfeatures such as Transaction.
>
>
>
> Does this look right?
>
I agree that we need both of these categories. Having the right samples
is a very important part of what it takes to get people on board (along
with good documentation).
The business samples should be aimed at people trying to understand
why they should use Tuscany rather than other approaches for solving
a given business problem. So ideally there would be some compelling
aspect of the Tuscany solution that makes it more attractive than
other alternatives.
However, there will be many situations where Tuscany isn't the "best"
solution. Often there will not be a single "best" solution. Different
solutions will have different positive and negative aspects. In these
cases it is important to show clearly how Tuscany solves the business
problem, and how it differs (or not) from other approaches. Then the
prospective user can make his or her choice based on a clear understanding
of what Tuscany does (and does not) bring to the table.
So I think our business scenarios should be chosen either because Tuscany
is a particularly appropriate solution, or because the scenario is very
common and everyone will want to know how Tuscany goes about solving that
class of problem. And the larger the intersection we have between these
categories, the more successful Tuscany will be.
>
>
> If yes, what are some good samples that we can consider for each category?
>
>
>
> What should our approach to Samples be? Start with one sample and expand it
> to show additional functionality; or
>
> create distinct samples?
>
>
I don't think we can get the range of coverage that we need (see above)
with a single sample. With a single "does everything" sample, the temptation
is to try to force-fit every scenario into it, which makes it too big and
complex. Then for any given business scenario, there will be some parts
of the sample that are relevant as well as others that aren't, but still
need to be understood.
With a range of business samples, each one should illustrate a few points
without bringing in too much overhead. Then people can focus on the
samples that are relevant to their needs, and they don't need to go deeply
into other samples that aren't relevant.
Simon