Adding your own FormatElement

The Built-in FormatElements provide a set of format elements. But they cannot cover all the requirements in your application development.

To add your own format element according to your needs, do the following:

  1. Add your class name into the class table of format component:
    <?xml version="1.0"?>
    <btt.xml>
        <kColl id="components">
            <kColl id="format">
                <field id="initializer"
    				        value="com.ibm.btt.format.FormatInitializer" />
                <field id="extFile" value="format.xml" />
                <kColl id="classTable">
                    <field id="myFormat" value="com.mycompany.format.MyFormatElement" />
                </kColl>
            </kColl>
        </kColl>
    </btt.xml> 
  2. Create a Java™ class com.mycompany.format.MyFormatElement. This class needs to be a subclass of com.ibm.btt.format.CompositeFormat, com.ibm.btt.format.FieldFormat or com.ibm.btt.format.BaseDecorator. Any class in package com.ibm.btt.format.impl is not intended to be subclassed.
  3. Create default constructor method for class com.mycompany.format.MyFormatElement. Every format element can be instantiated by default constructor method.
  4. Create get and set methods for your attributes. Format element can be customized in definition. For example, you can specify encoding attribute for com.ibm.btt.format.impl.StringFormat in the format definition xml tag. If your format element has some attributes to be customized, you need to create get and set methods for them. The methods need to comply with Java Bean specification. When you create the instance of FormatElement, FormatFactory populates your attributes from definition automatically. Your attribute can be in simple types such as int, Integer, float, Float, long, Long, double, Double, byte, Byte, char, Character and String, and so on.
  5. Override or implement methods from base class in class com.mycompany.format.MyFormatElement. The following table tells which method you should override or implement.
    Table 1. Methods that can be overridden
    Base Class Methods Override Description
    CompositeFormat public Message[] extract(Message message) throws ExtractException; YES Split the input message into two messages, and return them as an array in length of 2. The first message in the array is the message that should be processed by this format element, and the second message is the remaining message.

    Take Message 1FCD2639FE for example: the returned array of Message may be {1FCD, 2639FE}. The first element 1FCD is the Message required by this FormatElement, while the second element 2639FE is the remaining Message.
    public Message format(ReadAdapter dataAdapter) throws FormatException; YES Translate the data into binary message.
    public void unformat(Message message, WriteAdapter dataAdapter) throws UnformatException YES Translate the binary message into data.
    public List<FormatElement>getChildren (); NO Return the children format element of the composite format element. You can call it in extract, format and unformat methods.
    FieldFormat public Message[] extract(Message message) throws ExtractException; YES Split the input message into two messages, and returned them as an array in length of 2.
    public Message format(ReadAdapter dataAdapter) throws FormatException; YES Translate the data into binary message.
    public void unformat(Message message, WriteAdapter dataAdapter) throws UnformatException YES Translate the binary message into data.
    BaseDecorator public Message[] extract(Message message) throws ExtractException; YES Split the input message into two messages, and returned them as an array in length of 2.
      protected Message addDecoration(Message message) throws FormatException; YES Modify the binary message after execute format method of the decorated format element.
      protected Message removeDecoration(Message message) throws UnformatException; YES Modify the binary message before execute unformat method of the decorated format element.
  6. Override attribute() method if needed.
    protected Map<String, String> attributes();

    You can override this method. It returns a Map with both key and value in type of String. The key represents the attribute name and the value represents the attribute value. This method is only used in toString() method of the format element.