Sending downstream messages received from a source on to a codec plug-in

In order that messages can be easily sent on to a codec plug-in, an event transport will usually have saved a reference to the event codec(s) it will be using before it establishes a connection to the external source.

Typically an event transport will build up a list of registered codec plug-ins from the parameters passed to the addEventDecoder and removeEventDecoder methods. If this is the case, the start method of the plug-in can select one of these plug-ins on the basis of a plug-in property provided in the configuration file (e.g. <property name="decoderName" value="MyCodec"/>), and saving it in an instance field (e.g. currentDecoder).

Once the plug-in has a reference to the event codec (or codecs) it will use, whenever an external message is received it should be passed on by calling the sendTransportEvent method on the codec plug-in (from the EventDecoder interface):

/**
* 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;

MyCustomMessageType message = myCustomMessageSource.getNextMessage();
currentDecoder.sendTransportEvent(message, timestamps);

If an error occurs in the codec or Semantic Mapper layers preventing the message from being converted into an Apama event, a CodecException or SemanticMapperException is thrown. Like all per-message errors, these should be logged at Warning level, preferably with a full stack trace logged at Debug level too. If necessary, transports may also send messages downstream to the correlator to inform running monitors about the error.

When a transport sends a message to the codec via the sendTransportEvent method, it passes an Object reference and this allows custom types to be passed between the two plug-ins. However, any custom types should be loaded via the main (parent) classloader, as each plug-in specified in the IAF configuration file is loaded with its own classloader. Consider, for example, the following three classes all loaded into a single jar file, MyAdapter.jar, which is used in the IAF configuration file in the jarName attribute of the <transport> element.:

When you load the transport and codec, a new classloader is used for each. This means both have their own copy of the MyContainer class. When the transport creates an instance of MyContainer and then passes it into the codec, the codec will recognize that the Object getClass().getName() is MyContainer, but will not be able to cast it to this type as its MyContainer class is from a different classloader.

To prevent this from happening, make sure that all shared classes are in a separate jar that is specified by a <classpath> element. The shared classes are then loaded by the parent classloader. This ensures that when a codec or transport references a shared class, they will both agree it is the same class.