Java codec functions to implement

HTML Javadoc documentation for AbstractEventCodec and related classes is provided as part of the Apama documentation set. The Javadoc files are located in the Apama installation's doc\javadoc directory.

This topic includes the text of the Javadoc documentation for the functions that a codec plug-in author needs to implement, in addition to some pointers on how such plug-ins are usually written.

The Constructor

/**
  * Construct a new instance of AbstractEventCodec. All subclasses MUST
  * provide a constructor with the same signature, which will be used by the
  * IAF to create an instance of the codec class. <P><P>
  *
  * The AbstractEventCodec implementation does nothing, but subclasses
  * should make use of the arguments to initialize the codec.
  *
  * @param name The codec name, as specified in the IAF config file
  * @param properties The codec property set specified in the IAF
  * configuration file
  * @parm timestampConfig The timestamp recording/logging settings from the
  * IAF configuration file

* @throws CodecException
*/
public AbstractEventCodec(String name, EventCodecProperty[] properties,
      TimestampConfig timestampConfig)
    throws CodecException

A typical constructor would create a logger using the plug-in name provided (see Logging from plug-ins in Java), make a call to the updateProperties method to deal with the initial property set passed in, and perform any other initialization operations required for the particular event codec being developed.

updateProperties

/**
* Update the configuration of the codec. The codec may assume
* that flushUpstream() and flushDownstream() have been called
* before this function is invoked. The recommended procedure for
* updating properties is to first compare the new property set with the
* existing stored properties - if there are no changes, no action should
* be taken.
*
* @param properties The new codec property set specified in the IAF
* configuration file
* @param TimestampConfig timestampConfig
* @throws CodecException
*/
abstract public void updateProperties(EventCodecProperty[] properties,
TimestampConfig timestampConfig)
throws CodecException;

The properties array contains an EventCodecProperty object for each plug-in property specified in the IAF configuration file (in order). The getName and getValue methods allow the plug-in to retrieve the name and value of each property as String objects.

addEventTransport

/**
* Add a named event transport to the set of transports known to the
* codec. If the named transport already exists, it should be
* replaced.
*
* @param name The name of the transport to be added
* @param transport The transport object instance
* @throws CodecException
*/
abstract public void addEventTransport(String name, EventTransport transport)
throws CodecException;

In an adapter in which multiple event transports could be present, this function would usually be implemented by storing the <name, transport> pair in a Java map, from which the EventTransport object could later be retrieved when required by the sendNormalisedEvent method, using a plug-in property (e.g. “transportName” to determine which of the plug-ins in the map should be used.

Alternatively, if this codec plug-in will only ever be used in an adapter with just one transport plug-in, this method can be implemented simply by storing the provided EventTransport object in an instance field.

removeEventTransport

/**
* Remove a named event transport from the set of transports known to the
* codec. If the named transport does not exist, the function should do
* nothing.
*
* @param name The transport to be removed
* @throws CodecException
*/
abstract public void removeEventTransport(String name)
throws CodecException;

setSemanticMapper

/**
* Set the Semantic Mapper object to be used by the decoder. Currently
* only a single Semantic Mapper is supported in each adapter instance.
*
* @param mapper The Semantic mapper object instance
* @throws CodecException
*/
abstract public void setSemanticMapper(SemanticMapper mapper)
throws CodecException;

flushUpstream

/**
* Flush any pending codec events onto the codec. In many cases no action
* will be required to complete the flushing operation.
*
* @throws CodecException
*/
abstract public void flushUpstream() throws CodecException;

flushDownstream

/**
* Flush any pending codec events into the decoder. In many cases no action
* will be required to complete the flushing operation.
*
* @throws CodecException
*/
abstract public void flushDownstream() throws CodecException;

cleanup

/**
* Frees any resources allocated by the codec (useful for resources
* external to the JVM that were allocated in the constructor). The IAF
* guarantees to call this method exactly once.
*
* @throws CodecException
*/
abstract public void cleanup() throws CodecException;

getStatus

/**
* Return a CodecStatus class containing up-to-date status information
* for the codec.
*
* @return An immutable CodecStatus class containing status
* information.
*/
abstract public CodecStatus getStatus();

This method provides the statistics and status message displayed by the IAF Watch tool. A typical plug-in will continuously keep track of the number of messages sent upstream and downstream. Then, when getStatus is called, these message counts can simply be packaged up in a new CodecStatus object together with a String describing the current status of the plug-in (maximum length 1024 characters), and returned.

public CodecStatus getStatus()
{ String status = "Status: OK";
return new TransportStatus(status, totalReceived, totalSent);
}

getAPIVersion

/**
* Return the codec API version that the codec was built against.
* @return Must be EventCodec.API_VERSION.
*/
public abstract int getAPIVersion();

sendTransportEvent

/**
* Called by the event transport to decode a downstream event using a Java
* Codec, which will then send it on to the Semantic Mapper. It is assumed
* that the encoder and transport share the same definition
* of the content of the event, so that the transport can effectively
* interpret the event.
*
* @param event An object representing the event to be decoded, in a format
* shared by the decoder and transport.
* @param timestamps A TimestampSet representing the timestamps attached to
* the event.
*
* @throws CodecException Thrown by the decoder if the event provided
* has an invalid format.
* @throws SemanticMapperException Thrown if an error occurred during
* processing of the message by the Semantic Mapper.
*/
public void sendTransportEvent(Object event, TimestampSet timestamps)
throws CodecException, SemanticMapperException;

Note that there are no guarantees about which threads might be used to call this method, so plug-in authors will need to consider any thread synchronization issues arising from use of shared data structures here.

sendNormalisedEvent (send upstream)

/**
* Called by the Semantic Mapper to encode a normalized event and send
* it directly through to the transport.
*
* @param event A NormalisedEvent representing the event to be encoded.
* @params timestamps A TimestampSet representing the timestamps attached to
* the event.
*
* @throws CodecException Thrown by the codec if the event provided
* has an invalid format.
* @throws TransportException Thrown if an error occurred in the Transport
* when sending the message.
*/
public void sendNormalisedEvent(NormalisedEvent event,
TimestampSet timestamps)
throws CodecException, TransportException;

See Communication with other layers for more information about processing upstream messages and passing them on to a transport plug-in. See Working with normalized events for help working with NormalisedEvent objects.