Building a Custom Formatter Module

Use the ESP adapter toolkit to build a custom formatter module to use within the adapter instance of your choice.

1. Create a class that extends one of these Java classes:
   • (Row-based formatter) com.sybase.esp.adapter.framework.module.RowFormatter
   • (Streaming-based formatter) com.sybase.esp.adapter.framework.module.StreamingFormatter

   Make row-based formatters a subclass of RowFormatter, and stream-based formatters a subclass of StreamingFormatter. Use row-based formatters with row-based transporters, and stream-based formatters with stream-based transporters.

2. For row-based formatters, implement these functions:
   1. The init() function.
      Prepare your formatter module to convert between data formats; for example, obtain properties from the adapter configuration file and perform any required initialization tasks.
   2. The destroy() function.
      Perform cleanup actions for your formatter.
   3. The convert() function.
      Here is a simple example of a convert() function that converts Java objects to strings:

      public AdapterRow convert(AdapterRow in) throws Exception {
      	Object obj = in.getData(0);
      	in.setData(0, obj.toString());
      	return in;
      }

3. For stream-based formatters, implement these functions:
   1. The init() function.
      Prepare your formatter module to convert between data formats; for example, obtain properties from the adapter configuration file and perform any required initialization tasks.
   2. The start() function.
      Perform any necessary tasks when the adapter is started.
   3. The execute() function.
      Here is an example of the execute() function for a formatter that converts row-based data into stream-based:

      public void execute() throws Exception {
      	OutputStream output = utility.getOutputStream();
      	while(!utility.isStopRequested())
      	{
      	  AdapterRow row = utility.getRow();
      	    if(row != null)
      	    {
      		AepRecord record = (AepRecord)row.getData(0);
      		String str = record.getValues().toString() + "\n";
      		output.write(str.getBytes());
      	    }
      	  }
      	}

      For a formatter that converts from stream-based data into row-based, use:

      • utility.getInputStream() to obtain the InputStream
      • utility.createRow() to create the AdapterRow objects
      • utility.sendRow() to send the rows to the next module specified in the adapter configuration file
   4. The stop() function.
      Perform any necessary tasks when the adapter is stopped.
   5. The destroy() function.
      Perform clean up actions for your formatter.
4. (Optional) Call one of the following functions within the functions listed in the steps above:
   • Call utility.getParameters() to get parameters that are defined in the adapter configuration file.
   • Call utility.sendRow() to send data to the next module defined in the adapter configuration file.
   • Call utility.getRow() to obtain data from the previous module defined in the adapter configuration file.
   • Call utility.isStopRequested() to determine whether a stop command has been issued.
5. Register the implemented Java class to $STREAMING_HOME/adapters/framework/config/modulesdefine.xml. For example:

   <FormatterDefn>
   <Name>SampleFormatter</Name>
   <Class>com.sybase.esp.adapter.formatters.SampleFormatter</Class>
   <InputData>String</InputData>
   <OutputData>ESP</OutputData>
   <ParametersNodeName>SampleFormatterParameters</ParametersNodeName>
   </FormatterDefn>

   where <ParametersNodeName> is the optional node that represents the formatter subnode name in the adapter configuration file.

6. Add the schema definitions for any unique parameters of the newly created module to the $STREAMING_HOME/adapters/framework/config/parametersdefine.xsd file.
   If any of the parameters for the newly created module are the same as parameters for the standard formatter modules, you need not to add schema definitions for these parameters.
7. Copy the .jar file containing the class you previously implemented to $STREAMING_HOME/adapters/framework/libj.
8. (Optional) Start the adapter instance by issuing:

   $STREAMING_HOME/adapters/framework/bin/start.bat <config file> or $STREAMING_HOME/adapters/framework/bin/start.sh <config file>

   where <config file> is the adapter configuration file in which you specified the adapter instance using the newly created formatter module.

9. (Optional) Stop the adapter instance by issuing:

   $STREAMING_HOME/adapters/framework/bin/stop.bat <config file> or $STREAMING_HOME/adapters/framework/bin/stop.sh <config file>

   where <config file> is the adapter configuration file in which you specified the adapter instance using the newly created formatter module.