samples/README - tuscany-sca-2.x - Git at Google

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

 New Samples Structure
 ---------------------

 For the Milestone 5 release of Tuscany SCA Java 2.x we are beginning
 the process of moving to a new structure for samples. Milestone 5 is
 delivered in a state of partial change over to this new emphasis, and hence
 this README reflects that hybrid state.

 There are primarily 3 types of sample; those which focus on pure SCA
 concepts, those which demonstrate features of Tuscany and the last group
 is of samples which give a flavour of more complete, realistic applications.

 The new structure primarily focusses separating contributions from the way that
 contributions are launched. The samples demonstrate the way in which contributions are used by
 launchers to execute tuscany SCA applications.

 In this way you can explore the samples by chosing which launcher you wish
 to invoke which contribution. In the old style of sample this distinction was not clear;
 any given sample contained both launcher and contribution, and the set of samples provided
 represented a small subset of the combinations possible by the new approach.

 Within the SCA category of samples, most of the calculator samples, have been
 migrated to this new structure as follows.

 SCA Samples
   binding-rmi-calculator
     contribution-calculator-reference
     contribution-calculator-service
   binding-sca
     contribution-calculator
   contribution-binding-ws-calculator
   contribution-implementation-java-calculator
   calculator-sca-client
   launcher-command-line
   launcher-embedded-jse
   launcher-embedded-osgi
   launcher-mvn

 Please visit the 2.x documentation in our  website [1] to get a better understanding of SCA
 and Tuscany 2.x

 Running the New Style samples
 -----------------------------

 To run a new style sample there are 3 basic steps

 1) build the contribution: using either the command "mvn", "ant run" or your usual steps to build a
    module in your IDE
 2) unit test the contribution: if you used mvn or ant in step 1 then you will already have done this;
    if you used an IDE follow your usual steps to run the unit test in the contribution's module
 3) launch the contribution: go to one of the launcher* subdirectories of the samples root directory
    and follow the instructions there to use a launcher to launch your chosen contribution

 I the case where you want to exercise the sample contribution with a separate client program, such as
 an application using the SCA client API then there is a 4th step of starting that client application

 [1] http://tuscany.apache.org/documentation-2x/

 Running the Old Style 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 Layout
 -------------
 Generally 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.1                - if you are going to use Ant
 Apache Maven 2.0.9              - 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 ..\..\features\tuscany-sca-manifest.jar;target\<sample jar file> <sample runnable class>

 for example : java -cp ..\..\features\tuscany-sca-manifest.jar;target\sample-calculator.jar calculator.CalculatorClient

 on *nix

 java -cp ../../features/tuscany-sca-manifest.jar:target/<sample jar file> <sample runnable class>

 for example : java -cp ../../features/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 ..\..\features\tuscany-sca-manifest.jar;target\classes <sample runnable class>

 for example : java -cp ..\..\features\tuscany-sca-manifest.jar;target\classes calculator.CalculatorClient

 on *nix

 java -cp ../../features/tuscany-sca-manifest.jar:target/classes <sample runnable class>

 for example : java -cp ../../features/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

 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.
         launcher-embedded-jse
     Import all of the sample code and resources into this project, e.g.
         File, Import and then select tuscany-sca-1.0-incubating\samples\launcher-embedded-jse from the filesystem
     Configure the source path to include
         src/main/java
         src/main/resources
     Configure the output folder to be
         target
     Configure the build path to include the manifest jar tuscany-sca-manifiest.jar provided in
         features
      For here you have run;
         the unit test  (loads a sequence of contributions and runs them)
         SampleJSELauncher (you'll need to add the name of the contribution to run as a parameter)
         build.xml (you'll need to set tuscany.home to point to distribution\all\target\apache-tuscany-sca-all-2.0-SNAPSHOT.dir\tuscany-sca-2.0-SNAPSHOT)

 The details of how to do this for other development environments will
 vary but the process will be similar.
	The Apache Tuscany SCA Samples
	==============================

	New Samples Structure
	---------------------

	For the Milestone 5 release of Tuscany SCA Java 2.x we are beginning
	the process of moving to a new structure for samples. Milestone 5 is
	delivered in a state of partial change over to this new emphasis, and hence
	this README reflects that hybrid state.

	There are primarily 3 types of sample; those which focus on pure SCA
	concepts, those which demonstrate features of Tuscany and the last group
	is of samples which give a flavour of more complete, realistic applications.

	The new structure primarily focusses separating contributions from the way that
	contributions are launched. The samples demonstrate the way in which contributions are used by
	launchers to execute tuscany SCA applications.

	In this way you can explore the samples by chosing which launcher you wish
	to invoke which contribution. In the old style of sample this distinction was not clear;
	any given sample contained both launcher and contribution, and the set of samples provided
	represented a small subset of the combinations possible by the new approach.

	Within the SCA category of samples, most of the calculator samples, have been
	migrated to this new structure as follows.

	SCA Samples
	binding-rmi-calculator
	contribution-calculator-reference
	contribution-calculator-service
	binding-sca
	contribution-calculator
	contribution-binding-ws-calculator
	contribution-implementation-java-calculator
	calculator-sca-client
	launcher-command-line
	launcher-embedded-jse
	launcher-embedded-osgi
	launcher-mvn

	Please visit the 2.x documentation in our website [1] to get a better understanding of SCA
	and Tuscany 2.x

	Running the New Style samples
	-----------------------------

	To run a new style sample there are 3 basic steps

	1) build the contribution: using either the command "mvn", "ant run" or your usual steps to build a
	module in your IDE
	2) unit test the contribution: if you used mvn or ant in step 1 then you will already have done this;
	if you used an IDE follow your usual steps to run the unit test in the contribution's module
	3) launch the contribution: go to one of the launcher* subdirectories of the samples root directory
	and follow the instructions there to use a launcher to launch your chosen contribution

	I the case where you want to exercise the sample contribution with a separate client program, such as
	an application using the SCA client API then there is a 4th step of starting that client application

	[1] http://tuscany.apache.org/documentation-2x/

	Running the Old Style 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 Layout
	-------------
	Generally 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.1 - if you are going to use Ant
	Apache Maven 2.0.9 - 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 ..\..\features\tuscany-sca-manifest.jar;target\<sample jar file> <sample runnable class>

	for example : java -cp ..\..\features\tuscany-sca-manifest.jar;target\sample-calculator.jar calculator.CalculatorClient

	on *nix

	java -cp ../../features/tuscany-sca-manifest.jar:target/<sample jar file> <sample runnable class>

	for example : java -cp ../../features/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 ..\..\features\tuscany-sca-manifest.jar;target\classes <sample runnable class>

	for example : java -cp ..\..\features\tuscany-sca-manifest.jar;target\classes calculator.CalculatorClient

	on *nix

	java -cp ../../features/tuscany-sca-manifest.jar:target/classes <sample runnable class>

	for example : java -cp ../../features/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

	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.
	launcher-embedded-jse
	Import all of the sample code and resources into this project, e.g.
	File, Import and then select tuscany-sca-1.0-incubating\samples\launcher-embedded-jse from the filesystem
	Configure the source path to include
	src/main/java
	src/main/resources
	Configure the output folder to be
	target
	Configure the build path to include the manifest jar tuscany-sca-manifiest.jar provided in
	features
	For here you have run;
	the unit test (loads a sequence of contributions and runs them)
	SampleJSELauncher (you'll need to add the name of the contribution to run as a parameter)
	build.xml (you'll need to set tuscany.home to point to distribution\all\target\apache-tuscany-sca-all-2.0-SNAPSHOT.dir\tuscany-sca-2.0-SNAPSHOT)

	The details of how to do this for other development environments will
	vary but the process will be similar.