Data handlers are implemented as a library of classes that a connector or the Server Access Interface (for an access client communicating with the InterChange Server integration broker) can use. The DataHandler base class is an abstract class. Therefore, to instantiate a data handler, you must instantiate one of the DataHandler subclasses. Each data handler, either an IBM-delivered data handler or a custom data handler, is a subclass of the DataHandler base class. The method to instantiate an instance of a data handler is createHandler().
The createHandler() method uses information in the data-handler meta-objects to determine which data handler to instantiate and how to initialize this data handler. 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:
The createHandler() method takes the following steps to instantiate a data handler:
For a data handler to be created, an implementation of the DataHandler base class must be instantiated. The data-handler instantiation method derives the name of this data-handler class from one of two values, which is passed in as an argument to the createHandler() method:
If the data-handler caller passes in a class name as an argument, createHandler() instantiates a data handler of that class name. It looks for the specified class in the following places:
If the caller provides only the class name for the data handler, createHandler() neither looks for data-handler meta-objects nor sets configuration properties from these objects. Therefore, a data handler instantiated in this way does not require meta-objects. For more information on whether a custom data handler should use meta-objects, see Using data-handler meta-objects.
If the data-handler caller does not pass in the class name as an argument, the createHandler() method requires a value for a MIME type. When a calling component (connector or access client) passes a MIME type, createHandler() 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.
To derive a class name from a specified MIME type, the createHandler() method takes the following steps:
When the createHandler() method searches the top-level data-handler meta-object, it converts any non-alphanumeric characters, such as a hyphen (-), period (.) or slash (/), to an underscore (_). For example, if the MIME type is text/html, createHandler() parses the type to the string text_html.
The createHandler() method performs this conversion of non-alphanumeric characters is done in stages, so that matches of MIME type names that contain periods can occur. However, Business Object Designer does not allow the period character in attribute names. Therefore, IBM recommends that you do not include them in the MIME type names.
You can create unique MIME type/ subtype combinations to indicate variations on a particular MIME type. In the MIME-type name, you separate the MIME type and subtype with a non-alphanumeric character (such as a hyphen or underscore). However, because createHandler() replaces any non-alphanumeric character with an underscore, IBM recommends that you use only an underscore to separate the MIME type and subtype. If the MIME type is text/xml-sgml, the method converts the type to the string text_xml_sgml.
MIMETypeString_BOPrefix
If no attribute of this name exists, createHandler() looks for an attribute that matches only the MIME type. For example, if the caller passes in a MIME type of edi and a business-object prefix of x12, createHandler() looks for an attribute in the top-level meta-object named "edi_x12". If no attribute by this name exists, createHandler() looks for an attribute named "edi".
com.crossworlds.DataHandlers
For example, if the MIME-type string is text_html, the resulting string is:
com.crossworlds.DataHandlers.text.html
If the caller provides both the class name and the MIME type, createHandler() takes the following actions:
In other words, when the caller provides a class name, this class name overrides the class name specified in the ClassName attribute of the child meta-object.
All IBM-delivered data handlers (see Table 3 and Table 4) are designed to use data-handler meta-objects for their configuration information. A data-handler meta-object is a hierarchical business object:
The IBM-delivered data handlers use the configuration information in its associated a child data-handler meta-object to initialize its properties. Therefore, IBM delivers a child meta-object for each of its delivered data handlers (see Table 9).
After the createHandler() method instantiates the data handler instance, it calls a special protected method, setupOptions(), to initialize the data handler's configuration with the values in the appropriate child data-handler meta-object.
For more information on meta-objects, see Configuring data handlers.
The createHandler() method can accept an optional business-object prefix as its third argument. It uses this argument to determine the MIME type name (see Using a MIME type). After createHandler() has instantiated the data handler instance and set its configuration properties, its final task is to set the value of the BOPrefix configuration option (if one exists) in the data handler to the value of this third argument.
The data handler can prepend this prefix to the names of any business objects that it creates (during string-to-business-object conversion). It puts an underscore (_) between the prefix and the business-object name. For example, a connector might invoke the XML data handler with the following createHandler() call:
createHandler(null, "text/xml", "UserApp");
The createHandler() method instantiates the XML data handler and set its BOPrefix attribute to "UserApp". When the XML data handler creates a Customer business object, it: