Calling a data handler

The main task of a connector is to convert data between an application-specific form and a business object. Often, the connector must perform this conversion directly. For example, it can create the appropriate database statements to create or access the data as a row in a table of an application database. However, a connector might handle serialized data in a common

Multipurpose Internet Mail Extensions (MIME) format.

Rather than have each connector perform the conversions between a particular MIME format and a business object, both the and WebSphere InterChange Server and WebSphere Business Integration Adapters products provide data handlers to perform these common conversions. A data handler is a special Java class instance that converts between serialized data in a particular MIME format and a business object. For example, the WebSphere Business Integration Data Handler for XML provides a data handler that converts between an XML document and business objects.

Note:
This section provides a brief overview of data handlers. For a more complete description, see the Data Handler Guide.

The Java connector library provides several data-handler methods you can call a specific data handler from within the connector. To determine which data-handler method to use, you must perform the following tasks:

Determining direction of the data conversion

A data handler can usually convert between serialized data and a business object in both directions; that is, it can perform both of the following conversions:

The Java connector library provides the data-handler methods in Table 30 so that a connector can call a data handler to convert between serialized data in a particular MIME format and a business object. These methods are defined in the CWConnectorUtil class.

Table 30. Data-handler methods in Java Connector Library

Conversion Conversion process Method
Business-object-to-string Call a data handler to convert the specified business object (theBusObj argument) to serialized data, returning this data in one of the supported access forms. For more information, see Accessing the serialized data.. boToByteArray()


boToStream()


boToString()

String-to-business-object Call a data handler to convert the specified serialized data (the serializedData argument) to a business object. byteArrayToBo()


readerToBO()


streamToBO()


stringToBo()

If the data handler cannot perform the requested conversion, the data-handler method throws the ParseException exception.

Accessing the serialized data

To access the serialized data sent to or received from a data-handler method, you must provide the following information:

Choosing a data format

The purpose of a data handler is to convert between serialized data and a business object. Therefore, the code of the Java connector must be able to access to this serialized data. It might have access to this data in any of the forms listed in Table 31 The Java connector library provides data-handler methods that support each of these forms of serialized data.


Table 31.

Ways to access serialized data to and from data handlers
Access to
serialized data
Java construct Method
A string String object boToString()


stringToBo()

An input stream An object of java.io.InputStream class or one of its subclasses boToStream()


streamToBO()

A reader for character streams An object of java.io.Reader class or one of its subclasses readerToBO()
A byte array byte[] boToByteArray()


byteArrayToBo()

To access the serialized data sent to or received from a data handler, choose the data-handler method from Table 31 that handles the appropriate access format.

Identifying the data locale and encoding

As shown in Table 30., the data-handler methods call a data handler to either read serialized data (string-to-business-object conversion) or create serialized data (business-object-to-string conversion). During this process, the data handler might need to know about the character encoding or locale of the serialized data it is processing. To allow you to specify a different locale or character encoding for the data handler to use, the data-handler methods accept a Java Locale object and a String encoding argument to specify this information:

For information on how to obtain the connector-framework locale or character encoding, see Design considerations for an internationalized connector.

Identifying the data handler to instantiate

To identify the data handler that needs instantiation, the data-handler methods must provide the instantiation process with the information it needs to locate the data handler's class. This data-handler class is the name of the Java class that implements the data handler.

Note:
The data-handler methods must instantiate a data handler before they can request the specified conversion. This instantiation process is implemented by the createHandler() method of the DataHandler base class. For more information on the DataHandler class and the data-handler configuration information, see theData Handler Guide.

The data-handler method can specify the name of the data-handler class by providing the MIME type of the serialized data in its mimeType argument and, optionally its BOPrefix argument. It uses this MIME type to obtain the data handler's class from its child meta-object in the top-level meta object as follows:

In this case, the data-handler method instantiates a data handler of Java class listed in the child meta-object. The instantiation process uses the child data-handler meta-object associated with that MIME type to derive the class name and other configuration information for the data handler instance.

Note:
Each system on which data handlers are installed has a meta-object to describe the available data handlers. A meta-object is a special business object that contains configuration information. For data handlers, the top-level meta-object contains the available data handlers and the associated MIME type that each data handler supports.

For more information about the meta-objects and about how the instantiation process derives a class name from the specified MIME type, see the Data Handler Guide.

If the data handler cannot be instantiated, the data-handler method throws the DataHandlerCreateException.

Copyright IBM Corp. 1997, 2004