Simon Laws wrote:
Hi
Further comments in line
Simon
On Mar 14, 2010, at 4:32 PM, "Simon Nash" <[email protected]> wrote:
Simon Laws wrote:
Haven't looked at the travel sample README for a little while. Anyone
know how up to date it is?
It should be fully up to date and in sync with the current svn code.
OK, thanks
For example, the run commands are mostly given as "ant run" but this
doesn't seem to be the case in the binary distribution. For example,
from the binary distribution the interaction samples are run using
"ant run-interaction". So maybe it's just that we need to spell out
the different types of releases we will have and how to use them. In
the src distro launchers and contributions will be directories while
in the bin distro they will be jars.
Ah, didn't spot it as it comes after the first long list of samples.
Maybe we just need a section(s) at the start that
gives and index of what can be found in the README, i.e. so that
people like me know where to look. Alternatively
we could have a different README for the binary and src distros.
For now I'd like to try to keep a single README covering both binary
and source distros and add the extra section at the start as you suggest.
The "ant run" commands are listed in the section titled "Running the
travel
sample from the build directories" and are correct when running from
the
build directories. For running from the binary distribution, there
is a
later section titled "Running the travel sample from the distribution
directories" which explains the commands needed in this case. Here
is the
paragraph from this section that describes this:
To run a jar, you need to used the command "ant run-jarsuffix" where
"jarsuffix" is the last part of the jar file name omitting the
standard prefix
"scatours-client", "scatours-launcher" or "scatours-service". For
example,
to run the "jumpstart" scenario, you would set your current
directory to the
binary distribution "launchers" directory and run the command
ant run-jumpstart
This runs the travel sample jar file scatours-launcher-jumpstart.jar
using a
classpath with the required runtime dependencies from the Tuscany
SCA binary
distribution. The location of the Tuscany SCA binary distribution
is specified
by the TUSCANY_HOME environment variable).
Looking at the sample descriptions I'd like to add a little more
meat.
For example. currently the description of the interaction sample is
as
follows:
4) Interaction - Different SCA interaction styles
Command: ant run
Directory: launchers/interaction
Contributions: calendar, common, currency, flight, hotel,
interaction-client,
interaction-service-remote, shoppingcart
I'd like to flip the Directory and Command lines and then add a
description section as follows.
The Directory and Command lines were originally in the other other,
with Directory first. I changed the order of these when I added
descriptions of the .war samples because these start with a Webapp
line which I thought was more analogous to Command than to Directory.
However, on further reflection it seems that Webapp could equally well
be considered to be analogous to Directory, so I would be fine with
reverting to the previous order and putting Directory first.
OK
I also added the directory/run
command to for the binary distro but open to suggest about whether/
how
to do this.
4) Interaction - Shows different SCA interaction styles
Directory src(bin): launchers/interaction (launchers)
Command src(bin): ant run (ant run-interaction)
This would need a reorganisation of the structure of the README so
that
the sections titled "Running the travel sample from the build
directories"
and "Running the travel sample from the distribution directories" are
merged together into a single section. I'm concerned that doing this
would be more confusing because of the mix of information appearing
together, where some of it only applies to one case or the other.
Yep, tricky.
An alternative would be to keep the present structure of sections
but add cross-references between them and perhaps also flesh out the
section "Running the travel sample from the distribution directories"
to be more explicit about all the commands that are needed.
Another alternative would be to have a new section called something
like
"The travel sample scenarios" which describes the scenarios and
lists the
contributions/launchers/services/clients/webapps/URLs that they use,
but
doesn't go into full details of how to run them. These details
would be
provided in separate later sections, one for running from the build
directories and one for running from the binary distribution. This is
probably the best and clearest approach, and I'm happy to make the
edits
for this if others agree with this structure.
So let me see if I understand this. you would have some sections (not
right names of course)
Samples
======
4) Interaction - Shows different SCA interaction styles
Contributions
Description
etc.
Source Distro
==========
some detail about the source distro
4) Interaction
Directory: launchers/interaction
Command: ant run
Binary Distro
==========
some detail about the binary distro
4) Interaction -
Directory: launchers
Command: ant run-interaction
Is that right? Sounds like a reasonable compromise.
>
Yes, that's what I had in mind.
Maybe we could
shorten the list of run commands by putting them in
as table.
| 4 | interaction | launchers/interaction | ant run |
All the bulk into is in the samples section so the table is very
simple and should fit on one page.
Good suggestion. I'll make all these changes and check in the result
so that others can take a look and see if it is easier to follow.
Simon
Contributions: calendar, common, currency, flight, hotel,
interaction-client,
interaction-service-remote, shoppingcart
Description: Each SCA interaction pattern is
demonstrated
using a component from the travel booking application.
We’re going to see the Hotel, Calendar, CurrencyConverter and
ShoppingCart components used here. These components
don't work in isolation so for each interaction pattern we've
written a simple client component. For example, the
InteractionLocalClient component demonstrates local interactions
by sending a local message to the Calendar
component. The sample launcher will run samples for all of the
interaction patterns automatically.The launcher starts two
nodes. Node1 loads the contributions common, currency, calendar,
shoppingcart and interaction-client and runs the
client.composite from the interaction-client contribution. All
local interaction patterns are demonstrate by clients calling
currency, calendar, and shoppingcart components locally, within
node1. Node2 loads the contributions common, hotel,
and interaction-service-remote, and runs the service.composite
from the interaction-service-remote contribution. This node
provides the hotel component that client components in node1 can
send messages to remotely to demonstrate the
remote interaction pattern.
+1 for adding more detailed descriptions of all the scenarios.
Simon
Thoughts?
Simon
Simon
