WebSphere

Data Handler mediation primitive

Use the Data Handler mediation primitive to transform part of a message. The Data Handler primitive is used to convert an element of a message from a physical format to a logical structure, or from a logical structure to a physical format.

Introduction

The Data Handler mediation primitive transforms a targeted section of a message. The starting point of a transformation is indicated by an XPath expression.

The Data Handler mediation primitive can be used when you are trying to integrate services, and parts of the message are in a format that is not easy to manipulate with existing mediation primitives. The Data Handler primitive can also be used to transform the data in a message into a business object (BO) that can be manipulated by other mediation primitives. The part of the message not referenced by the XPath expression is left unmodified.

The Data Handler 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. The input message triggers a transformation and if the transformation is successful, the out terminal propagates the modified message. If an exception occurs during the transformation, the fail terminal propagates the input message, together with any exception information contained in the failInfo element.

Details

The Data Handler primitive gives you a simple mechanism for manipulating messages, using the data handler framework in the run time. You can change any section of the service message objects (SMO) using the Data Handler primitive.

You need to configure a data handler for this primitive. You can generate a configuration file using the Binding Resource Configuration panel. You must ensure that the data handler is compatible with the source and target elements identified by the XPath expressions.

Usage

You can use the Data Handler primitive to convert a physical format, such as a Text string inside a JMS Text Message object, into a logical BO structure and back again. This allows the transformation of the physical format into the specific BO to be completed in the mediation flow component, instead of the export and import.

You might commonly use the Data Handler primitive to do the following:
  • Transform a section of the input message from one defined structure to another defined structure. For example, if the SMO includes a string value that is comma delimited and you want to parse this into a specific BO.
  • Alter the message type. For example, when a JMS export has been configured to use a JMS basic-typed data binding and within the mediation module the integration developer decides that the content should be inflated to a specific BO structure.
In a gateway scenario, the Data Handler primitive can be used to inflate and serialize the data. For gateway scenarios that are Web service enabled, special configuration (as shown in the example section) is required.

Properties

Data handler configuration
Specify the Data handler configuration which the primitive should utilize, as created by the binding resource configuration wizard. The Data handler configuration will be used at run time to select the correct data handler to be invoked and pass in any associated parameter values.
Output Message field refinements
You can use the Output Message field refinements property to specify which fields in the message are refined using more specific type information. By default, this property is empty. Generally, you refine fields that are defined by the following XML schema weak types: xsd:any,xsd:anyType and xsd:anySimpleType. You specify the XPath of the message field you want to refine, and the data type to use. WebSphere® Integration Developer provides a graphical interface to help you specify the XPath and data type. You can specify refinements for more than one message field, but duplicate entries for the same message field are not allowed.
Weakly typed field
Specify the XPath of the weakly-typed field you want to refine.
Actual field type
Specify the data type you want to use for the refinement.
Source XPath
The location of the object, in the source SMO, that should be passed into the data handler, for example, /body/operation1/input1/value.
Target XPath
The location, in the target SMO, where the output from the data handler should be stored. (The target SMO is defined as the type of the output terminal.)
Action:
Convert from native data format to a business object calls the transform method of the data handler to de-serialise the data.
Convert from a business object to native data format calls the transformInto method of the data handler to serialise the data.
Table 1. Set Message Type mediation primitive properties
Property Valid values Default
Data handler configuration String  
Output message field refinements Weakly typed field XPath  
Actual field type    
Action Convert from native data format to a business object or Convert from a business object to native data format Convert from native data format to a business object
Source XPath XPath  
Target XPath XPath  

Example: Using Data Handler mediation primitive with service gateway for Web service binding

In a service gateway, you can inflate the messages to a concrete definition so that body manipulation is possible. The Data Handler primitive provides this capability for document literal wrapped and single-part document literal messages. To use this capability, configure the Data Handler primitive in a request flow as detailed below:
Source XPATH: /body/message/value
Target XPATH: /body
Data handler configuration: Point to a configuration of the XML DataHandler without any values specified for the root name or namespace
Action: Convert from native data format to a business object
Configure the response flow as detailed below:
Source XPATH: /body
Target XPATH: /body/message/value
Binding resources configuration: Point to a configuration of the XML DataHandler without any values specified for the root name or namespace
Action: Convert from a business object to native data format
Weakly typed field /body/message 
Actual field type: textBody

reference Reference topic

Terms of use | Feedback


Timestamp icon Last updated: 20 June 2010 00:39:52 BST (DRAFT)


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