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
