WebSphere Enterprise Service Bus, Version 6.2.0 Operating Systems: AIX, HP-UX, i5/OS, Linux, Solaris, Windows


Message Element Setter mediation primitive

Use the Message Element Setter mediation primitive to set the content of messages.

Introduction

The Message Element Setter mediation primitive provides a simple mechanism for setting message content: you can add, change or delete message elements by setting the mediation primitive properties. The Message Element Setter primitive does not change the type of the message.

You can make multiple message changes. The changes occur sequentially; therefore, elements can build on each other.

The Message Element 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.

Details

You can set target elements to a constant value, or to a value copied from somewhere in the input service message object (SMO). If a target element you specify does not exist, it is created in the SMO. You can also delete message elements, if they are optional or repeating elements.

Target elements are specified as XPath expressions using the Target property. If you set a target element to a constant value, the target XPath must resolve to a single leaf in an SMO node. If you set a target element from a source element, both the source and target XPaths must resolve to a single element (a single leaf or subtree).

Usage

Because the operations you define occur sequentially, a later operation can depend on an earlier operation. For example, you could define a Copy operation to copy a new element into the SMO, and a later operation to set a value in the new element.

It is often useful to combine the Message Element Setter mediation primitive with other mediation primitives. For example, you could use the Message Element Setter mediation primitive if you need to manipulate data, before or after the Database Lookup mediation primitive is invoked.

You can also use the Message Element Setter mediation primitive to change messages after filtering them, using the Message Filter mediation primitive. You might want to update or delete certain message elements after filtering.

Properties

Message Elements

Elements of the message that you want to add, change, or delete.

In WebSphere® Integration Developer, click Add to specify a message element update. After you have defined an update, it appears in the Message Elements table. You can change the order in which message element updates occur, by moving the Message Elements up and down in the table.

Action
The way you want to alter the message. The actions are: Set, Copy, Append, or Delete. Depending on the action you select, the WebSphere Integration Developer panel lets you fill in different properties. The default action is Set. The Set, Copy and Append actions create new elements (or trees of elements), if required.
  • Using Set, you can set a target element to a constant value (specified in the Value property).
  • Using Copy, you can copy from a source element to a target element.
    Note: You must ensure that the source data type is compatible with the target data type, or a runtime exception occurs.
  • Using Append, you can copy from a source element to a new element instance, by appending to a repeating element in the output. You can only append to a repeating element in the output.
    Note: You must ensure that the source data type is compatible with the target data type, or a runtime exception occurs.
  • Using Delete, you can delete an element instance from the SMO.
    Note: You should only attempt to delete optional or repeating elements.
Target
An XPath 1.0 expression that identifies the element you want to add, change, or delete, for example, /body/GetAddress/Name.

If you want to set a target element to a constant value, the target XPath expression must resolve to a single leaf element. If you want to copy from a source element to a target element, both the source and target must specify an XPath expression that resolves to a single message element (a single leaf or subtree).

If you set multiple targets, the updates occur sequentially. Therefore, if you set element X from value 13 to value 14, and then set element Y to the value of element X, the mediation sets element X to value 14 and element Y to value 14.

If you specify the same target element more than once, the last operation performed on the target element takes precedence.

Type
The type of the element value.

If you want to set the Target to a constant value, the Type must be a simple XML schema type, or an XML schema type that extends a simple XML schema type.

Value
If the Action property is Set, use the Value property to specify a constant value.
Note: the Value and Type properties must be compatible. For example, if the Type is the XML schema type int, the Value could validly be 14, but not GoldAccount.
Source
If the Action property is set to Copy or Append, the Source property should be an XPath 1.0 expression that indentifies the source element.
Validate input
If true, causes the input message to be validated before the mediation is performed.
Table 1. Message Element Setter mediation primitive properties
Property Valid Values Default
Message Elements Action Set, Copy, Append, or Delete Set
Target XPath expression  
Type Data type  
Value A value that is compatible with the Type property
Note: Only used with Set
 
Source XPath expression
Note: Only used with Copy or Append
 
Validate input Boolean: true or false false

Considerations

Consider the following when using the Message Element Setter mediation primitive:


reference Reference topic

Terms of use | Feedback


Timestamp icon Last updated: 21 June 2010


http://publib.boulder.ibm.com/infocenter/dmndhelp/v6r2mx/topic//com.ibm.websphere.wesb620.doc/ref/rwesb_MessageElementSettermediationprimitive.html
Copyright IBM Corporation 2005, 2010. All Rights Reserved.
This information center is powered by Eclipse technology (http://www.eclipse.org).