Package de.aristaflow.adept2.base.service

Class AbstractADEPT2Service

    • Field Detail

      • logger

        protected final Logger logger
        My classname-specific logger. This supports efficient filters on the name of this class.

      • startupRequiredServices

        protected final String[] startupRequiredServices
        The services which are required for starting the service.

      • runtimeRequiredServices

        protected final String[] runtimeRequiredServices
        The services which are required and requested lazily at runtime.

      • configuration

        protected final org.apache.commons.configuration2.Configuration configuration
        The configuration of this service. This is provided as parameter to the constructor when creating a service.

      • registry

        protected final Registry registry
        The registry to be used for accessing services by this service. This is provided as parameter to the constructor when creating a service.

    • Constructor Detail

      • AbstractADEPT2Service

        public AbstractADEPT2Service​(org.apache.commons.configuration2.Configuration configuration,
                             Registry registry,
                             Class<?> cls)
        Creates an ADEPT2 service with the designated registry, a logger for the designated class and assuming that there are no other services required.
        Parameters:
        configuration - The configuration of this service providing whether to enable CSV logging.
        registry - The registry to be used for accessing services by this service. This is provided as parameter to the constructor when creating a service.
        cls - The class specifying the name of the logger of this service.

      • AbstractADEPT2Service

        public AbstractADEPT2Service​(org.apache.commons.configuration2.Configuration configuration,
                             Registry registry,
                             String[] startupRequiredServices,
                             String[] runtimeRequiredServices,
                             Class<?> cls)
        Creates an ADEPT2 service with the designated registry, the designated required services and a logger for the designated class.
        Parameters:
        configuration - The configuration of this service providing whether to enable CSV logging.
        registry - The registry to be used for accessing services by this service. This is provided as parameter to the constructor when creating a service.
        startupRequiredServices - The service type names of services required at startup time (in init(URI[], URI[]) and start()).
        runtimeRequiredServices - The service type names of services required at runtime (after startup time).
        cls - The class specifying the name of the logger of this service.

    • Method Detail

      • isActive

        public boolean isActive()
        Returns whether this service is active or not. In case this service has not been started yet, the calling thread awaits the end of starting. In case a privileged thread (the starting thread) calls this method, the state starting thread calls this method, it does not wait but returns whether the service has been started (signalStart()) and is not shut down yet (signalShutdown(boolean)).
        This method allows threads started in init(URI[], URI[]) or start() to wait until the service has been started before they actually work.
        Callers of this method should check for the interrupt status of the thread. If the start of the service fails, this method returns false and the thread is also interrupted. In this case the request will never be satisfied.
        Returns:
        Whether this service is active, that is started and not shut down.

      • isShutdown

        protected boolean isShutdown()
        Gets whether this service has been shut down. This allows privileged threads to distinguish between starting or shutting down if this service is not active.
        Returns:
        Whether the service is shut down.

      • activeOrInvalidServiceStateException

        protected void activeOrInvalidServiceStateException​(SessionToken session)
        Checks whether this service is active and throws an InvalidStateException if isActive() returns false. This does not apply to privileged threads, (top-level) sessions already running and privileged (top-level) session. These are ignored by this method. Ignoring sessions allows active sessions to terminate completely.
        Parameters:
        session - The session which will be ignored if its top-level session is currently active or if it is privileged.
        Throws:
        InvalidServiceStateException - If this service failed to start or is shut down, an InvalidStateException will be thrown.

      • privilegeSession

        protected void privilegeSession​(SessionToken activeSession,
                                SessionToken newSession)
        Privileges the designated session which will allow this session to become active even if this service is shutting down. This allows registered sessions to start a new session and ensure that this session also terminates even while shutting down. This is useful for the execution manager where the termination of a node is done in one session while the further proceeding is done in a separate session. However, both sessions have to complete to prevent inconsistent node states in the corresponding instance.
        The registering (current session) has to be active and the registered (new) session has to be a top-level session.

        This method synchronises on the activeSessions object. So be sure not to hold any locks or at least acquire the locks in a well-defined order.

        Hint: This method must not be called by another component than this component or a sub component/sub module of this component.

        Parameters:
        activeSession - The session token with which to privilege a new session that should be allowed to terminate despite this service shutting down. This session token has to be active and must not be null.
        newSession - The session token which should be allowed to terminate despite this service shutting down. This has to be a top-level session token and it must not be null.

      • sessionActive

        public void sessionActive​(SessionToken session)
        Registers the designated session as active, tracks the current thread and registers the log context (if CSV-logging is configured). The session will not be allowed to proceed if the service has not been started or shut down. The former blocks until the service has started successfully, the later throws an InvalidStateException.
        This method has to be called as soon as a request is received from the outside. It may be called several times, but every call has to be complemented by a call to sessionFinished(SessionToken).

        This method synchronises on the activeSessions object. So be sure not to hold any locks or at least acquire the locks in a well-defined order.

        Hint: This method must not be called by another component than this component or a sub component/sub module of this component.

        Parameters:
        session - The session token with which a method is called and therefore active. This must not be null.

      • sessionActive

        protected void sessionActive​(SessionToken session,
                             int addStackElems)
        Similar to sessionActive(SessionToken) but allows the caller to remove additional stack elements stemming from internal method forwarding and hiding the actual called method.
        Parameters:
        session - The session token with which a method is called and therefore active. This must not be null.
        addStackElems - The additional elements to be removed from the stack so that the real method name is logged instead of a sessionActive. This is usually 0. Unless you override this method or call some sessionActive methods internally before calling methods of this class.

      • sessionActive

        public void sessionActive​(SessionToken session,
                          UUID templID,
                          UUID baseTemplID,
                          UUID embdTemplID,
                          UUID instID)
        Registers the designated session as active, tracks the current thread and registers the log context (if CSV-logging is configured). This method behaves just like sessionActive(SessionToken) but with additional log parameters.
        Parameters:
        session - The session token with which a method is called and therefore active. This must not be null.
        templID - The template ID for the log record. This may be null.
        baseTemplID - The base template ID for the log record. This may be null.
        embdTemplID - The (internal) ID of the embedded template ID the for the log record. This may be null.
        instID - The instance ID for the log record. This may be null.

      • sessionActive

        public void sessionActive​(SessionToken session,
                          UUID templID,
                          UUID embdTemplID,
                          EBPInstanceReference ebpIR)
        Registers the designated session as active, tracks the current thread and registers the log context (if CSV-logging is configured). This method behaves just like sessionActive(SessionToken) but with additional log parameters.
        Parameters:
        session - The session token with which a method is called and therefore active. This must not be null.
        templID - The template ID for the log record. This may be null.
        embdTemplID - The (internal) ID of the embedded template ID the for the log record. This may be null.
        ebpIR - The EBPInstanceReference for the log record. This may be null.

      • _sessionActive

        public void _sessionActive​(SessionToken session,
                           UUID templID,
                           UUID baseTemplID,
                           UUID embdTemplID,
                           UUID instID,
                           EBPInstanceReference ebpIR,
                           int addStackElems)
        Registers the designated session as active, tracks the current thread and registers the log context (if CSV-logging is configured). The session will not be allowed to proceed if the service has not been started or shut down. The former blocks until the service has started successfully, the later throws an InvalidStateException.
        This method has to be called as soon as a request is received from the outside. It may be called several times, but every call has to be complemented by a call to sessionFinished(SessionToken).

        This method synchronises on the activeSessions object. So be sure not to hold any locks or at least acquire the locks in a well-defined order.

        This method should not be called directly. Call sessionActive(SessionToken), sessionActive(SessionToken, int), sessionActive(SessionToken, UUID, UUID, UUID, UUID) or sessionActive(SessionToken, UUID, UUID, EBPInstanceReference) instead.

        Parameters:
        session - The session token with which a method is called and therefore active. This must not be null.
        templID - The template ID for the log record. This may be null.
        baseTemplID - The base template ID for the log record. This may be null.
        embdTemplID - The (internal) ID of the embedded template ID the for the log record. This may be null.
        instID - The instance ID for the log record. This may be null.
        ebpIR - The EBPInstanceReference for the log record. This may be null.
        addStackElems - The additional elements to be removed from the stack so that the real method name is logged instead of a sessionActive. This is usually 0. Unless you override this method or call some sessionActive methods internally before calling methods of this class.

      • isSessionActive

        protected final boolean isSessionActive​(SessionToken session)
        Gets whether the designated session token is active, that is, it is registered for this service.
        Parameters:
        session - The session token which to check for whether it is active.
        Returns:
        Whether the designated session token is active, that is, it is registered for this service.

      • sessionFinished

        public void sessionFinished​(SessionToken session)
        Unregisters the designated session, removes the current thread and the log context (if CSV-logging is configured).
        This method has to be called for every session signalled by sessionActive(SessionToken). Please be sure not to omit this. Usually this has to be in a finally-block for everything after calling sessionActive(SessionToken).

        This method synchronises on the activeSessions object. So be sure not to hold any locks or at least acquire the locks in a well-defined order.

        Hint: This method must not be called by another component than this component or a sub component/sub module of this component.

        Parameters:
        session - The session token with which a method has been executed and which is not active any more in this service. This must not be null.

      • sessionFinished

        protected void sessionFinished​(SessionToken session,
                               int addStackElems)
        Similar to sessionFinished(SessionToken) but allows the caller to remove additional stack elements stemming from internal method forwarding and hiding the actual called method.
        Parameters:
        session - The session token with which a method has been executed and which is not active any more in this service. This must not be null.
        addStackElems - The additional elements to be removed from the stack so that the real method name is logged instead of a sessionFinished. This is usually 0. Unless you override this method or call some sessionFinished methods internally before calling methods of this class.

      • _sessionFinished

        public void _sessionFinished​(SessionToken session,
                             int addStackElems)
        Unregisters the designated session, removes the current thread and the log context (if CSV-logging is configured).
        This method has to be called for every session signalled by sessionActive(SessionToken). Please be sure not to omit this. Usually this has to be in a finally-block for everything after calling sessionActive(SessionToken).

        This method synchronises on the activeSessions object. So be sure not to hold any locks or at least acquire the locks in a well-defined order.

        This method should not be called directly. Call sessionFinished(SessionToken) or sessionFinished(SessionToken, int) instead.

        Parameters:
        session - The session token with which a method has been executed and which is not active any more in this service. This must not be null.
        addStackElems - The additional elements to be removed from the stack so that the real method name is logged instead of a sessionActive. This is usually 0. Unless you override this method or call some sessionActive methods internally before calling methods of this class.

      • getLocalUris

        public URI[] getLocalUris()
        Description copied from interface: ADEPT2Service
        Returns the URIs under which the service is locally exported. If this service is only locally available, there will be only one URI and this is a local one. The request for the corresponding component will fail if it is not a local service.
        Internal services may return an empty array.
        Specified by:
        getLocalUris in interface ADEPT2Service
        Returns:
        The URIs with which this service is exported locally - this may also be one local URI or an empty array for internal services, that should not be reached at all, for instance communication services.

      • getLogger

        public Logger getLogger()
        Description copied from interface: LogService
        Gets the logger specific to this service. This logger ignores class names and logs in the global service log.
        Specified by:
        getLogger in interface LogService
        Returns:
        The logger for the whole service.

      • getClassSpecificJulLogger

        public Logger getClassSpecificJulLogger​(Class<?> cls)
        Description copied from interface: LogService
        Gets the logger of this service using and recognising class names. That is the logger logs for the service and may have a log filter only logging the designated class.
        Specified by:
        getClassSpecificJulLogger in interface LogService
        Parameters:
        cls - The class for which to get a class-specific service logger.
        Returns:
        The logger of this service specific for the designated class.

      • getDependencyRegistry

        protected Registry getDependencyRegistry()
        Returns the privileged session factory assigned to this service.
        Returns:
        the privileged session factory assigned to this service

      • privilegeThread

        public final boolean privilegeThread()
        Description copied from interface: ServiceThreadHandling
        Stores the current thread as privileged when the service has not been started or is currently shut down. Otherwise this method just returns. If you privilege threads from a thread pool, consider unprivileging them again.

        The thread running the constructor and the thread signalling the shutdown is implicitly privileged.

        Specified by:
        privilegeThread in interface ServiceThreadHandling
        Returns:
        Whether the designated thread has really been privileged by this call. In this case the caller must unprivilege the thread. If the thread has already been privileged, false will be returned and the caller must not unprivilege the thread.

      • unprivilegeThread

        public final void unprivilegeThread()
        Description copied from interface: ServiceThreadHandling
        Revokes the privileges of the current thread that is, it may not access the service any more in case it is not started or currently shut down. If the current thread is not privileged, this method just returns.
        This is only useful for threads from a thread pool. Besides, all threads are implicitly unprivileged as soon as this service is started.
        Specified by:
        unprivilegeThread in interface ServiceThreadHandling

      • init

        public void init​(URI[] localExportedUris,
                 URI[] globalExportedUris)
          throws AbortServiceException
        Description copied from interface: ADEPT2Service
        Initialise the service. Startup-required services may already be used here.
        After returning form ADEPT2Service.init(URI[], URI[]), the service must be ready for ADEPT2Service.start().
        Specified by:
        init in interface ADEPT2Service
        Parameters:
        localExportedUris - The URIs with which this service is exported locally or a local URI or an empty array for internal services.
        globalExportedUris - The URIs with which this service is published globally or null in case the service is not published.
        Throws:
        AbortServiceException - If this service cannot be initialised due to a severe problem, an AbortServiceException will be thrown. ADEPT2Service.shutdown(boolean) will not be called when aborting; the service has to shut down itself/clean up before throwing the exception.

      • signalStart

        public final void signalStart()
        Description copied from interface: ServiceThreadHandling
        Signals the successful start by counting down the latch and removing privileged threads.
        This method is called implicitly by the registry. If the service is not started by the registry, this method will have to be called at the end of the start-method.
        Specified by:
        signalStart in interface ServiceThreadHandling

      • start

        public void start()
           throws AbortServiceException
        Method setting the status to the current time. Subclasses have to call this method!
        Specified by:
        start in interface ADEPT2Service
        Throws:
        AbortServiceException - If this service cannot be started due to a severe problem, an AbortServiceException will be thrown. ADEPT2Service.shutdown(boolean) will not be called when aborting; the service has to shut down itself/clean up before throwing the exception.

      • preShutdown

        public void preShutdown​(boolean emergency)
        Empty convenience method.
        Specified by:
        preShutdown in interface ADEPT2Service
        Parameters:
        emergency - Whether the shutdown will be an emergency shutdown. Normally a service should not do anything in pre-shutdown in case of an emergency.

      • signalShutdown

        public final void signalShutdown​(boolean emergency)
        Description copied from interface: ServiceThreadHandling
        Privileges the current thread, sets the shutdown flag and in case of emergency interrupts all active threads without the privileged ones since they are shutting down this service.
        This method is called implicitly by the registry. If the service is not started by the registry, this method will have to be called at the beginning of the shutdown or emergency-shutdown-method.
        Specified by:
        signalShutdown in interface ServiceThreadHandling
        Parameters:
        emergency - Flag whether this is an emergency shutdown and the active sessions should be interrupted.

      • shutdown

        public void shutdown​(boolean emergency)
        This implementation waits 10 seconds in case of an emergency and otherwise indefinitely for the termination of the active sessions. In case of an emergency shutdown may proceed even if there are active sessions.
        Specified by:
        shutdown in interface ADEPT2Service
        Parameters:
        emergency - Whether the shutdown will be an emergency shutdown.

      • ping

        public long ping()
        Gets whether the service is running and accepts requests or not and since when. This allows, for instance, to check remotely whether this service is available. Additionally, restarts of the service can be detected by comparing the returned start time with the previous one.

        The difference to isActive() is, that it returns at once if the service did not start, yet, whereas isActive() blocks till the service is running.

        Specified by:
        ping in interface ADEPT2Service
        Returns:
        The start time of the service, 0 for a service that has not been started, -1 for a service that has been shut down.
        If you need the old boolean logic use 0 < ping().

      • getServiceInstanceName

        public SerialisableTriple<String,​String,​String> getServiceInstanceName()
        Description copied from interface: ADEPT2Service
        Gets the (optional) cluster name, the unique node name and the hierarchical instance name of this service.
        Specified by:
        getServiceInstanceName in interface ADEPT2Service
        Returns:
        The (optional) cluster name, the unique node name and the hierarchical instance name of this service.

      • csvLoggingEnabled

        public boolean csvLoggingEnabled()
        Description copied from interface: LogService
        Whether the debug/CSV-logging is being used. This allows to create complex log messages only when really required, for instance printing the complete content of a worklist in a log message.
        Specified by:
        csvLoggingEnabled in interface LogService
        Returns:
        Whether the debug/CSV-logging is being used.

      • logMethodEntry

        public void logMethodEntry​(String contextString,
                           SessionToken session,
                           String msg)
        Description copied from interface: LogService
        Registers the log context for the current thread (if CSV-logging is configured) and logs the designated message. If no CSV-logging is configured, this method does nothing.
        This method is usually called when entering a method without active session tracking. The session token provides additional information for the CSV-log but may be omitted (null can be provided for the session token).

        Make sure to call LogService.logMethodExit(String) when exiting the method using the same thread again. Otherwise the log context remains registered and all following log messages will have the wrong log context.

        Hint: This method must not be called by another component than this component or a sub component/sub module of this component.

        Specified by:
        logMethodEntry in interface LogService
        Parameters:
        contextString - An arbitrary string identifying the new log context. This string is used additionally for every message logged with this log context, that is all log messages occurring until a new log context is set or the log context is dropped since the method is exited.
        session - The session token with which a method is called providing useful information for the CSV-log. This may be null.
        msg - The message for logging the method entry.

      • logMethodEntry

        public void logMethodEntry​(String contextString,
                           SessionToken session,
                           String msg,
                           UUID templID,
                           UUID baseTemplID,
                           UUID embdTemplID,
                           UUID instID,
                           EBPInstanceReference ebpIR)
        Description copied from interface: LogService
        Registers the log context for the current thread (if CSV-logging is configured) and logs the designated message. If no CSV-logging is configured, this method does nothing.
        This method is usually called when entering a method without active session tracking. It is the same as LogService.logMethodEntry(String, SessionToken, String) but allows for more log context information.

        Make sure to call LogService.logMethodExit(String) when exiting the method using the same thread again. Otherwise the log context remains registered and all following log messages will have the wrong log context.

        Hint: This method must not be called by another component than this component or a sub component/sub module of this component.

        Specified by:
        logMethodEntry in interface LogService
        Parameters:
        contextString - An arbitrary string identifying the new log context. This string is used additionally for every message logged with this log context, that is all log messages occurring until a new log context is set or the log context is dropped since the method is exited. This is useful for sorting and/or filtering the CSV-log.
        session - The session token with which a method is called providing useful information for the CSV-log. This may be null.
        msg - The message for logging the method entry.
        templID - The template ID for the log record. This may be null.
        baseTemplID - The base template ID for the log record. This may be null.
        embdTemplID - The (internal) ID of the embedded template ID the for the log record. This may be null.
        instID - The instance ID for the log record. This may be null.
        ebpIR - The EBPInstanceReference for the log record. This may be null.

      • logMethodEntry

        public void logMethodEntry​(String contextString,
                           SessionToken session,
                           String msg,
                           UUID templID,
                           UUID baseTemplID,
                           UUID embdTemplID,
                           UUID instID,
                           EBPInstanceReference ebpIR,
                           int removeElems)
        Registers the designated parameters as log context and logs a message for the entry of a method. The log context is added to every method that is logged between the method entry and the method exit.
        Parameters:
        contextString - An arbitrary additional string for the log record allowing to sort and/or filter the log. This may be null.
        session - The session including the agent information for the log record. This may be null.
        msg - The actual log message logged once for the method entry.
        templID - The template ID for the log record. This may be null.
        baseTemplID - The base template ID for the log record. This may be null.
        embdTemplID - The (internal) ID of the embedded template ID the for the log record. This may be null.
        instID - The instance ID for the log record. This may be null.
        ebpIR - The EBPInstanceReference for the log record. This may be null.
        removeElems - The amount of stack elements to be removed when logging the entry message (until the calling of this method).

      • changeLogContext

        public void changeLogContext​(String contextString)
        Description copied from interface: LogService
        Convenience method for LogService.changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference). Changes just the context string for the previous registered log context.
        Note that this context string will be used until reverting log context changes or removing the log context completely.
        Specified by:
        changeLogContext in interface LogService
        Parameters:
        contextString - An arbitrary string identifying the current log context. This string is used additionally for every message logged with this log context, that is all log messages occurring until a new log context is set or the log context is dropped since the method is exited. This is useful for sorting and/or filtering the CSV-log.

      • consoleLog

        protected void consoleLog​(String message)
        Prints a formatted service message to the console log and as info to the logger, use this for service startup and shutdown progress.
        Parameters:
        message - The message to be printed.

      • changeLogContext

        public void changeLogContext​(String contextString,
                             SessionToken session,
                             UUID templID,
                             UUID baseTemplID,
                             UUID embdTemplID,
                             UUID instID,
                             EBPInstanceReference ebpIR)
        Description copied from interface: LogService
        Changes the current log record parameter values for the designated session intermediately to the designated values. If one of the designated values is null, it will not be changed. The agents will be retrieved from the session token and the service name from the registry of this service.
        The changes will be done on a copy of the original log context. This allows for reversible changes, that is one can restore the original context without needing to know it by calling LogService.revertLogContextChanges(). The changed log context will also be removed (together with the original log context) when unregistering the log context via LogService.logMethodExit(String).

        Make sure that you have registered the log context before (LogService.logMethodEntry(String, SessionToken, String) or LogService.logMethodEntry(String, SessionToken, String, UUID, UUID, UUID, UUID, EBPInstanceReference)).

        Specified by:
        changeLogContext in interface LogService
        Parameters:
        contextString - An arbitrary additional string for the log record allowing to sort and/or filter the log. This may be null.
        session - The session including the agent information for the log record. This may be null.
        templID - The template ID for the log record. This may be null.
        baseTemplID - The base template ID for the log record. This may be null.
        embdTemplID - The (internal) ID of the embedded template ID the for the log record. This may be null.
        instID - The instance ID for the log record. This may be null.
        ebpIR - The EBPInstanceReference for the log record. This may be null.

      • revertLogContextChanges

        public void revertLogContextChanges()
        Description copied from interface: LogService
        Reverts the current changes of the log context registered for the current thread. This restores the original log context and removes the changed log context completely.
        Note that this method will be a no-op if there have not been any changes to the log context - instead of throwing an exception.
        Specified by:
        revertLogContextChanges in interface LogService

      • logMethodExit

        public void logMethodExit​(String msg,
                          int removeElems)
        Logs the designated message and unregisters the log context for the current thread (if CSV-logging is configured).
        The stack is adapted by the designated amount of elements to be removed (additionally to the stack elements after this method). This method is only for subclasses or wrapping classes. Normal usages call logMethodExit(String).
        Parameters:
        msg - The message for logging the method exit.
        removeElems - The amount of stack elements to be removed when logging the entry message (until the calling of this method).

      • getUserCredentials

        protected Pair<QualifiedAgent,​QualifiedAgent> getUserCredentials​(SessionToken session)
        Gets the agent of the top-level session token and the agent of the designated session token if a session factory is available.
        Parameters:
        session - The session token of which to retrieve the agent of the top-level session token and the own agent.
        Returns:
        The agent of the top-level session token and the agent of the designated session token or an empty pair (containing null-values). This must not return null.