diff options
Diffstat (limited to 'java/sca/samples/README')
| -rw-r--r-- | java/sca/samples/README | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/java/sca/samples/README b/java/sca/samples/README new file mode 100644 index 0000000000..2646fbb73a --- /dev/null +++ b/java/sca/samples/README @@ -0,0 +1,306 @@ +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 most samples can also +be 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 notificatione +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-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 + +callbck-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 + +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-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) +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 + +implementation-composite - Shows how SCA composites are used + +osgi-supplychain - SCA asynchronous API with OSGi and Java + implementation types + +simple-bigbank - A banking application built with java components + and local wire +simple-bigbank-spring - A banking application showing how SCA works with Spring + +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 + +supplychain - shows how asynchronous callbacks can be used + +web-resource - Demonstrates using an SCA Web resource component + +quote-xquery - Demonstrate SCA components using XQuery + +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-notifiaction- 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 +Apache Ant 1.7.0 - if you are going to use Ant +Apache Maven 2.0.6 - 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.0 + MAVEN_HOME=/<installation_directory>/maven-2.0.6 + export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$MAVEN_HOME/bin:$PATH + +For Windows: + set JAVA_HOME=C:\<installation_directory> + set ANT_HOME=C:\<installation_directory>\apache-ant-1.7.0 + set MAVEN_HOME=C:\<installation_directory>\maven-2.0.6 + set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%MAVEN_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 sca +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. This works best if you +generate IDE projects for all of the Apache Tuscany modules. You can then +include the ones you are interested in working with in you IDE. + +To build IDE project files for all of the modules in Apache Tuscany SCA; + +cd sca + +If you are an Eclipse user do the following + +mvn -Peclipse eclipse:eclipse + +If you are an IDEA user do the following + +mvn idea:idea + +These commands generate project files for each module in Apache Tuscany SCA. +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 tuscany-sca-1.0-incubating\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. + + |