| 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 <example> 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.notification/> |
| 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=/<installation_directory> |
| ANT_HOME=/<installation_directory>/apache-ant-1.7.1 |
| M2_HOME=/<installation_directory>/maven-2.0.10 |
| export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$M2_HOME/bin:$PATH |
| |
| For Windows: |
| set JAVA_HOME=C:\<installation_directory> |
| set ANT_HOME=C:\<installation_directory>\apache-ant-1.7.1 |
| set M2_HOME=C:\<installation_directory>\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 <sampledir> |
| ant run |
| |
| Check each <sampledir>/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 <sampledir> |
| 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\<sample jar file> <sample runnable class> |
| |
| 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/<sample jar file> <sample runnable class> |
| |
| 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 <sample runnable class> |
| |
| for example : java -cp ..\..\lib\tuscany-sca-manifest.jar;target\classes calculator.CalculatorClient |
| |
| on *nix |
| |
| java -cp ../../lib/tuscany-sca-manifest.jar:target/classes <sample runnable class> |
| |
| 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 <sampledir> |
| 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=<path-to-eclipse-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. |
