SCA Java User Guide

This page is under construction- You are welcome to help and complete it

Welcome to the Apache Tuscany SCA User guide. Here you will find information aimed to help you understand SCA concepts and an example walk through for building your own SCA application.

Apache Tuscany SCA User Guide

Introduction
Quick Guide to SCA
Overview of Example
- get started
- Experience running calculator application
- Build your Calculator application in Java
  - What you will learn
  - Example walk through
- Build a Calculator application using different languages
- Build a Calculator application using web services

Introduction">Introduction

This user guide will help you become familiar with SCA concepts and walks you through an example that demonstrate how to build an SCA application. It also describes the different environments that Tuscany supports (such as command line clients or web applications) and how to package up applications to run in these environments.

There's nothing to it really! Building SCA applications is easy. One of the main goals of Tuscany and SCA is to avoid imposing rules and requirements on how people write applications. We want to let people write application code the way they want without being concerned about the environment in which it will be used. After all, writing code to handle plumbing just gets in the way of writing the interesting stuff. So basically, you write the code for interesting bits, and Tuscany provides the environment that lets it run. Therefore, this guide is just an example of how an SCA application can be developed and is not a rule.

Quick Guide to SCA "> Quick Guide to SCA

The quick guide to SCA gives you an overview of SCA concepts and prepares you to work on the example below. You can skip this step if you are already familiar with SCA.

For more details on SCA please refer to the specifications at Open SOA web site.

Example Walkthrough"> Example Walkthrough

Overview of Example"> Overview of Example

We will use the calculator sample to walk through the steps for building an SCA application. 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.

We start with a simple variation of the calculator example and extend it to include more advanced SCA features.

Getting Set Up"> Getting Set Up

Download Tuscany Java SCA release.
Please download the latest binary release. You can use the source code release but you will have to use Maven at all stages.
Download prerequisites
- Java 5
- Maven 2.0.4+

If you want to build the sample with Ant rather than Maven you will need to download Ant instead

- Ant 1.7.0

Running The Calculator Sample">Running The Calculator Sample

Calculator is provided as a sample under SCA Java binary distribution. Let's first run the sample before we go about
building it. It is easy!

Go to the directory ..\samples\calculator

if you are using Windows issue the command:

java -cp ..\..\lib\tuscany-sca-manifest.jar;target\sample-calculator.jar calculator.CalculatorClient

if you are using *nix issue the command:

java -cp ../../lib/tuscany-sca-manifest.jar:target/sample-calculator.jar calculator.CalculatorClient

You should see the following result:

3 + 2=5.0
3 - 2=1.0
3 * 2=6.0
3 / 2=1.5

If you are using the source disitribution then we suggest you use Maven to build and run the calculator sample because the tuscany-sca-manifest.jar is not provided with the source distribution. This jar is part of the binary distribution and collects together all of the tuscany jars in one place so that the java command line is nice and short when running samples.

Building The Calculator Sample In Java">Building The Calculator Sample In Java

What you will learn

This example illustrates how to define your application while staying focused on the business logic. It walks you through the steps of building a composite application called calculator. All connections between the components within the composite are local and defined using Java interfaces.

Example walk-through

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

(?)TODO - need to update the diagram to change Add -> AddService etc. Who has the editable version?

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 CalcualtorService 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.

public interface AddService {

    double add(double n1, double n2);
}

Now, we provide an implementation of this interface.

public class AddServiceImpl implements AddService {

    public double add(double n1, double n2) {
        return n1 + n2;
    }
}

But wait! Aren't we writing an SCA component? It must be more complicated that that - the mere, plain old Java interface and implementation, right? Well, actually an SCA component can just be plain old Java so we have just done all the coding we needed to implement the SCA AddService component. We can use SCA to expose the service that the AddService component provides over any of the supported bindings, for example, WebServices, JMS or RMI, without changing out the AddService implementation.

Let's take a look at the CalculatorService component. This is interesting because it's going to call the AddService component. In the full application it will call the SubtractService, MultiplyService and DivideService components as well, but we will ignore these for the time being as they follow the same pattern as we will implement for the AddService component.

Again we will start by defining an interface because CalcultorService is itself providing an interface that others will call.

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);
}

Now we implement this interface.

public class CalculatorServiceImpl implements CalculatorService {

    private AddService addService;
    private SubtractService subtractService;
    private MultiplyService multiplyService;
    private DivideService divideService;
   
    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
}

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 want's 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.

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
    }
}

But this doesn't run using the Tuscany SCA runtime. What do we have to do to make it run in Tuscany? Well Actually not much. First let's change the client to fire up the Tuscany SCA runtime before calling our components.

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();
    }
}

You can see that we start by using a static method on SCADomain to create a new instance of itself. The SCADomain is a concept in SCA that represents the boundary of an SCA system. This could be distributed across many processors but that's not implemented in Tuscany yet so lets concentrate on getting this working inside a single Java VM.

The parameter "Calculator.composite" refers to an XML file that tells SCA how the components in our calculator application are assembled into a working applcation. Here is the XML that's inside Calculator.composite.

<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" />
        <!-- references to SubtractComponent, MultiplyComponent and DivideComponent  -->
    </component>

    <component name="AddServiceComponent">
        <implementation.java class="calculator.AddServiceImpl"/>
    </component>

    <!-- definitions of SubtractComponent, MultiplyComponent and DivideComponent -->

</composite>

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 in the addService field in the CalculatorServiceImpl object. This is equivalent to this piece of code from our normal Java client.

        CalculatorServiceImpl calculatorService = new CalculatorServiceImpl();
        AddService            addService        = new AddServiceImpl();
        calculatorService.setAddService(addService);

Once the composite file is loaded into the SCADomain our client code asks the SCADomain to give us a reference to the component called "CalculatorServiceComponent".

        CalculatorService calculatorService = scaDomain.getService(CalculatorService.class, "CalculatorServiceComponent");

We cna use this reference

Step 4 - Deploying the applcation:

So as long at "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. Once recompiled you can run it as before in the Running The Calculator Sample section. We also provide a run target in the Ant build.xml file so the calculator sample can also be run using.

ant run

What Next?">What Next?

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 how 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 applicatiosn 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.

<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.
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 flxibility. 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 using RMI. 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.

<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.

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 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.

Tuscany SCA Extensions">Tuscany SCA Extensions

An Extensible Runtime">An Extensible Runtime

The Tuscany SCA runtime comprises a small set of core software which deals with:

Managing extesions to the Tuscany SCA Runtime(core)
Building and in memory assembly model of SCA applications (assembly)
Processing SCA applcations that are contributed (contribution)
Supporting databindings (databinding)
Supporting Tuscany SCA when its embedded in other environments (embedded)
Supporting Tuscany SCA when its running in a servlet container (http)

The collections of interfaces that describe these features are referred to as the SPI. The developer guide discussed them in more detail but from a user perpective the important thing to realize is that the majority of interesting functionality in Tuscany SCA is provided by extensions which build upon this core set of SPIs.

Extensions provide Tuscany SCA with its ability to support a wide variety of;

Implementation types
Binding types
Databinding types
Interface description styles
Hosting environments

So to undestand how to use the Tuscany SCA runtime is to understand how to use its extensions.

Using Extensions">Using Extensions

Extensions are loaded into the Tuscany SCA runtime using the Java service loading mechanism. Each extension is packaged as a jar and provides a file;

META-INF/services/org.apache.tuscany.sca.core.ModuleActivator

Using this information the Tuscany SCA runtime will load all extensions present on the the Java CLASSPATH.

Most extensions will include code to build extension specific parts of the assembly model and to provide the runtime support required by the extended model. As the extension mechanism is used to provide a wide variety of features the precise mechanism by which extensions are used in you application vary. The [extension guide] describes each of the extesions and how they can be used and configured.

Writing a new extension is a subject on its own and is described here ( link required ).

Tuscany SCA And IDEs">Tuscany SCA And IDEs

TODO At this point you have identified the IDE you want to use. Here is an example of how the environment can be setup in Eclipse.
[add a page to explain how Eclipse setup can be done - need help for this]

Unknown macro: {HTMLcomment}

Child pages