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. In addition, you can create custom data handlers to handler conversion between your own native format. 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 |
Custom data handlers | Data handlers that you implement | CustDataHandler.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 base 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 |
ContentMaster Data Handler | several | Complex Data data hander |
IBM makes separate installers available for a few data handlers. In order to install these special data handlers, you must follow the steps provided in the Installation Guide for WebSphere Business Integration Adapters.
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 for which IBM provides separate
installers and 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" |
If the IBM-delivered data handlers to not handle the conversion of serialized data to a business object, you can create your own custom data handler. The CustDataHandler.jar file is intended to hold any custom data handlers that you might develop. This file resides in the DataHandlers subdirectory of the product directory. For information about how to create a custom data handler, see "Creating a custom data handler".
A connector or Server Access Interface process (if InterChange Server if your integration broker) 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 (if InterChange Server if your integration broker) 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 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. 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 process, actually invokes the data handler.
InterChange Server |
---|
The Server Access Interface is an API that allows an access client to execute a collaboration inside InterChange Server. This interface is available for use only when InterChange Server is the integration broker. For more information on this interface and on access clients, see the Access Development Guide in the IBM WebSphere InterChange Server 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 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 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. 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