Tuscany SCA Java provides an implementation for the SCA specifications made available at Open SOA. This Java implementation provides an SCA runtime that is itself built as an assembly of SCA components. It is modularized into a core and a set of SPIs that provides the flexibility of varying parts or whole of the runtime implementation.

Tuscany SCA Java provides a number of useful extensions (implementation type containers and transport / protocol extension bindings) that can be used to quickly assemble solutions around components implemented over different technologies. Here is a diagram showing the extensions available with SCA Java.

You will find information here on how to download Tuscany SCA Java, install it, build and run the samples, and develop Tuscany SCA Java applications.

Downloading the Release Files

See SCA Downloads for links to the downloadable archives for Tuscany SCA Java. Note: These archives all unpack into the current directory.

Installing the Binary Distribution

If you would like to run from a pre-built binary distribution, proceed as follows:

1. Download the binary distribution tuscany-sca-1.0-incubator-M2-bin.tar.gz or tuscany-sca-1.0-incubator-M2-bin.zip.
2. Create an empty directory and unpack the binary distribution into that directory.
3. In later sections of this document, we will refer to the directory that was created in step 2 (or built from source following the alternative instructions above) as (sca-home).

Building the Source Distribution

If you prefer to build the Tuscany SCA Java implementation from the source distribution, the procedure is as follows:

1. Download the implementation source distribution tuscany-sca-1.0-incubator-M2-src.tar.gz or tuscany-sca-1.0-incubator-M2-src.zip.
2. Create an empty directory and unpack the source distribution into that directory.
3. Follow the instructions in the BUILDING.txt file that was unpacked.

As part of the above build process, the SCA and commonj specification files will be downloaded as pre-built binaries from the remote maven repositories into your local maven repository.

Alternatively, you can build these specification binaries from source and install them in your local maven repository, as follows:

1. Download the SCA specification source distribution tuscany-spec-sca-r0.95-incubator-M2-src.tar.gz or tuscany-spec-sca-r0.95-incubator-M2-src.zip.
2. Create a new empty directory and unpack the source distribution into that directory.
3. Change directory to the newly created directory and run "mvn install". The SCA specification binary jar will be installed in your local maven repository.
4. Download the commonj specification source distribution tuscany-spec-commonj-1.1-incubator-M2-src.tar.gz or tuscany-spec-commonj-1.1-incubator-M2-src.zip.
5. Create a new empty directory and unpack the source distribution into that directory.
6. Change directory to the newly created directory and run "mvn install". The commonj specification binary jar will be installed in your local maven repository.

Checking Out and Building the Source

If you want to do a development build from the latest Tuscany SCA Java source tree in the subversion repository, you will need to check out and build the code. You'll need Subversion and Maven installed on your machine. For details of where to obtain these, see the Java project page. The following instructions are correct at the time of writing, but may change in the near future because of build restructuring.

Note: Maven automatically downloads project dependencies from remote repositories, so a live internet connection is required the first time a build is run. Because of load on the repository servers, you may experience occasional download failures. If these should occur, simply rerun the build.

1. Before building Tuscany SCA Java, you will previously need to have built Tuscany SDO Java. The SDO Java build installs the SDO jars in your local Maven repository (located by default in ${user.home}/.m2/repository ) from where they will be picked up when building the Tuscany SCA implementation. See SDO Java for details of how to do this.
2. Create an empty directory and cd to that directory.
3. Check out the SCA specifications Java source by running the command

    svn co http://svn.apache.org/repos/asf/incubator/tuscany/java/spec/sca/ spec/sca

4. cd to the spec/sca subdirectory and run "mvn" from this directory. This will install the SCA specifications jar in your local Maven repository from where it will be picked up when building the Tuscany SCA implementation.
5. cd back to the directory you created and check out the commonj specifications Java source by running the command

    svn co http://svn.apache.org/repos/asf/incubator/tuscany/java/spec/commonj/ spec/commonj

6. cd to the spec/commonj subdirectory and run "mvn" from this directory. This will install the commonj specifications jar in your local Maven repository from where it will be picked up when building the Tuscany SCA implementation.
7. cd back to the directory you created and check out the Tuscany SCA Java source by running the command

    svn co http://svn.apache.org/repos/asf/incubator/tuscany/java/sca/ sca

8. cd to the sca subdirectory and run "mvn" from this directory. This will install the Tuscany SCA Java jars in your local Maven repository. It also assembles a binary distribution in the "distribution" module under the sca directory.

Building and Running the Samples

To build and run the samples in the release distribution, proceed as follows.

1. Download the samples distribution tuscany-spec-sca-r0.95-incubator-M2-samples.tar.gz or tuscany-spec-sca-r0.95-incubator-M2-samples.zip.
2. Create a new empty directory and unpack the samples distribution into that directory.
3. Change directory to the newly created directory and run "mvn -N install". This will install the samples parent pom.xml file into your local maven repository.
4. Follow the instructions in the readme.html files for the various samples.

The SCA-related samples in the latest Tuscany Java source tree in the subversion repository have been divided into two categories:

• Sample applications that use a mix of SCA, SDO and DAS. See "Running the Samples" on the Java project page for details.
• Technology samples that illustrate specific technical features of SCA and show how they can be used by an application developer. These are in the java/samples/sca module.

Tuscany SCA Java M2 files available from maven

The following Tuscany SCA Java M2 files have been published to the public maven repository http://people.apache.org/repo/m2-incubating-repository/ and will be downloaded automatically by maven as needed.

 org/apache/tuscany/sca/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/apache/tuscany/sca/kernel/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/apache/tuscany/sca/kernel/tuscany-api/1.0-incubator-M2/tuscany-api-1.0-incubator-M2.jar
 org/apache/tuscany/sca/kernel/tuscany-host-api/1.0-incubator-M2/tuscany-host-api-1.0-incubator-M2.jar
 org/apache/tuscany/sca/kernel/tuscany-spi/1.0-incubator-M2/tuscany-spi-1.0-incubator-M2.jar
 org/apache/tuscany/sca/kernel/core/1.0-incubator-M2/core-1.0-incubator-M2.jar
 org/apache/tuscany/sca/test/1.0-incubator-M2/test-1.0-incubator-M2.jar
 org/apache/tuscany/sca/services/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/apache/tuscany/sca/services/idl/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/apache/tuscany/sca/services/idl/wsdl/1.0-incubator-M2/wsdl-1.0-incubator-M2.jar
 org/apache/tuscany/sca/services/containers/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/apache/tuscany/sca/services/containers/javascript/1.0-incubator-M2/javascript-1.0-incubator-M2.jar
 org/apache/tuscany/sca/services/containers/ruby/1.0-incubator-M2/ruby-1.0-incubator-M2.jar
 org/apache/tuscany/sca/runtime/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/apache/tuscany/sca/runtime/webapp/1.0-incubator-M2/webapp-1.0-incubator-M2.jar
 org/apache/tuscany/sca/services/containers/spring/1.0-incubator-M2/spring-1.0-incubator-M2.jar
 org/apache/tuscany/sca/services/databinding/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/apache/tuscany/sca/services/databinding/databinding-axiom/1.0-incubator-M2/databinding-axiom-1.0-incubator-M2.jar
 org/apache/tuscany/sca/services/databinding/databinding-sdo/1.0-incubator-M2/databinding-sdo-1.0-incubator-M2.jar
 org/apache/tuscany/sca/services/bindings/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/apache/tuscany/sca/services/bindings/axis2/1.0-incubator-M2/axis2-1.0-incubator-M2.jar
 org/apache/tuscany/sca/services/bindings/rmi/1.0-incubator-M2/rmi-1.0-incubator-M2.jar
 org/apache/tuscany/sca/services/maven/1.0-incubator-M2/maven-1.0-incubator-M2.jar
 org/apache/tuscany/sca/runtime/webapp-host/1.0-incubator-M2/webapp-host-1.0-incubator-M2.jar
 org/apache/tuscany/sca/runtime/standalone/1.0-incubator-M2/standalone-1.0-incubator-M2.jar
 org/apache/tuscany/sca/runtime/standalone-host/1.0-incubator-M2/standalone-host-1.0-incubator-M2.jar
 org/apache/tuscany/sca/commands/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/apache/tuscany/sca/commands/launcher/1.0-incubator-M2/launcher-1.0-incubator-M2.jar
 org/apache/tuscany/sca/sca-tools/1.0-incubator-M2/sca-tools-1.0-incubator-M2.jar
 org/apache/tuscany/sca/plugins/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/apache/tuscany/sca/plugins/tuscany-war-plugin/1.0-incubator-M2/tuscany-war-plugin-1.0-incubator-M2.jar
 org/apache/tuscany/sca/plugins/tuscany-plugin-wsdl2java/1.0-incubator-M2/tuscany-plugin-wsdl2java-1.0-incubator-M2.jar
 org/apache/tuscany/sca/plugins/tuscany-plugin-java2wsdl/1.0-incubator-M2/tuscany-plugin-java2wsdl-1.0-incubator-M2.jar
 org/apache/tuscany/sca/distribution/1.0-incubator-M2/distribution-1.0-incubator-M2.pom
 org/apache/tuscany/sca/distribution/1.0-incubator-M2/distribution-1.0-incubator-M2-bin.zip
 org/apache/tuscany/sca/distribution/1.0-incubator-M2/distribution-1.0-incubator-M2-bin.tar.gz
 org/apache/tuscany/sca/samples/parent/1.0-incubator-M2/parent-1.0-incubator-M2.pom
 org/osoa/sca-api-r0.95/1.0-incubator-M2/sca-api-r0.95-1.0-incubator-M2.jar
 org/apache/tuscany/commonj-api_r1.1/1.0-incubator-M2/commonj-api_r1.1-1.0-incubator-M2.jar

The Tuscany runtime is able to download dependent jars of Tuscany extensions from the maven repositories as needed.

Packaging a Standalone Tuscany Application

To package a Tuscany application for running in the standalone environment (i.e., not within a web application), the application must be packaged as a jar file with the following contents:

 META-INF/MANIFEST.MF
 META-INF/sca/default.scdl
 application executable code and resources

In the following instructions, we will refer to this application jar file as (executable-jar).

The MANIFEST.MF file must contain the following line:

 Main-Class: packagename.classname

This is the name of the main class to be run by the Tuscany standalone launcher.

The default.scdl file defines the SCA components whose implementations are in the jar file. See the SCA documentation and the Tuscany samples for details of how to write an SCDL file.

Running a Standalone Tuscany Application

To run a Tuscany application in the standalone environment, issue the following command:

 java -jar (sca-home)/bin/launcher.jar (executable-jar)

The standalone launcher initializes the Tuscany runtime, deploys any installed extensions (see below), creates components defined by the default.scdl file, and calls the main class of the application jar file (executable-jar).

Adding Extensions to the Standalone Environment

To add extensions to the standalone environment, you need to copy the required extension jars into the directory

 (sca-home)/extensions

The launcher for the standalone environment looks for this directory and deploys all the extension jars that it finds there.

Applications may need a combination of extensions, and some extensions may depend on other extensions. For example, the helloworldwsclient sample needs the following extensions to be present in the extensions directory:

 axis2-1.0-incubator-M2.jar
 databinding-sdo-1.0-incubator-M2.jar

These extensions will load their required dependencies from the maven repository. The required dependencies are:

 databinding-axiom-1.0-incubator-M2.jar
 wsdl-1.0-incubator-M2.jar

Building a Tuscany Web Application

To package a Tuscany application for running in a web application container such as Apache Tomcat, the application must be packaged as a war file with some Tuscany-specific contents.

If you are buildng a Tuscany war file using maven, Tuscany provides a maven plugin

 org/apache/tuscany/sca/plugins/tuscany-war-plugin/1.0-incubator-M2/tuscany-war-plugin-1.0-incubator-M2.jar

that performs this packaging. It is downloaded automatically from the maven repository when invoked by a pom.xml. For an example of how to create a pom.xml file that uses this plugin, see the pom.xml file for the webapp/calculatorws sample. Within this pom.xml file, you will see the line

 <loadExtensionDependencies>false</loadExtensionDependencies>

This instructs the Tuscany maven war plugin to create a war file that does not include dependent jar files of Tuscany extensions. Instead, these jar files will be loaded on demand by the Tuscany runtime. If the value of this element is set to true, then the Tuscany maven war plugin will bundle all required dependent jar files within the war file.

If you are not using maven to build a Tuscany war file, then you will need to ensure that the following files are included in the war file:

The <web-app>...</webapp> section of the WEB-INF/web.xml file must contain the following code:

 <listener>
    <listener-class>org.apache.tuscany.runtime.webapp.TuscanyContextListener</listener-class>
 </listener>
 <servlet>
    <servlet-name>TuscanyServlet</servlet-name>
    <display-name>Tuscany Servlet</display-name>
    <servlet-class>org.apache.tuscany.runtime.webapp.TuscanyServlet</servlet-class>
 </servlet>
 <servlet-mapping>
    <servlet-name>TuscanyServlet</servlet-name>
    <url-pattern>/services/*</url-pattern>
 </servlet-mapping>

For runtime loading of dependent jars (see the description of the <loadExtensionDependencies> element above), the WEB-INF/tuscany/repository/dependency.metadata file must contain the following code:

 <?xml version="1.0" encoding="UTF-8"?>
 <java version="1.5.0_06" class="java.beans.XMLDecoder">
  <object class="java.util.HashMap"/>
 </java>

If these dependent jars are packaged within the web application's WEB-INF/tuscany/repository/ directory, please refer to the output of the Tuscany war plugin (with <loadExtensionDependencies> set to true) to see what code needs to be included within the WEB-INF/tuscany/repository/dependency.metadata file.

For Further Information

If you have any questions about installing, building, or running Tuscany SCA Java M2 that are not answered here, please post them to either the tuscany-user@ws.apache.org list (for end-user questions) or the tuscany-dev@ws.apache.org list (for developer questions).