SCA Java User Guide

Welcome to the Apache Tuscany SCA User guide. Here you will find information aimed to help you first develop a simple SCA calculator application and then enhance it with more advanced features and concepts. This guide is based on Java SCA implementation in Tuscany.

It is assumed that you are familiar with basic SCA concepts.

This is a work in progress, so please contribute and comment so we can make this valuable to you

Introduction">Introduction

Service Component Architecture (SCA) defines technologies for creating services and assembling them into higher-order service networks. SCA provides a language-independent way to compose and deploy service networks. SCA also defines language-specific client programming models for service authoring including Java, Spring, C++, and PHP. This user guide is for Java SCA implementation in Tuscany.

This user guide will help you build a simple application called calculator sample and extend it to more complicated use the Calculator Sample to demonstrate the concepts in SCA and helps you build a simple application using Tuscany Java SCA.

[NOTE: We should focus the user guide on end users. They should not need to download source code]

Why SCA? ">Why SCA?

Service Oriented Architecture (SOA) is an architectural approach driven by the need to overcome the challenges of tightly coupled and department-specific applications. SOA promises benefits such as improved business agility, improved flexibility, cost reduction, and the easy sharing of information in heterogeneous and distributed environments.

Service Component Architecture (SCA) addresses the complexity of developing an SOA solution through its simple model for creating service-oriented applications for the whole enterprise - from the client to the back-end in a distributed or simple environment.

SCA programming model frees developers from polluting business logic with protocol handling and instead enables them to focus on the business logic through clear component interfaces and binding extensions.

[NOTE: This is a good writeup, but better suited for intro o the user manual. For now, lets keep it here]

DownLoading SCA "> DownLoading SCA

Point to download page. (http://incubator.apache.org/tuscany/sca_downloads.html)
Decide which release this calculator sample will be tested with and guide user to download that release.

Example Overview "> Example Overview

We will use the calculcator sample for this excercise. The calculator sample consists of a calculator application and an SCA client that invokes the application. The calculator application performs four operations: Add, Substract, Multiply and Divide.

[Note: The following diagram is not correct!

Running the Calculator Sample">Running the Calculator Sample

[Note: We need to provide instruction for how to run sample without getting into IDE]

Running the Calculator Sample">Running the Calculator Sample

These are preliminary steps...details such as from where to download are forthcoming

1.  Download the sample file.
2.  Unzip it to a local folder such as C:\Temp
3.  In Eclipse, select File -> Import -> General -> Existing Projects into Workspace
4.  Click Next.
5.  Select the Select root directory option and click the "Browse" button to point to C:\Temp.
6.  Select CalcultorSample directory and click Finish. The project is created.
7.  Expand the CalcultorSample. Expand "src/main/java/calculator", right-click CalculatorClient.java and select Run as ... --> Java Application. You will see   the following output in the console view:

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

Building your own Calculator Application">Building your own Calculator Application

Topics to include?

Creating Java SCA Components
Creating the implementation for the Java SCA components
Creating the composite file
Creatomg a client to invoke the service
Packaging a Standalone Tuscany Application?
Building a Tuscany Web Application?

Step1: Diagram "> Step1: Diagram

think about how your application can be broken down into smaller functions/services. In this case, calculator application can be divided into four blocks: Add block, Substract block, Multiply block and Divide block. Each block is a logical unit of operation that can be used in the overall application.

Step2: Define components"> Step2: Define components

Now that you have defined the diagram, you can further define each block. A block is equivalent to a component in SCA programming model. A component is the smallest unit of function in your application that provides a service. A component can reference other components and also be referred by other components. Let's tart with the add component.

[Note: Add the correct diagram to show add component and its interfaces.]

borrow

After writing the Alert Aggregator sample for the Tuscany Native runtime I thought it would be worthwhile documenting my experiences. I've titled this "Best Practices" but perhaps "Hints & Tips" or "Andy's Observations" would be more appropriate! Anyway, below is a suggested list of things to do/think about when writing your own SCA based applications. A few of the points below are from general software development, but they apply equally to SCA development.

Start by drawing your SCA diagram (example here) - this helps with the componentization of your app. SCA diagrams aren't code path diagrams (such as a BPEL visualization): they simply show what blocks of function you have and which blocks are used by other blocks. Separating components into composites also helps you think about componentization and deployment, as (currently) the smallest deployable block is a composite. Similarly, an SCA diagram is not a class diagram - the smallest SCA unit is the component which could consist of multiple classes or scripts or similar. You may have a requirement for a "Utilities" class providing some basic function that is used by lots of other classes - SCA wires involve a certain amount of overhead, so it may not be worth creating a "Utilities" component that all other components reference. Instead, it can be valid to have multiple instances of the same class embedded as part of multiple components.

Think about the services and references that your components and composites provide/require, so you can draw the wiring on the diagram and work out which components and composites you need, but don't worry too much about bindings (REST, WS, etc) - SCA/Tuscany makes it so easy to switch bindings that this can be decided at a later time.

I didn't worry too much about interfaces at this point - I planned to do most of my components in scripting languages (which don't need defined interfaces in Tuscany Native). In other languages (Java, C++) it may be worth defining the public interfaces that your component implements, so you can see how and where functions are implemented within your composites.

When coding the component implementations, it's easiest to start with the 'least-dependent' components - those that don't need lots of other infrastructure or other components or composites in place. For the Alert Aggregator sample (see here), my order of component development was as follows:
RSSChecker
AlertConfig
AlertChecker
HTMLFormatter
POPChecker
Of course, as in normal software development, this was an iterative process where each component got revisited as necessary.

Component implementations were developed in a standard test-driven manner, but deploying within an SCA runtime adds extra layers of required testing (think unit vs. system tests). I began by testing my component implementations in a standalone, unit-testing-style fashion, then tested under Tuscany via local clients, then via remote clients using whichever service bindings I had chosen and finally via full system tests (in the Alert Aggregator case, through clicking on a web page). The power of SCA meant that I could use the same client code for both local and remote testing , just by adding in a local SCA reference that called the remote service (see the PythonCalculator sample for an example of this - the sample.calculator.client/client.py code is almost exactly the same as the sample.calculator.wsclient/client.py code).

I found I needed to programme somewhat defensively - Tuscany SCA Native (or at least the extensions I used) is not yet particularly good at handling exceptions or errors that get thrown, but not caught, in component code. Instead, I tried to check for bad data and catch exception cases within the component implementation. The handling of errors is something that definately needs more work in Tuscany SCA Native - should errors get propagated back to the original client, or should they be caught and logged? A problem that exacerbates this issue is that some of our logging messages don't provide much (or any!) useful information!

The XML story with Tuscany SCA Native is pretty good - I found using SDO/XML/Python ElementTree objects easy and very useful. I would probably go as far as suggesting that developers use XML complex types and SDO rather than trying to flow multiple method parameters, as this can mean less changes required in code and interfaces throughout the development cycle.

Components">Components

Compents are the building blocks for creating SOA Applications. They contain the information that defines the program logic or implementation (component implementation), how the component interacts with other components (component type) and defines how it fits in with the other parts of the soluion (composition/assembly).

• A service header file that defines the operations that can be invoked on the component
• An implementation header file that defines the implementation and extends the service header file
• A C++ implementation of the service that implements the operations defined in the service header file
• Proxy and wrapper header and implementation files generated by the Tuscany C++ SCAGEN tool
• A service definition in a .componentType file
• An SCDL component definition within an SCDL composite file. Usually this composite file will contain multiple components configured and assembled together.

Service Component Descritpion Language (SCDL)">Service Component Descritpion Language (SCDL)

Create a client to invoke the service.">Create a client to invoke the service.

1. Create a file and name it CalculatorClient.java 

Your component, composite and subsystem are now ready to be invoked. Create a client that will call the service. E.g. the Calculator client (in the CalculatorClient.cpp file) contains code similar to the following:

package calculator;

import org.apache.tuscany.api.SCAContainer;
import org.osoa.sca.CompositeContext;
import org.osoa.sca.CurrentCompositeContext;

/**
* This client program shows how to create an SCA runtime, start it,
* locate the Calculator service and invoke it.
**/
public class CalculatorClient {
public static void main(String[] args) throws Exception { 
  SCAContainer.start("Calculator.composite"); 
  CompositeContext context = CurrentCompositeContext.getContext(); 
  CalculatorService calculatorService = 
  context.locateService(CalculatorService.class, "CalculatorServiceComponent"); 
  // Calculate 
  System.out.println("3 + 2=" + calculatorService.add(3, 2)); 
  System.out.println("3 - 2=" + calculatorService.subtract(3, 2)); 
  System.out.println("3 * 2=" + calculatorService.multiply(3, 2)); 
  System.out.println("3 / 2=" + calculatorService.divide(3, 2)); 
  SCAContainer.stop(); 
 }
}

Building a Tuscany Web Application">Building a Tuscany Web Application

You can run Tuscany inside of a Web application running in any standard Web container such as Apache Tomcat. Once configured, the application is portable across container implementations.