Building a custom name handler

A data handler can call a name handler to extract the name of a business object definition from the serialized data. This task is needed during string-to-business-object conversion when the caller of the data handler does not pass in a business object to be populated with the serialized data. In this case, the data handler must create the business object before it can populate it. To create the business object, the data handler must know the name of the associated business object definition. It is the name handler that obtains this business object name.

Note:
Currently, the XML and EDI data handlers use name handlers to obtain the name of the business object to create.

The task of creating and implementing a custom name handler includes the following general steps:

  1. Create a class that extends the NameHandler class.
  2. Implement the abstract getBOName() method that reads the serialized data and returns the business object name.
  3. Compile the class and add it to the DataHandlers\CustDataHandler.jar file. For more information, see Adding a data handler to the jar file.
  4. Set the default value of the NameHandlerClass attribute in the meta-object for the data handler.

Extending the NameHandler class

To create a custom name handler, you extend the name-handler base class (NameHandler) to create your own name-handler class. The NameHandler class contains the method to extract the name of a business object from serialized data. The package for this name-handler base class is com.crossworlds.DataHandlers.NameHandler.

To dervide a name-handler class, follow these steps:

  1. Create a name-handler class that extends the NameHandler class.
  2. Ensure that the name-handler class file imports the classes of the NameHandler package:
    import 
     
    
  3. Implement the getBOName() method, which is the abstract method in the NameHandler class. For more information, see Implementing the getBOName() method.

The definition of the NameHandler class follows:

// Imports
 import java.lang.String;
 import java.io.Reader;
 import com.crossworlds.DataHandlers.Exceptions.MalformedDataException;
  
 public abstract class NameHandler {
  
 // Constructors
 public NameHandler() { }
  
 // Methods
 public abstract String getBOName(Reader serializedData,
 String boPrefix) 
 throws MalformedDataException;
 }
  
 /* This method was introduced so that the NameHandler would have 
  * a reference to the DataHandler. The DataHandler base calls this
  * method after it instantiated the NameHandler:
  * eg. nh = (NameHandler)Class.forName(className).newInstance();
  *     nh.setDataHandler(this);
 */
 public final void setDataHandler( DataHandler dataHandler )
 {
 dh = dataHandler;
 }
 

To create your own name handler, extend the NameHandler abstract base class.

Implementing the getBOName() method

Extending the NameHandler class requires implementing the getBOName() method, which reads serialized data and returns the name of the business object associated with the data. The syntax for this method is:

public abstract String getBOName(Reader serializedData, String BOPrefix) 
 throws MalformedDataException
 

where:

serializedData
Is a reference to an object that contains the message.
BOPrefix
Is a String value that contains the business object prefix for the names of the business object definitions; this argument can be set to the BOPrefix attribute in the meta-object (if one exists).

Setting the meta-object attribute

To tell the data handler to use a custom name handler, you must set the Default Value property of a meta-object attribute to the full class name. The data handler can then obtain the class name at runtime from one of its configuration options. By default, this meta-object attribute is called NameHandlerClass. The child meta-object associated with both the XML and EDI data handlers include this attribute. The IBM-delivered default value for this attribute specifies the name of the default name handler class. To have a data handler use a custom name handler, make sure that you update the Default Value property for the NameHandlerClass attribute in the child meta-object associated with the data handler you extend.

Copyright IBM Corp. 1997, 2003