Package com.apama.services.event

Interface IEventServiceChannel

  • public interface IEventServiceChannel
    IEventServiceChannel is the public interface for a class that represents a channel or channels on which events are received from a Correlator.

    IEventServiceChannel is an interface that forms part of the service style high-level public interface to the Correlator with a focus on only dealing with Events and consumer channels.

    To create an IEventServiceChannel, use the IEventService.addChannel(String[], Map) method. If the channel is no longer required, it can be removed using IEventService.removeChannel(String[])
    See Also:
    IEventService

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addEventListener​(IEventListener eventListener)
      Add an IEventListener that will be notified of every event (of a pre-registered type) that is received by this EventServiceChannel instance.
      void addEventListener​(IEventListener eventListener, EventType eventType)
      Add an IEventListener that will be notified of every event, of the specified EventType, that is received by this EventServiceChannel instance.
      void asyncRequestResponse​(IResponseListener responseListener, Event requestEvent, EventType responseEventType)
      Emulate an asynchronous RPC call to the Correlator by sending an event, and then invoking a callback when a matching response event is received (non-blocking call).
      void asyncRequestResponse​(IResponseListener responseListener, Event requestEvent, EventType responseEventType, long timeout)
      Emulate an asynchronous RPC call to the Correlator by sending an event, and then invoking a callback when a matching response event is received (non-blocking call, with timeout).
      void clearProcessingQueue()
      Immediately remove (discard) all events from the internal processing queue.
      java.util.Map<java.lang.String,​java.lang.Object> getConfig()
      Get the channel configuration that define the requested operating semantics of this instance.
      java.lang.String getName()
      Get the name of the channel(s) that this instance is consuming events from.
      boolean isDestroyed()
      Determine if this EventServiceChannel channel (not the Correlator) is destroyed, which is true if it has been removed from the parent EventService using IEventService.removeChannel(String[]).
      void registerEventType​(EventType eventType)
      Register an arbitrary EventType with this EventServiceChannel.
      void removeEventListener​(IEventListener eventListener)
      Remove a previously registered IEventListener that was listening to all events received.
      void removeEventListener​(IEventListener eventListener, EventType eventType)
      Remove a previously registered IEventListener that was listening to all events received of the specified EventType.
      IResponseWrapper requestResponse​(Event requestEvent, EventType responseEventType)
      Emulate a synchronous RPC call to the Correlator by sending an event and awaiting a matching response event (blocking call).
      IResponseWrapper requestResponse​(Event requestEvent, EventType responseEventType, long timeout)
      Emulate a synchronous RPC call to the Correlator by sending an event and awaiting a matching response event (blocking call with timeout).
      void setLateResponseListener​(IEventListener eventListener)
      Register the single IEventListener that will be notified of any "late" responses to either synchronous or asynchronous request-response calls.
      void unregisterEventType​(EventType eventType)
      Unregister an arbitrary EventType from this EventServiceChannel.

    • Field Detail

      • DEFAULT_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES

        static final java.util.Set<java.lang.String> DEFAULT_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES
        Default value for the set of event name prefixes that would cause a received event to be placed in the inbound event queue as a SoftReference (null).

      • DEFAULT_ENFORCE_RESPONSE_SEQUENCING

        static final boolean DEFAULT_ENFORCE_RESPONSE_SEQUENCING
        Default value for the flag specifying if strict response sequencing should be used (true).
        See Also:
        Constant Field Values

      • DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS

        static final long DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS
        Default value for the request-reponse timeout (3000ms).
        See Also:
        Constant Field Values

      • DEFAULT_MESSAGEID_FIELD_NAME

        static final java.lang.String DEFAULT_MESSAGEID_FIELD_NAME
        Default value for the field name of message ID's for request-response ("messageId").
        See Also:
        Constant Field Values

      • CONFIG_ENFORCE_RESPONSE_SEQUENCING

        static final java.lang.String CONFIG_ENFORCE_RESPONSE_SEQUENCING
        Configuration property name for specifying if a new EventServiceChannel should use strict response sequencing for synchronous request-response invocations.
        See Also:
        DEFAULT_ENFORCE_RESPONSE_SEQUENCING, Constant Field Values

      • PROP_DEFAULT_REQUEST_RESPONSE_TIMEOUT

        static final java.lang.String PROP_DEFAULT_REQUEST_RESPONSE_TIMEOUT
        System property (in millisecond) to set the default RequestResponseTimeout. If this property is defined, then its value will be used instead of the hard-coded DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS
        See Also:
        DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS, PROP_OVERRIDE_REQUEST_RESPONSE_TIMEOUT

      • CONFIG_MESSAGEID_FIELD_NAME

        static final java.lang.String CONFIG_MESSAGEID_FIELD_NAME
        Configuration property name for specifying the field name of message ID's (for request-response) that a new EventServiceChannel should use.
        See Also:
        DEFAULT_MESSAGEID_FIELD_NAME, Constant Field Values

    • Method Detail

      • getName

        java.lang.String getName()
        Get the name of the channel(s) that this instance is consuming events from.

        This is a read-only property.

        Returns:
        A single string containing the channel name, or a single string containin a comma separated list of channel names.

      • getConfig

        java.util.Map<java.lang.String,​java.lang.Object> getConfig()
        Get the channel configuration that define the requested operating semantics of this instance.

        This is a read-only property.

        Returns:
        an unmodifiable view of the channelConfig Map that was specified at construction.

      • clearProcessingQueue

        void clearProcessingQueue()
        Immediately remove (discard) all events from the internal processing queue.

      • requestResponse

        IResponseWrapper requestResponse​(Event requestEvent,
                                 EventType responseEventType)
                          throws ResponseTimeoutException,
                                 EngineException,
                                 EventServiceException
        Emulate a synchronous RPC call to the Correlator by sending an event and awaiting a matching response event (blocking call).

        Both the request event, and the response event must contain an integer field called messageId. This service will allocate a value to that field in the request event, and will await a response event of the specified type that contains a messageId field of the same value.

        The specified EventType will be automatically added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

        Note: this is a blocking call, with the default timeout for this channel. See also IEventService.addChannel(String[], Map), DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS, and ChannelConfig

        Parameters:
        requestEvent - the request Event to be sent to the Correlator.
        responseEventType - the expected EventType of the response Event from the Correlator.
        Returns:
        the response Event from the Correlator, inside the wrapper that is used for locking when response sequencing is enforced.
        Throws:
        ResponseTimeoutException - if the default timeout is exceeded without receiving the response.
        EngineException - if there was a problem sending the request.
        EventServiceException - if the event type of either the request of the response did not contain a messageId field.
        See Also:
        DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS

      • requestResponse

        IResponseWrapper requestResponse​(Event requestEvent,
                                 EventType responseEventType,
                                 long timeout)
                          throws ResponseTimeoutException,
                                 EngineException,
                                 EventServiceException
        Emulate a synchronous RPC call to the Correlator by sending an event and awaiting a matching response event (blocking call with timeout).

        Both the request event, and the response event must contain an integer field called messageId. This service will allocate a value to that field in the request event, and will await a response event of the specified type that contains a messageId field of the same value.

        The specified EventType will be automatically added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

        Note: this is a blocking call, but with a timeout.

        Parameters:
        requestEvent - the request Event to be sent to the Correlator.
        responseEventType - the expected EventType of the response Event from the Correlator.
        timeout - the maximum time (in milliseconds) to wait for a response.
        Returns:
        the response Event from the Correlator, inside the wrapper that is used for locking when response sequencing is enforced.
        Throws:
        ResponseTimeoutException - if the timeout is exceeded without receiving the response.
        EngineException - if there was a problem sending the request.
        EventServiceException - if the event type of either the request of the response did not contain a messageId field.

      • asyncRequestResponse

        void asyncRequestResponse​(IResponseListener responseListener,
                          Event requestEvent,
                          EventType responseEventType)
                   throws EngineException,
                          EventServiceException
        Emulate an asynchronous RPC call to the Correlator by sending an event, and then invoking a callback when a matching response event is received (non-blocking call).

        Both the request event, and the response event must contain an integer field called messageId. This service will allocate a value to that field in the request event, and will await a response event of the specified type that contains a messageId field of the same value.

        The responseListener will be notified of any exceptions thrown during the asynchronous call. The possible exceptions are:
        ResponseTimeoutException if the timeout is exceeded without receiving the response.
        EngineException if there was a problem sending the request.
        EventServiceException if the event type of either the request of the response did not contain a messageId field.

        The specified EventType will be automatically added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

        Note: this is a non-blocking call. The method will return as soon as the request is sent, and then at a later time when the response is received it will be passed to the supplied callback method. A ResponseTimeoutException would be given to the responseListener if the default timeout for this channel is exceeded. See also IEventService.addChannel(String[], Map), DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS, and ChannelConfig
        The request is sent on the client thread (whichever thread calls this method).
        The client callback handleResponse() method will be called on a background thread.
        The client callback handleException() method will be called on a background thread.

        Parameters:
        responseListener - the object implementing the callback interface.
        requestEvent - the request Event to be sent to the Correlator.
        responseEventType - the expected EventType of the response Event from the Correlator.
        Throws:
        EngineException - if there was a problem sending the request.
        EventServiceException - if the event type of either the request of the response did not contain a messageId field.
        See Also:
        DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS

      • asyncRequestResponse

        void asyncRequestResponse​(IResponseListener responseListener,
                          Event requestEvent,
                          EventType responseEventType,
                          long timeout)
                   throws EngineException,
                          EventServiceException
        Emulate an asynchronous RPC call to the Correlator by sending an event, and then invoking a callback when a matching response event is received (non-blocking call, with timeout).

        Both the request event, and the response event must contain an integer field called messageId. This service will allocate a value to that field in the request event, and will await a response event of the specified type that contains a messageId field of the same value.

        The responseListener will be notified of any exceptions thrown during the asynchronous call. The possible exceptions are:
        ResponseTimeoutException if the timeout is exceeded without receiving the response.
        EngineException if there was a problem sending the request.
        EventServiceException if the event type of either the request of the response did not contain a messageId field.

        The specified EventType will be automatically added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

        Note: this is a non-blocking call. The method will return as soon as the request is sent, and then at a later time when the response is received it will be passed to the supplied callback method. If a response is not received within the specified timeout period, the callback will be "unregistered".
        The request is sent on the client thread (whichever thread calls this method).
        The client callback handleResponse() method will be called on a background thread.
        The client callback handleException() method will be called on a background thread.

        Parameters:
        responseListener - the object implementing the callback interface.
        requestEvent - the request Event to be sent to the Correlator.
        responseEventType - the expected EventType of the response Event from the Correlator.
        timeout - the maximum time (in milliseconds) to wait for a response.
        Throws:
        EngineException - if there was a problem sending the request.
        EventServiceException - if the event type of either the request of the response did not contain a messageId field.

      • setLateResponseListener

        void setLateResponseListener​(IEventListener eventListener)
        Register the single IEventListener that will be notified of any "late" responses to either synchronous or asynchronous request-response calls.

        This callback will be invoked if a call had been made to one of the timeout versions of the request-response methods, but the response was received after the timeout period had elapsed.

        Parameters:
        eventListener - the object implementing the callback interface - only the single-event handleEvent(Event) method will be called.
        See Also:
        EventListenerAdapter

      • addEventListener

        void addEventListener​(IEventListener eventListener)
        Add an IEventListener that will be notified of every event (of a pre-registered type) that is received by this EventServiceChannel instance.

        Note The listener will only be notified about events that are of a type registered with the parser. Clients must first use registerEventType(EventType) to register the event types in which they are interested. All other event types will be ignored (parse errors will be logged).

        Parameters:
        eventListener - the object implementing the callback interface - only the single-event handleEvent(Event) method will be called.
        See Also:
        EventListenerAdapter

      • addEventListener

        void addEventListener​(IEventListener eventListener,
                      EventType eventType)
        Add an IEventListener that will be notified of every event, of the specified EventType, that is received by this EventServiceChannel instance.

        The specified EventType will be automatically added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

        Parameters:
        eventListener - the object implementing the callback interface - only the single-event handleEvent(Event) method will be called.
        eventType - the single EventType filter.
        See Also:
        EventListenerAdapter

      • removeEventListener

        void removeEventListener​(IEventListener eventListener)
        Remove a previously registered IEventListener that was listening to all events received.
        Parameters:
        eventListener - the object implementing the callback interface that is to be removed.

      • removeEventListener

        void removeEventListener​(IEventListener eventListener,
                         EventType eventType)
        Remove a previously registered IEventListener that was listening to all events received of the specified EventType.

        The specified EventType will NOT be removed from the types understood by the EventParser used by this EventServiceChannel.

        Parameters:
        eventListener - the object implementing the callback interface that is to be removed.
        eventType - the single EventType filter.

      • registerEventType

        void registerEventType​(EventType eventType)
        Register an arbitrary EventType with this EventServiceChannel.

        This method can be used in conjunction with a listener that is listening to all (unfiltered) events received.

        The specified EventType will be added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

        Parameters:
        eventType - a single EventType to be registered.

      • unregisterEventType

        void unregisterEventType​(EventType eventType)
        Unregister an arbitrary EventType from this EventServiceChannel.

        The specified EventType will be removed from the types understood by the EventParser used by this EventServiceChannel.

        Parameters:
        eventType - a single EventType to be unregistered.

      • isDestroyed

        boolean isDestroyed()
        Determine if this EventServiceChannel channel (not the Correlator) is destroyed, which is true if it has been removed from the parent EventService using IEventService.removeChannel(String[]).
        Returns:
        true if already destroyed, false otherwise.