1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
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.
|
