summaryrefslogtreecommitdiffstats
path: root/sca-java-1.x/branches/sca-java-travelsample-1.0/distribution/src/main/release/README
blob: da8922b7b538c7c4e4de9cb7a5e37446b2e64fd8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
README for the Apache Tuscany SCA Travel Sample 1.0 May 2010
============================================================

Structure of the travel sample
------------------------------

The travel sample consists of the following directory tree:

lib              dependencies for the travel sample (see notes below) 
  jaxws          jars from the JAX-WS reference implementation
  junit          the Junit jar
  openejb        jars from the OpenEJB binary distribution
travelsample     top-level directory for the travel sample
  binaries       builds a binaries-only package for the travel sample
  clients        non-SCA clients for the travel sample
  contributions  SCA contributions for the travel sample
  distribution   builds the travel sample distribution
  domainconfig   configuration files for the domain manager
  launchers      launcher programs for the travel sample
  services       non-SCA services used by the travel sample
  testdomain     scratch directory for trying out the domain manager
  util           utility code used by other parts of the travel sample

Note 1: The travel sample depends on the Apache Tuscany SCA Java 1.x binary
distribution, which is downloaded separately from the travel sample.
To avoid needless duplication, the "lib" directory of the travel sample
only contains dependencies that aren't provided in the current release
of the Tuscany SCA Java 1.x binary distribution.

Note 2: Before attempting to build or run the travel sample, you will need to
download the Apache Tuscany SCA Java 1.6 (or later) binary distribution and
set your TUSCANY_HOME environment variable to a local directory containing
the unpacked binary distribution. 


Overview of the travel sample
-----------------------------

The travel sample consists of a number of related scenarios. For each
scenario, this section lists the following:
 Description: A description of the scenario.
 Contributions: SCA contributions used in the scenario. Each contribution
   is a subdirectory of the travelsample/contributions directory.
 Launchers: Launchers used in the scenario. Each launcher is a subdirectory
   of the travelsample/launchers directory.
 Services: Non-SCA services used in the scenario, if any. Each non-SCA 
   service is a subdirectory of the travelsample/services directory.
 Clients: Non-SCA clients used in the scenario, if any. Each non-SCA
   client is a subdirectory of the travelsample/clients directory.
 Webapp: Web application (.war) file used to run the scenario, for those
   scenarios that use contributions packaged as web applications and
   deployed in a Web application server such as Tomcat.

Details of how to build and run these scenarios can be found in later
sections of this file.

1) Jumpstart - First simple example of using Tuscany 

Description: The jumpstart launcher shows the code needed to load an
 SCA contribution and invoke a method. The introducing-trips contribution
 shows how to package an SCA component in a contribution.
Contributions: introducing-trips
Launchers: jumpstart

2) Introducing - Simplified introduction to the travel application

Description: This scenario introduces a simplified form of the travel
 booking application that will be developed and extended by other
 scenarios in the travel sample. This scenario gives a clearer picture
 than jumpstart of how SCA applications are constructed because it
 shows multiple SCA components connected together with references wired
 to services.
Contributions: introducing-client, introducing-tours, introducing-trips
Launchers: introducing

3) Introducing (distributed) - Distributed services with a domain manager

Description: We're using the same SCA components, services, and implementations
 as in the previous scenario but with a big difference--they're distributed
 across multiple execution nodes and they make remote calls to each other
 using configuration information provided by the Tuscany domain manager.
 For simplicity these nodes are represented as different processes running on
 a single computer, though the domain manager configuration could easily be
 modified to run the nodes on different computers communicating across a network.
Contributions: introducing-client, introducing-tours, introducing-trips
Launchers: introducing-client, introducing-domain, introducing-tours,
 introducing-trips

4) Using SCA - Defining and using SCA Components

Description: The examples in this scenario show how to define SCA components
 and how to use SCA components in a business application.  This "guided tour"
 consists of code samples illustrating the major features of SCA components
 including implementations, services, interfaces, references, wires, properties,
 bindings and domains.
Contributions: usingsca
Launchers: usingsca

5) Building blocks - Using SCA composites as application building blocks

Description: We're looking at how to create composite applications using
 SCA composites as building blocks. The ToursImpl composite shows how to
 use a composite as a component implementation (black box reuse) and the
 ToursImplInclude composite demonstrates including one composite in another
 (white box reuse). The ToursAppl composite combines both of these kinds
 of reuse and shows how easy it is to build a full composite application
 using building blocks.
Contributions: buildingblocks, buildingblocks-client, introducing-trips
Launchers: buildingblocks

6) Interaction - Different SCA interaction styles

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 launcher starts two nodes (node1 and node2) which are used
 to run samples for all of the interaction patterns. The first node "node1"
 loads the contributions common, currency, calendar, shoppingcart, and
 interaction-client, and runs the client.composite from the interaction-client
 contribution. The local interaction patterns are demonstrated by clients
 calling the currency, calendar, and shoppingcart components locally within
 node1. The second node 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's used by client components in node1 for sending remote
 messages to demonstrate the remote interaction pattern.
Contributions: calendar, common, currency, flight, hotel, interaction-client, 
 interaction-service-remote, shoppingcart
Launchers: interaction

7) Full application - The full interactive travel application

Description: This is the fully functional travel application with a user
 interface for booking a trip (either pre-packaged or customized), adding the
 trip to a shopping cart, and checking out the purchase using a credit card.
Contributions: car, common, creditcard-payment-jaxb-policy, currency, flight,
 fullapp-bespoketrip, fullapp-coordination, fullapp-currency, fullapp-packagedtrip,
 fullapp-shoppingcart, fullapp-ui, hotel, payment-spring-policy, scatours,
 shoppingcart, travelcatalog, trip, tripbooking
Launchers: fullapp

8) Full application (distributed) - Distributed services with a domain manager

Description: This version of the full travel application uses multiple execution
 nodes and the domain manager. The execution nodes all run within the same
 process, which isn't very realistic but shows the flexibility of the Tuscany
 runtime model which allows nodes to be allocated to processes and computers in
 any combination. There's one small difference in the contributions used by this
 distributed version: payment-java-policy is used instead of payment-spring-policy
 because of an incompatibility between the domain manager and implementation.spring
 (see issue TUSCANY-3476).

Contributions: car, common, creditcard-payment-jaxb-policy, currency, flight,
 fullapp-bespoketrip, fullapp-coordination, fullapp-currency, fullapp-packagedtrip,
 fullapp-shoppingcart, fullapp-ui, hotel, payment-java-policy, scatours,
 shoppingcart, travelcatalog, trip, tripbooking
Launchers: fullapp-domain, fullapp-nodes

9) Callback

Description: SCA callbacks are illustrated using a variation of the Payment
 service which makes callbacks to the client to perform additional security
 checks for large payments.
Contributions: payment-java-callback 
Launchers: payment-java-callback

10) Reference passing

Description: We use another variation on the Payment service to show how
 SCA service references can be passed as parameters when invoking a service.
 The Payment service creates a service reference for the EmailGateway service
 and passes this service reference to the CreditCardPayment service.  When the
 CreditCardPayment service has finished doing the credit card authorization,
 it invokes the EmailGateway service using the service reference that was
 passed in.
Contributions: payment-java-reference-pass 
Launchers: payment-java-reference-pass

11) Help pages

Description: This scenario shows how an SCA application can expose HTML web pages
 by using an SCA component with the implementation.resource implementation type.
Contributions: help-pages
Launchers: help-pages

12) Blog feed

Description: An SCA component implementation of a blog is exposed as a
 feed via the Atom protocol using binding.atom and via the RSS protocol
 using binding.rss.  For each protocol there are example implementations
 using two different approaches: the getAll() method and the Collection API.
Contributions: blog-feed
Launchers: blog-feed

13) Feed logger

Description: An SCA component implementation is connected to an Atom feed
 using binding.atom and an RSS feed using binding.rss.  The SCA component
 receives and logs entries from both feeds.
Contributions: feed-logger
Launchers: feed-logger

14) Data binding

Description: A Payment component that uses JAXB as its data representation
 invokes a CreditCardPayment component that uses SDO to represent its data.
 The Tuscany data binding framework converts automatically between these
 different data representations.
Contributions: creditcard-payment-sdo, databinding-client, payment-java
Launchers: databinding

15) Policy

Description: The implementation of the Trip component has the tuscany:logging
 implementation policy applied to it which means that all invocations of all
 its services go through the JDKLoggingPolicyInterceptor class.  In addition
 the CreditCardPayment service has the "authentication" interaction policy
 intent which requires invocations of this service from the Payment component
 to use a policy set that satisifies this intent by providing authentication
 of the invoking client.
Contributions: creditcard-payment-jaxb-policy, payment-java-policy,
 policy-client, trip-policy
Launchers: policy

16) SCA credit card payment service packaged as a web application

Description: The CreditCardPayment service is packaged as a web application
 (.war file) including all its Tuscany runtime dependencies, so that it
 can be deployed to a Web application server such as Apache Tomcat. The web
 application also includes a JSP that invokes the CreditCardPayment service.
Contributions: creditcard-payment-jaxb, creditcard-payment-webapp
Webapp: creditcard-payment-webapp

17) Payment service with different implementation types

Description: In SCA the technology used to implement a service is encapsulated
 by the service and doesn't affect other components that invoke the service.
 In this scenario we show how the Payment service can be implemented using a
 range of different technologies while providing the same interface and the
 same semantics.

17a) implementation.bpel

Description: The Payment service is implemented using a BPEL process.
Contributions: creditcard-payment-jaxb, emailgateway, payment-bpel, payment-bpel-process 
Launchers: payment-bpel

17b) implementation.script written in Groovy

Description: The Payment service is implemented using a Groovy script.
Contributions: emailgateway, payment-groovy
Launchers: payment-groovy

17c) implementation.java

Description: The Payment service is implemented using a Java class.
Contributions: creditcard-payment-jaxb, payment-java 
Launchers: payment-java

17d) implementation.java with policy

Description: The Payment service is implemented using a Java class, and
 the reference from the Payment service to the CreditCardPayment service
 is defined as requiring the "authentication" security policy.
Contributions: creditcard-payment-jaxb-policy, payment-java-policy 
Launchers: payment-java-policy

17e) implementation.script written in Python

Description: The Payment service is implemented using a Python script.
Contributions: emailgateway, payment-python
Launchers: payment-python

17f) implementation.spring

Description: The Payment service is implemented using a Spring application
 context which doesn't use any SCA-specific features.
Contributions: creditcard-payment-jaxb, payment-spring
Launchers: payment-spring

17g) implementation.spring with SCA tags

Description: The Payment service is implemented using a Spring application
 context which uses SCA-specific XML elements (tags) to define SCA references
 and properties.
Contributions: creditcard-payment-jaxb, payment-spring-scatag
Launchers: payment-spring-scatag

18) SCA currency converter service interoperating with SCA or non-SCA client

Description: In SCA a service can be configured with a variety of bindings
 to expose it using a range of different communication protocols. This
 scenario contains a number of examples showing the CurrencyConverter service
 exposed using different bindings and invoked by SCA or non-SCA clients 
 using various protocols.

18a) SCA client

Description: The CurrencyConverter service uses the default SCA binding and
 is invoked by an SCA client running in the same process.
Contributions: currency
Launchers: currency-converter

18b) CORBA client

Description: The CurrencyConverter service is exposed as a CORBA service
 using binding.corba and is invoked by a Java CORBA client running in a
 different process.
Contributions: currency, currency-corba
Launchers: currency-converter-corba
Clients: currency-converter-corba

18c) JMS client

Description: The CurrencyConverter service is exposed as a JMS service
 using binding.jms and is invoked by an ActiveMQ JMS client running in
 a different process.
Contributions: currency, currency-jms
Launchers: currency-converter-jms
Clients: currency-converter-jms

18d) RMI client

Description: The CurrencyConverter service is exposed as an RMI service
 using binding.rmi and is invoked by a Java RMI client running in a
 different process.
Contributions: currency, currency-rmi
Launchers: currency-converter-rmi
Clients: currency-converter-rmi

18e) JAX-WS client

Description: The CurrencyConverter service is exposed as a web service
 using binding.ws and is invoked over SOAP/HTTP by a JAX-WS client
 running in a different process.
Contributions: currency, currency-ws
Launchers: currency-converter-ws
Clients: currency-converter-ws-jaxws

18f) Web application JSP client

Description:  The CurrencyConverter service is deployed as a web
 application using the default SCA binding and is invoked from the
 same process by a JSP client that's deployed as part of the same
 web application.
Contributions: currency, currency-jsp
Webapp: scatours-contribution-currency-jsp.war

18g) Web application servlet client

Description:  The CurrencyConverter service is deployed as a web
 application using the default SCA binding and is invoked from the
 same process using a servlet in the same web application which
 generates HTML to display a client page.
Contributions: currency, currency-servlet
Webapp: scatours-contribution-currency-servlet.war

19) SCA notification service interoperating with non-SCA SMS gateway service

Description: SCA references can invoke non-SCA services using a range
 of different communication protocols which are selected by choosing
 a suitable binding to configure the reference.  This scenario contains
 a number of examples showing an SCA Notification service using an
 SCA reference configured with different bindings to invoke a non-SCA
 SMSGateway service over various different protocols.

19a) SMS gateway CORBA service

Description: The SCA reference uses binding.corba to invoke an SMSGateway
 Java CORBA service running in a different process.
Contributions: notification, notification-corba
Services: smsgateway-corba
Launchers: notification-corba

19b) SMS gateway EJB service

Description: The SCA reference uses binding.ejb to invoke an SMSGateway
 EJB session bean running on OpenEJB in a different process.
Contributions: notification, notification-ejb
Services: smsgateway-ejb
Launchers: notification-ejb

19c) SMS gateway JMS service

Description: The SCA reference uses binding.jms to invoke an SMSGateway
 JMS service running on ActiveMQ in a different process.
Contributions: notification, notification-jms
Services: smsgateway-jms
Launchers: notification-jms

19d) SMS gateway RMI service

Description: The SCA reference uses binding.rmi to invoke an SMSGateway
 RMI service running in a different process.
Contributions: notification, notification-rmi
Services: smsgateway-rmi
Launchers: notification-rmi

19e) SMS gateway JAX-WS service

Description: The SCA reference uses binding.ws to invoke an SMSGateway
 JAX-WS web service running in a different process.
Contributions: notification, notification-ws
Services: smsgateway-jaxws
Launchers: notification-ws


Building the travel sample
--------------------------

Please see the BUILDING file in the travel sample distribution for full
details of how to build the travel sample using Maven or Ant.


Running travel sample scenarios from launcher source directories
----------------------------------------------------------------

After building the travel sample using either Maven or Ant, you can run
all the scenarios that have launchers by using ant scripts in the
subdirectories of the travelsample/launchers directory. For scenarios
that are packaged as web applications and don't have launchers, the next
section describes how you can run these.

You can run the launcher ant scripts as follows:
 1. Open a command prompt. 
 2. Change directory to travelsample/launchers/<launcher-dir> where
    <launcher-dir> is the launcher directory for the scenario that you
    want to run.
 3. Enter the command shown in Table 1 below. This command is usually
    "ant run". This runs an ant script that sets the necessary
    classpath and invokes the launcher class.
 4. Some scenarios require the above steps to be repeated multiple times
    with different commands. These cases are indicated by entries in
    Table 1 with more than one command listed. For these scenarios, all
    the listed commands should be entered in separate command prompts
    from the same current directory and in the same order as shown.
 5. Some scenarios have a browser-based user interface which is started
    by entering the URL shown in Table 1 in a browser after running the
    launcher or launchers for the scenario. The recommended browser is
    Firefox as some scenarios don't work with Internet Explorer.

Table 1. Running scenarios packaged as launchers and contributions
---------------------------------------------------------------------------------------------------------------
|    Scenario            Launcher directory            Commands         URLs                                  |
---------------------------------------------------------------------------------------------------------------
| 1) Jumpstart         | jumpstart                   | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 2) Introducing       | introducing                 | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 3) Introducing       | introducing-client          | ant run-domain |                                       |
|    (distributed)     |                             | ant run-trips  |                                       |
|                      |                             | ant run-tours  |                                       |
|                      |                             | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 4) Using SCA         | usingsca                    | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 5) Building blocks   | buildingblocks              | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 6) Interaction       | interaction                 | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 7) Full application  | fullapp                     | ant run        | http://localhost:8080/scatours        |
---------------------------------------------------------------------------------------------------------------
| 8) Full application  | fullapp-nodes               | ant run-domain |                                       |
|    (distributed)     |                             | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 9) Callback          | payment-java-callback       | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 10) Reference        | payment-java-reference-pass | ant run        |                                       |
|     passing          |                             | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 11) Help pages       | help-pages                  | ant run        | http://localhost:8085/help/index.html |
---------------------------------------------------------------------------------------------------------------
| 12) Blog feed        | blog-feed                   | ant run        | http://localhost:8090/BlogAtom        |
|                      |                             |                | http://localhost:8090/BlogRSS         |
|                      |                             |                | http://localhost:8090/BlogAtomAPIs    |
|                      |                             |                | http://localhost:8090/BlogRSSAPIs     |
---------------------------------------------------------------------------------------------------------------
| 13) Feed logger      | feed-logger                 | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 14) Data binding     | databinding                 | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 15) Policy           | policy                      | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 17) Payment service implementation types                                                                    |
|                                                                                                             |
|      Impl type         Launcher directory            Commands         URLs                                  |
---------------------------------------------------------------------------------------------------------------
| 17a) BPEL            | payment-bpel                | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 17b) Groovy          | payment-groovy              | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 17c) Java            | payment-java                | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 17d) Java + policy   | payment-java-policy         | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 17e) Python          | payment-python              | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 17f) Spring          | payment-spring              | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 17g) Spring SCA tags | payment-spring-scatag       | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 18) Currency converter service binding types                                                                |
|                                                                                                             |
|      Binding type      Launcher directory            Commands         URLs                                  |
---------------------------------------------------------------------------------------------------------------
| 18a) SCA             | currency-converter          | ant run        |                                       |
---------------------------------------------------------------------------------------------------------------
| 18b) CORBA           | currency-converter-corba    | ant run        |                                       |
|                      |                             | ant run-client |                                       |
---------------------------------------------------------------------------------------------------------------
| 18c) JMS             | currency-converter-jms      | ant run        |                                       |
|                      |                             | ant run-client |                                       |
---------------------------------------------------------------------------------------------------------------
| 18d) RMI             | currency-converter-rmi      | ant run        |                                       |
|                      |                             | ant run-client |                                       |
---------------------------------------------------------------------------------------------------------------
| 18e) WS              | currency-converter-ws       | ant run        |                                       |
|                      |                             | ant run-client |                                       |
---------------------------------------------------------------------------------------------------------------
| 19) Notification reference binding types                                                                    |
|                                                                                                             |
|      Binding type      Launcher directory        Commands             URLs                                  |
---------------------------------------------------------------------------------------------------------------
| 19a) CORBA           | notification-corba      | ant run-smsgateway |                                       |
|                      |                         | ant run            |                                       |
---------------------------------------------------------------------------------------------------------------
| 19b) EJB             | notification-ejb        | ant run-smsgateway |                                       |
|                      |                         | ant run            |                                       |
---------------------------------------------------------------------------------------------------------------
| 19c) JMS             | notification-jms        | ant run-smsgateway |                                       |
|                      |                         | ant run            |                                       |
---------------------------------------------------------------------------------------------------------------
| 19d) RMI             | notification-rmi        | ant run-smsgateway |                                       |
|                      |                         | ant run            |                                       |
---------------------------------------------------------------------------------------------------------------
| 19e) WS              | notification-ws         | ant run-smsgateway |                                       |
|                      |                         | ant run            |                                       |
---------------------------------------------------------------------------------------------------------------


Running travel sample scenarios in a Web application server
-----------------------------------------------------------

Some scenarios are packaged as web applications (.war files) and don't
have launchers. After building the travel sample using either Maven or Ant,
you can use a Web application server to run these scenarios.

You can run these web applications as follows:
 1. Deploy the web application (.war) file to a Web application server
    such as Tomcat. The .war file can be found in the directory
    travelsample/contributions/<contrib-dir>/target where <contrib-dir>
    is the contribution directory listed in Table 2 below. The name of
    the .war file is scatours-contribution-<contrib-dir>.war.
 2. Start the browser-based user interface for the scenario by entering
    its URL in a browser. The URL for each scenario is shown in Table 2.
    The host and port in the URL may need to be changed depending on the
    configuration of the Web application server in which the web application
    is deployed. The recommended browser is Firefox because some scenarios
    don't work with Internet Explorer.

Table 2. Running scenarios packaged as web applications
--------------------------------------------------------------------------------------------------------------------------
|    Scenario        | Contribution directory    | URL                                                                   |
--------------------------------------------------------------------------------------------------------------------------
| 16) Credit card    | creditcard-payment-webapp | http://localhost:8080/scatours-contribution-creditcard-payment-webapp |
|     webapp service |                           |                                                                       |                                     |
--------------------------------------------------------------------------------------------------------------------------
| 18f) Currency      | currency-jsp              | http://localhost:8080/scatours-contribution-currency-jsp              |                        |
|      converter JSP |                           |                                                                       |
--------------------------------------------------------------------------------------------------------------------------
| 18g) Currency      | currency-servlet          | http://localhost:8080/scatours-contribution-currency-servlet          |                        |
|      converter     |                           |                                                                       |
|      servlet       |                           |                                                                       |
--------------------------------------------------------------------------------------------------------------------------


Running the domain manager
--------------------------

The travelsample/testdomain directory is provided for the purpose
of running the domain manager and creating your own configuration.
You can do this as follows:

1. Open a command prompt and make travelsample/testdomain your
   current directory.

2. Enter "ant run" to start the domain manager.

3. In a browser, start the domain manager GUI by entering the URL
   "http://localhost:9990/ui/home". The recommended browser is Firefox
   because the domain manager GUI doesn't work with Internet Explorer.

4. In the browser window, create or update your domain manager
   configuration using the domain manager GUI.

5. To exit the domain manager, enter "q" in the command prompt window.
   The domain configuration is saved automatically and will be
   restored the next time you start the domain manager.

6. If you want to remove your saved configuration and start again from
   a clean slate, enter either "ant clean" or "mvn clean" from the
   command prompt window.


Running travel sample scenarios from the "binaries" directory
-------------------------------------------------------------

If the travel sample was built from the distribution using Ant or Maven,
a binary package for the travel sample will be created in the binaries/target
directory and its subdirectories. This binary package contains all the built
jar and war files and runtime dependencies for these files. By looking at the
contents of the binaries/target directory tree you can see how to package a
Yuscany application in binary form for distribution to users of the application.

The following subdirectories of binaries/target contain jar and war files
for the travel sample:
  clients - non-SCA clients using various communication technologies
  contributions - SCA contributions for the travel sample
  launchers - executable launchers for the travel sample
  services - non-SCA services using various communication technologies
  util - jar files needed by other jars in the travel sample
  webapps - war files for the travel sample

The following subdirectories of binaries/target contain runtime dependencies
for the above files:
  domainconfig - domain configuration files
  jaxws - JAX-WS runtime jars neeed when running the travel sample on JDK 5
  lib - Tuscany runtime jars and their dependencies needed by the travel sample
     (only present if the travel sample was built using "mvn -Pselfcontained")
  ode - JPA Derby database needed by the ODE runtime
  openejb - OpenEJB 3.1.2 runtime jars needed by the travel sample

To use the binary package to run the travel sample scenarios packaged with
launchers, you can do the following:
 1. Open a command prompt. 
 2. Change directory to travelsample/binaries/target/<runtime-dir> where
    <runtime-dir> is the directory for the scenario shown in Table 3 below.
 3. Enter the command for the scenario shown in Table 3. This runs an
    ant script that sets the necessary classpath and invokes the launcher class.
 4. Some scenarios require the above steps to be repeated multiple times
    with different commands. These cases are indicated by entries in
    Table 3 with more than one directory and command listed. For these
    scenarios, all the listed commands should be entered in separate command
    prompts from the listed current directories in the same order as shown.
 5. Some scenarios have a browser-based user interface which is started
    by entering the URL shown in Table 3 in a browser after running the
    launcher or launchers for the scenario. The recommended browser is
    Firefox as some scenarios don't work with Internet Explorer.

Table 3. Running scenarios with launchers from the binaries/target directory
-------------------------------------------------------------------------------------------------------------------
|    Scenario            Directory    Commands                              URLs                                  |
-------------------------------------------------------------------------------------------------------------------
| 1) Jumpstart         | launchers  | ant run-jumpstart                   |                                       |
-------------------------------------------------------------------------------------------------------------------
| 2) Introducing       | launchers  | ant run-introducing                 |                                       |
-------------------------------------------------------------------------------------------------------------------
| 3) Introducing       | launchers  | ant run-introducing-domain          |                                       |
|    (distributed)     | launchers  | ant run-introducing-trips           |                                       |
|                      | launchers  | ant run-introducing-tours           |                                       |
|                      | launchers  | ant run-introducing-client          |                                       |
-------------------------------------------------------------------------------------------------------------------
| 4) Using SCA         | launchers  | ant run-usingsca                    |                                       |
-------------------------------------------------------------------------------------------------------------------
| 5) Building blocks   | launchers  | ant run-buildingblocks              |                                       |
-------------------------------------------------------------------------------------------------------------------
| 6) Interaction       | launchers  | ant run-interaction                 |                                       |
-------------------------------------------------------------------------------------------------------------------
| 7) Full application  | launchers  | ant run-fullapp                     | http://localhost:8080/scatours        |
-------------------------------------------------------------------------------------------------------------------
| 8) Full application  | launchers  | ant run-fullapp-domain              |                                       |
|    (distributed)     | launchers  | ant run-fullapp-nodes               |                                       |
-------------------------------------------------------------------------------------------------------------------
| 9) Callback          | launchers  | ant run-payment-java-callback       |                                       |
-------------------------------------------------------------------------------------------------------------------
| 10) Reference        | launchers  | ant run-payment-java-reference-pass |                                       |
|     passing          |            |                                     |                                       |
-------------------------------------------------------------------------------------------------------------------
| 11) Help pages       | launchers  | ant run-help-pages                  | http://localhost:8085/help/index.html |
-------------------------------------------------------------------------------------------------------------------
| 12) Blog feed        | launchers  | ant run-blog-feed                   | http://localhost:8090/BlogAtom        |
|                      |            |                                     | http://localhost:8090/BlogRSS         |
|                      |            |                                     | http://localhost:8090/BlogAtomAPIs    |
|                      |            |                                     | http://localhost:8090/BlogRSSAPIs     |
-------------------------------------------------------------------------------------------------------------------
| 13) Feed logger      | launchers  | ant run-feed-logger                 |                                       |
-------------------------------------------------------------------------------------------------------------------
| 14) Data binding     | launchers  | ant run-databinding                 |                                       |
-------------------------------------------------------------------------------------------------------------------
| 15) Policy           | launchers  | ant run-policy                      |                                       |
-------------------------------------------------------------------------------------------------------------------
| 17) Payment service implementation types                                                                        |
|                                                                                                                 |
|      Impl type         Directory   Commands                               URLs                                  |
-------------------------------------------------------------------------------------------------------------------
| 17a) BPEL            | launchers  | ant run-payment-bpel                |                                       |
-------------------------------------------------------------------------------------------------------------------
| 17b) Groovy          | launchers  | ant run-payment-groovy              |                                       |
-------------------------------------------------------------------------------------------------------------------
| 17c) Java            | launchers  | ant run-payment-java                |                                       |
-------------------------------------------------------------------------------------------------------------------
| 17d) Java + policy   | launchers  | ant run-payment-java-policy         |                                       |
-------------------------------------------------------------------------------------------------------------------
| 17e) Python          | launchers  | ant run-payment-python              |                                       |
-------------------------------------------------------------------------------------------------------------------
| 17f) Spring          | launchers  | ant run-payment-spring              |                                       |
-------------------------------------------------------------------------------------------------------------------
| 17g) Spring SCA tags | launchers  | ant run-payment-spring-scatag       |                                       |
-------------------------------------------------------------------------------------------------------------------
| 18) Currency converter service binding types                                                                    |
|                                                                                                                 |
|      Binding type      Directories  Commands                              URLs                                  |
-------------------------------------------------------------------------------------------------------------------
| 18a) SCA             | launchers  | ant run-currency-converter          |                                       |
-------------------------------------------------------------------------------------------------------------------
| 18b) CORBA           | launchers  | ant run-currency-converter-corba    |                                       |
|                      | clients    | ant run-currency-converter-corba    |                                       |
-------------------------------------------------------------------------------------------------------------------
| 18c) JMS             | launchers  | ant run-currency-converter-jms      |                                       |
|                      | clients    | ant run-currency-converter-jms      |                                       |
-------------------------------------------------------------------------------------------------------------------
| 18d) RMI             | launchers  | ant run-currency-converter-rmi      |                                       |
|                      | clients    | ant run-currency-converter-rmi      |                                       |
-------------------------------------------------------------------------------------------------------------------
| 18e) WS              | launchers  | ant run-currency-converter-ws       |                                       |
|                      | clients    | ant run-currency-converter-ws-jaxws |                                       |
-------------------------------------------------------------------------------------------------------------------
| 19) Notification reference binding types                                                                        |
|                                                                                                                 |
|      Binding type      Directories  Commands                              URLs                                  |
-------------------------------------------------------------------------------------------------------------------
| 19a) CORBA           | services   | ant run-smsgateway-corba            |                                       |
|                      | launchers  | ant run-notification-corba          |                                       |
-------------------------------------------------------------------------------------------------------------------
| 19b) EJB             | services   | ant run-smsgateway-ejb              |                                       |
|                      | launchers  | ant run-notification-ejb            |                                       |
-------------------------------------------------------------------------------------------------------------------
| 19c) JMS             | services   | ant run-smsgateway-jms              |                                       |
|                      | launchers  | ant run-notification-jms            |                                       |
-------------------------------------------------------------------------------------------------------------------
| 19d) RMI             | services   | ant run-smsgateway-rmi              |                                       |
|                      | launchers  | ant run-notification-rmi            |                                       |
-------------------------------------------------------------------------------------------------------------------
| 19e) WS              | services   | ant run-smsgateway-jaxws            |                                       |
|                      | launchers  | ant run-notification-ws             |                                       |
-------------------------------------------------------------------------------------------------------------------

Some scenarios are packaged as web applications and don't have launchers.
You can run these using .war files from the binaries/target/webapps
directory as follows:
 1. Deploy the web application (.war) file to a Web application server
    such as Tomcat. The .war file can be found in the directory
    travelsample/binaries/target/webapps and has the name listed in
    Table 4 below.
 2. Start the browser-based user interface for the scenario by entering
    its URL in a browser. The URL for each scenario is shown in Table 4.
    The host and port in the URL may need to be changed depending on the
    configuration of the Web application server in which the web application
    is deployed. The recommended browser is Firefox because some scenarios
    don't work with Internet Explorer.

Table 4. Running scenarios packaged as web applications
----------------------------------------------------------------------------------------------------------------------------------------------------
|    Scenario        | Web application file                                | URL                                                                   |
----------------------------------------------------------------------------------------------------------------------------------------------------
| 16) Credit card    | scatours-contribution-creditcard-payment-webapp.war | http://localhost:8080/scatours-contribution-creditcard-payment-webapp |
|     webapp service |                                                     |                                                                       |                                     |
----------------------------------------------------------------------------------------------------------------------------------------------------
| 18f) Currency      | scatours-contribution-currency-jsp.war              | http://localhost:8080/scatours-contribution-currency-jsp              |                        |
|      converter JSP |                                                     |                                                                       |
----------------------------------------------------------------------------------------------------------------------------------------------------
| 18g) Currency      | scatours-contribution-currency-servlet.war          | http://localhost:8080/scatours-contribution-currency-servlet          |                        |
|      converter     |                                                     |                                                                       |
|      servlet       |                                                     |                                                                       |
----------------------------------------------------------------------------------------------------------------------------------------------------


Building and running the self-contained travel sample
-----------------------------------------------------

The travel sample can be built using the "mvn -Pselfcontained" command. This
puts all of its runtime dependencies under the binaries/target directory and
doesn't use any files from the Tuscany SCA Java binary distribution.

If the travel sample has been built in this way, you can run it as described
in the previous section using the same ant scripts. Alternatively you can
use the "java -jar" command to run the travel sample executable jars directly
using the manifest dependencies in the jar files. For example, the commands
  ant run-currency-converter-ws
  ant run-currency-converter-ws-jaxws
  ant run-smsgateway-corba
could be replaced by the commands
  java -jar scatours-launcher-currency-converter-ws.jar
  java -jar scatours-client-currency-converter-ws-jaxws.jar
  java -jar scatours-service-smsgateway-corba.jar


Cross-reference of contributions to scenarios
---------------------------------------------

The following table shows which contributions are used in which scenarios.

contributions/blog-feed  12
contributions/buildingblocks  5
contributions/buildingblocks-client  5
contributions/calendar  6
contributions/car  7, 8
contributions/common  6, 7, 8, 15
contributions/creditcard-payment-jaxb  17a, 17c, 17f, 17g, 16
contributions/creditcard-payment-jaxb-policy  7, 8, 15, 17d
contributions/creditcard-payment-sdo  14
contributions/creditcard-payment-webapp  16
contributions/currency  6, 7, 8, 18a, 18b, 18c, 18d, 18e, 18f, 18g
contributions/currency-corba  18b
contributions/currency-jms  18c
contributions/currency-jsp  18f
contributions/currency-rmi  18d
contributions/currency-servlet  18g
contributions/currency-ws  18e
contributions/databinding-client  14
contributions/emailgateway  17a, 17b, 17e
contributions/feed-logger  13
contributions/flight  6, 7, 8
contributions/fullapp-bespoketrip  7, 8
contributions/fullapp-coordination  7, 8
contributions/fullapp-currency  7, 8
contributions/fullapp-packagedtrip  7, 8 
contributions/fullapp-shoppingcart  7, 8
contributions/fullapp-ui  7, 8
contributions/help-pages  11
contributions/hotel  7, 8
contributions/interaction-client  6
contributions/interaction-service-remote  6
contributions/introducing-client  2, 3
contributions/introducing-tours  2, 3
contributions/introducing-trips  1, 2, 3, 5
contributions/notification  19a, 19b, 19c, 19d, 19e
contributions/notification-corba  19a
contributions/notification-ejb  19b
contributions/notification-jms  19c
contributions/notification-rmi  19d
contributions/notification-ws  19e
contributions/payment-bpel  17a
contributions/payment-bpel-process  17a
contributions/payment-groovy  17b
contributions/payment-java  14, 17c
contributions/payment-java-callback  9
contributions/payment-java-policy  8, 15, 17d
contributions/payment-java-reference-pass  10
contributions/payment-python  17e
contributions/payment-spring  17f
contributions/payment-spring-policy  7
contributions/payment-spring-scatag  17g
contributions/policy-client  15
contributions/scatours  7, 8
contributions/shoppingcart  6, 7, 8
contributions/travelcatalog  7, 8
contributions/trip  7, 8
contributions/tripbooking  7, 8
contributions/trip-policy  15
contributions/usingsca  4