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.

Prerequisites

(Optional) See the $ESP_HOME/adapters/framework/examples/src directory for source code for sample formatters.

Task

Create a class which 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.
For row-based formatters, implement these functions:
1. The init() function.
  Prepare your formatter module for converting between data formats, such as obtaining properties from the adapter configuration file and performing any required initialization tasks.
2. The destroy() function.
  Perform clean up actions for your formatter.
3. The convert() function.
  Here is a simple example of a convert() function which converts Java objects to strings:
```
public AdapterRow convert(AdapterRow in) throws Exception {
	Object obj = in.getData(0);
	in.setData(0, obj.toString());
	return in;
}
```
For stream-based formatters, implement these functions:
1. The init() function.
  Prepare your formatter module for converting between data formats, such as obtaining properties from the adapter configuration file and performing 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 which 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 which 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.
(Optional) Call one of the following functions within the functions listed in the steps above:
- Call utility.getParameters() to get parameter which are defined in the adapter configuration file.
- Call utility.sendRow() to send data to the next module which is defined in the adapter configuration file.
- Call utility.getRow() to obtain data from the previous module which is defined in the adapter configuration file.
- Call utility.isStopRequested() to determine whether a stop command has been issued.
Register the implemented Java class to $ESP_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 representing the formatter subnode name in the adapter configuration file.
Add the schema definitions for any unique parameters of the newly created module to the $ESP_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 do not need to add schema definitions for these parameters.
Copy the .jar file containing the class you previously implemented to $ESP_HOME/adapters/framework/libj.
(Optional) Start the adapter instance by issuing this command:

$ESP_HOME/adapters/framework/bin/start.bat <config file> or $ESP_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.
(Optional) Stop the adapter instance by issuing this command:

$ESP_HOME/adapters/framework/bin/stop.bat <config file> or $ESP_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.

Refer to $ESP_HOME/adapters/framework/examples for additional details and formatter examples, as well as $ESP_HOME/adapters/framework/examples/src for the source code for these examples.

Next

Create an adapter configuration (.xml) file to define which adapter instance uses this newly created formatter module