diff options
Diffstat (limited to 'sca-java-2.x/trunk/samples/README')
| -rw-r--r-- | sca-java-2.x/trunk/samples/README | 323 |
1 files changed, 99 insertions, 224 deletions
diff --git a/sca-java-2.x/trunk/samples/README b/sca-java-2.x/trunk/samples/README index 43b7cb3056..243d021d37 100644 --- a/sca-java-2.x/trunk/samples/README +++ b/sca-java-2.x/trunk/samples/README @@ -1,202 +1,119 @@ 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: +Welcome to the Apache Tuscany SCA Java runtime. You can find more general +documentation about the runtime at: -cd <sampledir> -ant run +http://tuscany.apache.org/documentation-2x/. -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. +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: -If you want to rebuild a sample, for example, if you have changed it, do the -following: +http://tuscany.apache.org/documentation-2x/samples-beta1 -cd <sampledir> -ant compile +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 -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. +learning-more +============= -The compile target builds the class files and then builds the jar so you can use -the same command as before: +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. -ant run +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 +organizes 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. -This will use the generated jar to run the samples. The command line version of -this is: +The contributions here can be run with using the approach that you find +most convenient from the running-tuscany directory. -on Windows +running-tuscany +=============== -java -cp ..\..\features\tuscany-sca-manifest.jar;target\<sample jar file> <sample runnable class> +The Tuscany SCA Java runtime is designed to be both embedded in other programs +and used as it directly. 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. -for example : java -cp ..\..\features\tuscany-sca-manifest.jar;target\sample-calculator.jar calculator.CalculatorClient +applications +============ -on *nix +The contributions here demonstrate more fully formed applications when +compared to the contributions found the getting-started or +learning-more directories. -java -cp ../../features/tuscany-sca-manifest.jar:target/<sample jar file> <sample runnable class> +extending-tuscany +================= -for example : java -cp ../../features/tuscany-sca-manifest.jar:target/sample-calculator.jar calculator.CalculatorClient +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 +--------------- -You can use the compiled classes directly using +Running a samples contribution involves 3 basic steps -ant run-classes +1) build the contribution -The command line version of this is: +Using ant, maven or eclipse (see below) -on Windows +2) launch the contribution -java -cp ..\..\features\tuscany-sca-manifest.jar;target\classes <sample runnable class> +Using one of the approaches described in the running-tuscany directory -for example : java -cp ..\..\features\tuscany-sca-manifest.jar;target\classes calculator.CalculatorClient +3) send a test message to the a component service -on *nix +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. -java -cp ../../features/tuscany-sca-manifest.jar:target/classes <sample runnable class> +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. -for example : java -cp ../../features/tuscany-sca-manifest.jar:target/classes calculator.CalculatorClient +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. -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. +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. -Building And Running The SCA Samples Using Maven ------------------------------------------------- +Once the sample is built you have the option of running the sample in whatever +way best suits you. -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. +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 sca +cd <sampledir> mvn This will take a little while to complete. Experience with Maven tells us that @@ -204,66 +121,24 @@ 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. +When using Maven the samples are unit tested using JUnit test cases and so you +will sometimes see test output during the build process. -cd <sampledir> -mvn +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. -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. +Building Samples In An IDE +--------------------------- -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. +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 imports SCA contribution projects into Eclipse are +documented at: +http://tuscany.apache.org/import-existing-tuscany-sca-projects-into-eclipse.html |