de.aristaflow.adept2.base.service

Class AbstractADEPT2Service

java.lang.Object

de.aristaflow.adept2.base.service.AbstractADEPT2Service

All Implemented Interfaces:

ADEPT2Service, LogService, ServiceThreadHandling

Direct Known Subclasses:

AbstractAuthenticatedService, AbstractConfigurableService, AbstractGUIManager, AbstractNonPrivilegedService, EmbeddedServletService, NullHTTPService, PVPUpdateManager, RegistryProviderConf, RegistryProviderDb

@ConfigurationDescription(properties=)
public class AbstractADEPT2Service
extends java.lang.Object
implements ADEPT2Service, LogService, ServiceThreadHandling

Abstract implementation for the ADEPT2 service interface.

The abstract implementation provides the basic logic for services which includes management of

• required services (startup- and runtime-required)
• provided registry, logger and URIs
• active sessions

This class does not provide support for configurations! Configurations should not be stored internally but rather parsed directly in the constructor of a service.

All active sessions of a service should be tracked by calling sessionActive(SessionToken) and sessionFinished(SessionToken) appropriately. This allows to notify the corresponding threads in case of an emergency shutdown. Additionally, a service must only be used when successfully started and not shut down. This is supported via isActive() and activeOrInvalidServiceStateException(SessionToken) directly. Subclasses do not call this explicitly since it is performed by sessionActive(SessionToken).

One exception for accessing a service when initialising or shutting down are privileged threads. These are not blocked in activeOrInvalidServiceStateException(SessionToken) and they are not interrupted when shutting down. A thread gets privileged by calling privilegeThread() in the startup or shutdown phase. When the start is signalled, all privileges are lost.

Author:

Ulrich Kreher, Kevin Goeser

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	AbstractADEPT2Service.ActiveSessions This class manages all sessions and threads currently active in this service.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CONF_CSV_LOGGING Configuration key for the CSV logging.
protected Configuration	configuration The configuration of this service.
protected java.util.logging.Logger	logger My classname-specific logger.
protected Registry	registry The registry to be used for accessing services by this service.
protected java.lang.String[]	runtimeRequiredServices The services which are required and requested lazily at runtime.
protected java.lang.String[]	startupRequiredServices The services which are required for starting the service.

Constructor Summary

Constructors

Constructor and Description
AbstractADEPT2Service(Configuration configuration, Registry registry, java.lang.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.
AbstractADEPT2Service(Configuration configuration, Registry registry, java.lang.String[] startupRequiredServices, java.lang.String[] runtimeRequiredServices, java.lang.Class<?> cls) Creates an ADEPT2 service with the designated registry, the designated required services and a logger for the designated class.

Method Summary

Modifier and Type	Method and Description
void	_sessionActive(SessionToken session, java.util.UUID templID, java.util.UUID baseTemplID, java.util.UUID embdTemplID, java.util.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).
void	_sessionFinished(SessionToken session, int addStackElems) Unregisters the designated session, removes the current thread and the log context (if CSV-logging is configured).
protected void	activeOrInvalidServiceStateException(SessionToken session) Checks whether this service is active and throws an InvalidStateException if isActive() returns false.
void	changeLogContext(EBPInstanceReference ebpIR) Convenience method for LogService.changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference).
void	changeLogContext(java.lang.String contextString) Convenience method for LogService.changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference).
void	changeLogContext(java.lang.String contextString, SessionToken session, java.util.UUID templID, java.util.UUID baseTemplID, java.util.UUID embdTemplID, java.util.UUID instID, EBPInstanceReference ebpIR) Changes the current log record parameter values for the designated session intermediately to the designated values.
protected void	consoleLog(java.lang.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.
boolean	csvLoggingEnabled() Whether the debug/CSV-logging is being used.
java.util.logging.Logger	getClassSpecificJulLogger(java.lang.Class<?> cls) Gets the logger of this service using and recognising class names.
protected Registry	getDependencyRegistry() Returns the privileged session factory assigned to this service.
java.net.URI[]	getLocalUris() Returns the URIs under which the service is locally exported.
java.util.logging.Logger	getLogger() Gets the logger specific to this service.
SerialisablePair<java.lang.String,java.lang.String>	getRelease() Gets the release of this service, that is, the build version and the build date.
java.lang.String[]	getRuntimeRequiredServices() This method should not be overridden, use the corresponding constructor instead.
SerialisableTriple<java.lang.String,java.lang.String,java.lang.String>	getServiceInstanceName() Gets the (optional) cluster name, the unique node name and the hierarchical instance name of this service.
java.lang.String[]	getStartupRequiredServices() This method should not be overridden, use the corresponding constructor instead.
java.net.URI[]	getURIs() Returns the URIs which are set for this service in ADEPT2Service.init(URI[], URI[]).
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.
void	init(java.net.URI[] localExportedUris, java.net.URI[] globalExportedUris) Initialise the service.
boolean	isActive() Returns whether this service is active or not.
protected boolean	isSessionActive(SessionToken session) Gets whether the designated session token is active, that is, it is registered for this service.
protected boolean	isShutdown() Gets whether this service has been shut down.
void	logMethodEntry(java.lang.String contextString, SessionToken session, java.lang.String msg) Registers the log context for the current thread (if CSV-logging is configured) and logs the designated message.
void	logMethodEntry(java.lang.String contextString, SessionToken session, java.lang.String msg, java.util.UUID templID, java.util.UUID baseTemplID, java.util.UUID embdTemplID, java.util.UUID instID, EBPInstanceReference ebpIR) Registers the log context for the current thread (if CSV-logging is configured) and logs the designated message.
void	logMethodEntry(java.lang.String contextString, SessionToken session, java.lang.String msg, java.util.UUID templID, java.util.UUID baseTemplID, java.util.UUID embdTemplID, java.util.UUID instID, EBPInstanceReference ebpIR, int removeElems) Registers the designated parameters as log context and logs a message for the entry of a method.
void	logMethodExit(java.lang.String msg) Logs the designated message and unregisters the log context for the current thread (if CSV-logging is configured).
void	logMethodExit(java.lang.String msg, int removeElems) Logs the designated message and unregisters the log context for the current thread (if CSV-logging is configured).
long	ping() Gets whether the service is running and accepts requests or not and since when.
void	preShutdown(boolean emergency) Empty convenience method.
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.
boolean	privilegeThread() Stores the current thread as privileged when the service has not been started or is currently shut down.
void	revertLogContextChanges() Reverts the current changes of the log context registered for the current thread.
void	sessionActive(SessionToken session) Registers the designated session as active, tracks the current thread and registers the log context (if CSV-logging is configured).
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.
void	sessionActive(SessionToken session, java.util.UUID templID, java.util.UUID embdTemplID, EBPInstanceReference ebpIR) Registers the designated session as active, tracks the current thread and registers the log context (if CSV-logging is configured).
void	sessionActive(SessionToken session, java.util.UUID templID, java.util.UUID baseTemplID, java.util.UUID embdTemplID, java.util.UUID instID) Registers the designated session as active, tracks the current thread and registers the log context (if CSV-logging is configured).
void	sessionFinished(SessionToken session) Unregisters the designated session, removes the current thread and the log context (if CSV-logging is configured).
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.
void	shutdown(boolean emergency) This implementation waits 10 seconds in case of an emergency and otherwise indefinitely for the termination of the active sessions.
void	signalShutdown(boolean emergency) 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.
void	signalStart() Signals the successful start by counting down the latch and removing privileged threads.
void	start() Method setting the status to the current time.
void	unprivilegeThread() 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONF_CSV_LOGGING

public static final java.lang.String CONF_CSV_LOGGING

Configuration key for the CSV logging.

See Also:

Constant Field Values

logger

protected final java.util.logging.Logger logger

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

startupRequiredServices

protected final java.lang.String[] startupRequiredServices

The services which are required for starting the service.

runtimeRequiredServices

protected final java.lang.String[] runtimeRequiredServices

The services which are required and requested lazily at runtime.

configuration

protected final 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(Configuration configuration,
                             Registry registry,
                             java.lang.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(Configuration configuration,
                             Registry registry,
                             java.lang.String[] startupRequiredServices,
                             java.lang.String[] runtimeRequiredServices,
                             java.lang.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,
                          java.util.UUID templID,
                          java.util.UUID baseTemplID,
                          java.util.UUID embdTemplID,
                          java.util.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,
                          java.util.UUID templID,
                          java.util.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,
                           java.util.UUID templID,
                           java.util.UUID baseTemplID,
                           java.util.UUID embdTemplID,
                           java.util.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.

getStartupRequiredServices

public java.lang.String[] getStartupRequiredServices()

This method should not be overridden, use the corresponding constructor instead.

Specified by:

getStartupRequiredServices in interface ADEPT2Service

Returns:

The services required for startup as provided to AbstractADEPT2Service(Configuration, Registry, String[], String[], Class).

getRuntimeRequiredServices

public java.lang.String[] getRuntimeRequiredServices()

This method should not be overridden, use the corresponding constructor instead.

Specified by:

getRuntimeRequiredServices in interface ADEPT2Service

Returns:

The services required at runtime as provided to AbstractADEPT2Service(Configuration, Registry, String[], String[], Class).

getLocalUris

public java.net.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.

getURIs

public java.net.URI[] getURIs()

Description copied from interface: ADEPT2Service

Returns the URIs which are set for this service in ADEPT2Service.init(URI[], URI[]). For a published service these are the global URIs, otherwise the method will return the local URIs.

Specified by:

getURIs in interface ADEPT2Service

Returns:

The URIs with which this service is globally published or the local URIs.

getLogger

public java.util.logging.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 java.util.logging.Logger getClassSpecificJulLogger(java.lang.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(java.net.URI[] localExportedUris,
                 java.net.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().

getRelease

public SerialisablePair<java.lang.String,java.lang.String> getRelease()

Description copied from interface: ADEPT2Service

Gets the release of this service, that is, the build version and the build date.

Specified by:

getRelease in interface ADEPT2Service

Returns:

The build version and the build date of this service.

getServiceInstanceName

public SerialisableTriple<java.lang.String,java.lang.String,java.lang.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(java.lang.String contextString,
                           SessionToken session,
                           java.lang.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(java.lang.String contextString,
                           SessionToken session,
                           java.lang.String msg,
                           java.util.UUID templID,
                           java.util.UUID baseTemplID,
                           java.util.UUID embdTemplID,
                           java.util.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(java.lang.String contextString,
                           SessionToken session,
                           java.lang.String msg,
                           java.util.UUID templID,
                           java.util.UUID baseTemplID,
                           java.util.UUID embdTemplID,
                           java.util.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(java.lang.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(java.lang.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(EBPInstanceReference ebpIR)

Description copied from interface: LogService

Convenience method for LogService.changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference). Changes just the EBPInstanceReference parameter value 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:

ebpIR - The EBPInstanceReference for the log record. This may be null.

changeLogContext

public void changeLogContext(java.lang.String contextString,
                             SessionToken session,
                             java.util.UUID templID,
                             java.util.UUID baseTemplID,
                             java.util.UUID embdTemplID,
                             java.util.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(java.lang.String msg)

Description copied from interface: LogService

Logs the designated message and unregisters the log context for the current thread (if CSV-logging is configured).
This method has to be called for every thread registered via LogService.logMethodEntry(String, SessionToken, String) or LogService.logMethodEntry(String, SessionToken, String, UUID, UUID, UUID, UUID, EBPInstanceReference). Please be sure not to omit this. Usually this has to be in a finally-block.

Specified by:

logMethodExit in interface LogService

Parameters:

msg - The message for logging the method exit.

logMethodExit

public void logMethodExit(java.lang.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.