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

Component Purpose For more information
Adapter

Handles transfer of information between a WebSphere business integration broker and an external process such as an application or technology.

Note:
The adapter uses a runtime component called a connector to actually handle the transfer of information between an integration broker 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 the business integration broker. 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 the InterChange Server integration broker 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. 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. 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 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.

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.

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

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 text data handlers that this base data-handler file contains.

Table 3.

Text 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
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 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"

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.

Contexts for calling data handlers

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

Data handlers in a connector context

In an event-triggered flow, the runtime 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.

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

  1. The connector receives a business object from an integration broker.
  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 email, 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 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

  1. The connector detects an application event. The event may be in the form of an email, 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 the integration broker.

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.

The Server Access Interface is an API that allows an access client to execute a collaboration inside InterChange Server Express.

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:

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