Class DefaultEventManager

All Implemented Interfaces:
ADEPT2Service, ConfigurableService, LogService, ServiceThreadHandling, ActivityEventManager, EventManager, InstanceStartEventManager

@ConfigurationDescription(properties={@Property(name="ScheduledStarts.Instances",documentationOnly=true,description="The names of the scheduled process starts of the configuration of this event manager, whose keys ScheduledProcessStartSource describes. They run only while this event manager binds their handler by \'TimeScheduleEvent.ScheduledProcessStartSource.EventHandler\', which requires it to be exported and published."),},validator=ConfigurationValidator.class) public class DefaultEventManager extends AbstractEventManager
The default event manager supports arbitrary events (e. g. events based on SQL databases, (incoming) mails and changes in the file system), executes the scheduled process starts of its configuration and provides access to a Connection.

The scheduled process starts of the configuration of this event manager are registered as scheduled sources after its preregistered sources, provided that a handler for them is registered; otherwise they are inert. A batch write of the configuration changes the scheduled process starts of the runtime configuration: it checks the starts it changes, writes all values or none and then adds, replaces or removes their sources.

Under the same condition and with a poll time, this event manager also polls the process manager for the scheduled starts of template statuses, and each poll removes, replaces and adds their sources. A start whose source has been removed keeps its state until the state expires, so that the start continues when it returns, in a new version of its template as well.

  • Field Details

    • PLUGIN_TYPE_DB_RESULT_SET_EVENT

      public static final String PLUGIN_TYPE_DB_RESULT_SET_EVENT
      The plug-in type ID for result set events.
      See Also:
    • PLUGIN_TYPE_DB_MEMORY_RESULT_SET_EVENT

      public static final String PLUGIN_TYPE_DB_MEMORY_RESULT_SET_EVENT
      The plug-in type ID for memory result set events.
      See Also:
    • PLUGIN_TYPE_MAIL_EVENT

      public static final String PLUGIN_TYPE_MAIL_EVENT
      The plug-in type ID for mail events.
      See Also:
    • PLUGIN_TYPE_FILE_EVENT

      public static final String PLUGIN_TYPE_FILE_EVENT
      The plug-in type ID for file events.
      See Also:
    • PLUGIN_TYPE_TIME_SCHEDULE_EVENT

      public static final String PLUGIN_TYPE_TIME_SCHEDULE_EVENT
      The plug-in type ID for time-schedule events.
      See Also:
    • SOURCE_TYPE_SCHEDULED_PROCESS_START

      public static final String SOURCE_TYPE_SCHEDULED_PROCESS_START
      The source type of scheduled process starts, the instance name of their source plug-in.
      See Also:
    • CONF_SCHEDULED_STARTS_POLL_TIME

      public static final String CONF_SCHEDULED_STARTS_POLL_TIME
      Configuration key: The time in milliseconds after which to poll the process manager for the scheduled starts of template statuses again.
      See Also:
    • scheduledStartsPollTime

      protected final long scheduledStartsPollTime
      The time in milliseconds after which to poll the process manager for the scheduled starts of template statuses again, 0 or less if this event manager does not poll.
    • scheduledStartLock

      protected final Lock scheduledStartLock
      The lock serialising the changes of the scheduled process starts: their registration at start-up, a batch write from checking the starts to changing their sources, the removal of an ended source, and a poll of the scheduled starts of template statuses from changing their sources to the sweep of the state. It is taken before the lock of the data structures, never while holding that.
    • scheduledStarts

      protected final Map<String,ScheduledProcessStart> scheduledStarts
      The configured scheduled process starts whose sources are registered, indexed by their names. This is accessed under the lock of the scheduled process starts.
    • templateStarts

      protected final Map<String,ScheduledProcessStart> templateStarts
      The scheduled process starts of template statuses whose sources are registered or being registered, indexed by their names. They change under the lock of the scheduled process starts and may be read without it, as their sources read them.
    • templateStartPoll

      protected volatile Future<Void> templateStartPoll
      The future of the runs of the poll of the scheduled starts of template statuses, whose cancellation ends the poll, or null if this event manager does not poll. The runs read it on the threads of the poll executor.
  • Constructor Details

    • DefaultEventManager

      protected DefaultEventManager(Configuration conf, Registry registry, String[] startupRequiredServices, String[] runtimeRequiredServices) throws ConfigurationException
      Creates a new service polling for events of registered event types (e. g. DB, mail and file events) and handling them appropriately. This constructor is for subclasses allowing to extend the startup and runtime required services.
      Parameters:
      conf - The configuration of this event manager.
      registry - The registry for retrieving the services required by this service.
      startupRequiredServices - The services required by subclasses for starting and shutting down the event manager. This must neither be null nor contain null values.
      runtimeRequiredServices - The services required at runtime of the event manager. This must neither be null nor contain null values.
      Throws:
      ConfigurationException - If the password for this authenticated service cannot be parsed from the configuration, a ConfigurationException will be thrown.
    • DefaultEventManager

      @Deprecated(since="15.0.0", forRemoval=true) protected DefaultEventManager(Configuration conf, Registry registry, String[] startupRequiredServices, String[] runtimeRequiredServices, Map<String,Class<? extends Event>> supportedEvents) throws ConfigurationException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Creates a new service polling for DB, mail and file events and handling them appropriately. This constructor is for subclasses allowing to extend the startup and runtime required services as well as the supported event types.
      Parameters:
      conf - The configuration of this event manager.
      registry - The registry for retrieving the services required by this service.
      startupRequiredServices - The services required by subclasses for starting and shutting down the event manager. This must neither be null nor contain null values.
      runtimeRequiredServices - The services required at runtime of the event manager. This must neither be null nor contain null values.
      supportedEvents - The events supported by subclasses. This may be null. The keys of this map will be used to preregister event sources and handlers.
      Throws:
      ConfigurationException - If the password for this authenticated service cannot be parsed from the configuration, a ConfigurationException will be thrown.
    • DefaultEventManager

      public DefaultEventManager(Configuration conf, Registry registry) throws ConfigurationException
      Creates a new service polling for DB, mail and file events and handling them appropriately.
      Subclasses should use DefaultEventManager(Configuration, Registry, String[], String[]) instead from their registry-conform public constructor.
      Parameters:
      conf - The configuration of this event manager.
      registry - The registry for retrieving the services required by this service.
      Throws:
      ConfigurationException - If the password for this authenticated service cannot be parsed from the configuration, a ConfigurationException will be thrown.
  • Method Details

    • getConnection

      public ExtendedConnection getConnection(String dataSource, boolean readOnly) throws ServiceNotKnownException, SQLException
      Retrieves a connection to the designated data source.
      Parameters:
      dataSource - The simple instance name of the data source to which to retrieve a connection.
      readOnly - whether the returned connection will be used as read-only
      Returns:
      A connection to the designated data source.
      Throws:
      ServiceNotKnownException - If the designated data source cannot be retrieved from the registry, a ServiceNotKnownException will be thrown.
      SQLException - If creating the connection to the data source fails, an SQLException will be thrown.
    • getConnection

      public Connection getConnection(String driver, String connectionURL, String userName, String password) throws ConfigurationException, SQLException
      Retrieves a connection to a JDBC-database using the designated information.
      Parameters:
      driver - The fully-qualified name of the class of the JDBC-driver.
      connectionURL - The URL to connect to the database.
      userName - The name of the user to log on at the database with. Depending on the JDBC-driver, this may be null.
      password - The password to log on at the database with. Depending on the JDBC-driver, this may be null.
      Returns:
      A connection to a JDBC-database using the designated information.
      Throws:
      ConfigurationException - If the designated JDBC-driver is not found or cannot be instantiated, a ConfigurationException will be thrown.
      SQLException - If creating the connection to the JDBC-database fails, an SQLException will be thrown.
    • getConnection

      public Connection getConnection(String driver, String connectionURL, String userName, String password, boolean readOnly) throws ConfigurationException, SQLException
      Retrieves a connection to a JDBC-database using the designated information.
      Parameters:
      driver - The fully-qualified name of the class of the JDBC-driver.
      connectionURL - The URL to connect to the database.
      userName - The name of the user to log on at the database with. Depending on the JDBC-driver, this may be null.
      password - The password to log on at the database with. Depending on the JDBC-driver, this may be null.
      readOnly - whether the returned connection will be used as read-only
      Returns:
      A connection to a JDBC-database using the designated information.
      Throws:
      ConfigurationException - If the designated JDBC-driver is not found or cannot be instantiated, a ConfigurationException will be thrown.
      SQLException - If creating the connection to the JDBC-database fails, an SQLException will be thrown.
    • shutdown

      public void shutdown(boolean emergency)
      Awaits the termination of the active sessions and nulls the session factory.

      The poll of the scheduled starts of template statuses is cancelled first.

      Specified by:
      shutdown in interface ADEPT2Service
      Overrides:
      shutdown in class AbstractEventManager
      Parameters:
      emergency - Whether the shutdown will be an emergency shutdown.
    • addPreregistered

      protected void addPreregistered(Configuration conf) throws ServiceNotKnownException, ConfigurationException
      Reads the event handler and sources from the configuration based on the supported event types, registers and starts them initially and adds them afterwards.

      Afterwards the sources of the scheduled process starts of the configuration of this event manager are registered and, with a poll time, the poll of the scheduled starts of template statuses is scheduled.

      Overrides:
      addPreregistered in class AbstractEventManager
      Parameters:
      conf - The configuration from which to retrieve the event handler and event sources to be registered when initialising/starting this event manager.
      Throws:
      ServiceNotKnownException - If there are problems with the plugin configuration or no plugin configured at all for the pre-registered event handler or event sources, a ServiceNotKnownException will be thrown.
      ConfigurationException - If there are problems with the configuration of an event source, a ConfigurationException will be thrown.
    • getChangeableConfigurationKeys

      public List<String> getChangeableConfigurationKeys(SessionToken session)
      Gets a list of configuration keys that may be changed by the owner of the designated session token. Note that these may contain keys that are not yet in the configuration, and that the service may accept further keys for setting configuration values, for instance keys containing a name which the user chooses.

      These are the keys of the scheduled process starts in the runtime configuration and the list of their names there, for a session with the supervisor role.

      Specified by:
      getChangeableConfigurationKeys in interface ConfigurableService
      Overrides:
      getChangeableConfigurationKeys in class AbstractEventManager
      Parameters:
      session - The session which is used to check for access rights on this method and to determine which configuration keys can be changed by the designated user.
      Returns:
      A list of strings that represent the keys that may be changed by the user identified by the designated session token.
    • setConfigurationValues

      public void setConfigurationValues(SessionToken session, Map<String,String> values) throws ConfigurationException
      Sets the designated configuration values as one batch. The keys and values are as for ConfigurableService.setConfigurationValue(SessionToken, String, String), so the empty string as value deletes the configuration of its key.

      This default implementation sets the values one after the other through ConfigurableService.setConfigurationValue(SessionToken, String, String) in the iteration order of the designated map, so if setting a value fails, the values before it stay set and those after it are not set.

      Note to implementors: Check all values for validity and the session token for whether it is allowed to change the configuration before setting any value, and set either all values or none.

      The values are those of the scheduled process starts in the runtime configuration and the list of their names there. The starts which the values change are checked as they result from the values, all values are written in one transaction, and the sources of the changed starts are removed, replaced or added afterwards, unless no handler of scheduled process starts is registered.

      Specified by:
      setConfigurationValues in interface ConfigurableService
      Overrides:
      setConfigurationValues in class AbstractEventManager
      Parameters:
      session - The session which is used to check for access rights on this method.
      values - The string representations of the configuration values to be set, mapped by their keys.
      Throws:
      ConfigurationException - If there are problems setting the designated values, for instance, a value does not conform to its key or the values do not conform to each other, a ConfigurationException will be thrown.
    • registerScheduledStarts

      protected void registerScheduledStarts()
      Registers the sources of the scheduled process starts of the configuration of this event manager, provided that a handler of scheduled process starts is registered; otherwise the starts are inert and their state stays as it is. A start which fails its checks is logged and skipped, unless a check has failed only since the process manager cannot be reached; the start then meets the checks before each start. Afterwards the state of the starts which the configuration does not hold any more and the expired state of the starts of template statuses are removed.
    • isScheduledStartHandlerBound

      protected boolean isScheduledStartHandlerBound()
      Gets whether a handler of scheduled process starts is registered, which makes this event manager execute the scheduled process starts of its configuration and, with a poll time, those of template statuses.
      Returns:
      Whether a handler of scheduled process starts is registered.
    • checkScheduledStart

      protected void checkScheduledStart(SessionToken session, ScheduledProcessStart start) throws ConfigurationException
      Checks the designated scheduled process start against the process manager as where it enters the configuration: its process reference resolves to a template, the template accepts its input values and has a value for each mandatory input parameter, and the starter rule of the template admits the agent of this event manager. A template ID whose template is not released, instantiable, not outdated and top-level usable is accepted with a warning, since the start skips its due times only until the template is.
      Parameters:
      session - The session of this event manager.
      start - The scheduled process start to check.
      Throws:
      ConfigurationException - If the designated start fails a check, a ConfigurationException naming the start will be thrown.
    • checkStarterRule

      protected void checkStarterRule(SessionToken session, ScheduledProcessStart start, TemplateReference template) throws ConfigurationException
      Checks whether the starter rule of the designated template admits the agent of this event manager, as the start of an instance checks it: an agent whose session has the supervisor role passes, any other has to be a member of the starter rule.
      Parameters:
      session - The session of this event manager.
      start - The scheduled process start of the designated template.
      template - The template whose starter rule to check.
      Throws:
      ConfigurationException - If the starter rule does not admit the agent of this event manager or cannot be resolved, a ConfigurationException naming the start will be thrown.
    • getChangedScheduledStarts

      protected Collection<String> getChangedScheduledStarts(Map<String,String> values, Configuration result)
      Gets the names of the scheduled process starts which the designated values of a batch write change: those with a key among the values and those which the values add to or remove from the list of the names in the runtime configuration.
      Parameters:
      values - The values of a batch write, indexed by their keys.
      result - The configuration of this event manager as it results from the batch write.
      Returns:
      The names of the scheduled process starts which the designated values change.
    • getScheduledStarts

      protected Map<String,ScheduledProcessStart> getScheduledStarts(Configuration conf, Collection<String> names)
      Gets the scheduled process starts of the designated names which the designated configuration holds, each as far as it passes the checks of its own keys.
      Parameters:
      conf - The configuration of this event manager or a copy of it.
      names - The names of the starts to get.
      Returns:
      The scheduled process starts of the designated names which the designated configuration holds and which pass the checks of their own keys, indexed by their names.
    • checkScheduledStarts

      protected Map<String,ScheduledProcessStart> checkScheduledStarts(Configuration result, Collection<String> changed) throws ConfigurationException
      Checks the designated configuration resulting from a batch write: the scheduled process starts of the designated names which it holds as they enter the configuration, and every name of a runtime start against the static starts which do not allow overriding.
      Parameters:
      result - The configuration of this event manager as it results from the batch write.
      changed - The names of the scheduled process starts which the batch write changes.
      Returns:
      The changed scheduled process starts which the resulting configuration holds, indexed by their names.
      Throws:
      ConfigurationException - If a changed start or the name of a runtime start fails a check, a ConfigurationException naming the start will be thrown.
    • applyScheduledStarts

      protected void applyScheduledStarts(Collection<String> changed, Map<String,ScheduledProcessStart> before, Map<String,ScheduledProcessStart> after)
      Changes the sources of the scheduled process starts which a batch write has changed: the source of a start which the configuration does not hold any more is removed together with the state of the start, and the source of a start which differs from the registered one is replaced or added. A start which is added, enabled or given another schedule counts its due times from now, since its last time event is removed; any other change keeps the state.
      Parameters:
      changed - The names of the scheduled process starts which the batch write has changed.
      before - The scheduled process starts of the changed names as the configuration has held them before the batch write, indexed by their names.
      after - The scheduled process starts of the changed names as the configuration holds them after the batch write, indexed by their names.
    • addScheduledStart

      protected void addScheduledStart(ScheduledProcessStart start) throws ConfigurationException, ServiceNotKnownException
      Registers the source of the designated scheduled process start, which reads the start and its state from the configuration of this event manager. Once the runs of the source of an enabled start end, which they do only for a one-shot start, the source and the state are removed; the runs of a disabled start end at once, while its source stays registered.
      Parameters:
      start - The scheduled process start whose source to register.
      Throws:
      ConfigurationException - If the source refuses the start, a ConfigurationException will be thrown.
      ServiceNotKnownException - If the source cannot be created as a plugin of this event manager, a ServiceNotKnownException will be thrown.
    • removeScheduledStart

      protected void removeScheduledStart(String name)
      Removes the source of the scheduled process start of the designated name, which cancels its pending run, while a run in progress completes.
      Parameters:
      name - The name of the scheduled process start whose source to remove.
    • removeEndedScheduledStart

      protected void removeEndedScheduledStart(String name, EventSource<?> source)
      Removes the source of the scheduled process start of the designated name and the state of the start, since the runs of the designated source have ended, which they do only for a one-shot start once it has fired or missed its due time. The configuration keeps the start. Nothing is removed if the designated source has been removed or replaced meanwhile.
      Parameters:
      name - The name of the scheduled process start whose source has ended.
      source - The source whose runs have ended.
    • removeScheduledStartState

      protected void removeScheduledStartState(String name)
      Removes the state of the scheduled process start of the designated name. A failure is logged and left to a later sweep of the state.
      Parameters:
      name - The name of the scheduled process start whose state to remove.
    • scheduleTemplateStartPoll

      protected void scheduleTemplateStartPoll()
      Schedules the poll of the process manager for the scheduled starts of template statuses if this event manager has a poll time and a handler of scheduled process starts is registered, the condition under which it registers the scheduled process starts of its configuration.
    • getTemplateStart

      public ScheduledProcessStart getTemplateStart(String name)
      Gets the scheduled process start of a template status which this event manager registers under the designated name, so that its source gets it, since such a start has no form in the configuration.
      Parameters:
      name - The name of the start, TemplateStarts. followed by its ID. This must not be null.
      Returns:
      The start of a template status which is registered under the designated name or null if there is none.
    • pollTemplateStarts

      protected void pollTemplateStarts(Filter filter)
      Polls the process manager for the template statuses which the designated filter matches, changes the sources of their scheduled starts accordingly and then sweeps the state of the scheduled process starts. A poll which fails changes nothing, and neither does a poll while no handler of scheduled process starts is registered or after the poll has been cancelled.
      Parameters:
      filter - The filter matching the template statuses with a live scheduled start.
    • getLiveStarts

      protected Map<String,ScheduledProcessStart> getLiveStarts(Collection<TemplateStatus> statuses)
      Gets the enabled scheduled starts of the designated template statuses as scheduled process starts of their templates, indexed by their names. A start whose ID two of the statuses carry enabled is left out with a warning naming both templates, so that it does not run until only one of them carries it; since the process manager refuses to store such statuses, only a change bypassing it causes this.
      Parameters:
      statuses - The template statuses whose enabled scheduled starts to get.
      Returns:
      The enabled scheduled starts of the designated statuses which only one of them carries enabled, indexed by their names. This will never be null.
    • applyTemplateStarts

      protected void applyTemplateStarts(SessionToken session, Map<String,ScheduledProcessStart> polled)
      Changes the sources of the scheduled starts of template statuses to the designated polled starts, in this order: the source of a registered start which the poll has not found is removed, as removeVanishedTemplateStart(String, Instant) states, that of a start which differs from the registered one is replaced and a source is registered for every polled start without one, each continuing with the state of the start. A start whose source cannot be changed is logged and left to the next poll.
      Parameters:
      session - The session of this event manager.
      polled - The live scheduled starts which the poll has found, indexed by their names.
    • removeVanishedTemplateStart

      protected void removeVanishedTemplateStart(String name, Instant now)
      Removes the source of the start of a template status of the designated name, which the poll has not found any more. A start due once loses its state with it; any other start keeps its state, marked as removed at the designated time, so that the start continues with it when it returns before the state expires. A failure to change the state is logged and left to the sweep of the state.
      Parameters:
      name - The name of the start of a template status whose source to remove.
      now - The time of the removal.
    • replaceTemplateStart

      protected void replaceTemplateStart(SessionToken session, ScheduledProcessStart start, Instant now) throws ConfigurationException, ServiceNotKnownException
      Replaces the source of the designated start of a template status, which differs from the registered start of its name, keeping its state. If its schedule has changed, its last time event is removed, so that it counts its due times from the change.
      Parameters:
      session - The session of this event manager.
      start - The start of a template status whose source to replace.
      now - The time of the poll.
      Throws:
      ConfigurationException - If the source refuses the start, a ConfigurationException will be thrown.
      ServiceNotKnownException - If the source cannot be created as a plugin of this event manager, a ServiceNotKnownException will be thrown.
    • addTemplateStart

      protected void addTemplateStart(SessionToken session, ScheduledProcessStart start, Instant now) throws ConfigurationException, ServiceNotKnownException
      Registers the source of the designated start of a template status, which gets the start from this event manager by its name, and lets the start continue with its state: as it is without a removal time, as after a restart, and after a pause, which the removal time marks, with the time of the registration as its last time event and its last instance kept. Expired state and state of the wrong form are removed, so that the start begins anew.
      Parameters:
      session - The session of this event manager.
      start - The start of a template status whose source to register.
      now - The time of the poll.
      Throws:
      ConfigurationException - If the source refuses the start, a ConfigurationException will be thrown.
      ServiceNotKnownException - If the source cannot be created as a plugin of this event manager, a ServiceNotKnownException will be thrown.
      ConfigurationRuntimeException - If the state of the start cannot be changed, a ConfigurationRuntimeException will be thrown before the source is registered.
    • removeTemplateStart

      protected void removeTemplateStart(String name)
      Removes the source of the start of a template status of the designated name, which cancels its pending run, while a run in progress completes.
      Parameters:
      name - The name of the start of a template status whose source to remove.
    • sweepScheduledStartState

      protected void sweepScheduledStartState(SessionToken session, boolean polled)
      Sweeps the state of the scheduled process starts: it removes the state of the configured starts which the configuration does not hold and the expired state of the starts of template statuses without a source. After a poll, it also removes the state of a start of a template status without a source if the start is due once, and marks any other such state as removed now unless it is marked already, so that the state of a start which the poll has not found expires. State of the wrong form is removed, and a failure is logged and left to a later sweep.
      Parameters:
      session - The session of this event manager.
      polled - Whether the sweep follows a poll of the scheduled starts of template statuses.
    • isTemplateStateExpired

      protected boolean isTemplateStateExpired(SessionToken session, String name, Instant removed, Instant now) throws ConfigurationException
      Gets whether the state of the start of a template status of the designated name has expired, whose source has been removed at the designated time. It expires at once for a start due once, two periods after the end of the last instance for a start with a fixed delay and a last instance, never while this instance runs, the removal counting as the end if the process manager knows no instance of its ID, and two periods after the removal for any other start. The period and whether it is a fixed rate are those the state records, and the periods are added in UTC, since the state holds no zone. If the process manager cannot be asked about the last instance, the state has not expired.
      Parameters:
      session - The session of this event manager.
      name - The name of the start of a template status.
      removed - The time at which the source of the start has been removed.
      now - The time at which to check the state.
      Returns:
      Whether the state of the start of the designated name has expired.
      Throws:
      ConfigurationException - If the state holds a value of the wrong form, a ConfigurationException naming the start and the key will be thrown.
    • getInstanceEnd

      protected Instant getInstanceEnd(SessionToken session, String name, UUID instanceID, Instant vanished)
      Gets the end of the designated instance, which the start of a template status of the designated name has started last, from the process manager of the instance.
      Parameters:
      session - The session of this event manager.
      name - The name of the start of a template status.
      instanceID - The ID of the instance which the start has started last.
      vanished - The time which counts as the end if the process manager knows no instance of the designated ID.
      Returns:
      The end of the designated instance, the designated time if the process manager knows no instance of its ID, or null if the instance has not ended or the process manager cannot be asked.