h1. Getting Started with Tuscany using the Command Line
This guide takes a command line based approach to getting started with Apache Tuscany Java SCA. For the Eclipse users amongst us there are other [guides|Java SCA Documentation Menu] that show how to install the distribution into Eclipse or how to exploit Tuscany SCA Java using the Eclipse plugin that is has been built as part of the project. This article however just uses the downloaded Tuscany SCA Java distribution, Java, Maven or Ant and the command line. So if you want to feel close to the action this is where to start!
Tuscany ships with a number of samples. One of the most straightforward of these is the calculator sample. We will use this to make sure that you installing is working properly. As the name indicates, this example performs typical calculator operations. It is given two numbers and asked to perform an operation on them. Our calculator will handle add, subtract, multiply and divide.
First of all we will walk through running the calculator sample to make sure you installation is working correctly. Then we will walk through the steps taken to implement the calculator sample in the first place. Following this you should be familiar with how to build a basic SCA application that runs in a single, stand-alone, SCA runtime. The next step is to update the sample to use some of the other Tuscany SCA java extensions. Finally we will use the calculator sample to show you how you can build a distributed Service Oriented Architecture using Tuscany SCA Java.
h2.Getting Set Up
* Download the [Tuscany Java SCA release|SCA Java Releases].
From this page you can get binary and source releases for both windows and linux. For this exercise you will need the binary release for your preferred platform. You can use the source code release but you will have to use Maven at all stages.
* Download java
[Java 5|http://java.sun.com/javase/downloads/index.jsp]
* Download a build tool
[Maven 2.0.7+|http://maven.apache.org/download.html]
OR
[Ant 1.7.0|http://ant.apache.org/bindownload.cgi]
h2. Running The Calculator Sample
The calculator sample is provided with the Tuscany SCA Java binary distribution. You can find it in the samples/calculator direc
!calculator1.png|align=centre!
Let's first run the sample before we go about building it. It is easy!
* Go to the directory ..\samples\calculator
{code}
ant run
{code}
Alternatively if you want to run the sample directly from the command line try the following.
* if you are using Windows issue the command:
{code} Column |
---|
|
Panel |
---|
borderColor | #C3CDA1 |
---|
bgColor | #ECF4D1 |
---|
titleBGColor | #C3CDA1 |
---|
title | Build Calculator Using Command Line |
---|
borderStyle | solid |
---|
| |
Background Color |
---|
| What this is about |
This guide takes a command line based approach to getting started with Apache Tuscany Java SCA. For the Eclipse users amongst us there are other guides that show how to install the distribution into Eclipse or how to exploit Tuscany SCA Java using the Eclipse plugin that is has been built as part of the project. This article however just uses the downloaded Tuscany SCA Java distribution, Java, Maven or Ant and the command line. So if you want to feel close to the action this is where to start! Tuscany ships with a number of samples. One of the most straightforward of these is the calculator sample. We will use this to make sure that you installation is working properly. As the name indicates, this example performs typical calculator operations. It is given two numbers and asked to perform an operation on them. Our calculator will handle add, subtract, multiply and divide. By the end of this exercise you know how to develop, deploy and run the calculator application and how to reconfigure it to make it work for different environments. Background Color |
---|
| Setup Environment |
First of all we will walk through running the calculator sample to make sure you installation is working correctly. Then we will walk through the steps taken to implement the calculator sample in the first place. Following this you should be familiar with how to build a basic SCA application that runs in a single, stand-alone, SCA runtime. The next step is to update the sample to use some of the other Tuscany SCA Java extensions. Finally we will use the calculator sample to show you how you can build a distributed Service Oriented Architecture using Tuscany SCA Java. - Download the Tuscany Java SCA release.
From this page you can get binary and source releases for both windows and linux. For this exercise you will need the binary release for your preferred platform. You can use the source code release but you will have to use Maven at all stages. - Download java
Java 5 - Download a build tool
Maven 2.0.7+ OR Ant 1.7.0
Anchor |
---|
| run calculator |
---|
| run calculator |
---|
|
Background Color |
---|
| Run An Existing Calculator Appliction |
Tuscan SCA provides a calculator sample with its binary distribution. You can find it in the samples/calculator directory. As shown below, this sample and every sample in Tuscany has a "readme" that explains how to run the sample, a *.png file that has shows how the SCA application looks like. Image Added
Let's first run the sample before we go about building it. It is easy! Go to the directory ..\samples\calculator Alternatively if you want to run the sample directly from the command line try the following. - if you are using Windows issue the command:
|
java -cp ..\..\lib\tuscany-sca-manifest.jar;target\sample-calculator.jar calculator.CalculatorClient
|
| {code}
* if you are using *nix issue the command:
{code}- if you are using *nix issue the command:
Code Block |
---|
java -cp ../../lib/tuscany-sca-manifest.jar:target/sample-calculator.jar calculator.CalculatorClient
|
| {code}
!calculator2.png|align=centre!
If you are using the source disitribution then we suggest you use Maven to build and run the calculator sample because the Image Added
If you are using the source distribution then we suggest you use Maven to build and run the calculator sample because the tuscany-sca-manifest.jar | samples.
h2. Building The Calculator Sample In Java
This example illustrates how to define your application while staying focused on the business logic. It walks you through the steps of building the calculator sample. All connections between the components within the composite are local and described using Java interfaces.
*Step 1 - Define what building blocks are needed:* Think about how your application can be broken down into smaller functions/services. Each block is a logical unit of operation that can be used in the overall application. In this case, calculator application can be divided into five blocks: AddService block, SubstractService block, MultiplyService block and DivideService block and a main block that takes a request and routes it to the right operation. We have called this main block the CalculatorService
!calculatorblocks.jpg|align=centre!
*Step 2 - Implement each block:* Now that you have identified the blocks of functionality in your application, you are ready to create each block. In SCA the blocks of functionality are referred to as components so let's look at how we implement a component. We'll take the AddService component as our first example.
The AddService component will provide a service that adds two numbers together. The CalculatorService component uses the AddService component whenever it is asked to perform additions. If we were writing the AddService component in plain old Java we would start by describing a (Java) interface.
{code}samples. Background Color |
---|
| Build The Calculator Sample In Java |
This example illustrates how to define your application while staying focused on the business logic. It walks you through the steps of building the calculator sample. All connections between the components within the composite are local and described using Java interfaces. Step 1 - Define what building blocks are needed: Think about how your application can be broken down into smaller functions/services. Each block is a logical unit of operation that can be used in the overall application. In this case, calculator application can be divided into five blocks: AddService block, SubstractService block, MultiplyService block and DivideService block and a main block that takes a request and routes it to the right operation. We have called this main block the CalculatorService Image Added
Step 2 - Implement each block: Now that you have identified the blocks of functionality in your application, you are ready to create each block. In SCA the blocks of functionality are referred to as components so let's look at how we implement a component. We'll take the AddService component as our first example. The AddService component will provide a service that adds two numbers together. The CalculatorService component uses the AddService component whenever it is asked to perform additions. If we were writing the AddService component in plain old Java we would start by describing a (Java) interface. Code Block |
---|
public interface AddService {
double add(double n1, double n2);
}
|
| {code}
{} |
---|
public class AddServiceImpl implements AddService {
public double add(double n1, double n2) {
return n1 + n2;
}
}
|
| {code}
But wait! out
{} |
---|
public interface CalculatorService {
double add(double n1, double n2);
double subtract(double n1, double n2);
double multiply(double n1, double n2);
double divide(double n1, double n2);
}
|
| {code}
{code} Code Block |
---|
public class CalculatorServiceImpl implements CalculatorService {
private AddService addService;
private SubtractService subtractService;
private MultiplyService multiplyService;
private DivideService divideService;
@Reference
public void setAddService(AddService addService) {
this.addService = addService;
}
...set methods for the other attributes would go here
public double add(double n1, double n2) {
return addService.add(n1, n2);
}
...implementations of the other methods would go here
}
|
| {code}
case.
!calculator3.png|align=centre!
*Step 3 - Assembling the application:*
So all well and good but how do we actually run these two components. Well of course the java programmer in us wants to get down to it, write a mainline to connect our two components together and run then. We could still do that easily in this case.
{code}case. Notice that these are just plain Java services with business logic and nothing else in them. Image Added
Background Color |
---|
| Assemble the Calculator Application |
So far we have created the components. How do we actually run the calculator application? Well of course the java programmer in us wants to get down to it, write a mainline to connect our two components together and run then. We could still do that easily in this case. Code Block |
---|
public class CalculatorClient {
public static void main(String[] args) throws Exception {
CalculatorServiceImpl calculatorService = new CalculatorServiceImpl();
AddService addService = new AddServiceImpl();
calculatorService.setAddService(addService);
System.out.println("3 + 2=" + calculatorService.add(3, 2));
// calls to other methods go here if we have implemented SubtractService, MultiplyService, DivideService
}
}
|
| {code}
{code} Code Block |
---|
public class CalculatorClient {
public static void main(String[] args) throws Exception {
SCADomain scaDomain = SCADomain.newInstance("Calculator.composite");
CalculatorService calculatorService = scaDomain.getService(CalculatorService.class, "CalculatorServiceComponent");
System.out.println("3 + 2=" + calculatorService.add(3, 2));
// calls to other methods go here if we have implemented SubtractService, MultiplyService, DivideService
scaDomain.close();
}
}
|
| {code}
{code} Code Block |
---|
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
name="Calculator">
<component name="CalculatorServiceComponent">
<implementation.java class="calculator.CalculatorServiceImpl"/>
<reference name="addService" target="AddServiceComponent" />
<!-- You can add references to SubtractComponent, MultiplyComponent and DivideComponent -->
</component>
<component name="AddServiceComponent">
<implementation.java class="calculator.AddServiceImpl"/>
</component>
<!-- definitions of SubtractComponent, MultiplyComponent and DivideComponent -->
</composite>
|
| {code}
You can see that we define two components here and specify the Java implementation classes that Tuscany SCA needs to load to make them work. These are the classes we have just implemented.
Also note that the CalculatorServiceComponent has a reference named "addService". In the XML, this reference targets the AddServiceComponent. It is no coincidence that the reference name, "addService", matches the name of the addService field we created when we implemented CalculatorServiceImpl. The Tuscany SCA runtime parses the information from the XML composite file and uses it to build the objects and relationships that represent our calculator application. It first creates instances of AddServiceImpl and CalcualtorSreviceImpl. It then injects a reference to the AddServiceImpl object into the addService field in the CalculatorServiceImpl object. If you look back at how we implemented the CalculatorService you will see an @Reference annotation that tells SCA which fields are expecting to be set automatically by SCA. This is equivalent to this piece of code from our normal Java client.
{code}In our case so far, we defined two components and we specify the Java implementation classes that Tuscany SCA needs to load to make them work in the .composite file. These are the classes we have just implemented. Also note that the CalculatorServiceComponent has a reference named "addService". In the XML, this reference targets the AddServiceComponent. It is no coincidence that the reference name, "addService", matches the name of the addService field we created when we implemented CalculatorServiceImpl. The Tuscany SCA runtime parses the information from the XML composite file and uses it to build the objects and relationships that represent our calculator application. It first creates instances of AddServiceImpl and CalcualtorSreviceImpl. It then injects a reference to the AddServiceImpl object into the addService field in the CalculatorServiceImpl object. If you look back at how we implemented the CalculatorService you will see an @Reference annotation that tells SCA which fields are expecting to be set automatically by SCA. This is equivalent to this piece of code from our normal Java client. Code Block |
---|
CalculatorServiceImpl calculatorService = new CalculatorServiceImpl();
AddService addService = new AddServiceImpl();
calculatorService.setAddService(addService);
|
| {code}
"CalculatorServiceComponent". |
{code} Code Block |
---|
CalculatorService calculatorService = scaDomain.getService(CalculatorService.class, "CalculatorServiceComponent");
|
| {code}
CalculatorServiceImpl.add() |
{} |
---|
return addService.add(n1, n2);
|
| {code}
!calculator4.png|align=centre!
You will notice that diagrams are provided with all of our samples. If you like to take a visual approach to things this may help you become quickly familiar with the components in the samples. Take a look at the ".png" files in the top level directory of each sample.
*Step 4 - Deploying the applcation:*
So as long as the "Calculator.composite" file is present on our class path, along with the rest of the tuscany jars, we can run our sample as we did previously. The samples come with an Ant build.xml file that allows the sample files to be rebuilt so if you want to experiment with the sample code you can do so and then recompile it.
{code}
ant compile
{code}
Once recompiled you can run it as before in the [Running The Calculator Sample|SCA Java User Guide#Running The Calculator Sample] section, for example, we provide a run target in the Ant build.xml file so the calculator sample can also be run using.
{noformat}
ant run
{noformat}
h3. {anchor:What Next}{bgcolor:#C3CDA1}Using more advanced features in calculator{bgcolor}
Looking back, the client code we have written to start the calculator application using the Tuscany SCA runtime is no longer than a normal Java client for the application. However we do now have the XML composite file that describes how our application is assembled.
This concept of assembly is a great advantage as our applications become more complex and we want to change them, reuse them, integrate them with other applications or just further develop them using a programming model consistent with all our other SCA applications. Regardless of what language is used to implement each of them.
For example, lets say our calculator sample is so poweful and popular that we want to put it on the company intranet and let other people access it as a service directly from their browser based Web2.0 applications. It's at this point we would normally start reaching for the text books to work out how to make this happen. As we have an XML file that describes our application it's easy in Tuscany SCA. The following should do the trick.
{code}
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
name="Calculator">
<service name="CalculatorService" promote="CalculatorServiceComponent/CalculatorService">
<interface.java interface="calculator.CalculatorService"/>
<binding.jsonrpc/>
</service>
<component name="CalculatorServiceComponent">
<implementation.java class="calculator.CalculatorServiceImpl"/>
<reference name="addService" target="AddServiceComponent" />
<!-- references to SubtractComponent, MultiplyComponent and DivideComponent -->
</component>
<component name="AddServiceComponent">
<implementation.java class="calculator.AddServiceImpl"/>
</component>
<!-- definitions of SubtractComponent, MultiplyComponent and DivideComponent -->
</composite>
{code}
All we have done is added the <service> element which tells Tuscany SCA how to expose our CalculatorServiceComponent as a JSONRPC service. Note that we didn't have to change the Java code of our components. This is just a configuration change. The helloworld-jsonrpc sample shows a working example of the jsonrpc binding.
(?) TODO - we don't have a JSONRPC version of the calculator sample
If we really wanted a SOAP/HTTP web service we can do that easily too. The helloworld-ws-service and helloworld-ws-reference samples show you how to work with web services.
(?) TODO - we don't have a web services version of the calcualtor sample
SCA allows other kinds of flexibility. We can rewire our components, for example, using a one of the remote bindings, like RMI, we could have the CalculatorServiceComponent running on one machine wired to a remote version of the application running on another machine. The calculator-rmi-service and calculator-rmi-reference samples show the RMI binding at work.
We could also introduce components implemented in different languages, for example, let's add the SubtractServiceComponent implemented in Ruby.
{code}
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
name="Calculator">
<component name="CalculatorServiceComponent" Image Added
You will notice that diagrams are provided with all of our samples. If you like to take a visual approach to things this may help you become quickly familiar with the components in the samples. Take a look at the ".png" files in the top level directory of each sample. Background Color |
---|
| Deploy the Calculator Application |
The composite describes how SCA components are implemented and how they are assembled by wiring references to targets. This composite file has some dependencies, in this case the Java class and interface files that are used to implement the SCA components that it defines. The collection of composite files and other artifacts that are required to run an SCA application are collected together into one or more SCA contributions. A contribution can be a simple as a directory in a file system or could be packaged in, for example, a Jar file. SCA does not mandate any particular packing scheme. For our calculator sample you can imagine the contribution holding the calculator composite and all of its dependencies. In fact if you look inside the jar file that the calculator sample produces, you will find the following Code Block |
---|
calculator/AddService.class
calculator/AddServiceImpl.class
calculator/CalculatorClient.class
calculator/CalculatorService.class
calculator/CalculatorServiceImpl.class
calculator/DivideService.class
calculator/DivideServiceImpl.class
calculator/MultiplyService.class
calculator/MultiplyServiceImpl.class
calculator/SubtractService.class
calculator/SubtractServiceImpl.class
Calculator.composite
|
Which are all the artifacts that are required to run the calculator sample. We just need to add this contribution to the Tuscany SCA java runtime and then call the services that will be enabled. The samples in Tuscany come with an Ant build.xml file that allows the sample files to be rebuilt so if you want to experiment with the sample code you can do so and then recompile it. Once recompiled you can run it as before in the Running The Calculator Sample section, for example, we provide a run target in the Ant build.xml file so the calculator sample can also be run using. Background Color |
---|
| Reconfigure The Calculator Application - Change Bindings |
Looking back, the client code we have written to start the calculator application using the Tuscany SCA runtime is no longer than a normal Java client for the application. However we do now have the XML composite file that describes how our application is assembled. This concept of assembly is a great advantage as our applications become more complex and we want to change them, reuse them, integrate them with other applications or just further develop them using a programming model consistent with all our other SCA applications. Regardless of what language is used to implement each of them. For example, lets say our calculator sample is so poweful and popular that we want to put it on the company intranet and let other people access it as a service directly from their browser based Web2.0 applications. It's at this point we would normally start reaching for the text books to work out how to make this happen. As we have an XML file that describes our application it's easy in Tuscany SCA. The following should do the trick. Code Block |
---|
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
name="Calculator">
<service name="CalculatorService" promote="CalculatorServiceComponent/CalculatorService">
<interface.java interface="calculator.CalculatorService"/>
<binding.jsonrpc/>
</service>
<component name="CalculatorServiceComponent">
<implementation.java class="calculator.CalculatorServiceImpl"/>
<reference name="addService" target="AddServiceComponent" />
<!-- references to SubtractComponent, MultiplyComponent and DivideComponent -->
</component>
<component name="AddServiceComponent">
<implementation.java class="calculator.AddServiceImpl"/>
</component>
<!-- definitions of SubtractComponent, MultiplyComponent and DivideComponent -->
</composite>
|
All we have done is added the <service> element which tells Tuscany SCA how to expose our CalculatorServiceComponent as a JSONRPC service. Note that we didn't have to change the Java code of our components. This is just a configuration change. The helloworld-jsonrpc sample shows a working example of the jsonrpc binding that you can use as an example to change the calculator application to use JSONRPC. If we really wanted a SOAP/HTTP web service we can do that easily too. Code Block |
---|
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
name="Calculator">
<service name="CalculatorService" promote="CalculatorServiceComponent/CalculatorService">
<interface.java interface="calculator.CalculatorService"/>
<!-- ** Below we added info for json binding ** -->
<binding.jsonrpc/>
|
| <implementation.java class="calculator.CalculatorServiceImpl"/>
<referenceaddService" target="AddServiceComponent" CalculatorServiceComponent">
<implementation.java class="calculator.CalculatorServiceImpl"/>
<reference name=" |
| subtractServiceSubtractServiceComponentAddServiceComponent" />
<!-- references to SubtractComponent, MultiplyComponent and DivideComponent |
| -->
</component>
<component name="AddServiceComponent">
<implementation.java class="calculator.AddServiceImpl"/ -->
</component>
<component name=" |
| SubtractServiceComponentAddServiceComponent">
<implementation. |
| scriptscript/SubtractServiceImplrbAddServiceImpl"/>
</component> |
|
<!-- definitions of MultiplyComponent and DivideComponent -->
</composite>{code}
Of course we need the Ruby codethatimplementsthe component.
{code}
def subtract(n1, n2)
return n1 - n2
end
{code}
The Tuscany SCA runtime handles wiring Java components to Ruby components and performs any required data transformations. The calculator-script sample shows different script languages in use.
So, now that our application is desribed as an SCA assembly there are lots of possibilities as we futher develop it and integration it with other applications. The following sections provide more detail on the features provided by Tuscany SCA.
h2. {anchor:OnlineStore application}{bgcolor:#C3CDA1}Creating An OnLineStore SCA composite appllication{bgcolor}
Now that you are familiar with SCA concepts you can use this step by step guide to create an OnlinStore composite SCA application which provides a web interface to a shopping cart. This excercise will take less than half an hour and it familiarizes you with the steps of creating and running a real SCA composite application. Although Eclipse IDE is used, no previous knowledge of Eclipse is required. You can easily see how the same steps can be used in your favorite IDE.
[Want to Create my own OnlineStore SCA application|http://incubator.apache.org/tuscany/sca-java-releases.data/onlineStore.pdf] <!-- definitions of SubtractComponent, MultiplyComponent and DivideComponent -->
</composite>
|
We have added binding.ws here so that your calculator service is available over JSONRPC and WebService bindings at the same time. The helloworld-ws-service and helloworld-ws-reference samples show you how to work with web services. SCA allows other kinds of flexibility. We can rewire our components, for example, using a one of the remote bindings, like RMI, we could have the CalculatorServiceComponent running on one machine wired to a remote version of the application running on another machine. The calculator-rmi-service and calculator-rmi-reference samples show the RMI binding at work. Anchor |
---|
| implementation |
---|
| implementation |
---|
|
Background Color |
---|
| Use Alternative Implementation Types |
We could also introduce components implemented in different languages, for example, let's add the SubtractServiceComponent implemented in Ruby. Code Block |
---|
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
name="Calculator">
<component name="CalculatorServiceComponent">
<implementation.java class="calculator.CalculatorServiceImpl"/>
<reference name="addService" target="AddServiceComponent" />
<reference name="subtractService" target="SubtractServiceComponent" />
<!-- references to MultiplyComponent and DivideComponent -->
</component>
<component name="AddServiceComponent">
<implementation.java class="calculator.AddServiceImpl"/>
</component>
<component name="SubtractServiceComponent">
<implementation.script script="calculator/SubtractServiceImpl.rb"/>
</component>
<!-- definitions of MultiplyComponent and DivideComponent -->
</composite>
|
Of course we need the Ruby code that implements the component. Code Block |
---|
def subtract(n1, n2)
return n1 - n2
end
|
The Tuscany SCA runtime handles wiring Java components to Ruby components and performs any required data transformations. The calculator-script sample shows different script languages in use. So, now that our application is described as an SCA assembly there are lots of possibilities as we further develop it and integrate it with other applications. |
|