path: root/sca-java-2.x/trunk/samples/README

The Apache Tuscany SCA Samples
==============================

Structure
---------
For the Milestone 5 release of Tuscany SCA Java 2.x we are beginning
the process of moving to a new structure for samples. Milestone 5 is 
delivered in a state of partial change over to this new emphasis, and hence
this README reflects that hybrid state.

There are primarily 3 types of sample; those which focus on pure SCA
concepts, those which demonstrate features of Tuscany and the last group
is of samples which give a flavour of more complete, realistic applications.

The new structure focusses on the way in which contributions are used by
launchers to execute tuscany SCA applications.

In this way you can explore the samples by chosing which launcher you wish
to invoke which contribution. In the old style of sample this distinction was not clear;
any given sample contained both launcher and contribution, and the set of samples provided
represented a small subset of the combinations possible by the new approach.

 
Within the SCA category of samples, all the calculator samples, have been
migrated to this new structure.

Please visit the 2.x documentation in our  website [1] to get a better understanding of SCA
and Tuscany 2.x

Running the New Style samples
-----------------------------

To run a new style sample there are 3 basic steps

1) build the contribution: using either the command "mvn", "ant run" or your usual steps to build a
   module in your IDE
2) unit test the contribution: if you used mvn or ant in step 1 then you will already have done this;
   if you used an IDE follow your usual steps to run the unit test in the contribution's module
3) launch the contribution: go to one of the launcher* subdirectories of the samples root directory
   and follow the instructions there to use a launcher to launch your chosen contribution 

[1] http://tuscany.apache.org/documentation-2x/


SCA Samples
  binding-ws-calculator 
  binding-ws-sdo-helloworld
  binding-sca-calculator
  binding-rmi-calculator
    binding-rmi-calculator-reference
    binding-rmi-calculator-service
  helloworld
  implementation-java-calculator
  implementation-java-helloworld
  implementation-bpel-helloworld
  implementation-spring-helloworld
  scaclient-helloworld
Tuscany Samples
  osgi-bundle-calculator  E, F?
  dosgi-calculator
    dosgi-calculator
    dosgi-calculator-operations
  dosgi-dynamic-calculator
    dosgi-dynamic-calculator
    dosgi-dynamic-calculator-operations
  webapp-calculator G?
Application Samples
  store
  store-webapp
Launchers
  launcher-embedded-jse  Ca, Da
  launcher-embedded-osgi Cb, Db, F?
  launcher-command-line  A
  launcher-sca-client
  launcher-eclipse - I what's this? Just embedded-jse with eclipse project files provided? Do we need this?


1/ Use local SCAClient
2/ Use remote SCAClient and distributed domain
3/ Use interoperable binding

Launch Mechanisms
-----------------

A. running a contribution from the command line
  Command:   tuscany.bat/.sh
  Classpath: core, extension and dependency jars

B. running a contribution from Maven
  Command:   Maven Tuscany plugin with mvn truscany:run
  Classpath: Maven dependency on core + extension features

Ca. running a contribution from Ant (JSE)
  Command:   call tuscany.bat/.sh launcher directly
  Classpath: core, extension and dependency jars

Cb. running a contribution from Ant (OSGi)
  Command:   tuscany-sca-equinox-manifest.jar
  Classpath: sca-api, node-api, node-launcher-equinox - TBD

Da. running a contribution from JSE program (or JUnit) (JSE)
  Command:   org.apache.tuscany.sca.node.launcher.NodeLauncher.createNode(...).start()
  Classpath: core, extension and dependency jars

Db. running a contribution from JSE program (or JUnit) (OSGi)
  Command:   org.apache.tuscany.sca.node.equinox.launcher.NodeLauncher.createNode(...).start()
  Classpath: sca-api, node-api, node-launcher-equinox - TBD

E. running a contribution from Junit under OSGi in Maven
  Command:   Maven Tuscany OSGi JUnit plugin
  Classpath: maven dependency on features

F. running a contribution from OSGi
  Command:   Package contribution as a bundle that has an activator
that uses pattern D
  Classpath: Load the OSGi runtime (Equinox) with
features/configuration/config.ini

Ga. running a contribution from a webapp (.war as contribution)
  Command:   web.xml configured to specify filter

 <filter>
   <filter-name>tuscany</filter-name>
   <filter-class>org.apache.tuscany.sca.host.webapp.TuscanyServletFilter</filter-class>
 </filter>

  Classpath: core, extension and dependency jars

Gb. running a contribution from a webapp (contributions inside war)
  Command:  web.xml configured to specify filter

 <context-param>
   <param-name>contributions</param-name>
   <param-value>/WEB-INF/sca-contributions</param-value>
 </context-param>

 <filter>
   <filter-name>tuscany</filter-name>
   <filter-class>org.apache.tuscany.sca.host.webapp.TuscanyServletFilter</filter-class>
 </filter>

  Classpath: core, extension and dependency jars

H. running a contribution from Tomcat
  Command:   install tomcat.war, from there install integration
             I don't remember how contributions are installed.
  Classpath: pakaged as part of deep integration
  DEFER

I. running a contribution from eclipse (or any other IDE)
  Command:   No point and click tool in 2.x for eclipse yet
             Use Da or Db
  Classpath:
  DEFER

Developing Tuscany
------------------

J. Developing Tuscany and/or extensions in Eclipse

K. Developing Tuscany and/or extensions in Eclipse PDE


OLD STUFF
=========
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-ws-calculator              - Calculator running inside a web app also 
                                     showing webservices binding

calculator (also traced)           - Calculator built with java components and 
                                     local wires. A second build target shows how to
                                     execute the sample with Tuscany trace turned on. 

calculator-equinox                 - Calculator running inside a Equinox OSGi runtime

calculator-osgi                    - Calculator running inside a OSGi runtime

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

implementation-java-calculator


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.1                - if you are going to use Ant 
Apache Maven 2.0.9              - 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 ..\..\features\tuscany-sca-manifest.jar;target\<sample jar file> <sample runnable class>

for example : java -cp ..\..\features\tuscany-sca-manifest.jar;target\sample-calculator.jar calculator.CalculatorClient

on *nix 

java -cp ../../features/tuscany-sca-manifest.jar:target/<sample jar file> <sample runnable class>

for example : java -cp ../../features/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 ..\..\features\tuscany-sca-manifest.jar;target\classes <sample runnable class>

for example : java -cp ..\..\features\tuscany-sca-manifest.jar;target\classes calculator.CalculatorClient

on *nix 

java -cp ../../features/tuscany-sca-manifest.jar:target/classes <sample runnable class>

for example : java -cp ../../features/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

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 the manifest jar tuscany-sca-manifiest.jar provided in
        features
     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.