The Apache Tuscany SCA Samples ============================== The Apache Tuscany SCA samples are built as part of the main Maven build and run, using the provided JUnit test cases, as tests in the Maven build. In the binary distribution of Apache Tuscany the samples can also be built and run using the provided Ant build.xml files. These show the samples running from a simple main() method without the need for a JUnit test case. In these notes text that appears in angled brackets like this means that you need to make a choice and provide your own text at that point. These simple samples have been created with the intention of illustrating the usage of the SCA API and annotations and certainly not to levels of SCA component abstraction. In real life situations you should use SCA to assemble real and usually bigger components, and when you do that you'll get all the benefits of SCA, bindings, policies, integration in an SOA environment etc.. Sample Overview --------------- The samples generally show off different features of the SCA runtime and the extensions that come packaged with it. binding-notification-broker - A broker for notifications binding-notification-consumer - A consumer of notifications binding-notification-producer - A producer of notifications calculator - Calculator built with java components and local wires. calculator-distributed - A calculator built using SCA nodes running on multiple JVMs calculator-implementation-policies - Shows logging policites associated with SCA implementations calculator-corba-reference - The calculator configured to use existing CORBA service calculator-corba-service - The calculator configured to be accessible as CORBA service calculator-rmi-reference - The calculator configured to talk RMI to the calculator-rmi-service sample calculator-rmi-service - The calculator configured to accept RMI requests from calculator-rmi-reference calculator-script - Calculator built using various script languages calculator-webapp - Calculator running inside a web app calculator-ws-webapp - Calculator running inside a web app also showing webservices binding callbacks-jms - Shows how to use callbacks with JMS callback-ws-client - The client for showing callbacks across web services callback-ws-service - The server for showing callbacks across web serviced chat-webapp - A simple chat style web app demonstrating use of AJAX binding databinding-echo - An SCA application that shows how databindings transform data domain-management - Shows how to use domain management APIs feed-aggregator - Demonstrates using the ATOM binding feed-aggregator-webapp - feed-aggregator running in webapp helloworld-bpel - Demonstrates an SCA component invoking a BPEL process in a composition helloworld-dojo-webapp - An SCA application that exposes a service using JSONRPC and a client using the Dojo toolkit helloworld-jsonrpc-webapp - helloworld using jsonrpc binding helloworld-reference-jms - The client side of a hello world sample that uses a JMS binding (requires helloworld-service-jms) helloworld-service-jms - The server side of a hello world sample that uses a JMS binding helloworld-ws-reference - The client side of a hello world sample that uses a web service binding (requires helloworld-ws-service) helloworld-ws-service - The server side of a hello world sample that uses a web service binding helloworld-ws-reference-jms - The client side of a hello world sample that uses a web service binding with SOAP/JMS (requires helloworld-ws-service-jms) helloworld-ws-service-jms - The server side of a hello world sample that uses a web service binding with SOAP/JMS helloworld-ws-reference-secure - The client side of a hello world sample that shows how policy intent can be used. helloworld-ws-service-secure - The client side of a hello world sample that shows how policy intent can be used. helloworld-ws-sdo - helloworld using ws binding and SDO helloworld-ws-sdo-webapp - helloworld using ws binding and SDO within a webapp holder-ws-service - Sample web service that uses a JAX-WS holder implementation-composite - Shows how SCA composites are used osgi-supplychain - SCA asynchronous API with OSGi and Java implementation types photo-gallery - A sample SCA picture gallery application quote-xquery - Demonstrate SCA components using XQuery simple-bigbank - A banking application built with java components and local wire simple-bigbank-spring - A banking application showing how SCA works with Spring spring-bigbank-calculator - part of the simple-bigbank-spring sample spring-bigbank-checkaccount - part of the simple-bigbank-spring sample spring-bigbank-stockquote - part of the simple-bigbank-spring sample simple-callback - demonstrates the callback interface simple-callback-ws - demonstrates use of callback interface across WS binding store - Step by step guide for creating an online store store-secure - the Store application using security policies store-webapp - the Store application running as a webapp supplychain - shows how asynchronous callbacks can be used web-resource - Demonstrates using an SCA Web resource component Samples for building extensions ------------------------------- There are samples that demonstrate how to build extensions for the Tuscany SCA runtime. These samples are slightly different from the samples above in that the provided code is concerned with building the extension and not with building an application that uses it. The application that shows how the new extension can be used is provided in an associated sample. implementation-crud-extension - Shows how to build new implementation type extensions implementation-crud - A sample application that exercises the new implementation extensions binding-echo-extension - Shows how to build new binding extensions binding-echo - A sample application that exercises the new binding extension implementation-notification - Illustrates the use of implementation-pojo-extension - shows how new implementation types are constructed Sample Layout ------------- All sample directories are organized in the same way based on the default project template provided by Maven. For example, take a look at the calculator sample; calculator/ src/ - Holds all of the source files for the sample main/ - Groups together the files that implement the sample java/ - Java source files resources/ - Non java resource files such as composte files test/ - Groups together files that provide sample tests java - Java test sources files. Usually JUnit test cases target/ - Holds the files generated when the sample is built classes/ - For example, Java class files test-classes/ - classes from src/test and other test files Getting Ready To Build ---------------------- You will need to install the following software before you start. J2SE Development Kit (JDK) 5.0 or higher Apache Ant 1.7.1 or higher - if you are going to use Ant Apache Maven 2.0.10 or higher - if you are going to use Maven Java and Ant and/or Maven binary directories must be present in your PATH so that their executable programs are available in your environment. You may find it useful to use a script to set up your environment, for example; For UNIX: JAVA_HOME=/ ANT_HOME=//apache-ant-1.7.1 M2_HOME=//maven-2.0.10 export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$M2_HOME/bin:$PATH For Windows: set JAVA_HOME=C:\ set ANT_HOME=C:\\apache-ant-1.7.1 set M2_HOME=C:\\maven-2.0.10 set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%M2_HOME%\bin;%PATH% Building And Running The SCA Samples Using Ant ---------------------------------------------- The build.xml files provided with the Apache Tuscany SCA samples are designed to work with the binary distribution. They rely on the tuscany-sca-manifest.jar to describe the class path and this jar is only provided as part of the binary distribution. The binary distribution of SCA also includes precompiled versions of each sample. If you look in the target directory of each sample you will see this jar file. To run a sample based on all of the precompiled artifacts all you have to do is: cd ant run Check each /README file as some samples require that two progams are run to get the desired result, for example, the two samples that show how to build extensions are run from their associated application samples. If you want to rebuild a sample, for example, if you have changed it, do the following: cd ant compile Once the sample is built you have the option of running the sample in whatever way best suits you. Two alternatives are provided in the ant build files. The compile target builds the class files and then builds the jar so you can use the same command as before: ant run This will use the generated jar to run the samples. The command line version of this is: on Windows java -cp ..\..\lib\tuscany-sca-manifest.jar;target\ for example : java -cp ..\..\lib\tuscany-sca-manifest.jar;target\sample-calculator.jar calculator.CalculatorClient on *nix java -cp ../../lib/tuscany-sca-manifest.jar:target/ for example : java -cp ../../lib/tuscany-sca-manifest.jar:target/sample-calculator.jar calculator.CalculatorClient You can use the compiled classes directly using ant run-classes The command line version of this is: on Windows java -cp ..\..\lib\tuscany-sca-manifest.jar;target\classes for example : java -cp ..\..\lib\tuscany-sca-manifest.jar;target\classes calculator.CalculatorClient on *nix java -cp ../../lib/tuscany-sca-manifest.jar:target/classes for example : java -cp ../../lib/tuscany-sca-manifest.jar:target/classes calculator.CalculatorClient The class specified on the command of course depends on which sample you want to run. In the examples we have used we are running the CalculatorClient from the calculator sample. Building And Running The SCA Samples Using Maven ------------------------------------------------ The Maven build process will work from both source and binary distributions. To build and test all of the Apache Tuscany SCA sources, including the samples, do the following. cd samples mvn This will take a little while to complete. Experience with Maven tells us that sometimes there are problems downloading the dependencies that Apache Tuscany SCA requires. If Maven reports that it cannot download required dependencies try running the Maven build again. Once you have all of the source built you can build and run each sample independently if required. cd mvn When using Maven the samples are run within JUnit test cases and so you will sometimes not see any test output. You will always see an indication of test success or failure. Using The Samples In An IDE --------------------------- The easiest way to use the samples in an IDE is to use Maven to generate all of the IDE project files for you automatically. If you are using the Apache Tuscany SCA source distribution, you can find details of how to generate IDE project files (including IDE project files for the samples) in the "Using an IDE" section of the BUILDING file. If you are using the Apache Tuscany SCA binary distribution, follow these steps to generate IDE project files for all of the samples; cd samples If you are an Eclipse user do the following mvn eclipse:eclipse mvn -Declipse.workspace= eclipse:add-maven-repo If you are an IDEA user do the following mvn idea:idea These commands generate project files for each module in the samples directory. The modules you are interested in can now be included in your IDE. For example, in Eclipse, if you create a new Java project and use the option to "create a new project from existing source" you can specify an SCA module directory, which includes the generated project files, and Eclipse will treat it like any other Java project. Using The Samples In An IDE Without Maven ----------------------------------------- We don't provide any IDE project files with our distributions so you will have to import the sample files into your IDE manually. Here's an example of how it can be done using Eclipse. In a new or existing workspace Create a new java project to represent the sample you want to work on, e.g. calculator Import all of the sample code and resources into this project, e.g. File, Import and then select samples/calculator from the filesystem Configure the source path to include src/main/java src/main/resources Configure the output folder to be calculator/target Configure the build path to include all of the jars provided in lib If you select calculator.CalculatorClient.java and run as "Java Application" you should see 3 + 2=5.0 3 - 2=1.0 3 * 2=6.0 3 / 2=1.5 The details of how to do this for other development environments will vary but the process will be similar.