JavaTM Platform, Enterprise Edition (Java EE) 5 Technologies
Project Open ESB Starter Kit

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


XSLT Service Engine Overview


Contents

The following topics describe the XSLT Service Engine.

About the XSLT Service Engine
XSLT SE Features
Configuring the XSLT SE

About the XSLT Service Engine

The XSLT SE is a Java based transformation engine that is used to convert XML documents from one data format to another. The XSLT SE makes it easier for users to configure and expose XSL style sheets as web services. Using the XSLT SE requires no special knowledge of XSL, but rather allows any XSL style sheet to be deployed as a JBI Service Unit.

The XSLT Service Engine in and of itself does not perform any transformations. XSL style sheets implement a web service operation (as normally defined in a WSDL). When deployed as JBI Service Units (SUs), these SUs correspond to a service endpoint. Each endpoint is activated when the XSLT SU is deployed. In a sense, the XSLT SE is a “container” of XSL style sheets, each of which represents a service endpoint in the JBI environment.

The following steps highlight the life cycle of a typical message using the XSLT SE:

  1. The XSLT Service Unit (SU) is configured with service endpoint information.

  2. The SU is deployed, along with the XSL style sheet, to the JBI environment.

  3. The XSLT SE compiles the style sheet.

  4. A message arrives and the XSLT SE searches for the service endpoint responsible for handling the message.

  5. The message is transformed using the service endpoint's XSL style sheet

  6. A response is sent back using the NMR.

top


XSLT SE Features

The XSLT SE can support the following three Use Cases:

  • Request-Reply ("requestReplyService")
  • Invoke-Send ("filterOneWay")
  • Request-Invoke-Reply Chain ("filterRequestReply")

Request-Reply ("requestReplyService")

A standard request-reply scenario. An XML message request is transformed and the result is sent back to the original consumer of the XSLT endpoint. The sequence of events include:

  • XML message in
  • XSL transformation of message
  • Transformed result out

Invoke-Send ("filterOneWay")

A standard one-way invocation. An XML message request is transformed, and the result is sent (not to the original consumer but rather) to another endpoint in the JBI environment. The sequence of events include:

  • XML message in
  • XSL transformation of message
  • Transformed result out to third party

Request-Invoke-Reply Chain ("filterRequestReply")

A representation of the adapter pattern, this scenario applies two separate XSL transformations. This scenario is useful when there are two existing web services (having incompatible input and output) which must be integrated.

The first existing service acts as a consumer to the XSLT endpoint, sending a request. This message is transformed to match the input of the second service.

The second service is then invoked in an asynchronous manner. When the response from the second service arrives via the NMR, it is transformed to match the expected reply to the first (consuming) service. The sequence of events include:

  • XML message in
  • XSL transformation of message using first XSL style sheet
  • Invoke service, sending transformed message as input
  • Receive response from invoked service endpoint
  • XSL transformation of response using second XSL style sheet
  • Reply to original sender with transformed third party response

top


Configuring the XSLT SE

No special knowledge of XSL is required to configure an XSLT Service Unit. The only requirements are a WSDL configuration, an XSL style sheet, and the XSLT map configuration file.

The creation of the WSDL–defining the service, port type, and creating the binding information for the service definition–is a separate step from the XSLT map configuration file. Properly configuring an XSLT SU means understanding what pieces to migrate from the WSDL into the XSLT map file.

XSLT Projects contain a configuration file called xsltmap.xml. Most of the information needed to configure an XSLT Project as a JBI Service Unit is contained in a WSDL, which defines the operation an XSLT transformation is implementing. A sample configuration follows:

Use Case # 1

<xsltmap>
  <requestReplyService>
    <input partnerLink="{foo}pl0" 
      roleName="server" 
      portType="portType" 
      operation="operation" 
      messageType="{ns}msg-name" 
      file="map.xsl" 
      transformJBI="false" />
  </requestReplyService>


<-- Names partnerlink defined in deployed WSDL
<-- Matches partnerLink role name
<-- Matches partnerLink portType name
<-- Operation this transformation implements
<-- Identifies reply message definition in deployed WSDL
<-- The transformation applied to request
<-- See details below

 

Use Case # 2

<filterOneWay>
  <input partnerLink="{foo}pl1" 
    roleName="server"
    portType="portType" 
    operation="operation" 
    messageType="{ns}msg-name 
    file="map.xsl" />
    transformJBI="false" /> 
  <output partnerLink="{bar}pl2"
    roleName="client" 
    portType="outPortType" 
    operation="outOp" /> 
  </filterOneWay>


<-- Names partnerlink defined in deployed WSDL
<-- Matches partnerLink role name
<-- Matches partnerLink portType name
<-- Operation this transformation implements
<-- Identifies transformed message definition in deployed WSDL
<-- The transformation applied to request
<-- See details below
<-- Names partnerLink of operation to invoke
<-- Matches named partnerLink
<-- Matches portType of operation to invoke
<-- Operation to invoke/send transformed request

Use Case # 3

<filterRequestReply> 
  <input partnerLink="{foo}pl1" 
    roleName="server" 
    portType="portType" 
    operation="operation" 
    messageType="{ns}msg-name"
    file="map.xsl"
    transformJBI="false" />
  <output partnerLink="{bar}pl2"
    roleName="client"
    portType="outPortType"
    operation="outOp"
    messageType="{ns}msg-name"
    file="map2.xsl"
    transformJBI="false" />
  </filterRequestReply>
</xsltmap>


<-- Names partnerlink defined in deployed WSDL
<-- Matches partnerLink role name
<--Matches partnerLink portType name
<-- Operation this transformation implements
<-- Identifies transformed message definition in deployed WSDL
<-- The transformation applied to request
<-- See details below
<-- Names partnerLink of operation to invoke
<-- Matches named partnerLink
<-- Matches portType of operation to invoke
<-- Operation to invoke/send transformed request
<-- Identifies reply message definition in deployed WSDL
<-- Transformation applied to response from invoked operation
<-- See details below

 

The 'transformJBI' attribute

To support multiple-part WSDL 1.1 message definitions, the JBI specification defines an XML document format for “wrapping” WSDL 1.1 message parts. Since the XSLT Service Engine does not lend itself to transforming multiple message parts, the XSLT SE instead supports the transformation of the entire JBI message wrapper. To enable this transformation, the transformJBI attribute flag must be set to true; the default value is false if the attribute is not specified in the xsltmap.xml file.

It is important to note that when this attribute is set to true, the XSL style sheet MUST generate a properly formed JBI message wrapper document. Failure to do so will result in mishandled message exchanges. As noted in the Java Business Integration (JBI) 1.0 specification, the wrapping of message parts allows both consumer and provider to interact using this well-known mapping to a “wrapped doc-literal” form of the message that is used for normalized message content.

A wrapped literal document must conform to the schema given in the listing below.

default namespace jbi = "http://java.sun.com/xml/ns/jbi/wsdl-11-wrapper"
start =
element message {
attribute version { xsd:decimal },
attribute type { xsd:QName },
attribute name { xsd:nmtoken }?,
part*
}
part =
element part {
# part value
( (element* { text }) | text)
} 

See the Java Business Integration (JBI) 1.0 specification for additional information on the normalized message context schema for wrapper document for WSDL 1.1-defined messages.

The 'messageType' attribute

To eliminate the need of parsing the WSDL to determine the output message definition (as it is required in a JBI message wrapper), this attribute must be specified for all non-JBI transformations. That is, if the 'transformJBI' attribute is "false", then the 'messageType' attribute MUST be specified. The value of this attribute usually takes the form: {msg-def-ns}msg-def.

XSLT SE Component Limitations - Running the JBI Runtime Separately

Due to a dependency on the design-time XSLT project (part of the NetBeans IDE), XSLT service units used outside the NetBeans environment do not benefit from the functionality built into the XSLT project. Specifically, the generation of the SU's jbi.xml file and the creation of a distributable/deployable SU must be done manually.

 

top