Building Composite Applications

Sang Shin, sang.shin@sun.com, Sun Microsystems, www.javapassion.com/webservices



In this lab, you are going to build a simple composite applications step by step.  The hands-on labs were created based on Developing a Hello World Composite Application tutorial from netbeans.org from netbeans.org.

Expected duration: 60 minutes (excluding homework)



Software Needed


OS platforms you can use

Change Log


Things to do (by Sang Shin)


Lab Exercises



Exercise 1: Create BPEL Module project and a simple Composite Application


Acknowlegement: This exercise is based on the  Developing a Hello World Composite Application tutorial from netbeans.org.

In this exercise, you create a simple BPEL Module project called SynchronousSample and a Composite Application project called SynchronousSampleApplication. This exercise illustrates how to design a simple XML schema file, a simple WSDL file, and a BPEL file. You learn how to design a BPEL process and deploy. You also learn how to create and perform a test run of a composite application. The process is a simple BPEL process that echoes back the input message. The BPEL process returns the result to the client synchronously. A client starts the BPEL process by invoking a request-response operation. The client is blocked until the process finishes and returns the result. The project includes WSDL and XML schema files, and input files for testing.

This exercise is intended to be the first step towards building a more complex composite application.

  1. Create a "BPEL Module" NetBeans project
  2. Create XML Schema
  3. Create WSDL document
  4. Create BPEL process
  5. Create a "Composite Application" NetBeans project
  6. Deploy the Composite application
  7. Test the Composite application
  8. Debug the Composite application


(1.1) Create a "BPEL Module" NetBeans project

0. Start NetBeans IDE. 
1. Create SynchronousSample NetBeans project.


Figure-1.11: Create BPEL Module

Figure-1.12: Name and Location
                                                                                                             return to top of the exercise


(1.2)  Create XML Schema


1. Create SynchronousSample.xsd.

Figure-1.21: Select Other

Figure-1.22: Create XML Schema

Figure-1.23: Name and Location

2. Add a Complex Type to the XML schema.

Figure-1.24: Display Palette (if it has not been displayed)

Figure-1.25: Add a Complex Type to the schema

3. Add a local element to simpleProcess complex type

Figure-1.26: Add a local element to the complex type

Figure-1.27: Display Properties window

Figure-1.28: Select a definition of the element

Figure-1.29: Expand Built-in Types

Figure-1.30: Select string



Figure-1.31: paramA has string as a definition

Figure-1.32:Display  XML schema

4. Add a global element to the schema.

Figure-1.33: Add a global element

Figure-1.34: typeA global element



Figure-1.35: Select simpleProcess as a definition

Figure-1.36: typeA global element is type of simpleProcess complex type

5. Save all the changes.

Figure-1.37: Save all the changes

6. Display and study the XML schema file.

<?xml version="1.0" encoding="UTF-8"?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            targetNamespace="http://xml.netbeans.org/schema/SynchronousSample"
            xmlns:tns="http://xml.netbeans.org/schema/SynchronousSample"
            elementFormDefault="qualified">
    <xsd:complexType name="simpleProcess">
        <xsd:sequence>
            <xsd:element name="paramA" type="xsd:string"/>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:element name="typeA" type="tns:simpleProcess"/>
</xsd:schema>
Code-1.38: XML schema file




                                                                                                             return to top of the exercise


(1.3)  Create WSDL document


In this step, you are going to create a WSDL document of the Web services that represents the BPEL process.  (BPEL process, to its client, is a Web service, which means BPEL process has to have its own WSDL document.)

1. Create WSDL Document.

Figure-1.39: Create WSDL document

Figure-1.40: Name and Location

Figure-1.41: Add Import

Figure-1.42: Name and Location

Figure-1.43:  Abstract Configuration

Figure-1.44: Select Element Or Type

Figure-1.45: Abstract Configuration - Input

Figure-1.46: Abstract Configuration - Output

Figure-1.47: Document Literal

Figure-1.48: SynchronousSample.wsdl
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="SynchronousSample" targetNamespace="http://j2ee.netbeans.org/wsdl/SynchronousSample"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns="http://xml.netbeans.org/schema/SynchronousSample" xmlns:plnk="http://docs.oasis-open.org/wsbpel/2.0/plnktype" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://j2ee.netbeans.org/wsdl/SynchronousSample">
    <types>
        <xsd:schema targetNamespace="http://j2ee.netbeans.org/wsdl/SynchronousSample">
            <xsd:import namespace="http://xml.netbeans.org/schema/SynchronousSample" schemaLocation="SynchronousSample.xsd"/>
        </xsd:schema>
    </types>
    <message name="SynchronousSampleOperationRequest">
        <part name="inputType" element="ns:typeA"/>
    </message>
    <message name="SynchronousSampleOperationReply">
        <part name="resultType" element="ns:typeA"/>
    </message>
    <portType name="SynchronousSamplePortType">
        <wsdl:operation name="SynchronousSampleOperation">
            <wsdl:input name="input1" message="tns:SynchronousSampleOperationRequest"/>
            <wsdl:output name="output1" message="tns:SynchronousSampleOperationReply"/>
        </wsdl:operation>
    </portType>
    <binding name="SynchronousSampleBinding" type="tns:SynchronousSamplePortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="SynchronousSampleOperation">
            <soap:operation/>
            <wsdl:input name="input1">
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output name="output1">
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
    </binding>
    <service name="SynchronousSampleService">
        <wsdl:port name="SynchronousSamplePort" binding="tns:SynchronousSampleBinding">
            <soap:address location="http://localhost:18181/SynchronousSampleService/SynchronousSamplePort"/>
        </wsdl:port>
    </service>
    <plnk:partnerLinkType name="SynchronousSample1">
        <!-- A partner link type is automatically generated when a new port type is added. Partner link types are used by BPEL processes.
In a BPEL process, a partner link represents the interaction between the BPEL process and a partner service. Each partner link is associated with a partner link type.
A partner link type characterizes the conversational relationship between two services. The partner link type can have one or two roles.-->
        <plnk:role name="SynchronousSamplePortTypeRole" portType="tns:SynchronousSamplePortType"/>
    </plnk:partnerLinkType>
</definitions>

Figure-1.50: Partner

                                                                                                             return to top of the exercise


(1.4) Create BPEL process


          In this step, you are going to create SynchronousSample.bpel.

1. Create a empty SynchronousSample.bpel.

Figure-1.51: Ceate BPEL Process

Figure-1.52: Name and Location

Figure-1.53: BPEL design mode

2.  Add a partner link.

Figure-1.54: Drag SynchronousSample.wsdl to the design view (if you are using NetBeans 6.1)

Figure-1.56: Fit diagram

3. Add a Receive activity

Figure-1.57: Add Receive BPEL activity

Figure-1.58: Receive1 is added

Figure-1.59: Receive1 Property Editor

Figure-1.60: New Input Variable

Figure-1.61: Property Editor

Figure-1.62: Receive activity is added
<?xml version="1.0" encoding="UTF-8"?>
<process
    name="SynchronousSample"
    targetNamespace="http://enterprise.netbeans.org/bpel/SynchronousSample/SynchronousSample"
    xmlns="http://docs.oasis-open.org/wsbpel/2.0/process/executable"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:tns="http://enterprise.netbeans.org/bpel/SynchronousSample/SynchronousSample"
    xmlns:ns1="http://j2ee.netbeans.org/wsdl/SynchronousSample">
    <import namespace="http://j2ee.netbeans.org/wsdl/SynchronousSample"
                 location="SynchronousSample.wsdl"
                 importType="http://schemas.xmlsoap.org/wsdl/"/>
    <partnerLinks>
        <partnerLink name="PartnerLink1"
                             partnerLinkType="ns1:SynchronousSample1"
                             myRole="SynchronousSamplePortTypeRole"/>
    </partnerLinks>
    <variables>
        <variable name="inputVar" messageType="ns1:SynchronousSampleOperationRequest"/>
    </variables>
    <sequence>
        <receive name="start"
                      createInstance="yes"
                      partnerLink="PartnerLink1"
                      operation="SynchronousSampleOperation"
                      portType="ns1:SynchronousSamplePortType"
                      variable="inputVar"/>
    </sequence>
</process>
Code-1.63: SynchronousSample.bpel



4. Add a Reply activity

Figure-1.64: Add Reply Activity

Figure-1.65: Property Editor

Figure-1.66: New Output Variable



Figure-1.67: Reply activity is added
<?xml version="1.0" encoding="UTF-8"?>
<process
    name="SynchronousSample"
    targetNamespace="http://enterprise.netbeans.org/bpel/SynchronousSample/SynchronousSample"
    xmlns="http://docs.oasis-open.org/wsbpel/2.0/process/executable"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:tns="http://enterprise.netbeans.org/bpel/SynchronousSample/SynchronousSample"
    xmlns:ns1="http://j2ee.netbeans.org/wsdl/SynchronousSample">
    <import namespace="http://j2ee.netbeans.org/wsdl/SynchronousSample" location="SynchronousSample.wsdl"
                 importType="http://schemas.xmlsoap.org/wsdl/"/>
    <partnerLinks>
        <partnerLink name="PartnerLink1"
                             partnerLinkType="ns1:SynchronousSample1"
                             myRole="SynchronousSamplePortTypeRole"/>
    </partnerLinks>
    <variables>
        <variable name="outputVar" messageType="ns1:SynchronousSampleOperationReply"/>
        <variable name="inputVar" messageType="ns1:SynchronousSampleOperationRequest"/>
    </variables>
    <sequence>
        <receive name="start"
                      createInstance="yes"
                      partnerLink="PartnerLink1"
                      operation="SynchronousSampleOperation"
                      portType="ns1:SynchronousSamplePortType"
                      variable="inputVar"/>
        <reply name="end"
                    partnerLink="PartnerLink1"
                    operation="SynchronousSampleOperation"
                    portType="ns1:SynchronousSamplePortType"
                    variable="outputVar"/>

    </sequence>
</process>
Code-1.68: Interim SynchronousSample.bpel



5. Add an Assign activity

Figure-1.69: Ass Assign activity



Figure-1.70:  Assign activity is added
<?xml version="1.0" encoding="UTF-8"?>
<process
    name="SynchronousSample"
    targetNamespace="http://enterprise.netbeans.org/bpel/SynchronousSample/SynchronousSample"
    xmlns="http://docs.oasis-open.org/wsbpel/2.0/process/executable"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:tns="http://enterprise.netbeans.org/bpel/SynchronousSample/SynchronousSample"
    xmlns:ns1="http://j2ee.netbeans.org/wsdl/SynchronousSample" 
    xmlns:ns0="http://xml.netbeans.org/schema/SynchronousSample">
    <import namespace="http://j2ee.netbeans.org/wsdl/SynchronousSample"
                 location="SynchronousSample.wsdl" importType="http://schemas.xmlsoap.org/wsdl/"/>
    <partnerLinks>
        <partnerLink name="PartnerLink1" partnerLinkType="ns1:SynchronousSample1"
                             myRole="SynchronousSamplePortTypeRole"/>
    </partnerLinks>
    <variables>
        <variable name="outputVar" messageType="ns1:SynchronousSampleOperationReply"/>
        <variable name="inputVar" messageType="ns1:SynchronousSampleOperationRequest"/>
    </variables>
    <sequence>
        <receive name="start" createInstance="yes" partnerLink="PartnerLink1"
                      operation="SynchronousSampleOperation"
                      portType="ns1:SynchronousSamplePortType" variable="inputVar"/>
        <assign name="Assign1">
            <copy>
                <from>$inputVar.inputType/ns0:paramA</from>
                <to>$outputVar.resultType/ns0:paramA</to>
            </copy>
        </assign>
        <reply name="end" partnerLink="PartnerLink1" operation="SynchronousSampleOperation"
                   portType="ns1:SynchronousSamplePortType" variable="outputVar"/>
    </sequence>
</process>
Code-1.71: SynchronousSample.bpel

So far, what you have done is to create BPEL module project.  This BPEL module needs to be added to a Composite application before it can be deployed and executed, which you will do in the subsequent steps.

                                                                                                             return to top of the exercise


(1.5) Create a "Composite Application" NetBeans project


In this step, you are going to creates an empty Composite Application project, which may include multiple BPEL Modules and other types of Java Business Integration (JBI) modules.

1. Create an empty Composite Application

Figure-1.81: Create Composite Application

Figure-1.82: Name and Location

2. Add JBI Modules

Figure-1.83: Add JBI Module

Figure-1.84: Add Project JAR Files

Figure-1.85: JBI Module is added to the Composite Application


                                                                                                             return to top of the exercise


(1.6) Deploy the Composite application


1. Right click SynchronousSampleApplication project node and select Deploy.  (Figure-1.91 below)


Figure-1.91: Deploy the application

2. Observe that the "BUILD SUCCESSFUL  (total time: 4 seconds)" message gets displayed in the Output window. (Figure-1.92 below)


Figure-1.92: Observe that the application is deployed

3. Verify the Composite application is deployed.

Figure-1.93: SynchronousSampleApplication


                                                                                                             return to top of the exercise


(1.7) Test the Composite application


You can enhance the Composite Application project by adding test cases, binding to the operation, supplying input, and then using the Tester.

1. Right click Test under SynchronousSampleApplication project node and select New Test Case. (Figure-1.95 below)


Figure-1.95: New Test Case

2. Observe that the New Test Case dialog box appears.
3. Click Next.  (Figure-1.96 below)


Figure-1.96: Enter the Test Case Name

4. Observe that the Select the WSDL Document pane appears.
5. Expand SynchronousSample - Source Pacakges and select SynchronousSample.wsdl.
6. Click Next. (Figure-1.97 below)


Figure-1.97: Select the WSDL Document

7.  Observe that the Select the Operation to Test pane appears.
8.  Select SynchronousSampleOperation.
9.  Click Finish. (Figure-1.98 below)


Figure-1.98: Select the Operation to Test

10. Double click Input under Test->TestCase1 to open in the source editor.
11. Change the ?string? to Hello World.  (Figure-1.99 below)


Figure-1.99: Change string

12. Right click TestCase1 and select Run. (Figure-1.100 below)


Figure-1.100: Run the Test case

13.  Observe that the Overwrite Empty Output? dialog box appears,
14.  Click Yes. (Figure-1.101 below)


Figure-1.101: Confirmation

15.  Observe that the Output.xml is filled with the SOAP response message.  You will also note that the Output window indicates a failure.  This is expected since for the first test, there was no Output.xml defined. From the subsequent steps, it will result in a success since we defined the Output.xml in the previous step. (Figure-1.102 below)


Figure-1.102: Output.xml

16.  Right click TestCase1 and select Run. (Figure-1.103 below)


Figure-1.103: Run the TestCase1

17. Observe that the test is passed. (Figure-1.104 below)


Figure-1.104: TestCase1 passed
                                                                                                             return to top of the exercise



(1.8) Debug the Composite application


1. Make a break point in the BPEL process.

Figure-1.81: Make a breakpoint

2. Change the timeout value (from 30 seconds to 200 seconds)

Figure-1.82: Display Properties of TestCase1

Figure-1.83: Change timeout value

3. Run the BPEL process in the Debug mode.

Figure-1.84: Debug the TestCase`1

Figure-1.85: Breakpoint is hit

4. Finish the test.

Figure-1.86: Finish the test
                                                                                                                        return to top of the exercise


Summary

In this exercise,  you have built  a simple "Hello World" composite application in which a BPEL process which receives a request message and echos it back to the client is included.

                                                                                                                        return to the top



Homework Exercise (for people who are taking Sang Shin's "Web Services & SOA Programming online course")



1. The homework is to build a composite application as following:
Hint: Provided by one of the attendees of this course. (Thanks, Tim)

"One of your provided links, A Simple Synchronous BPEL Process, http://www.netbeans.org/kb/55/synchronousample.html,
has an excellent example of how to receive data, manipulate it and return it.  There is even a screen shot of how to hook things up.
In fact, it is the solution to the homework exercise.  Here is an excerpt:

3 Select new Assign2 activity.
4 From the Method Palette of the Mapper, click String method and select the concat Concat from the String drop-down list. The concat method appears in the middle portion of the Editor.
5 Double-click the first field in the concat box and type Hello followed by space in the first string. Press the Enter key.
6 From the left side of the Mapper, expand inputVar > inputType.
7 Drag paramA onto the string2 part of the concat method, the second field.
8 From the right of the Mapper, expand outputVar > resultType.
9 Drag the return string from the concat method onto the paramA under outputVar > resultType. This concatenates the string Hello to the input and copies the statement into the output."

2. Send the following files to  webserviceshomework@sun.com with Subject as WebServices-wscompositeapps.

                                                                                                                        return to the top