Package com.apama.services.event

Interface IEventService

  • All Superinterfaces:
    java.lang.AutoCloseable
    public interface IEventService
extends java.lang.AutoCloseable
    IEventService is an interface that represents the public API to the EventService.

    IEventService 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. The EventService automatically takes care of connecting to the Correlator in the background, and reconnecting when disconnected.

    IEventService users who need to take action when the connectivity of the service changes should usually add a listener for the PROPERTY_CONNECTED IEventService property (rather than adding listeners to the lower engine client layer which can cause locking issues).

    Use EventType and its associated classes to parse and generate Event objects for receiving and sending using this class.

    See Also:
    IEventServiceChannel

    • Field Detail

      • PROPERTY_CONNECTED

        static final java.lang.String PROPERTY_CONNECTED
        Property name for events fired that signal a change in the connectivity of the event service.
        See Also:
        isConnected(), Constant Field Values

    • Method Detail

      • addPropertyChangeListener

        void addPropertyChangeListener​(java.lang.String propertyName,
                               java.beans.PropertyChangeListener listener)
        Add a change listener for the specified property.

        All property change callbacks on the IEventService object are guaranteed to be invoked asynchronously with no locks held (but each property's callbacks will still be fired in the order the property changes occurred). This means it is safe to call any engine client or event service method (except dispose) from a listener implementation. However it also means that by the time the listener fires the current value of the property might have changed since the change notification was fired.

        Parameters:
        propertyName - the name of the property to listen on.
        listener - the listener to be added.

      • removePropertyChangeListener

        void removePropertyChangeListener​(java.lang.String propertyName,
                                  java.beans.PropertyChangeListener listener)
        Remove the property change listener for the specified property.
        Parameters:
        propertyName - the name of the property to listen on.
        listener - the listener to be added.

      • getEngineClient

        EngineClientInterface getEngineClient()
        Get a handle on the underlying EngineClient.
        Returns:
        the EngineClientInterface implementation used by this service, or null if the EventService has been destroyed.

      • addChannel

        @Deprecated
IEventServiceChannel addChannel​(java.lang.String channelName,
                                java.util.Map<java.lang.String,​java.lang.Object> channelConfig)
        Deprecated.
        Use addChannel(String[], Map)
        Create an EventServiceChannel specifically for listening to a given channel or channels.

        The channelName parameter is normalized by tokenizing and the tokens added to a SortedSet. If an EventServiceChannel has already been created for the normalized channelName then the existing instance will be returned.

        Valid channel name delimiters are the comma, space, and tab characters.

        Note: Even if the channelConfig supplied are different to those of an existing EventServiceChannel for the normalized channelName, a new EventServiceChannel will not be created.

        Parameters:
        channelName - The name of the channel to receive events on (may be a comma separated list).
        channelConfig - Configuration properties of the EventServiceChannel. See also ChannelConfig.
        Returns:
        A new or pre-existing EventServiceChannel.

      • addChannel

        IEventServiceChannel addChannel​(java.lang.String[] channelNames,
                                java.util.Map<java.lang.String,​java.lang.Object> channelConfig)
        Create an EventServiceChannel specifically for listening to given channels. This is the recommended method going forward providing array of channels. The older method addChannel(String, Map) is deprecated.

        The channelNames parameter contains names of channels which is normalized by sorting it. If an EventServiceChannel has already been created for the normalized channelNames then the existing instance will be returned.

        Note: Even if the channelConfig supplied are different to those of an existing EventServiceChannel for the normalized channelNames, a new EventServiceChannel will not be created.

        Parameters:
        channelNames - The names of the channels to receive events on
        channelConfig - Configuration properties of the EventServiceChannel. See also ChannelConfig.
        Returns:
        A new or pre-existing EventServiceChannel.

      • getChannel

        @Deprecated
IEventServiceChannel getChannel​(java.lang.String channelName)
        Deprecated.
        Use getChannel(String[])
        Get an EventServiceChannel for a given channel or channels.

        The channelName parameter is normalized by tokenizing and the tokens added to a SortedSet. If an EventServiceChannel has already been created for the normalized channelName then that instance will be returned, otherwise null is returned.

        Valid channel name delimiters are the comma, space, and tab characters.

        Parameters:
        channelName - The name of the channel for a previously added EventServiceChannel (may be a comma separated list).
        Returns:
        the requested EventServiceChannel, or null is none is found.

      • getChannel

        IEventServiceChannel getChannel​(java.lang.String[] channelNames)
        Get an EventServiceChannel for given channels This is the recommended method going forward providing array of channels. The older method getChannel(String) is deprecated.

        The channelNames parameter contains names of channels which is normalized by sorting it. If an EventServiceChannel has already been created for the normalized channelNames, then that instance will be returned, otherwise null is returned.

        Parameters:
        channelNames - Names of channels for a previously added EventServiceChannel
        Returns:
        the requested EventServiceChannel, or null is none is found.

      • removeChannel

        @Deprecated
void removeChannel​(java.lang.String channelName)
        Deprecated.
        Use removeChannel(String[])
        Remove an EventServiceChannel for a given channel or channels.

        This will cause the EventServiceChannel to be destroyed and disconnected from the Correlator. Any client code that has a reference to the EventServiceChannel will not receive any more events.

        If no EventServiceChannel is found with the given channelName then a warning is logged, and the call is a no-op.

        Parameters:
        channelName - The name of the channel for a previously added EventServiceChannel (may be a comma separated list).

      • removeChannel

        void removeChannel​(java.lang.String[] channelNames)
        Remove an EventServiceChannel for given channels. This is the recommended method going forward providing array of channels. The older method removeChannel(String) is deprecated.

        This will cause the EventServiceChannel to be destroyed and disconnected from the Correlator. Any client code that has a reference to the EventServiceChannel will not receive any more events.

        If no EventServiceChannel is found with given channelNames then a warning is logged, and the call is a no-op.

        Parameters:
        channelNames - Names of channels for a previously added EventServiceChannel

      • isConnected

        boolean isConnected()
        Get the current connectivity of the event service. This value is true when everything is fine and events can be sent and received, but false if any part of the connection has a problem (for example, if the entire connection is lost, or if the remote engine has disconnected the service's consumers for being slow).
        Returns:
        true if the connection is fully working, false if there is a problem.
        See Also:
        PROPERTY_CONNECTED

      • close

        void close()
        Disconnects this service from the Correlator and stops background threads.

        This will cause all EventServiceChannels to be removed and disconnected from the correlator, and the underlying EngineClient will then also be disconnected.

        Java client applications should dispose any created event services once they are done with using them. To avoid deadlock, this method should never be invoked synchronously from an EventService listener.

        This is a one-time operation - the service cannot be restarted.

        This method is invoked automatically on objects managed by the try-with-resources statement.

        Specified by:
        close in interface java.lang.AutoCloseable
        See Also:
        AutoCloseable.close()

      • dispose

        @Deprecated
void dispose()
        Deprecated.
        Replaced by close() as of Apama version 9.10
        Disconnects this service from the Correlator and stops background threads.

        This will cause all EventServiceChannels to be removed and disconnected from the correlator, and the underlying EngineClient will then also be disconnected.

        Java client applications should dispose any created event services once they are done with using them. To avoid deadlock, this method should never be invoked synchronously from an EventService listener.

        This is a one-time operation - the service cannot be restarted.

      • destroy

        @Deprecated
void destroy()
        Deprecated.
        Replaced by close() as of Apama version 9.10
        Identical to the dispose() method, retained for backwards compatibility only.

      • isDestroyed

        boolean isDestroyed()
        Determine if this service (not the Correlator) is disposed.
        Returns:
        true if already disposed, false otherwise.

      • setDisconnectIfSlow

        @Deprecated
void setDisconnectIfSlow​(boolean disconnectIfSlow)
        Deprecated.
        see EventServiceFactory#createEventService(String, int, boolean) to disconnect any slow receiver
        Set the disconnect if slow property.

        This must be set before any EventService channels are created, or any other event receiver to the component this event service listens to, as only the first setting on a connection is used.

        If an EventService's consumers are disconnected for being slow, the EventService will notify the application using the PROPERTY_CONNECTED property and attempt to disconnect and reconnect the client automatically, subject to any minimum reconnection time set using EngineClientInterface.setReconnectPeriod(long).

      • getEventParser

        EventParser getEventParser()
        Get a handle on the underlying event Parser.
        Returns:
        EventParser implementation used by this service or null if the EventService has been destroyed.
        Since:
        10.1