Working With a Service Bridge XSL Transformation Service

Contents

• Overview
• Configuring the Tutorial Environment
• Creating the XSLT Module Project
• Importing WSDL and XSD Files
• Creating an XML Schema
• Creating a WSDL File
• Creating XSL Stylesheets
• Deploying the Composite Application
• Performing a Test Run of the XSL Transformation Service

Overview

In this tutorial you continue exploring the possibilities of the XSLT Designer included in NetBeans IDE 6.0. The XSLT Designer is used to develop, deploy and test XSL Transformation Services.

An XSL Transformation Service acts as a web service. It receives messages from an external client, transforms the messages in accordance with an XSL stylesheet, and either sends the messages back to the originator or forwards them to another web service.

In this tutorial you create, deploy and test an XSL Transformation Service of the Service Bridge type that receives a message from an external client, transforms the message, invokes another web service, receives a reply message, transforms it, and sends the message back to the original caller.

Prerequisites

This tutorial assumes that you have some basic knowledge of, or programming experience with, the NetBeans IDE.

This tutorial uses the XSL Transformation Service (HelloXSLTransformation) created in the XSLT Designer Quick Start Guide. Before starting this tutorial, ensure that you have successfully created, deployed and tested the HelloXSLTransformation Transformation Service as described in the XSLT Designer Quick Start Guide.

System Requirements

This tutorial assumes that your system meets the requirements specified in the System Requirements section of the NetBeans IDE 6.0 Release Notes.

Software Needed for the Tutorial

Before you begin, download and install the following software on your computer: NetBeans IDE 6.0. Select the Download All option. The Download All option includes SOA Pack and GlassFish V2, which are required for this tutorial.

Transformation Logic

The transformation process that you create in this tutorial is as follows:

1. Send a message to the Service Bridge XSL Transformation Service (HelloXSLTBridge) using the test driver.
2. The HelloXSLTBridge Transformation Service transforms the message and forwards it to the Request-Reply XSL Transformation Service (HelloXSLTransformation) created in the XSLT Designer Quick Start Guide.
3. The HelloXSLTransformation service transforms the message and sends it back to the HelloXSLTBridge service.
4. The HelloXSLTBridge service transforms the message and sends it to the original caller (the test driver).

The transformation logic is presented in the following diagram:

top

Configuring the Tutorial Environment

This tutorial requires that the GlassFish Application Server V2, which includes the JBI runtime, has been installed installed with NetBeans IDE 6.0. Additionally, the HelloXSLTCAP Service Assembly you created in the XSLT Designer Quick Start Guide is deployed and running.

Perform the following steps to confirm that GlassFish Application Server V2 has been installed and that the HelloXSLTCAP Service Assembly is deployed and running:

1. Open the Runtime window.
2. Expand the Servers node.
3. Right-click the GlassFish V2 node and choose Start form the pop-up menu.
   
   If the Start option is not available and there is a green “badge” next to the GlassFish V2 node, the server is already running.
4. After the server is started, expand the GlassFish V2 > JBI node. Then expand the Service Assemblies node and make sure HelloXSLTCAP Service Assembly is started.
   
   If a "down arrow" badge or "warning" badge appears next to the Service Assembly, the Service Assembly is either shutdown or stopped. In either case, right-click the Service Assembly and choose Start from the pop-up menu.
   
   

   

top

Creating the XSLT Module Project

To create an XSL Transformation Service, you must first create an XSLT Module project.

To create a new XSLT Module Project:

1. From the IDE's main menu, choose File > New Project.
2. Under Categories select SOA.
3. Under Projects, select XSLT Module.
4. Click Next.
   
   

   

5. In the Project Name field, type HelloXSLTBridge.
6. Modify the project location, or accept the default.
   
   

   

7. Click Finish. The Projects window now contains the HelloXSLTBridge project node.
   
   

   

Next you will import the two XML Schema files (HelloXSLTIncoming.xsd and HelloXSLTOutgoing.xsd) and a web service description file (HelloXSLTWSDL.wsdl) from the HelloXSLTransformation project, create a new XML Schema file (HelloXSLTBridgeIncoming.xsd), a new web service description file (HelloXSLTBridgeWSDL.wsdl), and two XSL stylesheet files (HelloXSLTBridgeRequest.xsl and HelloXSLTBridgeReply.xsl).

top

Importing WSDL and XSD Files

Import the WSDL and XSD files from the HelloXSLTransformation project and use them in the HelloXSLTBridge project.

To import WSDL and XSD files from the HelloXSLTransformation project:

1. In the Projects window, right-click HelloXSLTBridge > Transformation Files and choose New > Other from the pop-up menu.
2. In the New File dialog box, under Categories, select XML.
3. Under File Types, select External XML Schema Document(s). Click Next.
4. Select the From Local File System radio button and click the Browse button next to the input field to navigate to the src folder in the HelloXSLTransformation project folder.
   
   

   

5. Click Finish. Three files appear under HelloXSLTBridge > Transformation Files.
   
   

   

top

Creating an XML Schema

For the purpose of this tutorial, you will create one XML Schema: HelloXSLTBridgeIncoming.xsd. It will be used for the incoming message (message 1 in the diagram). For the outgoing message (message 4 in the diagram), you will re-use HelloXSLTOutgoing.xsd imported from the HelloXSLTransformation project.

To create the XML Schema:

1. In the Projects window, right-click the HelloXSLTBridge > Transformation Files node and choose New > XML Schema.
2. In the File Name field, type HelloXSLTBridgeIncoming.
3. Click Finish. A new node—HelloXSLTBridgeIncoming.xsd—appears under the Transformation Files node in the HelloXSLTBridge project and the new schema file opens in the Schema View of the XML schema editor.
   
   

   

4. In the first column of the Schema view, right-click the Elements node and choose Add Element from the pop-up menu. The Element dialog box opens.
5. In the Name field, type person.
6. Under Type, select the Inline Complex Type radio button.
7. Click OK.
   
   

   

   A new global schema element is added to the schema.
   
   

   

8. Add a local element to the person schema component by doing the following:
   1. In the first column of the Schema view, select the Elements node, then select the person node in the second column.
   2. Right-click and choose Add > Element from the pop-up menu.
   3. In the Element dialog box, in the Name field, type firstname.
   4. Under Type, select the Use Existing Type radio button.
   5. Expand the Built-in Types and select string.
   6. Click OK.
      The IDE adds the firstname local element to the schema.

   

9. Repeat step 8 to add another local element, lastname to the schema.
10. To view the source of the schema you created, click the Source button on the Editor toolbar. You should see the following code:

    <?xml version="1.0" encoding="UTF-8"?>
    
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                targetNamespace="http://xml.netbeans.org/schema/HelloXSLTBridgeIncoming"
                xmlns:tns="http://xml.netbeans.org/schema/HelloXSLTBridgeIncoming"
                elementFormDefault="qualified">
        <xsd:element name="person">
            <xsd:complexType>
                <xsd:sequence>
                    <xsd:element name="firstname" type="xsd:string"></xsd:element>
                    <xsd:element name="lastname" type="xsd:string"></xsd:element>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:element>
    </xsd:schema>

11. Click the Save All button on the toolbar.

Note: The XML Schema Editor is not the subject of this tutorial. For detailed information on the XML Schema Editor, see Getting Started With XML Schema Tools.

top

Creating a WSDL File

Now create a web service description file defining the web interface of our XSL Transformation Service.

To create a WSDL file:

1. In the Projects window, right-click the HelloXSLTBridge > Transformation Files node and choose New > WSDL Document.
2. In the File Name field, type HelloXSLTBridgeWSDL, then click Next.
3. Under Input, in the Element Or Type column, click the ellipsis (...) button. The Select Element Or Type dialog box opens.
4. Select By File > HelloXSLTBridge > src/HelloXSLTBridgeIncoming.xsd > Elements > person and click OK.
5. Under Output, in the Element Or Type column, click the ellipsis (...) button. The Select Element Or Type dialog box opens.
6. Select By File > HelloXSLTBridge > src/HelloXSLTOutgoing.xsd > Elements > greeting and click OK.
7. Click Next.
8. In the Binding Type Field, select SOAP.
9. Under Binding Subtype, select Document Literal, then click Finish.

You should see the HelloXSLTBridgeWSDL.wsdl file added to the Transformation Files node in the HelloXSLTransformation project.

Note: Creating and Editing WSDL files is not the subject of this tutorial. For detailed information, see Developer Guide to the WSDL Editor.

top

Creating XSL Stylesheets

An XSL stylesheet is an XML file that contains instructions about transforming the incoming message into the outgoing message.

An XSL Transformation Service of the service bridge type interacts with two external parties—the originator and the addressee—transforming messages going from the originator to the addressee, and, optionally, messages going in the reverse direction.

For the purpose of this tutorial, you will create an XSL Transformation Service that transforms messages going in both directions. In this case you need two XSL stylesheets: one for messages going from the originator to the addressee—HelloXSLTBridgeRequest.xsl, the other for messages going in the reverse direction—HelloXSLTBridgeReply.xsl.

To create the HelloXSLTBridgeRequest.xsl and HelloXSLTBridgeReply.xls XSL stylesheets:

1. In the Projects window, right-click the HelloXSLTBridge > Transformation Files node and choose New > XSLT Service.
2. Under Service Type, select Service Bridge. Click Next.
3. In the Operation drop-down list of the We Implement section, make sure that HelloXSLTBridgeWSDL.wsdl is selected.
4. In the Web Service drop-down list of the We Call section, select HelloXSLTBridgeWSDL.wsdl. Click Next.
5. In the XSL File field of the Transform Request section, replace the default name for the file with HelloXSLTBridgeRequest.xsl.
6. Select the Transform Reply checkbox.
7. In the XSL File field of the Transform Reply section, replace the default name for the file with HelloXSLTBridgeReply.xsl.

   
   
   Click to enlarge

8. Click Finish.

   The HelloXSLTBridgeRequest.xsl and HelloXSLTBridgeReply.xsl nodes appear under the Transformation Files node in the HelloXSLTBridge project. The HelloXSLTBridgeReply.xsl file opens in the Design view of the XSL Transformation Editor. The Design view Palette opens on the right.

   
   Click to enlarge

To edit the HelloXSLTBridgeRequest.xsl XSL Stylesheet:

1. In the Projects window, double-click HelloXSLTBridge > Transformation Files > HelloXSLTBridgeRequest.xsl.
   The HelloXSLTBridgeRequest.xsl file opens in the Design view of the XSL Transformation Editor. The Source tree pane located on the left side shows the person node with the firstname and lastname subnodes. The Destination tree pane located on the right side shows the name node.
2. In the Palette, expand the String section and drag the concat function onto the Transformations pane of the XSLT Design view.
3. In the Palette, under the String section, select the string-literal function and drag it to the Transformations pane. Double-click the return_string field to make it editable and press the Space key.
   Note: We will concatenate the content of the firstname and lastname nodes. Hence, we need to add a space between them.
4. Select the firstname element in the Source tree pane on the left, and drag the handle to the string1 row in the Concat function. An arrow snaps in place to indicate the flow.
5. Drag the handle on the right side of the String Literal function input field to the handle on the left side of the string2 row in the Concat function.
6. Select the lastname element in the Source tree pane on the left, and drag the handle to the string3 row in the Concat function.
7. Drag the return string handle to the name element in the Destination tree pane on the right. The Design view should now resemble the following:
   
   

   

8. Click the Source button on the Design view toolbar. You should see the following code:

   <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:ns1="http://xml.netbeans.org/schema/HelloXSLTBridgeIncoming" xmlns:ns="http://xml.netbeans.org/schema/HelloXSLTIncoming">
       <xsl:template match="/">
           <xsl:element name="ns:name">
               <xsl:value-of select="concat(/ns1:person/ns1:firstname, &apos; &apos;, /ns1:person/ns1:lastname)"/>
           </xsl:element>
       </xsl:template>
   </xsl:stylesheet>

9. Click the Save All button on the toolbar.

To edit the HelloXSLTBridgeReply.xsl XSL Stylesheet:

1. In the Projects window, double-click HelloXSLTBridge > Transformation Files > HelloXSLTBridgeReply.xsl.
   The HelloXSLTBridgeReply.xsl file opens in the Design view of the XSL Transformation Editor. The Source tree and Destination tree panes both show the greeting node. This is because we use the same XML Schema for the incoming and the outgoing messages.
2. In the Palette, expand the String section and drag the concat function onto the Transformations pane of the XSLT Design view.
3. In the Palette, under the String section, select the string-literal function and drag it to the Transformations pane. Double-click the return_string field to make it editable and type ", how are you doing?" (without quotes).
4. Select the greeting element in the Source tree pane on the left, and drag the handle to the string1 row in the Concat function. An arrow snaps in place to indicate the flow.
5. Drag the handle on the right side of the String Literal function input field to the handle on the left side of the string2 row in the Concat function.
6. Drag the return string handle to the greeting element in the Destination tree pane on the right. The Design view should now resemble the following:
   
   

   

7. Click the Source button on the Design view toolbar. You should see the following code:

   <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:ns1="http://xml.netbeans.org/schema/HelloXSLTOutgoing">
       <xsl:template match="/">
           <xsl:element name="ns1:greeting">
               <xsl:value-of select="concat(/ns1:greeting, &apos;, how are you doing?&apos;)"/>
           </xsl:element>
       </xsl:template>
   </xsl:stylesheet>

8. Click the Save All button on the toolbar.

The HelloXSLTBridge project is now properly configured and contains all necessary artifacts to be deployed.

top

Deploying the Composite Application

An XSLT project is not directly deployable. You must first add an XSLT project as a JBI module to a Composite Application project before you can deploy the Composite Application project. Deploying the project makes the service assembly available to the application server, thus allowing its service units to be run.

You already have a Composite Application—HelloXSLTCAP— that you used to deploy the HelloXSLTransformation project. You can use it to deploy the HelloXSLTBridge project.

To add a JBI module:

1. Right-click the HelloXSLTCAP node and choose Add JBI Module from the pop-up menu.
2. Select the HelloXSLTBridge project and click Add Project Jar Files.
3. To verify that the JBI module has been added, expand HelloXSLTCAP > JBI Modules. Notice that there are two JBI Modules: HelloXSLTBridge.jar and HelloXSLTransformation.jar.
   
   

   

To deploy the HelloXSLTCAP Composite Application:

1. In the Projects window, right-click the HelloXSLTCAP node and choose Deploy Project from the pop-up menu.
2. To verify that the project has been deployed, expand Sun Java System Application Server 9 > JBI > Service Assemblies in the Runtime window. You should see the HelloXSLTCAP node.
3. Expand the HelloXSLTCAP node. Notice that it has three subnodes: one for each of the XSL Transformation Services and one for the Binding Component.
   
   

   

top

Performing a Test Run of the XSL Transformation Service

Testing an XSL Transformation Service means sending a message that the Service is expecting and receiving a reply message.

Before we can perform the testing, we must create a test case.

To create a test case:

1. In the Projects window, expand the HelloXSLTCAP node and right-click the Test node.
2. From the pop-up menu, select New Test Case.
3. In the Test Case Name field, type TestBridge. Click Next.
4. Under Select the WSDL Document, expand HelloXSLTBridge - XSLT Process Files and select HelloXSLTBridgeWSDL.wsdl. Click Next.
5. Under Select the Operation to Test, expand HelloXSLTBridgeWSDLBinding and select HelloXSLTBridgeWSDLOperation. Click Finish.
   The TestBridge node appears under HelloXSLTCAP > Test and the input message file—Input.xml—opens in the editor.
6. In the Input.xml, modify the

   <hel:person>
      <hel:firstname>?string?</hel:firstname>
      <hel:lastname>?string?</hel:lastname>
   </hel:person>

   lines to

   <hel:person>
      <hel:firstname>John</hel:firstname>
      <hel:lastname>Smith</hel:lastname>
   </hel:person>

   The Input.xml file should be:

   <soapenv:Envelope xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/ http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:hel="http://xml.netbeans.org/schema/HelloXSLTBridgeIncoming">
     <soapenv:Body>
       <hel:person>
         <hel:firstname>John</hel:firstname>
         <hel:lastname>Smith</hel:lastname>
       </hel:person>
     </soapenv:Body>
   </soapenv:Envelope>

7. Click the Save All button on the toolbar.

The Output node under the test case node refers to the expected reply message that is used for comparison with the actual reply messages. Before we run the test for the first time, the Output.xml file is empty. We will populate it with the content of the reply message (provided that it is what we expect).

To run the test:

1. Right-click the TestBridge node and select Run. Notice that the test fails and the Overwrite Empty Output dialog box appears.
2. Click Yes. Notice that the failed test node appears below the Output node.
3. Double-click the failed test node to see the message that the XSL Transformation Service sent back:

   <?xml version="1.0" encoding="UTF-8"?>
   <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <SOAP-ENV:Body>
       <ns1:greeting xmlns:ns1="http://xml.netbeans.org/schema/HelloXSLTOutgoing">Hello John Smith, how are you doing?</ns1:greeting>
     </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

   Notice the line

    <ns1:greeting xmlns:ns1="http://xml.netbeans.org/schema/HelloXSLTOutgoing">Hello John Smith, how are you doing?</ns1:greeting>
                   

   The message has returned completing the full cycle. Both of our XSL Transformation Services work!
4. Run the test again. The test is marked as passed.

Congratulations! You have successfully created, deployed and tested an XSL Transformation Service of the Service Bridge type.

top