Move Tuscany from Incubator to top level.

git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@668359 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 309 insertions, 0 deletions

diff --git a/branches/sca-java-1.2.1/samples/README b/branches/sca-java-1.2.1/samples/README
new file mode 100644
index 0000000000..e4c2bcf7fb
--- /dev/null
+++ b/branches/sca-java-1.2.1/samples/README
@@ -0,0 +1,309 @@
+The Apache Tuscany SCA Samples
+==============================
+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-notification-broker        - A broker for notificatione
+binding-notification-consumer      - A consumer of notifications
+binding-notification-producer      - A producer of notifications
+
+calculator                         - Calculator built with java components and 
+                                     local wires. 
+calculator-distributed             - A calculator built using SCA nodes running 
+                                     on multiple JVMs
+calculator-implementation-policies - Shows logging policites associated with 
+                                     SCA implementations
+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
+calculator-script                  - Calculator built using various script languages
+calculator-webapp                  - Calculator running inside a web app
+calculator-ws-webapp               - Calculator running inside a web app also 
+                                     showing webservices binding
+
+callbck-ws-client                  - The client for showing callbacks across web services
+callback-ws-service                - The server for showing callbacks across web serviced
+
+chat-webapp                        - A simple chat style web app demonstrating
+                                     use of AJAX binding
+
+databinding-echo                   - An SCA application that shows how databindings 
+                                     transform data
+                    
+feed-aggregator                    - Demonstrates using the ATOM binding
+feed-aggregator-webapp             - feed-aggregator running in webapp
+
+helloworld-bpel                    - Demonstrates an SCA component invoking a BPEL 
+                                     process in a composition
+
+helloworld-dojo-webapp             - An SCA application that exposes a service using 
+                                     JSONRPC and a client using the Dojo toolkit
+helloworld-jsonrpc-webapp          - helloworld using jsonrpc binding
+helloworld-ws-reference            - The client side of a hello world sample that uses a 
+                                     web service binding (requires helloworld-ws-service)
+helloworld-ws-service              - The server side of a hello world sample that uses a 
+                                     web service binding
+helloworld-ws-reference-jms        - The client side of a hello world sample that uses a 
+                                     web service binding with SOAP/JMS (requires 
+                                     helloworld-ws-service)
+helloworld-ws-service-jms          - The server side of a hello world sample that 
+                                     uses a web service binding with SOAP/JMS
+helloworld-ws-reference-secure     - The client side of a hello world sample that 
+                                     shows how policy intent can be used.
+helloworld-ws-service-secure       - The client side of a hello world sample that 
+                                     shows how policy intent can be used.
+helloworld-ws-sdo                  - helloworld using ws binding and SDO
+helloworld-ws-sdo-webapp           - helloworld using ws binding and SDO within a webapp
+
+implementation-composite           - Shows how SCA composites are used 
+                     
+osgi-supplychain                   - SCA asynchronous API with OSGi and Java 
+                                     implementation types
+
+quote-xquery                       - Demonstrate SCA components using XQuery
+
+simple-bigbank                     - A banking application built with java components 
+                                     and local wire
+simple-bigbank-spring              - A banking application showing how SCA works with Spring
+
+simple-callback                    - demonstrates the callback interface
+simple-callback-ws                 - demonstrates use of callback interface across WS binding
+
+store                              - Step by step guide for creating an online store
+
+supplychain                        - shows how asynchronous callbacks can be used
+
+web-resource                       - Demonstrates using an SCA Web resource component
+
+
+Samples for building extensions
+-------------------------------
+There are samples that demonstrate how to build extensions for the 
+Tuscany SCA runtime. These samples are slightly different from the samples
+above in that the provided code is concerned with building the extension
+and not with building an application that uses it. The application
+that shows how the new extension can be used is provided in an associated
+sample. 
+
+implementation-crud-extension - Shows how to build new implementation type 
+                                extensions
+implementation-crud           - A sample application that exercises the new 
+                                implementation extensions
+binding-echo-extension        - Shows how to build new binding extensions
+binding-echo                  - A sample application that exercises the new 
+                                binding extension
+implementation-notifiaction   - Illustrates the use of <implementation.notification/>
+implementation-pojo-extension - shows how new implementation types are constructed 
+implementation-pojo           - A sample application that exercises the new 
+                                implementation type
+
+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.0                - if you are going to use Ant 
+Apache Maven 2.0.6              - 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 ..\..\lib\tuscany-sca-manifest.jar;target\<sample jar file> <sample runnable class>
+
+for example : java -cp ..\..\lib\tuscany-sca-manifest.jar;target\sample-calculator.jar calculator.CalculatorClient
+
+on *nix 
+
+java -cp ../../lib/tuscany-sca-manifest.jar:target/<sample jar file> <sample runnable class>
+
+for example : java -cp ../../lib/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 ..\..\lib\tuscany-sca-manifest.jar;target\classes <sample runnable class>
+
+for example : java -cp ..\..\lib\tuscany-sca-manifest.jar;target\classes calculator.CalculatorClient
+
+on *nix 
+
+java -cp ../../lib/tuscany-sca-manifest.jar:target/classes <sample runnable class>
+
+for example : java -cp ../../lib/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 eclipse:eclipse  
+
+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 all of the jars provided in
+        lib
+     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. 
+
+