Appendix A. Setting up
This chapter is a hands-on guide for getting you started with Tuscany and the examples that are used in this book. Here we’ll talk about how to install Tuscany and set up the environment necessary to run and test the book examples and to develop your own SCA applications. We also give a brief overview of the Tuscany project so that you can navigate the website and interact with the Tuscany community.
A.1. Installing Tuscany
Installing Tuscany is simple: Download a Tuscany release and a Java JDK. The JDK is used to compile and run Java programs. Let’s get started by first getting the Tuscany prerequisites.
A.1.1. Getting Tuscany’s prerequisites
Running Tuscany SCA Java 1.x is dependent on JDK version 5.0 or later. The Tuscany samples can be run out of the box with Apache Ant and Apache Maven. To set up a development environment and run samples, follow these steps:
1. Download and install Java Development Kit (JDK) version 5 or later.
2. Download and install Apache Ant version 1.7.1 or later.
3. Download and install Apache Maven version 2.0.7 or later.
Now that you have the Tuscany prerequisites in place, you’ll install Tuscany itself.
A.1.2. Downloading and installing Tuscany
Download Tuscany SCA Java 1.6 (or a later 1.x release) from the following web page: http://tuscany.apache.org/sca-java-1x-releases.html. This page contains the binary and source distributions of Tuscany SCA Java. For now, download the binary distribution for your platform. This contains a compiled version of the Tuscany core and extension JARs that are ready to be run. At a later point, if you want to examine the Tuscany source code or make changes to it, you can download the source code distribution that contains all the Tuscany source code.
Once you’ve downloaded the Tuscany binary distribution, you’ll need to expand it. Figure A.1 shows the expanded Tuscany binary distribution when unpacked to the C: directory on Windows.
Figure A.1. The expanded Tuscany binary distribution on Windows
The Tuscany binary distribution contains the directories shown in table A.1.
Table A.1. The contents of the Tuscany binary distribution
|
Path |
What it contains |
|---|---|
| /modules | The Tuscany core and extension JARs |
| /lib | The third-party software that Apache Tuscany requires, and a manifest JAR that pulls together the third-party dependencies and Tuscany module JARs to make constructing the runtime classpath straightforward |
| /samples | Samples that demonstrate some of the features of Tuscany and SCA |
| /demos | More complex applications that bring together Tuscany features into working applications |
| /tutorials | An example based on an e-business website selling fruit and vegetables |
The binary distribution doesn’t include Javadoc. There’s some Javadoc available on the Tuscany website at http://tuscany.apache.org/doc/javadoc/.
Now that you’ve expanded the binary distribution, let’s test the Tuscany installation.
A.1.3. Testing the Tuscany installation
It’s a good idea to use a simple sample to verify that Tuscany works properly in your environment before moving on to developing applications. The calculator sample is ideal for this because it’s a very simple SCA application.
The calculator sample can be found in the samples/calculator directory. To run the sample with Ant, change into this directory and type
ant run
Assuming that Apache Ant has been installed correctly and is on your path, you’ll see output similar to the following:
C: uscany-sca-1.6samplescalculator>ant run
Buildfile: build.xml
run:
[java] 14-Jan-2010 19:34:28 org.apache.tuscany.sca.node.impl.NodeImpl
<init>
[java] INFO: Creating node: Calculator.composite
[java] 14-Jan-2010 19:34:29 org.apache.tuscany.sca.node.impl.NodeImpl
configureNode
[java] INFO: Loading contribution: file:/C:/tuscany-sca-1.6/
samples/calculator/target/sample-calculator.jar
[java] 14-Jan-2010 19:34:31 org.apache.tuscany.sca.node.impl.NodeImpl
start
[java] INFO: Starting node: Calculator.composite
[java] 3 + 2=5.0
[java] 3 - 2=1.0
[java] 3 * 2=6.0
[java] 3 / 2=1.5
[java] 14-Jan-2010 19:34:31 org.apache.tuscany.sca.node.impl.NodeImpl
stop
[java] INFO: Stopping node: Calculator.composite
BUILD SUCCESSFUL
Total time: 3 seconds
If the calculator sample doesn’t work for you, take a look at section A.4, which gives some hints on how to troubleshoot the Tuscany installation. If you still can’t get the simple calculator sample to work, you can get help from the Tuscany community by posting the issue that you are seeing on the mailing list. See section A.3 for how to do this.
A.1.4. SCA samples provided with Tuscany
A good way to become familiar with Tuscany is to look at the samples that are bundled with the Tuscany distribution. These are small applications that demonstrate specific SCA and Tuscany features. They’re ready to be compiled and run using Ant or Maven. Each sample is accompanied by a README file that explains what the sample does and how to run it. These samples should help you to learn the basics of developing and running SCA applications.
The Tuscany website contains some useful resources that will walk you through getting started with Tuscany. For example, the following link walks you through how to build the Tuscany calculator sample using command-line tools: http://tuscany.apache.org/getting-started-with-tuscany-using-the-command-line.html.
So far we’ve used Tuscany from the command line. Next we’ll look at how Tuscany can be used from an IDE.
A.1.5. Setting up your Java IDE
You can develop SCA applications using your favorite IDE. If you’re using Eclipse, you can import Tuscany samples into Eclipse using three alternative approaches: using Maven’s Eclipse plug-in, manually without using Maven, and using Eclipse’s Maven plug-in. An article at http://tuscany.apache.org/import-existing-tuscany-sca-projects-into-eclipse.html describes these approaches. For developing a new Tuscany application using Eclipse, you can find a step-by-step tutorial at http://tuscany.apache.org/getting-started-with-tuscany.html. A similar approach should also work with other Java IDEs.
A.2. Installing the examples for this book
All of the examples in this book come from the Tuscany SCA Java Travel Sample (hereafter referred to as the travel sample). The code in the travel sample implements the travel-booking application that we’re using in this book. The book chapters configure different components of this application in different ways to demonstrate the various features of SCA and Apache Tuscany.
A.2.1. Downloading the travel sample
You can download the travel sample 1.0 (or later) release from the following web page:
Download the distribution and extract the artifacts from the archive into a directory on your hard drive. The directory path must not contain any spaces. Then you can use Maven to compile all the sample source code by entering the following:
cd the_directory_containing_the_sample
mvn
Alternatively, you can compile the source code using Ant by entering the following:
cd the_directory_containing_the_sample
ant
If you’re using Ant to compile the source, you’ll first need to set the TUSCANY_HOME environment variable, as described in section A.2.2.
A.2.2. Setting the TUSCANY_HOME environment variable
The samples in this book require the Tuscany SCA Java runtime. To specify its location for use when running the samples, you need to set the TUSCANY_HOME environment variable. For example, on Windows, enter the following:
set TUSCANY_HOME=c: uscany-sca-1.6
On Linux, enter the following:
export TUSCANY_HOME=$HOME/tuscany-sca-1.6
Now that the travel sample knows where to find the Tuscany runtime, let’s try running some sample code.
A.2.3. Testing the travel sample installation
To make sure that the travel sample has been installed and built successfully, let’s run a simple example from it. Assuming that you are using Windows, the command would look like the following:
cd travelsamplelaunchersjumpstart
ant run
This example will send a request to the TripProvider component asking for availability of a packaged trip called FS1APR4. If the example runs properly, you should see the following result included in the output on your screen:
Trip booking code = 6R98Y
If you’re not seeing this output, refer to section A.4 for troubleshooting.
A.2.4. Travel sample structure
The main directories in the travel sample are listed in table A.2.
Table A.2. Main directories in the travel sample
|
Directory |
Contents |
|---|---|
| binaries | Maven scripts for producing a complete set of runtime binary artifacts for the travel sample |
| clients | Used to show how non-SCA clients can connect to SCA services |
| contributions | SCA contributions that make up the travel sample |
| distribution | Maven scripts for building the sample distribution |
| domainconfig | The domain manager configuration files used in chapters 3 and 12 |
| launchers | Launchers for running the various elements of the travel sample |
| services | Used to show how SCA references can connect to non-SCA services |
| testdomain | A test directory where you can run the domain manager and experiment with configuration |
| util | Utility code and runtime dependencies for the travel sample |
The various contributions of the travel sample can be found in the contributions directory. Each chapter in the book identifies which contribution to look at when a sample is referenced.
To run a sample you’ll need to use a launcher from the launchers directory. In some cases the launcher name matches the contribution name that it loads and runs. This isn’t always true, though—for example, the fullapp launcher runs the complete travel-booking application and so loads multiple contributions.
The clients and services directories provide external non-SCA client and service programs to demonstrate various SCA bindings. Typically the client programs call an SCA service, so you’ll run a launcher first followed by the client program. The external services are called by an SCA service, so you run the service program first followed by the launcher.
The binaries directory is used to build a self-contained executable set of runtime binary artifacts for the travel sample. This demonstrates how a Tuscany application can be packaged and distributed to end users in binary executable form.
Detailed information about the structure and contents of the travel sample can be found in the travel sample’s README file. This file includes a complete list of the launchers and instructions on how to run them.
A.2.5. Using a Java IDE with the travel sample
You can use a Java IDE to run the code in the travel sample. If you’re using Eclipse, see http://tuscany.apache.org/import-existing-tuscany-sca-projects-into-eclipse.html for a detailed description of the steps that you need to follow. It’s important to import the travel sample code into Eclipse without copying it into the Eclipse workspace, because copying it would change the directory structure and cause problems with some of the code.
A.3. Interacting with the Tuscany project and community
Since its inception, Apache Tuscany has gained a large global community of users and developers with different business requirements and a varying depth of understanding of Tuscany and SCA. Members of this community communicate with one another via the Tuscany mailing lists. Please feel welcome to use the mailing list to ask any questions and get involved in the community.
Tuscany has three main mailing lists, and anyone can subscribe to these lists. Each list has a different purpose, so we’ll briefly describe them:
- User mailing list— Subscribers to this mailing list are typically Tuscany users and Tuscany software developers. This mailing list is used for discussing usage scenarios and questions related to using Tuscany. Tuscany releases are announced on this list and the developer mailing list.
- Developer mailing list— Subscribers are typically Tuscany software developers (core and extension developers). Some users may be interested in watching these discussions because they’re related to the ongoing development of the Tuscany runtime and its extensions.
- Commits mailing list— Subscribers are typically Tuscany software developers. Code commit notifications and automated test run results are published to this mailing list.
You can subscribe to any of these mailing lists by going to the Tuscany mailing lists page: http://tuscany.apache.org/mailing-lists.html.
To subscribe to a particular mailing list, click the appropriate link. Once subscribed, you’ll see email exchanges related to that mailing list, and you can post to the list. You can unsubscribe at any time by going to the same Tuscany mailing lists page and clicking the Unsubscribe link.
- To post to the user mailing list, use the email address [email protected].
- To post to the developer mailing list, use the email address [email protected].
Note that you can send an email to [email protected] without being subscribed to the user list. The disadvantage of this approach is that you won’t see all the other users’ questions and answers.
You can also watch the activity on the mailing lists by browsing one of the mailing list archives that are listed on the Tuscany mailing lists page. The archive is read-only, and you can’t respond to any of the email threads.
Tuscany values user feedback, and the community’s goal is to build solutions that solve real IT problems. Please use the mailing lists to share feedback, to contribute, or to suggest new ideas regarding Tuscany. We look forward to talking with you.
A.4. Troubleshooting
If you’ve tried various options, and you’re unable to run an example or your own application, there are several steps that you can take:
1. Check the mailing list archives at http://tuscany.apache.org/mailing-lists.html to see if another user detected the same problem.
2. Check the Tuscany JIRA bug database to see if the problem has already been reported and if a patch is available. Go to http://issues.apache.org/jira/browse/TUSCANY, click the Find Issues tab at the top, and then select Tuscany in the project box on the left panel. Enter your query in the Text Search box on the left panel. Click the View button to get the list of reported problems.
3. If you can’t find your answer, post your question on the Tuscany user mailing list including any error messages, information about the Tuscany release you are using, the environment, a pointer to the example or your code sample, and the behavior that you’re seeing. Someone from the community will respond to your post.
4. If this turns out to be a bug, you can report it on the Tuscany JIRA bug database at http://issues.apache.org/jira/browse/TUSCANY by creating a new bug.
Please feel free to post the problem on the Tuscany user mailing list to discuss the issue and seek a workaround. When posting on the mailing list, it’s good practice to share what you have researched and found thus far.