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. >>> >>> 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. 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. >>> >>>> 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
