Package de.aristaflow.adept2.core.eventmanager.common

Class AbstractSharedEventSource<E extends Event,​S extends SharingSource<E>>

  • Type Parameters:
    E - The type of the event.
    S - The type of the SharingSource.
    All Implemented Interfaces:
    EventSource<E>, PollingSource<E>, SharedPollingSource<E>, Runnable
    public abstract class AbstractSharedEventSource<E extends Event,​S extends SharingSource<E>>
extends Object
implements SharedPollingSource<E>
    An event source that distributes events among several sharing event sources. Each sharing event source is registered at a shared event source. For this to work, the sharing event sources need to have events similar to that of the shared event source. For instance, several sharing event sources waiting for specific data in a DBMS, may be using a common shared event source if they have the same SQL query that only differs in the filtering attributes (i. e. the values of the WHERE columns).
    Each sharing event source is identified by a set of keys (e. g. the values of the WHERE columns). If the shared event source detects an event, it forwards this event to the corresponding sharing event source.

    This way, sharing event sources do not need to poll separately but can share the same resources when checking for their respective event.

    • Field Detail

      • logger

        protected final Logger logger
        The logger for exceptions that occur when handling an event.

      • sourceType

        protected final String sourceType
        The type of this shared DB event source. This is used in the configuration of the event manager as well as for the sharing event sources to retrieve the shared event source.

      • initConf

        protected org.apache.commons.configuration2.Configuration initConf
        The configuration of this event source that is shared by all sharing sources. This will be configuration set via setConfiguration(Configuration, String).

      • sources

        protected final Map<List<Serializable>,​List<S extends SharingSource<E>>> sources
        All sharing sources registered at this shared source, indexed by their identifying values and in the order they have been added to this sharing event source.

      • eventManager

        protected final DefaultEventManager eventManager
        The event manager of this event source providing the connection to the event source.

    • Constructor Detail

      • AbstractSharedEventSource

        public AbstractSharedEventSource​(org.apache.commons.configuration2.Configuration conf,
                                 DefaultEventManager eventManager,
                                 Registry registry,
                                 Class<S> sharingSourceClass,
                                 String eventType,
                                 String sourceType)
        Default constructor for a plugin of the DefaultEventManager called by a service registry.
        Parameters:
        conf - The configuration as provided from the registry. Since this is a shared event source, the configuration will be ignored and only the explicitly set configuration will be used. This is usually a configuration of a/all sharing event sources.
        eventManager - The event manager this event source is a plugin of.
        registry - The registry of this plugin.
        sharingSourceClass - The class of S, used for type checks.
        eventType - The event type, cf. Event.getEventType().
        sourceType - The name of the source type.

    • Method Detail

      • getEventType

        protected String getEventType()
        Gets the type of the events, this shared event source generates.
        Returns:
        The type of the events, this shared event source generates.
        See Also:
        Event.getEventType()

      • getType

        public String getType()
        Description copied from interface: EventSource
        Gets the type of this source. This is usually the simple instance name of the plugin, if the event source has been loaded as plugin.
        Specified by:
        getType in interface EventSource<E extends Event>
        Returns:
        The type of this source.

      • getID

        public String getID()
        Description copied from interface: EventSource
        Gets the ID of this source. Until separately set this ID is arbitrary and may even be null.
        Specified by:
        getID in interface EventSource<E extends Event>
        Returns:
        The ID of this source.

      • getHierarchicalSourceName

        public String getHierarchicalSourceName()
        Description copied from interface: EventSource
        Gets the hierarchical name of this source, that is the event type, the source type and the source ID for usage in log messages and alike.
        Specified by:
        getHierarchicalSourceName in interface EventSource<E extends Event>
        Returns:
        The hierarchical name of this source, that is the event type, the source type and the source ID.

      • setConfiguration

        public void setConfiguration​(org.apache.commons.configuration2.Configuration conf,
                             String id)
                      throws ConfigurationException
        Description copied from interface: EventSource
        Sets the (additional) configuration of this event source and its ID. The configuration is additional with respect to the configuration provided by the plugin load mechanism, if the event source is loaded as plugin.
        It is ensured that this method will be called before Runnable.run().
        Specified by:
        setConfiguration in interface EventSource<E extends Event>
        Parameters:
        conf - The configuration of this event source. This adheres (and overwrites) the configuration provided by the plugin loading, if this event source has been loaded as plugin. Whether this is allowed to be null depends on the implementation of the event source.
        id - The ID of this event source. This must not be null nor the empty string.
        Throws:
        ConfigurationException - If there are problems with the designated configuration (configuration is null although this is not allowed, a required configuration value is missing, ...), a ConfigurationException will be thrown.

      • parseConfiguration

        protected void parseConfiguration​(org.apache.commons.configuration2.Configuration conf)
                           throws ConfigurationException
        Parses the designated (initial) configuration. Subclasses should parse the configuration values they need from it.
        The designated configuration will usually be the initial configuration right after setting it.

        This implementation does nothing as default.

        Parameters:
        conf - The configuration to parse the required configuration values from.
        Throws:
        ConfigurationException - If there are problems with the designated configuration, for instance the configuration does not provide required values, a ConfigurationException may be thrown.

      • getEventHandler

        public List<EventHandler> getEventHandler()
        Description copied from interface: EventSource
        Gets the event handler that have been registered for this event source. These handler are notified about an event in the designated order.
        Specified by:
        getEventHandler in interface EventSource<E extends Event>
        Returns:
        The event handler that have been registered for this event source.

      • addHandler

        public void addHandler​(EventHandler handler,
                       int index)
        Description copied from interface: EventSource
        Adds the designated handler at the designated position (0-based) to the list of registered handler. It is not checked, whether the handler is already registered.
        Specified by:
        addHandler in interface EventSource<E extends Event>
        Parameters:
        handler - The handler which to add.
        index - The index (0-based) at which to add the handler in the list.

      • addAll

        public void addAll​(List<EventHandler> handlers)
        Description copied from interface: EventSource
        Adds the designated event handler in the designated order to the list of the handler that are already registered. It is not checked whether a handler is already registered (and neither whether a handler is several times in the designated list.
        Specified by:
        addAll in interface EventSource<E extends Event>
        Parameters:
        handlers - The handler to register in the designated order. They are added at the end of the list of handler that are already registered.

      • removeHandler

        public EventHandler removeHandler​(String handlerID)
        Description copied from interface: EventSource
        Removes the handler with the designated ID from the list and returns it. If there is no handler registered with the designated ID, null will be returned.
        Specified by:
        removeHandler in interface EventSource<E extends Event>
        Parameters:
        handlerID - The ID of the handler which to remove.
        Returns:
        The removed handler or null in case no handler with the designated ID has been registered.

      • init

        public void init()
        Description copied from interface: PollingSource
        Initialises this polling source. This is called once before polling is started the first time.
        Specified by:
        init in interface PollingSource<E extends Event>

      • terminate

        public void terminate()
        Description copied from interface: PollingSource
        Terminates this polling source. This is called once after polling has terminated and this source is removed.
        Note that this may be called any time, even when creating or handling an event. So take care to synchronise the implementation appropriately!
        Specified by:
        terminate in interface PollingSource<E extends Event>

      • supportsSharingSource

        public boolean supportsSharingSource​(SharingSource<?> source)
        Gets whether this shared source can handle the designated sharing source and combine it with the already registered sharing sources. This usually analyses some of the configuration values of the designated sharing source. This implementation only checks for whether the designated source has the right class. Usually subclasses need to do more, e. g. check for compatibility of the configuration of the designated sharing source.
        Specified by:
        supportsSharingSource in interface SharedPollingSource<E extends Event>
        Parameters:
        source - The source that wants to share a source for polling.
        Returns:
        Whether this shared source can handle the designated sharing source and combine it with the already registered sharing sources.

      • addSharingSource

        public boolean addSharingSource​(SharingSource<?> source)
        Description copied from interface: SharedPollingSource
        Adds the designated sharing source at this shared source. This will add it to the existing sharing sources by combining the poll for the events.
        Implementations should usually also add the designated sharing source as event handler. Callers do not register the sharing source as event handler separately.
        Specified by:
        addSharingSource in interface SharedPollingSource<E extends Event>
        Parameters:
        source - The source that wants to share a source for polling.
        Returns:
        Whether the designated sharing sources has been successfully added. This is quite similar to the return value of SharedPollingSource.supportsSharingSource(SharingSource).

      • addedSharingSourceLocked

        protected boolean addedSharingSourceLocked​(List<Serializable> sourceKeys,
                                           S source)
        Signals subclasses that the designated sharing source has been added to this shared source. The write lock for adding is still held.
        Subclasses may refuse to add the designated sharing source by returning false. In this case the sharing source will be removed from this shared source.
        Note that supportsSharingSource(SharingSource) has already been called before calling this method.

        This implementation does nothing as default.

        Parameters:
        sourceKeys - The data (key values) of the designated source which also identify it.
        source - The sharing source which has been added and should be added to this shared source.
        Returns:
        Whether the designated sharing sources has been successfully added.
        See Also:
        addSharingSource(SharingSource)

      • removeSharingSource

        public boolean removeSharingSource​(SharingSource<?> source)
        Description copied from interface: SharedPollingSource
        Removes the designated sharing source from this shared source. This will remove it from the existing sharing sources. Afterwards no polling for the designated sharing source will occur.
        Implementations should usually also remove the designated sharing source as event handler. Callers do not unregister the sharing source as event handler separately.
        Specified by:
        removeSharingSource in interface SharedPollingSource<E extends Event>
        Parameters:
        source - The source that does no longer want to share a source for polling.
        Returns:
        Whether the last sharing source has been removed. In this case this shared polling source should also be removed from polling.

      • removingSharingSourceLocked

        protected void removingSharingSourceLocked​(List<Serializable> sourceKeys,
                                           SharingSource<?> source)
        Signals subclasses that the designated sharing source is about to be removed from this shared source. The write lock for removing is still held.

        This implementation does nothing as default.

        Parameters:
        sourceKeys - The data (key values) of the designated source which also identify it.
        source - The sharing source which is about to be removed from this shared source.
        See Also:
        removeSharingSource(SharingSource)

      • getSourceKeys

        protected abstract List<Serializable> getSourceKeys​(S source)
                                             throws InvalidDataTypeException,
                                                    NoSuchParameterException
        Gets the data (key values) that identifies the designated sharing event source.
        Usually the list should be unmodifiable.
        Parameters:
        source - The sharing event source for which to retrieve the key values identifying it.
        Returns:
        A list of key values identifying the designated sharing event source.
        Throws:
        InvalidDataTypeException - If a parameter reference identifying the designated sharing event source has not the same data type as in the data context, an InvalidDataTypeException will be thrown.
        NoSuchParameterException - If a parameter reference identifying the designated sharing event source is not in the data context, an InvalidDataTypeException will be thrown.