Use 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 model, Message, and PHysical format for the generated message.
- Application Integration Suite
This node was formerly known as the XMLTransformation node.
This topic contains the following sections:
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 in 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 IBM® Integration Toolkit by the following 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.
You cannot use relative path
external entities that are defined in the DTD of input messages (for
<!DOCTYPE note [<!ENTITY chap1 SYSTEM "chap1.xml">]>).
Use an absolute path definition.
The XSLTransform node supports a number of local environment message tree variables, which you can use to dynamically alter the values that are set in the node's properties. For more details, see Using local environment variables to set properties.
You can use style sheets in two different ways with the XSLTransform node. For more details, see Deployed and non-deployed style sheets.
Use the mqsichangeproperties command to increase the Java Heap size:
mqsireportproperties integrationNodeName -e integrationServerName -o ComIbmJVMManager -n jvmMaxHeapSize
In the previous examples, replace integrationNodeName, integrationServerName, and newSize with the integration node name, integration server name, and the size wanted for the Java Heap.
mqsichangeproperties integrationNodeName -e integrationServerName -o ComIbmJVMManager -n jvmMaxHeapSize -v newSize
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.
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.
Terminals and properties
The XSLTransform node terminals are described in the following table.
|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.
|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||mqsiapplybaroverride command property|
|Stylesheet name||No||Yes||The name of the style sheet, which is used if
the style sheet specification is searched for in node properties.
To specify a style sheet by using node properties, enter the required
value for Stylesheet name.
Specify a principal style sheet using one of the following methods:
The XSLTransform node Advanced properties are described in the following table.
|Property||M||C||Default||Description||mqsiapplybaroverride command property|
|Stylesheet directory||No||Yes||The path where the style sheet is located. This
path is used by all location methods.
If the style sheet identification is fully qualified, the Stylesheet directory property 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.
|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 zero (0), no style sheet is cached, and style sheets are interpreted rather than compiled. If your message flow does not set the style sheet dynamically by using the local environment, the same style sheet is always used, and any value greater than zero ensures that it is compiled. If your message flow does set the style sheet dynamically, you can tune the value to improve performance. If you set this property to a character other than a positive integer, a flow configuration exception error message is issued.
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 integration server 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. If a deployed style sheet is redeployed, or an external style sheet is replaced in the file system, the update is detected but you cannot replace a style sheet that is deployed in a BAR file by changing the deployed style sheet on disk. To change a style sheet that is deployed in a BAR file, you must redeploy the BAR file. If you are changing several style sheets, stop the 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.
Consider performance when you set this property. Typically, when you set this property to a number greater than the default value of 5, performance is faster because style sheet re-compilation is less likely. However, cached style sheets use Java virtual machine (JVM) heap space; if you keep too many cached style sheets, the JVM is likely to slow. In addition, if the cached style sheets are not used regularly and you set this property to a large number, performance can be affected because compiling style sheets increases processor usage. Therefore, to decide on the most suitable value for this property, you must balance how many style sheets you use with the size of the style sheets, the size of the JVM heap space, and your usage pattern. For more information about the JVM heap space, see JVM heap sizing.
The XSLTransform node Output Message Parsing properties are described in the following table.
|Message domain||No||No||BLOB||The message domain that is associated with the
output message. To associate a specific parser with the output message,
specify the new domain in Message
domain. The default value is BLOB. This domain is applied
to the output message. Alternatively, use Inherit to associate the parser
that owned the input message. XML is
deprecated; use XMLNSC instead.
You can also specify a user-defined parser if appropriate.
|Message model||No||No||The name or location of the message model schema
file in which the message is defined. If you are using the XMLNSC
parser in validating mode, or the MRM parser, select the Message model that you want to use.
When you click Browse, you see a list of available
message models schema files when you select XMLNSC or MRM as the domain.
If you set this property, then subsequently update the project dependencies to remove this message model reference, a warning is issued. Either update the Message model property, or restore the reference to this message model.
|Message||No||No||The message type that is associated with the output message. If you are using the MRM parser, select the correct message from the list in Message. This list is populated with messages that are defined in the Message model that you have selected.|
|Physical format||No||No||The message format that is associated with the output message. If you are using the MRM parser, select the XML physical format for the output message from the list in Physical format. This list includes all the physical formats that you have defined for this Message model.|
|Character set||No||No||The numeric value of the character set for the output message. To specify a character set for the output message by using node properties, specify the required value for Character set. The value that you specify must be numeric; for example, specify 1200 to encode the output message as UTF-16.|
The XSLTransform node Parser Options are described in the following table.
|Parse timing||No||No||On Demand||This property controls when an output message is parsed. Valid values are On Demand, Immediate, and Complete. Parse timing is, by default, set to On Demand, which causes parsing of the message to be delayed. To cause the message to be parsed immediately, see Parsing on demand.|
|Build tree using XML schema data types||No||No||Cleared||This property controls whether the XMLNSC parser creates syntax elements in the message tree with data types taken from the XML Schema. You can select this property only if you set the Validate property to Content or Content and Value. For more information, see Manipulating messages in the XMLNSC domain.|
|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 MQRFH2 header or Domain is XMLNS.|
The XSLTransform node Validation properties are described in the following table. Set the validation properties for the parser to validate the body of messages against the Message set. (If a message is propagated to the Failure terminal of the node, it is not validated.) For more details, see Validating messages and Validation properties.
|Validate||No||Yes||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.|
The XSLTransform node Detail Trace properties are described in the following table.
|Trace setting||Yes||No||Off||This property is deprecated. Start
user trace instead. The user trace contains the same XSL trace information.
If you set this property, it does not affect user trace.
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.
|Events||No||No||None||Events that you have defined for the node are
displayed on this tab. By default, no monitoring events are defined
on any node in a message flow. Use Add, Edit,
and Delete to create, change or delete monitoring
events for the node; see Configuring monitoring event sources by using monitoring properties for details.
You can enable and disable events that are shown here by selecting or clearing the Enabled check box.