com.apama.iaf.plugin
Class AbstractEventTransport

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

All Implemented Interfaces:

EventTransport

public abstract class AbstractEventTransport
extends java.lang.Object
implements EventTransport

AbstractEventTransport is the abstract base class which all Java IAF event transports should extend. It includes the EventTransport interface the IAF uses to tell the transport 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 EventTransport 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.EventTransport

API_VERSION

Constructor Summary

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

Method Summary

abstract void	addEventDecoder(java.lang.String name, EventDecoder decoder) Add a named event decoder to the set of decoders known to the transport.
abstract void	cleanup() Frees any resources allocated by the transport (useful for resources external to the JVM that were allocated in the constructor).
void	flushDownstream() Flush any pending transport events into the decoder.
void	flushUpstream() Flush any pending normalized events onto the external transport.
abstract int	getAPIVersion() Return the transport API version that the transport was built against.
int	getCapabilities() Return the capabilities of the transport.
abstract TransportStatus	getStatus() Return a TransportStatus or ExtendedTransportStatus object containing up-to-date status information for the transport.
abstract void	removeEventDecoder(java.lang.String name) Remove a named event decoder from the set of decoders known to the transport.
abstract void	sendTransportEvent(java.lang.Object event, TimestampSet timestamps) Called by an event encoder to send an upstream message to the external transport.
abstract void	start() Establish a connection and start processing incoming data from the external transport.
abstract void	stop() Stop processing incoming data from the external transport, typically by pausing or closing down connections.
java.lang.String	toString()
void	updateProperties(EventTransportProperty[] properties, TimestampConfig timestampConfig) Update the configuration of the transport.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractEventTransport

public AbstractEventTransport(java.lang.String name,
                              EventTransportProperty[] properties,
                              TimestampConfig timestampConfig)
                       throws TransportException

Construct a new instance of AbstractEventTransport. All subclasses MUST provide a constructor with the same signature, which will be used by the IAF to create an instance of the transport class.

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

Parameters:

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

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

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

Throws:

TransportException

Method Detail

updateProperties

public void updateProperties(EventTransportProperty[] properties,
                             TimestampConfig timestampConfig)
                      throws TransportException

Update the configuration of the transport. The transport may assume that stop(), flushUpstream() and flushDownstream() have all 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 transport property set specified in the IAF configuration file

timestampConfig - Timestamp recording/logging settings

Throws:

TransportException

addEventDecoder

public abstract void addEventDecoder(java.lang.String name,
                                     EventDecoder decoder)
                              throws TransportException

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

Parameters:

name - The name of the decoder to be added

decoder - The decoder object instance

Throws:

TransportException

removeEventDecoder

public abstract void removeEventDecoder(java.lang.String name)
                                 throws TransportException

Remove a named event decoder from the set of decoders known to the transport. If the named decoder does not exist, the function should do nothing.

Parameters:

name - The decoder to be removed

Throws:

TransportException

flushUpstream

public void flushUpstream()
                   throws TransportException

Flush any pending normalized events onto the external transport. The transport may assume that the stop() function has been called before this function, so in many cases no action will be required to complete the flushing operation.

Throws:

TransportException

flushDownstream

public void flushDownstream()
                     throws TransportException

Flush any pending transport events into the decoder. The transport may assume that the stop() function has been called before this function, so in many cases no action will be required to complete the flushing operation. Under no circumstances should any events be sent to the Correlator after flushDownstream() has returned.

Throws:

TransportException

start

public abstract void start()
                    throws TransportException

Establish a connection and start processing incoming data from the external transport.

An adapter should send events to the correlator only after its start() method is called and before the stop() method returns. Therefore we strongly recommend that a transport should not change to a state where it is possible to receive events from any external transport until the start() method has been called. In many cases, adapters will also need to communicate with service monitors in the correlator to ensure that the required monitors and event definitions are injected before they begin to process messages from the external system. This is necessary in order to avoid events from the adapter being lost if the correlator is not yet ready to parse and process them.

Throws:

TransportException

stop

public abstract void stop()
                   throws TransportException

Stop processing incoming data from the external transport, typically by pausing or closing down connections.

Adapter authors must ensure that no events are sent to the Correlator after stop() has returned (the only exception being rare cases where the transport sends buffered events in the Correlator in the flushDownstream() method, which is called by the IAF after stop()). If necessary any messages that are unavoidably received from the transport after stop() has returned should be blocked, queued or simply dropped.

Throws:

TransportException

cleanup

public abstract void cleanup()
                      throws TransportException

Frees any resources allocated by the transport (useful for resources external to the JVM that were allocated in the constructor). The IAF guarantees to call this method exactly once.

Throws:

TransportException

getStatus

public abstract TransportStatus getStatus()

Return a TransportStatus or ExtendedTransportStatus object containing up-to-date status information for the transport.

Returns:

An immutable TransportStatus or ExtendedTransportStatus object containing status information.

getAPIVersion

public abstract int getAPIVersion()

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

Returns:

Must be EventTransport.API_VERSION.

getCapabilities

public int getCapabilities()

Return the capabilities of the transport. 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 TransportException

Description copied from interface: EventTransport

Called by an event encoder to send an upstream message to the external transport.

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 EventTransport

Parameters:

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

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

Throws:

TransportException - Thrown by the transport if any error occurs sending the message.