Introduction

The components in an SCA composite application can run on different nodes in a network. In Apache Tuscany, an SCA domain can be used to administer a set of nodes. In SCA, the definitions of composites, components, their implementations, and the nodes they run on belong to what's called an SCA domain. SCA implementations like Tuscany provide administration tools that let a system administrator manage the SCA artifacts in the domain. Using the domain gives you the flexibility to specify installation characteristics of nodes, such as host or port, at the time the nodes are added to the domain instead of in composite files. This article demonstrates how an application comprised of a number of SCA components can be administered via an SCA domain. Learn each step involved in adding an SCA application to the domain.

The example you use in this article is the store application from the "Getting started with Tuscany" guide (see the Resources section for a link). While the "Getting started with Tuscany" guide uses Eclipse to deploy the application, this article shows you how to run the same application in a real production environment. This article illustrates the required steps using an application that you can run in stand-alone Tuscany run time without additional middleware requirements.

System requirements

Make sure that you have:

• The Tuscany distribution downloaded and installed locally in some directory, such as /tuscany-sca-1.3.1.
• Java Platform 2, Standard Edition (J2SE) 1.5 installed.

Back to top

Application packages

Before you start deploying the solution, you need to get the installation archives for the solution. These archives contain SCA contributions, composites, and SCA components, concepts that are briefly described in the following section. The store solution is comprised of three Eclipse projects:

• assets contains a required Java™ implementation of all services and the store UI (see Figure 1).
  
  Figure 1. Project assets
  
  
  
• web-services contains composites that describe Web services catalogs and currency (see Figure 2).
  
  Figure 2. Project web-services
  
  
  
• store contains the store composite, as shown in Figure 3.
  
  Figure 3. Project store
  
  
  

Export these projects as JAR files into the c:\repository directory. If you download a complete Tuscany 1.3.1 distribution, you'll find the already exported JAR files for the store example in the tutorial subdirectory of your Tuscany distribution directory. These include:

• /tuscany-sca-1.3.1/tutorial/assets/target/tutorial-assets.jar
• /tuscany-sca-1.3.1/tutorial/store/target/tutorial-store.jar
• /tuscany-sca-1.3.1/tutorial/web-services/target/tutorial-web-services.jar

Back to top

Basic concepts

Before you continue, let's briefly describe the following SCA and Tuscany concepts:

• Contribution: A collection of composite files and project artifacts that describe a composite service application. A typical contribution includes SCA artifacts: one or more composite files, Java class and interface files, HTML files, and so on. A contribution can be an individual composite, a directory, or a JAR, WAR or EAR archive. In this case, you have three contributions:
  • tutorial-assets.jar contains classes used by other components.
  • tutorial-web-services.jar contains the composites describing Web services catalogs and currency.
  • tutorial-store.jar contains a composite describing the store solution.
  The store solution uses classes in tutorial-assets.jar and services described by composites in the contribution tutorial-web-services.jar. The overall composition of the store application and its contributions are shown in the Figures 4 and 5. Figure 4 is taken from the tutorial.pdf file from the Tuscany distribution.
  
  Figure 4. Overall composition of the store application
  
  
  
  
  Figure 5. Contributions for the store application
  
  
  In Figure 4, the store composite contained in the tutorial-store.jar contribution, and the catalog and currency composites contained in the tutorial-web-services.jar contribution, import implementations contained in the tutorial-assets.jar contribution. store.composite references components described in composites that are contained in the tutorial-web-services.jar contribution.
• Composite: Describes components that make up the application, services provided by each component, references components have to services provided by other components, and the wires that connect them. Some composites are included within other composites.
• Deployable composite: A top-level composite that's packaged for deployment. store.composite, catalog.composite, and currency.composite in this article's example are all deployable composites.
• Node: Wraps the Tuscany run time, which is comprised of Tuscany distribution libraries. In Tuscany, each SCA deployable composite is run in a node. Each node is configured using a contribution, a composite, and the properties of the environment, like host and port, where the node is run.
• Domain: Where contributions, composites, and nodes are configured.

All SCA resources—contributions, composites, and nodes—in a domain are Web resources accessible through HTTP. The collections of these resources are accessible through Atom and can be managed using Atompub. This is the SCA and Tuscany standard. (See Resources for a description of the Atom publishing protocol.)

Back to top

Deployment steps

The installation of an SCA component to a Tuscany domain involves:

1. Starting the domain manager application.
2. Adding contribution(s) to our domain.
3. Adding composites.
4. Adding nodes for composites.
5. Starting nodes.

Let's break these down in the following sections.

Start the domain manager application

1. Choose a directory that you'd like to be a working directory for the domain manager application. For this example, let's call it /tuscany/admin.
2. Switch to this directory and issue this command:
   
   java -jar \tuscany-sca-1.3.1\modules\tuscany-node2-launcher-1.3.1.jar domain
   
   
3. Open a browser window and go to your domain manager home page. If you started the domain manager on your local host, the home page of the domain manager is at http://localhost:9990/ui/home.
4. From the home page, click Contributions from the menu at the top. If the domain manager is started correctly, you should see the page shown in Figure 6.
   
   Figure 6. Empty domain
   
   
   

Add contributions

Now you need to add the contributions containing your application artifacts. For a contribution to be successfully added and used, it has to be accessible to both the domain manager and the nodes that run the application, as they need to load these artifacts at run time. If all components are located on the same host, the file path can be specified. In a distributed deployment you can use one of the following configurations:

• Make the contributions available from a repository accessible from all nodes and the domain manager application. The repository can be a plain HTTP server, an Apache Maven repository, or a Subversion repository, and is referenced via a URL.
• Make the contributions available locally on the machine running the domain and node using FTP, a network file system (NFS), Samba, or any other file-sharing mechanism.

The first option is preferred because it allows multiple people to contribute to a distributed SCA domain.

For simplicity in this example, let's assume all nodes are running on the same host. When it's applicable, we'll point out the differences between the local and distributed deployment.

1. Before you add contributions, select a contribution URI for each contribution. For example, for tutorial-assets.jar, use the contribution URI http://myassets (see Figure 7).
   
   Figure 7. Add a contribution
   
   
   
2. Click Add. The contribution should now be added to the domain and appear in the list of contributions.
3. Repeat the steps above for tutorial-web-services.jar and tutorial-store.jar using, for example, contribution URIs http://myws and http://mystore, respectively. If you added the contributions correctly, you should now see the list shown in Figure 8.
   
   Figure 8. Contributions page with all contributions added
   
   
   

In this example, you added contributions to an SCA domain using a GUI. It's also possible to add contributions using a program. In Tuscany 1.3.1, you can do this by posting the form containing the contribution name and URI to the domain manager URL for contributions <domainURL>/workspace. For example, the entry to be posted for the tutorial-web-services.jar contribution looks like Listing 1.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'> 
 <title>Contribution - http://myws</title>
 <id>http://myws</id>
 <link href="file:/c:/repository/tutorial-web-services.jar"/>
</entry>

You can add a contribution to an SCA domain using the code in Listing 2.

String contributionURI = "http://myws"; 
String contributionLocation = "file:/c:/repository/tutorial-web-services.jar";
String domainURL = "http://localhost:9990";	
try {
 String entry =  "<?xml version=\'1.0\' encoding=\'UTF-8\'?>"+
  "<entry xmlns=\'http://www.w3.org/2005/Atom\'>" +
  "<title>Contribution - " + contributionURI +"</title>" +
  "<id>" + contributionURI+ "</id>" +
  "<link href=\"" + contributionLocation + "\" />" +
  "</entry>";
              		
  post(domainURL+"/workspace", entry);
} catch (MalformedURLException e1) { // from post() method
 e1.printStackTrace();
} catch (Exception e) {
 e.printStackTrace();
}

In Listing 2, contributionLocation is the URL of your contribution archive in the contribution repository or on disk. In the example used in this article, the contribution location for tutorial-web-services.jar would be file:/c:/repository/tutorial-web-services.jar.

Listing 2 uses the post() method. This local method posts the string to a URL using a Java java.net.URLConnection class. (See Resources for the code to post a string to a URL.) When posting this form to the URL, set the Content-Type request property of the URLConnection object to "application/atom+xml", as shown in Listing 3.

URL url = new URL (targetURL); 
URLConnection conn =  url.openConnection();
conn.setDoInput (true); 
conn.setDoOutput (true); 
// Disable use of caches. 
conn.setUseCaches (false); 
conn.setRequestProperty("Content-Type","application/atom+xml");
[...]

Add composites

The next step is to add composites to the domain. In this example there are three composites:

• catalogs
• currency
• store

Start by adding catalogs.composite. If you look inside the composite, you see that its target namespace is http://services. It's located in the tutorial-web-services.jar contribution that you just added with the namespace http://myws.

1. In the menu on the domain manager Web page, click Composites.
2. Enter the information for catalogs.composite as shown in Figure 9.
   
   Figure 9. Add composite
   
   
   Here the namespace and the name identify the composite inside the contribution, while the contribution URI is the URI you gave to the contribution in the previous step.
3. Click Add. The composite appears in the list in the top portion of the page.
4. Repeat the steps to add currency.composite and store.composite. If you've done everything correctly, you'll see what's shown in Figure 10.
   
   Figure 10. Composites page section with added composites
   
   
   

You can also add composites via a script or a program. In this example, you can add catalogs.composite to the domain by posting the XML in Listing 4 to the URL http://localhost:9990/composite.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
 <title>composite:http://myws;http://services;catalogs</title>
 <id>composite:http://myws;http://services;catalogs</id>
</entry>

The title and ID need to contain the following string of syntax: composite:contribution-namespace;composite-namespace;composite-name.

Listing 5 shows the code needed to do this from a Java program.

String compositeName = "catalogs";
String compositeNamespace = "http://services";
String contributionURI = "http://myws";
String domainURL="http://localhost:9990";
       
String id = "composite:"+contributionURI+";"+compositeNamespace+";"+compositeName;
String entry= "<?xml version=\'1.0\' encoding=\'UTF-8\'?>" +
  "<entry xmlns=\"http://www.w3.org/2005/Atom\">" +
  "<title>" + id +"</title>" +
  "<id>" + id + "</id>" +
  "</entry>";
try {
 post(domainURL+"/composite", entry);
} catch (Exception e) {
 e.printStackTrace();			
}

Add nodes

The last step is to create nodes for each composite. Remember that a node provides a Tuscany runtime environment in which the composite is run. In this step, you need to specify the host and port for the node. This information can also be specified in the composite itself. It's important to note, however, that omitting this information from a composite and specifying it during node creation allows greater flexibility for deployment of an application component in a distributed environment. Doing this means you won't tie your composite to where it's deployed, and you won't need to change it if you need to move it to a different host or port at some point. Normally, an application developer doesn't know which ports are available in the environment where the application is to be installed. At this step, however, the available ports need to be provided.

1. Click the Cloud link at the top of the page.
2. Create a node for the catalogs.composite.

   If you intend to run the node on a local host, specify localhost in the URL and choose an available port. Because your catalogs node is run in a stand-alone Tuscany environment, you can specify any available TCP/IP port. If the components defined in the catalogs composite were implemented as a Web application, the node would run in a Web container, and you'd have to specify the appropriate URL as configured in the Web container.

   If you intend to run a node on a remote host, you need to ensure that the remote host has Tuscany run time installed and that the required contributions for running the node are accessible at a URL you specified when you added a contribution.

   In this case, let's use a local host (see Figure 11).

   
   
   Figure 11. Add node
   
   
   
   • Node name: You can use any name.
   • Node URI: This specifies the host and the port where you want to run the node.
   • Composite namespace and Composite name: These identify the composite for which you are creating the node. These are the same namespace and name you entered when you added the composite.
   • Contribution URI: This is the URI of the corresponding contribution you added in the first step.
3. Click Add. The node appears in the node list.
4. Similarly, add nodes for the currency and store composites. If the nodes were added correctly, you'll see the page shown in Figure 12.
   
   Figure 12. Cloud page section with added nodes
   
   
   

You can also add nodes to the domain from a Java program by posting the entry in Listing 6 to the domain at the cloud context root. In this example, you can add a node for catalogs.composite by posting the entry shown in Listing 6 to http://localhost:9990/cloud.

If you added the node manually in the steps above, you can click the name of the node. You'll see that the content of the entry shown in Listing 6 exactly corresponds to what you see when you click the node. This is the composite file describing the node. It includes its name, in this case MyCatalogsNode, the composite for which you are creating the node, in this case catalogs, the namespace of the composite for which the node is created, here http://services, and the node's host and port information specified in bindings that enable communication between this node and other nodes.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
 <id>
composite:http://tuscany.apache.org/cloud;http://tuscany.apache.org/cloud;MyCatalogsNode
 </id>
 <content type="text/xml">
  <composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
   xmlns:t="http://tuscany.apache.org/xmlns/sca/1.0" 
   targetNamespace="http://tuscany.apache.org/cloud"
   xmlns:c="http://services"
   name="MyCatalogsNode">
        				
   <component name="MyCatalogsNode"">
    <t:implementation.node uri="http://myws" composite="c:catalogs"/>
    <service name="Node"> 
     <binding.ws uri="http://localhost:8081">
     <t:binding.http uri="http://localhost:8081"/>
     <t:binding.jsonrpc uri="http://localhost:8081"/>
     <t:binding.atom uri="http://localhost:8081"/>
    </service>
   </component>
  </composite>
 </content>
</entry>

Note that in this example, http://localhost is used for the node's URI. If the node will be started on a machine different from the domain manager's host, then the host name of the machine where the node is run needs to be specified instead of localhost.

The sample Java code in Listing 7 posts the entry in Listing 6 to the domain.

String compositeName = "catalogs"; 
String contributionURI = "http://myws";
String compositeNamespace = "http://services";
String nodeName = "MyCatalogsNode";
String domainURL="http://localhost:9990";
String host = "localhost";
String port = "8081";
                                                            
String nodeIdEntry = "composite:" +
   "http://tuscany.apache.org/cloud" + ";" +
   "http://tuscany.apache.org/cloud" + ';' +  nodeName;
     
String addNodeEntry =  "<?xml version=\'1.0\' encoding=\'UTF-8\'?>"
  + "<entry xmlns=\"http://www.w3.org/2005/Atom\">"
  + "<id>" + nodeIdEntry + "</id>"
  + "<content type=\"text/xml\">"
  + "<composite xmlns=\"http://www.osoa.org/xmlns/sca/1.0\"\n"
  + "xmlns:t=\"http://tuscany.apache.org/xmlns/sca/1.0\"\n" 
  + "targetNamespace=\"http://tuscany.apache.org/cloud\"\n"
  + "xmlns:c=\""+ compositeNamespace + "\"\n"
  + "name=\""+nodeName + "\">\n\n"
  + "<component name=\"" +nodeName +"\">\n"
  + "<t:implementation.node uri=\""+contributionURI 
  + "\" composite=\"c:" + compositeName +"\"/>\n"
  + "<service name=\"Node\">"
  + "<binding.ws uri=\"http://"+host+":"+port+"\"/>\n"
  + "<t:binding.http uri=\"http://"+host+":"+port+ "\"/>\n"
  + "<t:binding.jsonrpc uri=\"http://"+host+":"+port+"\"/>\n"
  + "<t:binding.atom uri=\"http://"+host+":" + port +"\"/>\n </service>\n"
  + "</component>\n</composite>\n</content>\n</entry>"; 
         
try {
 post(domainURL+"/cloud", addNodeEntry);
} catch (Exception e) {
 e.printStackTrace();				
}

Start nodes

You can now start the nodes. There are several ways to start an SCA runtime node in Tuscany:

• Select a node and click Start from the UI shown above. This, however, doesn't work for remote nodes unless you have Tuscany run time running there.
• From a command line on the node's host, enter:
  
  java -jar <tuscany-install>/modules/tuscany-node2-launcher-1.3.1.jar <domainURL>/node-config/<nodeName>
  
  where <tuscany-install> is the directory where you installed your Tuscany distribution. For example, c:\tuscany-sca-1.3.1, <domainURL> is the URL of a domain manager, such as http://localhost:9990, and <nodeName> is the name of the node you entered when you created the node, for example, MyCatalogsNode. Because you're issuing the command on the host where the node is run, you can use localhost here, as shown in Listing 8.
• From the Java program, use the code in Listing 8.

import org.apache.tuscany.sca.node.launcher.LauncherException;
import org.apache.tuscany.sca.node.launcher.NodeLauncher;
import org.apache.tuscany.sca.node.SCANode2;

...

NodeLauncher nodeLauncher = NodeLauncher.newInstance();
String domainURL = "http://localhost:9990";  // could be read from input argument
String nodeName = "MyCatalogsNode";
SCANode2 node;
try {
 node = nodeLauncher.createNode(domainURL+"/node-config/"+nodeName);
 node.start();
} catch (LauncherException e) {
 System.out.println("Exception starting node");
 e.printStackTrace();
}
...

Note that the code in Listing 8 requires Tuscany libraries from the <tuscany-install>/lib directories to be added to the class path of your project.

Figure 13 shows the sample output from the start node command. In this output, the displayed URL of the node shows the actual host name where the node is run, while the Tuscany run time is installed in the c:\tuscany\tuscany-sca-1.3.1 directory.

Test the application

Now you can test the application in your Web browser. The application is running on the port that you selected when you added the node for store.composite. You called it MyStoreNode. For example, if you're running the application on your localhost, you can point your browser to it at http://localhost:8083/ui/store.html (see Figure 14).

You can now use the application to select items from your catalog, add them to your shopping cart, empty your cart, and check out.

Back to top

Conclusion

You've seen how to deploy an SCA application in an SCA domain using the Tuscany domain manager application. In this example, you ran the Tuscany run time in J2SE without a Web container or application server. For more complex configurations, an SCA domain can also include nodes that run IBM WebSphere Application Server, IBM WebSphere Process Server, Apache Geronimo, Apache Tomcat, or other application servers. A future related article will go further into detail about how you deploy composite applications to these different environments.

Resources

Learn

• Read the Getting Started with Tuscany guide for the steps to install the Tuscany distribution in Eclipse, set up Eclipse for Tuscany, create the store application, and test it in Eclipse.
  
  
• Check out the Apache Tuscany SCA Java Architecture Guide for a high-level view of Tuscany architecture, including details about basic concepts like contributions, composites, and nodes.
  
  
• Read the Apache Tuscany SCA User guide for a detailed explanation of SCA and Tuscany concepts.
  
  
• See the Open SOA SCA Resources for a number of papers describing various aspects of SCA specifications.
  
  
• Read the article "Getting to know the Atom Publishing Protocol, Part 1: Create and edit Web resources with the Atom Publishing Protocol" (developerWorks, Oct 2006), which provides an introduction to the Atom publishing protocol.
  
  
• Get sample code to post a string to a URL from The Java Developers Almanac 1.4.
  
  
• The SOA and Web services zone on IBM developerWorks hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
  
  
• Play in the IBM SOA Sandbox! Increase your SOA skills through practical, hands-on experience with the IBM SOA entry points.
  
  
• The IBM SOA Web site offers an overview of SOA and how IBM can help you get there.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  
• Browse for books on these and other technical topics at the Safari bookstore.
  
  
• Check out a quick Web services on demand demo.
  
  

Get products and technologies

• Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

About the authors

Alla Segal is an advisory software engineer for the Service Infrastructure Management team in the IBM TJ Watson Research Center. Her most recent project included exploring methods for automated deployment of multitenant SCA solutions into the cloud environment. Alla has over 15 years of experience in software design and development. She holds an MS in computer science from the University of Illinois at Urbana-Champaign.

Michael Beisiegel is a distinguished engineer with the IBM Software Group. He is responsible for SCA programming model development and has 19 years of experience in tools, integration technology, and programming models.

Jean-Sebastien Delfino is a senior technical staff member at the IBM Burlingame Lab. Currently, Jean-Sebastien is working on the SCA of the Apache Tuscany project. He has been working on SOA for more than five years as a technical lead on the IBM WebSphere Process Server team and previously on the IBM WebSphere Studio tooling team at the IBM Toronto Lab. Jean-Sebastien has over 15 years of experience in software development and system integration. Prior to joining IBM, he worked for Atos-Origin on a number of integration projects for European top companies in the banking, insurance, and telecom sectors, and various government agencies, including the European Commission.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Application packages
• Basic concepts
• Deployment steps
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

Rational Tester for SOA Quality is an automated web services testing and SOA testing tool that supports Web services SOAP, HTTP(S), JMS, WS-Security, UDDI, and RESTful standards.

---

• Try: The no-charge Rational Service Tester for SOA Quality helps quality assurance professionals validate web service based SOA application..
• Article: See the whats new with Rational Service Tester for SOA Quality, and its Generic Service Client, which provides a single client to interact with any SOA service type.
• Tutorial: Get hands-on experience with this Transport for SOAP feature tutorial using Rational Tester for SOA Quality.
• Buy: Rational Service Tester for SOA Quality

Dig deeper into SOA and Web services on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers