summaryrefslogtreecommitdiffstats
path: root/sca-java-2.x/contrib/samples/README
diff options
context:
space:
mode:
Diffstat (limited to 'sca-java-2.x/contrib/samples/README')
-rw-r--r--sca-java-2.x/contrib/samples/README154
1 files changed, 154 insertions, 0 deletions
diff --git a/sca-java-2.x/contrib/samples/README b/sca-java-2.x/contrib/samples/README
new file mode 100644
index 0000000000..15736845da
--- /dev/null
+++ b/sca-java-2.x/contrib/samples/README
@@ -0,0 +1,154 @@
+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