5b67e082ce
git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@791397 13f79535-47bb-0310-9956-ffa450edef68
310 lines
14 KiB
Text
310 lines
14 KiB
Text
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-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
|
|
|
|
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.
|
|
|
|
|