Use the XMLTransformation node to transform an XML message to another form of XML message, according to the rules provided by an XSL (Extensible Stylesheet Language) style sheet.
This topic contains the following sections:
You can specify the location of the style sheet to apply to this transformation in three ways:
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 XMLTransformation node ignores the encoding, and always uses the CodedCharSetId in the message property folder to decode the message.
The XMLTransformation node is contained in the Transformation drawer of the palette, and is represented in the workbench by the following icon:
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.
Be aware of the following considerations if the input to the XMLTransformation node is generated from the XMLNSC parser or the MRM parser. 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 XMLTransformation 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.
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.
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.
Typically, all references to a deployed style sheet must be made relative, no matter where they are displayed. 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 XMLTransformation 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).
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. You can use the MQSI_WORKPATH environment variable to find the location of the workpath on your system; for example, on Windows® systems, the default workpath is MQSI_WORKPATH=C:\Documents and Settings\All Users\Application Data\IBM\MQSI.
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.
Deploy manually only those style sheets or XML files that are not picked up by the system (the Message Brokers 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, see Adding files to a broker archive and Adding keywords to XSL style sheets.
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.
When you have put an instance of the XMLTransformation 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. To display the properties of the node in the Properties dialog, right-click the node and click Properties. (If you double-click the XMLTransformation node, you open the XSL Selection dialog box.)
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 XMLTransformation node:
If you change a cached style sheet (by redeploying or replacing the file in the file system), the XMLTransformation 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.
<?xml-stylesheet type="text/xsl" href="foo.xsl"?>
This node was available in a SupportPac™ for Version 2.1, and element ComIbmXslMqsiStylesheetname was used for the name of the style sheet, therefore, the current node checks both elements. If both are present, the value in ComIbmXslXmltStylesheetname takes precedence.
You can set more than one property to the same value, although if you do, the order of priority that is set by the node is the default order that is indicated previously.
If you set a value of 0, the node does not search the corresponding location for the style sheet identification. If you set all three properties to 0, a runtime error is generated.
This node was available in a SupportPac for Version 2.1, and element ComIbmXslMqsiOutputcharset was used for the output character set, therefore, the current node checks both elements. If both are present, the value in ComIbmXslXmltOutputcharset takes precedence.
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.
You can set more than one property to the same value, although if you do, the order of priority that is set by the node is the default order that is indicated previously.
If you set a value of zero, the node does not search the corresponding location for the character set identification.
If the node cannot determine the output character set from either of these two sources, either because no value is set, or because the selection priorities are set to zero, the default value 1208 (UTF-8) is used. (The XSL specification indicates that the output character set can be specified in the style sheet; however, the XMLTransformation node ignores this value.)
The trace information is written to a trace file XMLTTrace.log:
If you set Trace setting to On for one XMLTransformation node, it is on for all of the nodes in the execution group.
This property is deprecated. Start user trace instead. The user trace contains the same XML trace information. If you set Trace setting in the XMLTransformation node, it does not affect user trace.
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 previous 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.
The XMLTransformation 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 XMLTransformation 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 XMLTransformation 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 XMLTransformation 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. Enter a positive integer between zero (0) and 100. The default value is 5. If you set this property to a character other than a positive integer, a flow configuration exception error message is issued. If you set this property to zero (0), no style sheet is cached, and style sheets are interpreted rather than compiled. |
XML embedded stylesheet selection priority | Yes | No | 1 | The priority value for searching for style sheet location information in the XML data. |
Message environment selection priority | Yes | No | 2 | The priority value for searching for style sheet location information in the LocalEnvironment folder of the current message. |
Broker node attribute selection priority | Yes | No | 3 | The priority value for searching for style sheet location information as a property of the node |
The XMLTransformation node Output Character Set properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Output character set | No | No | The numeric value of the Output character set | |
Message environment selection priority | Yes | No | 1 | The priority value for searching for the Output Character Set ID in the LocalEnvironment folder of the current message. |
Broker node attribute selection priority | Yes | No | 2 | The priority value for searching for the Output Character Set ID as a property of the node. |
The XMLTransformation node Detail Trace properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Trace setting | Yes | No | Off | ![]() In previous versions of WebSphere® Message Broker, this property controls whether tracing is on or off. If tracing is on, low level tracing is recorded in a file. ![]() |