What is a data handler?

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.

Table 1. Components that transfer information in the WebSphere Business Integration Server Express system
Component Purpose For more information
Adapter

Handles transfer of information between InterChange Server Express and an external process such as an application or technology.

Note:
The adapter uses a run-time component called a connector to actually handle the transfer of information between InterChange Server Express and an application (or technology).

These external processes identify events that occur within them by sending an event record to an event store. The adapter detects events in this event store. When it finds a triggering event, the adapter creates a business object that represents the event and sends this event asynchronously to Interchange Server Express. This business object contains data and a verb to indicate the type of event (such as Create or Update).

For IBM-delivered adapters: see the individual adapter guides.

Access client

Handles transfer of information between InterChange Server Express and some external process such as a servlet within a Web server.

An access client is an external process that uses the Server Access Interface to communicate directly with InterChange Server Express. When this component receives some information that needs to be transferred, it creates a business object that represents the event and sends this event synchronously to a collaboration within InterChange Server Express. As with the adapter, the business object contains data and a verb to indicate the type of event (such as Create or Update).

Server Access Interface Development Guide

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.

Note:
A data handler is implemented in a Java class named DataHandler. This class is an abstract class, which the data-handler developer extends to implement a data handler instance. For more information, see Extending the data handler base class.

The section provides the following information about data handlers:

IBM-delivered 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

Base data handlers

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.

Table 3. Base data handlers in the base data-handler file
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

Note:
This manual describes the text data handlers that Table 3 lists. The base data-handler file also contains several data handlers specific to certain IBM-delivered adapters. If an IBM adapter uses a special data handler, its adapter guide describes the installation, configuration, and use of its data handler.

Special data handlers

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.

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

Custom data handlers

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.

Note:
To assist in develop of custom data handlers, IBM also delivers source code for the FixedWidth, Delimited, and NameValue data handlers as sample code. For more information, see Sample data handlers.

Data-handler meta-objects

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:

Note:
A data handler is not required to use meta-objects to hold configuration information. However, all IBM-delivered data handlers are designed to use meta-objects for their configuration information.

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).

Note:
Each IBM-delivered data handler uses configuration properties that are defined in data-handler meta-objects. However, a custom data handler might or might not use meta-objects for its configuration properties. For more information, see Using data-handler meta-objects.

Contexts for calling data handlers

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.

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 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.

Data handlers in a connector context

In an event-triggered flow, the run-time component of an adapter, called the connector, interacts directly with a data handler to convert data.

Note:
For IBM-delivered adapters, see the individual adapter guides. Depending on the language in which the adapter is implemented.

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:

Connector business-object-to-string conversion

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.

Figure 2. Business-object-to-string conversion in the connector context

  1. The connector receives a business object from InterChange Server Express.
  2. The connector creates an instance of a data handler to handle the business object (using the createHandler() static method in the DataHandler base class).

    For more information about how a connector instantiates the data handler, see Instantiation in the context of a connector.

  3. The connector requests a business-object-to-string conversion by calling one of the following data-handler methods: Into this method, the connector sends the business object as an argument. The data handler serializes the business object into the requested data format.
  4. The data handler returns the serialized data to the connector.
  5. The connector writes the serialized data to the destination, which could be an e-mail, a file, or an HTTP connection.
Connector string-to-business-object conversion

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.

Figure 3. String-to-business-object conversion in the connector context

  1. The connector detects an application event. The event may be in the form of an e-mail, a text file, an XML document, or any other common format for which a data handler exists.
  2. The connector creates an instance of a data handler to handle the event (using the createHandler() static method in the DataHandler base class).

    For more information about how a connector instantiates the data handler, see Instantiation in the context of a connector.

  3. The connector sends in the serialized data as an argument to the getBO() method of the data-handler instance. The data handler builds an instance of a business object.

    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.

  4. The data handler returns the business object to the connector.
  5. The connector sends the business object to InterChange Server Express.

Data handlers in the context of the Server Access Interface

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 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.

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:

Server Access Interface business-object-to-string conversion

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

  1. The collaboration returns the requested data or the results of requested actions to the access client.
  2. To convert the business object to the required format, the access client sends the business object as an argument to the ItoExternalForm() method of the Server Access Interface.
  3. The Server Access Interface takes the following actions:
  4. The data handler parses the business object to create the serialized data.
  5. The data handler returns the serialized data to the Server Access Interface.
  6. The Server Access Interface returns the serialized data to the access client.
Server Access Interface string-to-business-object conversion

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

  1. To convert serialized data to a business object, the access client sends the serialized data as an argument to the IcreateBusinessObjectFrom() method of the Server Access Interface.
  2. The Server Access Interface takes the following actions:
  3. The data handler builds an instance of a business object.

    The data handler parses the data and populates the attribute values for the business object based on the serialized data.

  4. The data handler returns the business object to the Server Access Interface.
  5. The Server Access Interface returns the business object to the access client.
  6. The access client calls a collaboration that uses the business object data in a business process.

Copyright IBM Corp. 2004, 2005