Package com.apama.iaf.plugin

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

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      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)
      This is the method that a codec layer plug-in calls when it receives a translated upstream Apama event that needs to be sent on to an event transport for transmission to an external message sink.
      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. A typical constructor would create a logger using the plug-in name provided and make a call to the updateProperties(EventTransportProperty[], TimestampConfig) method to deal with the initial property set passed in, and perform any other initialization operations required for the particular transport being developed.

        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. The properties array contains an EventTransportProperty 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 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. In an adapter in which multiple event codecs could be present, this function would usually be implemented by storing the name, decoder pair in a Java map, from which the EventDecoder could later be retrieved using a plug-in property (for example, "decoderName") to determine which of the plug-ins in the map should be used. Alternatively, if this transport plug-in will only ever be used in an adapter with just one codec plug-in, this method can be implemented simply by storing the provided EventDecoder object in an instance field.
        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. Usually has a blank implementation, unless there is some kind of upstream buffering.
        Throws:
        TransportException

      • start

        public abstract void start()
                    throws TransportException
        Establish a connection and start processing incoming data from the external transport.

        This is where a plug-in should establish a connection to its external message source/sink, often by starting a new thread to process or poll for new downstream messages. Events should not be sent to the correlator until the start method has been called. 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.

        New events arriving may be blocked, queued or simply dropped, but under no circumstances should any be sent into the adapter until the start() function is called. 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. This is where any heavy-weight threads or data structures used for interfacing with the external transport that do not get cleaned up when the plug-in is stopped should be destroyed.
        Throws:
        TransportException

      • getStatus

        public abstract TransportStatus getStatus()
        Return a TransportStatus or ExtendedTransportStatus object containing up-to-date status information for the transport. 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 TransportStatus object together with a String describing the current status of the plug-in (maximum length 1024 characters), and returned. As an example 
         
 public TransportStatus getStatus()
 {      
         String status = (started) ? "Status: Running" : "Status: Not running";
         return new TransportStatus(status, totalReceived, totalSent);
 }
        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
        This is the method that a codec layer plug-in calls when it receives a translated upstream Apama event that needs to be sent on to an event transport for transmission to an external message sink. 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 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.
        See Also:
        com.apama.iaf.plugin.EventTransport#sendTransportEvent(java.lang.Object)