A data handler is a Java class instance that converts between a
particular serialized format and a business object. Data handlers are
used by components of a business integration system that transfer information
between a WebSphere business integration broker and some external
process. Table 1 shows the components that handle transfer of
information between a WebSphere business integration broker and an external
process.
Table 1. Components that transfer information in the WebSphere business integration system
As Table 1 shows, the task of both these components (connector and access client) is to transfer information between a broker and an external process, as follows:
Often, the external process uses some common format such as XML for its native serialized data. Rather than have every adapter (or access client) handle the transformation between these common formats and business objects, the WebSphere business integration system provides several IBM-delivered data handlers. The adapter (or access client) can then call the appropriate data handler to perform the data conversion based on the Multipurpose Internet Mail Extensions (MIME) type of the serialized data.
The section provides the following information about data handlers:
IBM delivers data handlers in the Java archive (jar) files shown
in Table 2. These jar files reside in the
DataHandlers subdirectory under the product directory.
Table 2. IBM-delivered data-handler jar files
Contents | Description | Data-handler jar file |
---|---|---|
Base data handlers | Text-based data handlers and data handlers specific to some IBM-delivered adapters | CwDataHandler.jar |
Special data handlers | XML data handler | CwXMLDataHandler.jar |
| EDI data handler | CwEDIDataHandler.jar |
The base data-handler file,
CwDataHandler.jar, contains most of the IBM-delivered data
handlers. This file resides in the DataHandlers subdirectory
of the product directory. Table 3 shows the text data handlers that this base data-handler
file contains.
Data handler | MIME type | For more information |
---|---|---|
Request-Response Data Handler |
text/requestresponse
| Request-Response data handler |
FixedWidth Data Handler |
text/fixedwidth
| FixedWidth data handler |
Delimited Data Handler |
text/delimited
| Delimited data handler |
NameValue Data Handler |
text/namevalue
| NameValue data handler |
IBM delivers a few data handlers in their own separate Java jar
files. The separation of a data handler from the base data-handler file
allows many adapters to use the data handler without incurring the overhead of
storing the other data handlers that reside in the base data handler
file. Table 4 shows the data handlers that IBM delivers as separate
jar files.
Table 4. IBM-delivered data handlers with separate jar files
Data handler | Data-handler jar file | MIME type | For more information |
---|---|---|---|
XML Data Handler |
CwXMLDataHandler.jar
|
text/xml
| "XML data handler" |
EDI Data Handler |
CwEDIDataHandler.jar
|
edi
| "EDI data handler" |
A connector or Server Access Interface process instantiates a data handler based on the MIME type of an input file or the MIME type specified in a business object request.
A data-handler meta-object is a hierarchical business object that can contain any number of child objects. The data-handler configuration information is arranged in the following hierarchy:
Data-handler meta-objects allow a connector or Server Access Interface process to instantiate a data handler based on the MIME type of an input file or the MIME type specified in a business object request. To configure a data handler, you must ensure that its meta-objects are correctly initialized and available to the callers (a connector or an access client).
As Table 1 describes, a component that needs to transfer data in the
WebSphere business integration system can invoke a data handler. Table 5 provides additional information about the components that
can invoke a data handler.
Table 5. Context for calling data handlers
Component | Type of event communication | Type of flow | Software that invokes the data handler |
---|---|---|---|
Adapter | Asynchronous | Event-triggered flow | Connector |
Access client (InterChange Server Express integration broker only) | Synchronous | Call-triggered flow | Server Access Interface (within InterChange Server) |
As Table 5 shows, in an event-triggered flow, an adapter calls a data handler directly. In a call-triggered flow, an external process that uses the Server Access Interface (called an access client) initiates a call to the data handler. A data handler operates the same whether it is called directly by an adapter or indirectly by an access client. These contexts are described in the next sections.
In an event-triggered flow, the runtime component of an adapter, called the connector, interacts directly with a data handler to convert data.
When a connector calls a data handler, the data handler runs as part of the connector process. Figure 1 illustrates the data handler in the context of a connector.
Figure 1. Data handler in the context of a connector
The data conversion reflects the business object requirements and the direction of the flow:
For a business-object-to-string conversion, the connector calls the data handler, passing it a business object. The data handler uses the information in the business object and the business object definition to create a stream or string of data. This stream or string of data is in the format associated with the data handler, usually of a particular MIME type. Business-object-to-string conversion is useful when the connector receives information from an integration broker in the form of a business object. The connector must then send the information in the business object to its application (or technology) as serialized data.
Figure 2 illustrates the data handler in the context of a connector when the data handler performs a business-object-to-string conversion.
Figure 2. Business-object-to-string conversion in the connector context
For more information about how a connector instantiates the data handler, see Instantiation in the context of a connector.
Into this method, the connector sends the business object as an argument. The data handler serializes the business object into the requested data format.
For a string-to-business-object conversion, the connector calls the data handler, passing it the serialized data and its associated MIME type object. The data handler receives a stream or string of data. The data handler uses the information in the data stream to create, name, and populate a business object instance of the specified type. String-to-business-object conversion is useful when the connector needs to send an event to an integration broker. The application sends this event as serialized data having a particular MIME type, to the connector.
Figure 3 illustrates the data handler in the context of a connector when the data handler performs a string-to-business-object conversion.
Figure 3. String-to-business-object conversion in the connector context
For more information about how a connector instantiates the data handler, see Instantiation in the context of a connector.
The connector might also specify the business object to which the getBO() method converts the data. Some connectors specify the business object type; others assume that the data handler can extract the business object type from the serialized text. The data handler parses the data and populates the attribute values for the business object based on the serialized data.
In a call-triggered flow, an access client interacts with a data handler to convert data. An access client is an external process that uses the Server Access Interface to interact with InterChange Server Express. When an access client calls either the ItoExternalForm() or IcreateBusinessObjectFrom() method of the Server Access Interface API, it initiates a call to a data handler. The Server Access Interface, which runs as part of the InterChange Server Express process, actually invokes the data handler.
InterChange Server Express |
---|
The Server Access Interface is an API that allows an access client to execute a collaboration inside InterChange ServerInterChange Server Express. For more information on this interface and on access clients, see the Access Development Guide in the documentation set. |
An access client might be a servlet that handles a request from a client browser. The request might be a request for data, an order request, or another type of business-to-business transaction. As another example, an access client might be a C++ or Java program that uses the Server Access Interface to access InterChange Server Express and exchange data with another application.
When an access client initiates a call that requires a data handler, the data handler runs as part of InterChange Server Express the process. Figure 4 illustrates the data handler in the context of the Server Access Interface. In this example, the access client is a Web server and servlet.
Figure 4. Data handler in the context of the Server Access Interface
The data conversion reflects the business object requirements and the direction of the flow:
For a business-object-to-string conversion, the data handler receives a business object as the result of the execution of a collaboration. The data handler uses the information in the business object to create a stream or string of data. This data is in the format associated with the data handler, usually of a particular MIME type. The access client often sends the resulting business object to the application as serialized data.
Figure 5 illustrates the data handler in the context of the Server Access Interface when the data handler performs a business-object-to-string conversion for an access client.
Figure 5. Business-object-to-string conversion in the Server Access Interface context
For a string-to-business-object conversion, the data handler receives a stream or string of data. The data handler uses the information in the data stream to create, name, and populate a business object instance of the specified type. String-to-business-object conversion is useful when the access client needs to send a business object to a collaboration in InterChange Server Express. The access client sends the serialized data, usually having a particular MIME type, to the data handler.
Figure 6 illustrates the data handler in the context of the Server Access Interface when the data handler performs a string-to-business-object conversion for an access client.
Figure 6. String-to-business-object conversion in the Server Access Interface context
The data handler parses the data and populates the attribute values for the