This topic contains sections marked as revised for this release

WebSphere Message Brokers
File: ac12490_
Writer: Terry Cowling

Reference topic

This build: July 31, 2007 21:18:28

XSLTransform node

The XSLTransform node transforms an XML message to another message, according to the rules provided by an XSL style sheet.

Start of changeThis node was formerly known as the XMLTransformation node.End of change

This topic contains the following sections:

Purpose

Start of changeUse the XSLTransform node to transform an XML message to another form of message, according to the rules provided by an XSL (Extensible Stylesheet Language) style sheet, and to set the message domain, message set, message type, and message format for the generated message.End of change

You can specify the location of the style sheet to apply to this transformation in three ways:

  • Use the content of the XML data within the message itself to transform the message according to a style sheet that the message itself defines.
  • Set a value within the LocalEnvironment folder. You must set this value in a node that precedes the XSLTransform node (for example, a Compute node). You can therefore use a variety of inputs to determine which style sheet to use for this message, such as the content of the message data, or a value in a database.
  • Use node properties to ensure that the transformation that is defined by this single style sheet is applied to every message that is processed by this node.

An XSLT (Extensible Stylesheet Language for Transformations) compiler is used for the transformation if the style sheet is not embedded within the message, and the node cache level (node property Stylesheet Cache Level) is greater than zero. If the XSLT is cached, the performance is improved because the XSLT is not parsed every time it is used.

If the prologue of the input message body contains an XML encoding declaration, the XSLTransform node ignores the encoding, and always uses the CodedCharSetId in the message property folder to decode the message.

The XSLTransform node is contained in the Transformation drawer of the palette, and is represented in the workbench by the following icon:

XMLTransformation node icon

Using this node in a message flow

For an example of how to use this node, consider two news organizations that exchange information on a regular basis. One might be a television station, the other a newspaper. Although the information is similar, the vocabulary that is used by the two is different. This node can transform one format to the other by applying the rules of the specified style sheet. If you specify the style sheet in the message (either the XML data or the LocalEnvironment), the same node can perform both transformations.

Look at the following sample for more details about how to use the XSLTransform node: You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.
Start of changeThis node searches for the name of the style sheet to be used by interrogating, in the following order:
  1. The input message. The node searches the message XML data for information about the location of the style sheet. For example, the XML data might contain:
    <?xml-stylesheet type="text/xsl" href="foo.xsl"?>
    and "foo.xsl" would then be used as the name of the style sheet.
  2. The LocalEnvironment. If no style sheet name is found in the input message, the node searches the LocalEnvironment that is associated with the current message for style sheet information stored in an element called XSL.StyleSheetName.

    This node was available in Version 5.0 and Version 6.0, and element ComIbmXslXmltStylesheetname was used for the name of the style sheet, therefore the current node checks both elements. If both are present, the value in XSL.StyleSheetName takes precedence.

  3. The node's properties. If no style sheet name is found in the input message or LocalEnvironment, the node uses the Stylesheet Name and Stylesheet Directory properties to determine the correct values.
End of change
Start of changeThe node searches for the character set to use for the output message by interrogating, in the following order:
  1. The LocalEnvironment. The node searches the LocalEnvironment that is associated with the current message for character set information stored in an element called XSL.OutputCharSet; for example, to encode the output of the transformation as UTF-8, enter the value 1208 as a string in this element.

    This node was available in Version 5.0 and Version 6.0, and element ComIbmXslXmltOutputcharset was used for the output character set, therefore the current node checks both elements. If both are present, the value in XSL.OutputCharSet takes precedence.

  2. The node's properties. If no character set information is found in the LocalEnvironment, the node uses the Output Character Set property to determine the correct value.

    If you set a value for Output Character Set, the value that you enter must be numeric; for example, to encode the output of the transformation as UTF-16, enter 1200.

If the node cannot determine the output character set from either of these two sources, because either no value is set or the selection priorities are set to zero, the default value of 1208 (UTF-8) is used. End of change

The XMLNSC parser discards certain information in XML documents, such as processing instructions and comments, if you do not set properties to retain this information in a preceding node. To ensure that the XSLTransform node transforms the message correctly, set the Retain Mixed Content, Retain Comments, and Retain Processing Instructions properties correctly on the preceding node (for example, an MQInput node). The MRM parser also discards this information, but you cannot retain information for this parser, therefore avoid using the MRM domain if such information is vital to your transformation.

Deployed and non-deployed style sheets

You can use style sheets in two different ways with the XSLTransform node:
Deployed style sheets
Deployed style sheets are style sheets that you import into a broker archive (bar) file and deploy to target systems. Deployed style sheets are managed by the broker. A principal style sheet is the root style sheet that is referenced in a message flow; for example, a reference to a principal style sheet in the Eclipse workspace, C:\\project1\a\b.xsl must be specified as a/b.xsl (or ./a/b.xsl). A principal style sheet can reference (include or import) its descendent style sheets.
Non-deployed style sheets
Non-deployed style sheets are style sheets that you store in a location where the XSLTransform node can access them. Non-deployed style sheets are not managed by the broker.
For more information, refer to Migrating style sheets and XML files from Version 5.0.

Deployment of deployed style sheets or XML files

Before you can configure the XSLTransform node, you must understand how to work with style sheets. A style sheet can refer to another XML file as well as a style sheet. To use deployed style sheets or XML files:
  1. Make sure that the files have the correct file name extensions.

    Style sheets that are to be deployed must have either .xsl or .xslt as their file extension, and XML files to be deployed must have .xml as their file extension.

  2. Import the files into the Eclipse workspace.

    Import into an Eclipse workspace project all style sheets and XML files that are to be deployed. Put location-dependent descendant style sheets, or XML files that are to be deployed, in the correct directory structure relative to their parent style sheets. Do not put in the Eclipse workspace location-dependent descendants that you do not want to deploy.

  3. Make sure that all references to the files are relative.

    Generally, all references to a deployed style sheet must be made relative, no matter where they appear. A reference to a principal style sheet must be made relative to the root of the relevant Eclipse workspace project.

    The only exception is when you specify a principal style sheet as the Stylesheet Name property on an XSLTransform node; you can use an absolute path that points to the correct directory structure in the Eclipse workspace. If the principal style sheet is found, the system resets the node property automatically to the correct relative value.

    The system also performs an automatic deployment of the principal style sheet, together with all of its location-dependent descendant style sheets that are available in the relevant Eclipse workspace project. All references to the location-dependent descendant style sheets (or XML files) of a principal style sheet must be made relative to the location of their parent style sheets. For example, if style sheet //project1/a/b.xsl references style sheet //project1/a/c/d.xsl, the reference must be changed to c/d.xsl (or ./c/d.xsl).

  4. Handle non-deployed child style sheets or XML files.

    Style sheets can refer to other style sheets. If you have a relatively-referenced child style sheet (or XML file) that is not to be deployed, yet its parent is, make sure that the child style sheet is placed in the correct location under workpath/XSL/external (workpath/XML/external), where workpath is the full path to the working directory of the broker.

    A broker automatically associates the execution group deployed storage tree, workpath/XSL/external, and workpath/XML/external tree, together. Therefore if, for example, the document b/c.xml is not found in the broker’s deployed storage, the broker automatically searches for a reference to it in the workpath/XML/external/a/b directory in the deployed principal style sheet a/style.xsl. Relative path references must also be used for files that have been deployed but which are not available in the workspace.

  5. Deploy the files.

    Deploy manually only those style sheets or XML files that are not picked up by the system (the Message Broker Toolkit provides warnings about these files). If you click Browse for the node, or provide the full path of the location of the style sheet in the Eclipse workspace, the style sheet is included automatically in the bar file.

    To deploy manually, add the files to be deployed to a broker archive. For more information refer to Adding files to a broker archive and Adding keywords to XSL style sheets.

    For every execution group that uses the XSLTransform node, perform one of the following actions:
    • Include the style sheet in the workpath/XSL/external directory on the broker; do not include the style sheet in the bar file.

      If a style sheet in the workpath/XSL/external directory shares the same path and name with a deployed style sheet, the deployed style sheet is used.

    • Include the style sheet in the bar file and deploy the bar file. If multiple bar files include the same style sheet name, the style sheet from the last bar file that was deployed is used.
    • Deploy the style sheet in its own bar file. If the bar files use XSLTransform nodes, but do not include the style sheet, the Message Broker Toolkit issues warning messages.

Configuring the XSLTransform node

When you have put an instance of the XSLTransform node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view.

All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

Configure the XSLTransform node:

  1. Optional: On the Description tab, enter a short description, a long description, or both. You can also rename the node on this tab.
  2. On the Stylesheet tab, to specify a non-deployed style sheet using node properties, enter the required value for Stylesheet Name.
    Specify a principal style sheet using one of the following methods:
    • Click Browse next to the Stylesheet Name property. The identified principal style sheet and all its relatively-referenced descendant style sheets are added automatically to the bar file when you add a message flow to a bar file (as long as both they and their parent style sheets are available).
    • To identify an already deployed, or ready to be deployed, style sheet, use the Stylesheet Name property, and leave the Stylesheet Directory property blank.
    • In the Message Flow editor, drag an .xslt file onto the XSLTransform node; the Stylesheet Name is set automatically.
  3. Start of changeOn the Output Message Parsing tab:
    1. To use a different parser associated with the message, specify the new domain in Message Domain:
      • MRM
      • Start of changeSOAPEnd of change
      • XMLNS
      • Start of changeDataObjectEnd of change
      • XMLNSC
      • JMSMap
      • JMSStream
      • MIME
      • BLOB
      • IDOC
      • XML
      • inherit

      You can also specify a user-defined parser if appropriate.

      If the domain is either XMLNS or XMLNSC as a result of being set explicitly or having been inherited from the input node, and the style sheet defines the output as XML (achieved by coding <xsl:output method="xml"), the output message is generated directly as a message tree. In all other cases, a bit stream is generated.

    2. If the MRM domain is selected, specify the other properties of the model that are to be associated with the output message.
      1. Enter the message set in Message Set. Choose a value from the list of available message sets (the name and identifier of the message set are shown).
      2. Enter the identifier of the message in Message Type. You can find this identifier in the properties of the message in the editor view. You specified the message identifier when you created the message. Enter the identifier exactly as shown in the message properties.
      3. Enter the format of the message in Message Format. This property specifies the wire format for the MRM parser. You can select one of the formats from the list (which lists the identifiers of those formats that you have defined on the message set specified above).

      These properties set the domain, set, type, and format that you want in the message header of the output message. However, these actions are taken only if suitable headers already exist in the input message. If the input message does not have an MQRFH2 header, the node does not create one.

      Leave Message Set, Message Type, and Message Format blank if you have specified the XML, JMS, MIME, or BLOB parser.

    End of change
  4. On the Advanced tab:
    1. If the style sheet identification is fully qualified, Stylesheet Directory is ignored; otherwise, the value that you set in this property is added to the beginning of the specification, regardless of where it is found.
    2. In Stylesheet Cache Level, specify the number of compiled or parsed style sheets that are stored in this instance of the node; the default value is 5. The style sheet cache is retained for the life of the node, and is cleared when the node is deleted from the flow, when the flow is deleted, or when the execution group is stopped.

      If you change a cached style sheet (by redeploying or replacing the file in the file system), the XSLTransform node that is holding the cache replaces the cached version with the modified (latest) version before a new message is processed. However, if you are changing several style sheets, stop relevant message flows before you make any changes. If you do not stop the relevant message flows before you make the changes, the order of the changes cannot be guaranteed by running message flows, which might cause an incompatibility between the style sheets that are changed. Use the mqsireload command to reload a style sheet; however, this command does not prevent incompatibility.

  5. On the Detail Trace tab, set the Trace setting property to trace the actions of the XSLTransform node. The default value is Off. To activate trace, set the property to On.

    The trace information is written to a trace file XMLTTrace.log:

    • z/OS platform On z/OS® systems, the file is located in install_dir/output, where install_dir is the directory in which you have installed the broker.
    • Windows platform On Windows® systems, the file is located in workpath\log if you have specified the -w option of the mqsicreatebroker command. If you have not specified the broker workpath, data is written to C:\Documents and Settings\All Users\Application Data\IBM\MQSI\common\log.
    • Linux platform UNIX platform On Linux® and UNIX® systems, the file is located in /var/mqsi/common/log.

    If you set Trace setting to On for one XSLTransform node, it is on for all nodes in the execution group.

    This property is now deprecated. Any relevant trace now goes into the user trace, provided that user debug trace is enabled. The setting of Trace setting in the XSLTransform node does not affect any user trace.

Start of changeThis node supports a number of LocalEnvironment message tree variables, which you can use to dynamically alter the values that are set in the node's properties. The following table lists each LocalEnvironment variable against the name of the node property that it overrides, and lists any permitted values.
Local environment variable name Node property name Permitted values
XSL.MessageDomain Message Domain
  • MRM
  • Start of changeSOAPEnd of change
  • XMLNS
  • Start of changeDataObjectEnd of change
  • XMLNSC
  • JMSMap
  • JMSStream
  • MIME
  • BLOB
  • IDOC
  • XML
  • inherit
XSL.MessageSet Message Set  
XSL.MessageType Message Type  
XSL.MessageFormat Message Format  
XSL.Validate Validate
  • None
  • Content
  • Content and value
  • Inherit
XSL.FailureAction Failure action
  • Exception
  • Exception List
  • User Trace
  • Local Error Log
XSL.ParseTiming Parse Timing
  • Deferred
  • Immediate
  • Complete
XSL.UseXmlnscForXmlnsDomain Use XMLNSC compact parser for XMLNS domain
  • Yes
  • No
XSL.OutputCharSet Character Set  
XSL.StyleSheetName Stylesheet Name  
End of change
If you have large XML messages and receive an out of memory error, use the mqsireportproperties command to see the current value of the Java™ Heap size for the XSLT engine:
mqsireportproperties brokerName -e executionGroupLabel 
                                 -o ComIbmJVMManager -n jvmMaxHeapSize
Use the mqsichangeproperties command to increase the Java Heap size:
mqsichangeproperties brokerName -e executionGroupLabel 
                                 -o ComIbmJVMManager -n jvmMaxHeapSize -v newSize
In the above examples, replace brokerName, executionGroupLabel, and newSize with the appropriate values.

The value that you choose for newSize depends on the amount of physical memory that your computer has, and how much you are using Java. A value in the range 512 MB (536870912) to 1 GB (1073741824) is typically sufficient.

Start of change

When the message domain is XMLNS or XMLNSC

When the output message domain is either XMLNS or XMLNSC, particular circumstances apply. If the domain is either XMLNS or XMLNSC as a result of being set explicitly or having been inherited from the input node, and the style sheet defines the output as XML (achieved by coding <xsl:output method="xml"), the output message is generated directly as a message tree. In all other cases, a bit stream is generated. Because WebSphere Message Broker parses message trees to be single-rooted, ensure that, should a multiple-rooted message tree be produced, it is distributed into well-formed message trees if they are to be serialized.

For XMLNSC input messages, ensure that you select the Retain Processing Instructions option on the Input Message Parsing tab so that embedded style sheet name declarations in input messages can be found by the code.

Some differences occur in what happens to the output message when the output message domain is specified as either XMLNS or XMLNSC, and when the output message domain is specified as any other value. They are summarized in the following table:
Difference XMLNS or XMLNSC Other domains
Output format Message tree Bit stream
Parse Timing property Not applicable Applied if bit stream is subsequently parsed
Use XMLNSC compact parser for XMLNS domain property Applied when the message tree is serialized Not applicable
Validate property Applied when the message tree is serialized Applied if the bit stream is subsequently parsed
Failure property Applied when the message tree is serialized Applied if the bit stream is subsequently parsed
End of change

Terminals and properties

The XSLTransform node terminals are described in the following table.

Terminal Description
In The input terminal that accepts the message for processing by the node.
Failure The output terminal to which the original message is routed if an error is detected during transformation.
Out The output terminal to which the successfully transformed message is routed.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the bar file to deploy it).

The XSLTransform node Description properties are described in the following table.

Property M C Default Description
Node name No No The node type The name of the node.
Short Description No No   A brief description of the node.
Long Description No No   Text that describes the purpose of the node in the message flow.

The XSLTransform node Stylesheet properties are described in the following table.

Property M C Default Description
Stylesheet Name No Yes   The name of the style sheet, used if the style sheet specification is searched for in node properties.

The XSLTransform node Advanced properties are described in the following table.

Property M C Default Description
Stylesheet Directory No Yes   The path where the style sheet is located. This path is used by all location methods.
Stylesheet Cache Level No No 5 The number of compiled or parsed style sheets that are stored in this instance of the node.

Start of changeThe XSLTransform node Output Message Parsing properties are described in the following table.End of change

Start of change
Property M C Default Description
Message Domain No No BLOB The message domain that is associated with the output message.
Message Set No No   The message set that is associated with the output message.
Message Type No No   The message type that is associated with the output message.
Message Format No No   The message format that is associated with the output message.
Output Character Set No No   The numeric value of the Output Character Set
End of change

Start of changeThe XSLTransform node Parser Options are described in the following table.End of change

Start of change
Property M C Default Description
Parse Timing No No On Demand This property controls when an output message is parsed. Valid values are On Demand, Immediate, and Complete.

For a full description of parsing on demand refer to the related links.

Use XMLNSC Compact Parser for XMLNS Domain No No No This property controls whether the XMLNSC Compact Parser is used for output messages in the XMLNS Domain. If you set this property, the message data appears under XMLNSC in nodes that are connected to the output terminal when the input RFH2 header or Domain is XMLNS.
End of change

The XSLTransform node Detail Trace properties are described in the following table.

Property M C Default Description
Trace Setting Yes No Off This property controls whether tracing is on or off. If tracing is on, low level tracing is recorded in a file.

Start of changeThe XSLTransform node Validation properties are described in the following table. Refer to the related links for a full description of Validation properties.End of change

Start of change
Property M C Default Description
Validate No No None This property controls whether validation takes place of the output message. Valid values are None, Content, Content and Value, and Inherit.
Failure Action No No Exception This property controls what happens if validation of the output message fails. You can set this property only if you set Validate to Content and Value or Content. Valid values are User Trace, Local Error Log, Exception, and Exception List.
End of change
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:18:29

ac12490_ This topic's URL is: