Use the Java Messaging Service Header Setter primitive
to create, modify, copy or delete JMS message headers.
Introduction
The JMS Header Setter mediation
primitive provides a mechanism for managing JMS headers in the message.
You can change, copy, add, or delete JMS headers by setting the mediation
primitive properties.
If you want multiple header changes you
can set multiple actions. Multiple actions are acted on sequentially,
in the order in which they are specified; this means that header changes
can build on each other.
You can create new JMS headers by specifying
header field values. You can search for JMS headers that already exist
in the Service Message Object by specifying the header name to match
on. If a matching header is found, it can then be deleted from the
message, copied to another location in the SMO, or have the value
set. If a matching header is not found, a new header can be created
using a specified header field value.
The JMS Header Setter
mediation primitive has one input terminal (in), one output terminal
(out) and a fail terminal (fail). The in terminal is wired to accept
a message and the other terminals are wired to propagate a message.
If the mediation is successful, the out terminal propagates the modified
message. If an exception occurs during the transformation, the fail
terminal propagates the original message, together with any exception
information contained in the failInfo element.
The JMS Header
Setter mediation primitive uses the given header name to determine
where to look in the SMO. There are two different types of JMS Header,
distinguished by name and their location in the SMO.
- Standard JMS Headers, which have their own schema in the SMO,
located at /headers/JMSHeader.
- Any other headers are User Headers and are listed at /headers/properties.
Usage
You can use the JMS Header Setter
mediation primitive to ensure that when a JMS message is sent to another
system, via the JMS binding, the headers that are sent with the message
are correctly set.
Because the operations you define occur sequentially,
a later operation can depend on an earlier operation. For example,
you could create a new header, copy it to elsewhere in the SMO and
then delete it from the list of headers it was initially appended
to.
You can also use the JMS Header Setter mediation primitive
to help to filter messages, using the Message Filter mediation primitive.
You might want to find a particular header and make it available to
be used in the filtering.
Properties
- JMS Header Elements
- Mode
- If you want to create a new JMS header, the Mode property must
be set to 'Create'.
- If you want to search for a JMS header and then modify the value
of any header that is found, or create a new header if none are found,
the Mode property must be set to 'Modify'.
- If you want to search for a JMS header and then copy the first
found header to another location in the SMO, the Mode property must
be set to 'Copy' .
- If you want to search for a JMS header and then delete any headers
that are found, the Mode property must be set to 'Delete'.
- Header name
- You can specify a JMS header field name; any JMS headers in the
SMO that has a matching name can then be set, copied, or deleted.
- Header Type
- Specify the JMS header type. This is only used for User Headers
that are listed at /headers/properties and is a Java primitive type
or String,
- Set Value using XPath
- Determine whether the Value to set should be a literal value or
an XPath expression that identifies a source value to copy into the
JMS header at runtime. This property is only used when the Mode property
is set to 'Create' or 'Modify',
- Value
- If the Mode property is set to 'Create' or 'Modify', the Value
property should be set to a JMS header literal value or an XPath expression
that identifies a value to copy into the JMS header at runtime. When
a new JMS header is created or a matching JMS header is found, this
new value is set in the specified field.
- If the Mode property is set to 'Copy', the Value property should
be an XPath 1.0 expression, identifying the target element to where
the first found JMS header will be copied.
- If the Mode property is set to 'Delete', the Value property should
not be set.
- Validate Input
- If true, causes the input message to be validated before the mediation
is performed.
Table 1. JMS Header Setter mediation primitive
propertiesProperty |
Valid Values |
Default |
JMS Header Elements |
Mode |
String: Create or Modify or Copy or Delete |
|
Header Name |
String: a field name |
|
Header Type |
String: String or byte or short or int or long
or float or double or boolean or char |
|
Set Value using XPath |
Boolean: true or false |
false |
Value |
String: An XPath expression or value |
|
Validate input |
|
Boolean: true or false |
false |
Considerations
Consider the following when
using the JMS Header Setter mediation primitive:
- If the Mode property is "Modify" and a header cannot be found,
a new header will be created.
- If the XPath expression of the copy target resolves to more than
one element in the SMO, a runtime exception occurs.
- The location of the header within the SMO depends upon its type;
standard or user.
- If the Validate input property is true and the input message is
invalid, a runtime exception occurs.