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

Welcome to the Apache Tuscany SCA Java runtime. You can find more general 
documentation about the runtime at:

http://tuscany.apache.org/documentation-2x/ 

Here we give a short overview of what you can find in the samples directory. 
More detail on the individual sample contributions can be found at:

http://tuscany.apache.org/documentation-2x/20-beta-samples-documentation.html

There are several samples subdirectories in the distribution; 
  
getting-started
===============
     
This is a good place to start if you've not tried Tuscany SCA Java before. This 
directory contains a number of simple "SCA Contributions" that can be run using 
the Tuscany SCA runtime. An SCA Contribution is the way that SCA composite
applications are packaged so they can be run. For general information on SCA
see http://tuscany.apache.org/documentation-2x/sca-introduction.html

learning-more
=============

This directory contains many more SCA Contributions that you can try with 
the Tuscany SCA Java runtime. Some demonstrate particular features of the 
runtime, or example, the contributions under the async directory demonstrate
the asynchronous programming model that the runtime supports. 

SCA is extensible. You can plug in extensions to support many different types
of technology. The Tuscany SCA Java runtime comes with lots of extensions
and the majority of contributions here demonstrate these extensions. They are
organized under directories following the name of the extension, for example, 
contributions that demonstrate the web services binding in operation can
be found in the binding-ws directory. When you want to use the web service
binding with an SCA service a reference it appears in the composite XML in 
the following way:

<service>
  <binding.ws/>
</service> 

Hence it should be easy to map between extensions, as they appear in 
composite files and other samples that demonstrate various features of the 
extension. 

The contributions here can be run with using the approach that you find
most convenient from the running-tuscany directory. 

running-tuscany
===============

The Tuscany SCA Java runtime can be used directly from the command line. It can
also be embedded in other programs. As such there are many different ways that 
you can start the Tuscany SCA runtime and deploy contributions to it. Each 
directory here describes a different way of running Tuscany. In most cases these 
different approaches can be used to run any of the contributions from the 
getting-started or learning-more directories.

applications
============

The contributions here demonstrate more fully formed applications when 
compared to the contributions found the getting-started or learning-more 
directories.

extending-tuscany
=================

Once you're familiar with Tuscany and SCA you're likely to find that to 
implement you're application you need particular bindings, implementation 
types, policies or databindings. The examples in this directory show you
how to extend the Tuscany runtime to include the technologies you need to use.

Running samples
---------------

Running a samples contribution involves 3 basic steps

1) build the contribution

Using ant, maven or eclipse (see below)

2) launch the contribution

Using one of the approaches described in the running-tuscany directory

3) send a test message to the a component service 

When you want to exercise an SCA composite application you have to send a 
message to a component service. There are several ways of doing this depending
on how the sample contribution has been configured. For example, you could
send a SOAP message using the Web Services explorer in Eclipse, you could 
use a separate client program that uses the SCA client API, the sample
contribution itself may even include initialization code that sends a test
message when the contribution is started. The documentation for each sample
describes what to do to send a test message.  

Building the sample contributions using Ant
--------------------------------------------
Most sample contributions are provided with a build.xml file. When you see one
you can build it using Ant. 

These build.xml files are designed to work with the Tuscany SCA Java binary
distribution and build a classpath that, by various means, refers to the 
jars that are shipped in the modules directory. For them to work properly
they should be run from the directory in which you find the build.xml file. 

cd <sampledir>
ant

The result of this process will be the built contribution (a jar file) in the 
target subdirectory of the sample contribution directory. 

Once the sample is built you have the option of running the sample in whatever 
way best suits you.  

Building SCA Samples Using Maven
--------------------------------
All sample contributions are provided with a pom.xml Maven build file. The 
Maven build process will work from both source and binary distributions. 

cd <sampledir>
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. 

When using Maven the samples are unit tested using JUnit test cases and so you 
will sometimes see test output during the build process.  

The result of this process will be the built contribution (a jar file) in the 
target subdirectory of the sample contribution directory. 

Once the sample is built you have the option of running the sample in whatever 
way best suits you. 

Building 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. You don't have to do this 
though and can use a series of manual steps in order to import the Tuscany
samples into an IDE. 

Both approaches to importing SCA contribution projects into Eclipse are 
documented at:

http://tuscany.apache.org/import-existing-tuscany-sca-projects-into-eclipse.html