blob: 15736845dad05919d7ce178c0b35c441de42a77c [file] [log] [blame]
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