@ConfigurationDescription(properties=) public class AbstractADEPT2Service extends java.lang.Object implements ADEPT2Service, LogService, ServiceThreadHandling
The abstract implementation provides the basic logic for services which includes management of
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.
| Modifier and Type | Class and Description |
|---|---|
protected static class |
AbstractADEPT2Service.ActiveSessions
This class manages all sessions and threads currently active in this
service.
|
| 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 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.
|
| 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.
|
public static final java.lang.String CONF_CSV_LOGGING
protected final java.util.logging.Logger logger
protected final java.lang.String[] startupRequiredServices
protected final java.lang.String[] runtimeRequiredServices
protected final Configuration configuration
protected final Registry registry
public AbstractADEPT2Service(Configuration configuration, Registry registry, java.lang.Class<?> cls)
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.public AbstractADEPT2Service(Configuration configuration, Registry registry, java.lang.String[] startupRequiredServices, java.lang.String[] runtimeRequiredServices, java.lang.Class<?> cls)
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.public boolean isActive()
signalStart()) and is not shut down yet
(signalShutdown(boolean)). init(URI[], URI[]) or
start() to wait until the service has been started before they
actually work. protected boolean isShutdown()
protected void activeOrInvalidServiceStateException(SessionToken session)
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.session - The session which will be ignored if its top-level session
is currently active or if it is privileged.InvalidServiceStateException - If this service failed to start or is
shut down, an InvalidStateException will be thrown.protected void privilegeSession(SessionToken activeSession, SessionToken newSession)
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.
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.public void sessionActive(SessionToken session)
InvalidStateException. 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.
session - The session token with which a method is called and
therefore active. This must not be null.protected void sessionActive(SessionToken session, int addStackElems)
sessionActive(SessionToken) but allows the caller to
remove additional stack elements stemming from internal method forwarding
and hiding the actual called method.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.public void sessionActive(SessionToken session, java.util.UUID templID, java.util.UUID baseTemplID, java.util.UUID embdTemplID, java.util.UUID instID)
sessionActive(SessionToken) but with additional
log 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.public void sessionActive(SessionToken session, java.util.UUID templID, java.util.UUID embdTemplID, EBPInstanceReference ebpIR)
sessionActive(SessionToken) but with additional
log 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.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)
InvalidStateException. 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.
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.protected final boolean isSessionActive(SessionToken session)
session - The session token which to check for whether it is active.public void sessionFinished(SessionToken session)
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.
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.protected void sessionFinished(SessionToken session, int addStackElems)
sessionFinished(SessionToken) but allows the caller to
remove additional stack elements stemming from internal method forwarding
and hiding the actual called method.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.public void _sessionFinished(SessionToken session, int addStackElems)
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.
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.public java.lang.String[] getStartupRequiredServices()
getStartupRequiredServices in interface ADEPT2ServiceAbstractADEPT2Service(Configuration, Registry, String[], String[], Class).public java.lang.String[] getRuntimeRequiredServices()
getRuntimeRequiredServices in interface ADEPT2ServiceAbstractADEPT2Service(Configuration, Registry, String[], String[], Class).public java.net.URI[] getLocalUris()
ADEPT2ServicegetLocalUris in interface ADEPT2Servicepublic java.net.URI[] getURIs()
ADEPT2ServiceADEPT2Service.init(URI[], URI[]).
For a published service these are the global URIs, otherwise the method
will return the local URIs.getURIs in interface ADEPT2Servicepublic java.util.logging.Logger getLogger()
LogServicegetLogger in interface LogServicepublic java.util.logging.Logger getClassSpecificJulLogger(java.lang.Class<?> cls)
LogServicegetClassSpecificJulLogger in interface LogServicecls - The class for which to get a class-specific service logger.protected Registry getDependencyRegistry()
public final boolean privilegeThread()
ServiceThreadHandlingunprivileging them again.
The thread running the constructor and the thread signalling the shutdown is implicitly privileged.
privilegeThread in interface ServiceThreadHandlingfalse will be
returned and the caller must not unprivilege the thread.public final void unprivilegeThread()
ServiceThreadHandlingunprivilegeThread in interface ServiceThreadHandlingpublic void init(java.net.URI[] localExportedUris,
java.net.URI[] globalExportedUris)
throws AbortServiceException
ADEPT2ServiceADEPT2Service.init(URI[], URI[]), the service must be ready
for ADEPT2Service.start().init in interface ADEPT2ServicelocalExportedUris - 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.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.public final void signalStart()
ServiceThreadHandlingsignalStart in interface ServiceThreadHandlingpublic void start()
throws AbortServiceException
start in interface ADEPT2ServiceAbortServiceException - 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.public void preShutdown(boolean emergency)
preShutdown in interface ADEPT2Serviceemergency - Whether the shutdown will be an emergency shutdown. Normally a service should
not do anything in pre-shutdown in case of an emergency.public final void signalShutdown(boolean emergency)
ServiceThreadHandlingsignalShutdown in interface ServiceThreadHandlingemergency - Flag whether this is an emergency shutdown and the active
sessions should be interrupted.public void shutdown(boolean emergency)
shutdown in interface ADEPT2Serviceemergency - Whether the shutdown will be an emergency shutdown.public long ping()
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.
ping in interface ADEPT2Service0 for a service that has not been started,
-1 for a service that has been shut down. boolean logic use 0 < ping().public SerialisablePair<java.lang.String,java.lang.String> getRelease()
ADEPT2ServicegetRelease in interface ADEPT2Servicepublic SerialisableTriple<java.lang.String,java.lang.String,java.lang.String> getServiceInstanceName()
ADEPT2ServicegetServiceInstanceName in interface ADEPT2Servicepublic boolean csvLoggingEnabled()
LogServicecsvLoggingEnabled in interface LogServicepublic void logMethodEntry(java.lang.String contextString,
SessionToken session,
java.lang.String msg)
LogServicenull 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.
logMethodEntry in interface LogServicecontextString - 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.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)
LogServiceLogService.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.
logMethodEntry in interface LogServicecontextString - 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.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)
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).public void changeLogContext(java.lang.String contextString)
LogServiceLogService.changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference).
Changes just the context string for the previous registered log context. removing the log context completely.changeLogContext in interface LogServicecontextString - 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.protected void consoleLog(java.lang.String message)
message - The message to be printed.public void changeLogContext(EBPInstanceReference ebpIR)
LogServiceLogService.changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference).
Changes just the EBPInstanceReference parameter value for the
previous registered log context. changeLogContext in interface LogServiceebpIR - The EBPInstanceReference for the log record. This
may be null.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)
LogServicenull, it will not be changed. The agents will be retrieved
from the session token and the service name from the registry of this
service. 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)).
changeLogContext in interface LogServicecontextString - 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.public void revertLogContextChanges()
LogServicerevertLogContextChanges in interface LogServicepublic void logMethodExit(java.lang.String msg)
LogServicelogMethodExit in interface LogServicemsg - The message for logging the method exit.public void logMethodExit(java.lang.String msg,
int removeElems)
logMethodExit(String).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).protected Pair<QualifiedAgent,QualifiedAgent> getUserCredentials(SessionToken session)
session - The session token of which to retrieve the agent of the
top-level session token and the own agent.