Page History

*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 example walk through for building your own SCA application. 

{section}{column:width=50%}{column}

\\
{panel:title=Apache Tuscany SCA User Guide|borderStyle=solid|borderColor=#6699ff|titleBGColor=#D5EFFF|bgColor=#ffffff}

* [Introduction|#Intro]
* [Quick Guide to SCA |#Quick Guide to SCA]
* [Overview of Example| #Overview of Example]
  ** [get started|#get started]
  ** [Experience running calculator application|#Experience running calculator application]
  ** [Build your  Calculator application in Java|#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
\\
 
{panel}{section}

h3. {anchor:Intro}{color:#0099cc}Introduction{color}

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.


h3. {anchor:Quick Guide to SCA} {color:#0099cc}Quick Guide to SCA  {color}
The [*quick guide to SCA*|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|http://www.osoa.org].

h3. {anchor:Overview of Example} {color:#0099cc}Overview of Example{color}

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 those numbersthem. Our calculator will handle add, subtract, multiply and divide. 

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

h3. {anchor:getGet started} {color:#0099cc}Get started{color}

* Download [Tuscany Java SCA release|http://incubator.apache.org/tuscany/sca_downloads.html].
Please download the latest release. 
* Download prequisitsprerequisites 
  ** [JDKJava 5.0|http://java.sun.com/javase/downloads/index.jsp]
  ** [Maven 2.0.044+|http://maven.apache.org/download.html]

If you want to build the sample with Ant rather than ManvenMaven you will need to download Ant instead
  ** [Ant 1.7.0|http://ant.apache.org/bindownload.cgi]

h3. {anchor:Experience running calculator application}{color:#0099cc}Experience running calculator application{color}

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

* goGo doto the directory ..\samples\calculator
* if you are using Windows issue the command:
{code}
java -cp ..\..\lib\tuscany-sca-manifest.jar;target\sample-calculator.jar calculator.CalculatorClient
{code}
* if you are using *nix issue the command:
{code}
java -cp ../../lib/tuscany-sca-manifest.jar:target/sample-calculator.jar calculator.CalculatorClient
{code}

You should see the following result:

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

h3. {anchor:Build your  Calculator application in Java}{color:#0099cc}Build your  Calculator application in Java{color}

h4. 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 compostecomposite are local and are defined using Java interfaces.

h4. 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  
!CalculatorBlocks2.jpg!

TODO - need to update the diagram to change Add -> AddService etc. 

*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 letslet's look at how we implement a component. We'll take the AddService component as out first example. 

The AddService component will simple 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 the interface that is provides Javaan (Java) interface.

{code}
public interface AddService {

    double add(double n1, double n2);
}
{code}

Now, we provide an implementation of this interface.

{code}
public class AddServiceImpl implements AddService {

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

But we are arewait! Aren't we writing an SCA component? and thatIt must be much 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 needneeded to do 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.

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

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

Now we implement this interface. 

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

So all well and goo good.

There are 3 distinct steps.
# Create component implementation by writing the business logic. No need to worry about it now - it accesses services.
# Define service dependencies without needing to know how it is donethey're implemented.
# DefiningDefine properties and policies. 

For the purpose of this excerciseexercise, we will walk through building the add and calculator blocks using Java as an implementation language.

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]

{code}
Add link to a page that shows Add component implementation
Add a link to a page that shows calculator implementation
{code}

*Step 3 - Assemble the calculator application:*

*Step 4 - Deploy and run the calculator application:*


{HTMLcomment:hidden}{children:sort=creation}{HTMLcomment}