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 InterChange Server Express (the integration broker for WebSphere Business Integration Server Express) and some external process. Table 1 shows the components that handle this transfer of information.
As Table 1 shows, the task of both these components (connector and access client) is to transfer information between InterChange Server Express 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 Server Express 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.
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 handler |
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 WebSphere Business Integration Server Express Installation Guide for Windows or for Linux.
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.
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 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 Server Express system can invoke a data handler. Table 5 provides additional information about the components that can invoke a data handler.
Component | Type of event communication | Type of flow | Software that invokes the data handler |
---|---|---|---|
Adapter | Asynchronous | Event-triggered flow | Connector |
Access client | Synchronous | Call-triggered flow | Server Access Interface |
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 run-time 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.
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 InterChange Server Express 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.
For more information about how a connector instantiates the data handler, see Instantiation in the context of a connector.
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 InterChange Server Express. 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.
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.
The Server Access Interface is an API that allows an access client to execute a collaboration inside InterChange Server Express. This interface is available for use only when InterChange Server Express is the integration broker. For more information on this interface and on access clients, see the Access Development Guide in the IBM WebSphere Business Integration Server Express 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 the InterChange Server Express 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.
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.
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.
The data handler parses the data and populates the attribute values for the business object based on the serialized data.