Package com.apama.iaf.plugin

Class 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.

    • 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. 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.
        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. In an adapter in which multiple event transports could be present, this function would usually be implemented by storing the 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 (for example, "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.
        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. This method is usually implemented by removing the named transport plug-in from a map, or nulling out a field holding the previously added EventTransport.
        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. This method is usually implemented by storing the provided SemanticMapper object in an instance field, for use when sending on downstream messages.
        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. Usually has a blank implementation, unless there is some kind of upstream buffering.
        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. Usually has a blank implementation, unless there is some kind of downstream buffering.
        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. 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. For example: 
        
  public CodecStatus getStatus() 
        {    String status = "Status: OK"; 
                return new TransportStatus(status, totalReceived, totalSent); 
        }
        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
        This is the method that a transport layer plug-in calls when it receives a message that should be decoded and then sent downstream towards the Apama correlator. 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.
        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
        This is the method that the Semantic Mapper calls when it receives a message that should be encoded and then sent upstream to an event transport. 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.
        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.