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.
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:
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:
Within a connector, this conversion is useful during event processing, when the connector receives serialized data from the application and must create the appropriate business-object representation of this data, which it then sends to the integration broker. The connector can send the business object to the appropriate data handler and receive from it the corresponding serialized data (as long as a data handler exists to convert to the desired format of serialized data).
This conversion is useful during request processing when the connector receives a business object from the integration broker and must create the appropriate serialized data, which it then sends to the application. The connector can send in the business object to the appropriate data handler and receive the corresponding business object (as long as a data handler exists to convert the desired format for the serialized data).
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.
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.
To access the serialized data sent to or received from a data-handler method, you must provide the following information:
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.
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.
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.
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.
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.
For more information about the meta-objects and about how the instantiation process derives a class name from the specified MIME type, see the WebSphere Business Integration Adapters: Data Handler Guide.
If the data handler cannot be instantiated, the data-handler method throws the DataHandlerCreateException.