com.apama.iaf.plugin
Class AbstractEventCodec

java.lang.Object
  com.apama.iaf.plugin.AbstractEventCodec

All Implemented Interfaces:

EventCodec, EventDecoder

public abstract class AbstractEventCodec
extends java.lang.Object
implements EventCodec

AbstractEventCodec is the abstract base class which all Java IAF event codecs should extend. It includes the EventCodec interface the IAF uses to tell the codec to send an upstream event, and also contains abstract definitions of the other methods the IAF will need to call (via a JNI interface to libraries written in C)

In addition to implementing the abstract methods here and in the EventCodec interface, valid subclasses must provide a constructor with the same signature as the one provided here. Note that the IAF provides NO guarantees about what threads that will be used to call these functions, so to ensure correct operation care must be taken to use locking where required.

Field Summary

Fields inherited from interface com.apama.iaf.plugin.EventCodec

API_VERSION

Constructor Summary

AbstractEventCodec(java.lang.String name, EventCodecProperty[] properties, TimestampConfig timestampConfig)
Construct a new instance of AbstractEventCodec.

Method Summary

abstract void	addEventTransport(java.lang.String name, EventTransport transport) Add a named event transport to the set of transports known to the codec.
abstract void	cleanup() Frees any resources allocated by the codec (useful for resources external to the JVM that were allocated in the constructor).
void	flushDownstream() Flush any pending codec events into the semantic mapper.
void	flushUpstream() Flush any pending codec events onto the transport.
abstract int	getAPIVersion() Return the codec API version that the codec was built against.
int	getCapabilities() Return the capabilities of the codec.
abstract CodecStatus	getStatus() Return a CodecStatus or ExtendedCodecStatus object containing up-to-date status information for the codec.
abstract void	removeEventTransport(java.lang.String name) Remove a named event transport from the set of transports known to the codec.
abstract void	sendNormalisedEvent(NormalisedEvent event, TimestampSet timestamps) Called by the Semantic Mapper to encode a normalised event and send it through to the transport.
abstract void	sendTransportEvent(java.lang.Object event, TimestampSet timestamps) Called by the event transport to decode a downstream event using a Java Codec, which will then send it on to the Semantic Mapper.
abstract void	setSemanticMapper(SemanticMapper mapper) Set the Semantic Mapper object to be used by the decoder.
java.lang.String	toString()
void	updateProperties(EventCodecProperty[] properties, TimestampConfig timestampConfig) Update the configuration of the codec.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractEventCodec

public AbstractEventCodec(java.lang.String name,
                          EventCodecProperty[] properties,
                          TimestampConfig timestampConfig)
                   throws CodecException

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.

The AbstractEventCodec implementation does nothing, but subclasses should make use of the arguments to initialize the codec.

Parameters:

name - The codec name, as specified in the IAF config file

properties - The codec property set specified in the IAF configuration file

timestampConfig - Timestamp recording/logging settings from the IAF configuration file

Throws:

CodecException

Method Detail

updateProperties

public void updateProperties(EventCodecProperty[] properties,
                             TimestampConfig timestampConfig)
                      throws CodecException

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.

Parameters:

properties - The new codec property set specified in the IAF configuration file

timestampConfig - Timestamp recording/logging settings

Throws:

CodecException

addEventTransport

public abstract void addEventTransport(java.lang.String name,
                                       EventTransport transport)
                                throws CodecException

Add a named event transport to the set of transports known to the codec. If the named transport already exists, it should be replaced.

Parameters:

name - The name of the transport to be added

transport - The transport object instance

Throws:

CodecException

removeEventTransport

public abstract void removeEventTransport(java.lang.String name)
                                   throws CodecException

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.

Parameters:

name - The transport to be removed

Throws:

CodecException

setSemanticMapper

public abstract void setSemanticMapper(SemanticMapper mapper)
                                throws CodecException

Set the Semantic Mapper object to be used by the decoder. Currently only a single Semantic Mapper is supported in each adapter instance.

Parameters:

mapper - The Semantic mapper object instance

Throws:

CodecException

flushUpstream

public void flushUpstream()
                   throws CodecException

Flush any pending codec events onto the transport. In many cases no action will be required to complete the flushing operation.

Throws:

CodecException

flushDownstream

public void flushDownstream()
                     throws CodecException

Flush any pending codec events into the semantic mapper. In many cases no action will be required to complete the flushing operation.

Throws:

CodecException

cleanup

public abstract void cleanup()
                      throws CodecException

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

getStatus

public abstract CodecStatus getStatus()

Return a CodecStatus or ExtendedCodecStatus object containing up-to-date status information for the codec.

Returns:

An immutable CodecStatus or ExtendedCodecStatus class containing status information.

getAPIVersion

public abstract int getAPIVersion()

Return the codec API version that the codec was built against.

Returns:

Must be EventCodec.API_VERSION.

getCapabilities

public int getCapabilities()

Return the capabilities of the codec. In this version, all values are reserved for future use.

Returns:

Must be 0.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

sendTransportEvent

public abstract void sendTransportEvent(java.lang.Object event,
                                        TimestampSet timestamps)
                                 throws CodecException,
                                        SemanticMapperException

Description copied from interface: EventDecoder

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.

Specified by:

sendTransportEvent in interface EventDecoder

Parameters:

event - An object representing the event to be decoded, in a format shared by the decoder and transport.

timestamps - A TimestampSet representing the timestamps attached to the event.

Throws:

CodecException - Thrown by the decoder if the event provided has an invalid format.

SemanticMapperException - Thrown if an error occurred during processing of the message by the Semantic Mapper.

sendNormalisedEvent

public abstract void sendNormalisedEvent(NormalisedEvent event,
                                         TimestampSet timestamps)
                                  throws CodecException,
                                         TransportException

Description copied from interface: EventCodec

Called by the Semantic Mapper to encode a normalised event and send it through to the transport.

Specified by:

sendNormalisedEvent in interface EventCodec

Parameters:

event - A NormalisedEvent representing the event to be encoded.

timestamps - A TimestampSet representing the timestamps attached to the event.

Throws:

CodecException - Thrown by the codec if the event provided has an invalid format.

TransportException - Thrown if an error occurred in the Transport when sending the message.