Package de.aristaflow.adept2.core.registry

Class InitialisedInjectedService

java.lang.Object

de.aristaflow.adept2.core.registry.InjectedADEPT2Service

de.aristaflow.adept2.core.registry.InitialisedInjectedService

All Implemented Interfaces:

ADEPT2Service, LogService, ServiceThreadHandling

Direct Known Subclasses:

AuthenticatedInjectedService

@ConfigurationDescription(properties=)
public class InitialisedInjectedService
extends InjectedADEPT2Service
implements LogService, ServiceThreadHandling

This class is similar to AbstractADEPT2Service. The main difference is that the injected service has constructors without a configuration and a registry. Both are provided when this service is initialised by the platform. This is also an additional step in the lifecycle of this service. Before this initialisation, most features will not work properly, e. g. session tracking since this requires a registry. Check with isInitialised() whether the injected service is usable. Methods that usually wait for this service to be started, will not block but throw an exception before the initialisation. This is similar to their behaviour after the service has been shut down.

Field Summary

Fields

Modifier and Type	Field	Description
protected AbstractADEPT2Service	adept2Service	The wrapped AbstractADEPT2Service after initialisation by the platform, null before.
protected Class<?>	loggerClass	The class which to use for the logger provided by AbstractADEPT2Service, this is usually the interface of the service.
static String	NOT_INITIALISED_EXCEPTION	The message for the InvalidServiceStateException for methods of AbstractADEPT2Service before the initialisation by the platform.

Fields inherited from class de.aristaflow.adept2.core.registry.InjectedADEPT2Service

EMPTY_STRING_ARRAY, logger, runtimeRequiredServices, startupRequiredServices

Constructor Summary

Constructors

Constructor	Description
InitialisedInjectedService(Logger logger)	Creates an injected service that can be initialised by the platform.
InitialisedInjectedService(Logger logger, String[] startupRequiredServices, String[] runtimeRequiredServices, Class<?> cls)	Creates an injected service that can be initialised by the platform.

Method Summary

Modifier and Type	Method	Description
protected void	_sessionActive(SessionToken session, UUID templId, UUID baseTemplId, UUID embdTemplId, UUID instId, EBPInstanceReference ebpIR, int addStackElems)
protected void	_sessionFinished(SessionToken session, int addStackElems)
void	changeLogContext(EBPInstanceReference ebpIr)	Convenience method for LogService.changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference).
void	changeLogContext(String contextString)	Convenience method for LogService.changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference).
void	changeLogContext(String contextString, SessionToken session, UUID templId, UUID baseTemplId, UUID embdTemplId, UUID instId, EBPInstanceReference ebpIr)	Changes the current log record parameter values for the designated session intermediately to the designated values.
boolean	csvLoggingEnabled()	Whether the debug/CSV-logging is being used.
Logger	getClassSpecificJulLogger(Class<?> cls)	Gets the logger of this service using and recognising class names.
Logger	getLogger()	If this service has not been initialised by the platform yet, the logger provided in the constructor will be returned.
SerialisablePair<String,String>	getRelease()	If this service has not been initialised by the platform yet, the release will be unknown.
void	init(URI[] localExportedUris, URI[] globalExportedUris)	Initialise the service.
void	initPlatform(org.apache.commons.configuration2.Configuration conf, Registry registry)	Initialises this service by the platform, that is, sets a configuration and a registry thus allowing access to the platform.
boolean	isActive()	Gets whether this service has been initialised by the platform and AbstractADEPT2Service.isActive().
protected boolean	isInitialised()	Gets whether this service has been initialised by the platform.
void	logMethodEntry(String contextString, SessionToken session, String msg)	Registers the log context for the current thread (if CSV-logging is configured) and logs the designated message.
void	logMethodEntry(String contextString, SessionToken session, String msg, UUID templId, UUID baseTemplId, UUID embdTemplId, UUID instId, EBPInstanceReference ebpIr)	Registers the log context for the current thread (if CSV-logging is configured) and logs the designated message.
protected void	logMethodEntry(String contextString, SessionToken session, String msg, UUID templId, UUID baseTemplId, UUID embdTemplId, UUID instId, EBPInstanceReference ebpIr, int removeElems)
void	logMethodExit(String msg)	Logs the designated message and unregisters the log context for the current thread (if CSV-logging is configured).
protected void	logMethodExit(String msg, int removeElems)
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)
protected void	sessionActive(SessionToken session, UUID templId, UUID embdTemplId, EBPInstanceReference ebpIr)
protected void	sessionActive(SessionToken session, UUID templId, UUID baseTemplId, UUID embdTemplId, UUID instId)
void	sessionFinished(SessionToken session)
void	shutdown(boolean emergency)	Signals this service that it is being shut down.
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()	Starts the service.
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 de.aristaflow.adept2.core.registry.InjectedADEPT2Service

getLocalUris, getRuntimeRequiredServices, getServiceInstanceName, getStartupRequiredServices, getURIs, ping, preShutdown

Methods inherited from class java.lang.Object

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

Field Detail

NOT_INITIALISED_EXCEPTION

public static final String NOT_INITIALISED_EXCEPTION

The message for the InvalidServiceStateException for methods of AbstractADEPT2Service before the initialisation by the platform.

See Also:

Constant Field Values

loggerClass

protected final Class<?> loggerClass

The class which to use for the logger provided by AbstractADEPT2Service, this is usually the interface of the service.

adept2Service

protected AbstractADEPT2Service adept2Service

The wrapped AbstractADEPT2Service after initialisation by the platform, null before.

Constructor Detail

InitialisedInjectedService

public InitialisedInjectedService(Logger logger)

Creates an injected service that can be initialised by the platform. It assumes that there are no other services required.

Parameters:

logger - The logger which to use for this service. This will only be used until initialisation by the platform. Afterwards the logger of the AbstractADEPT2Service will be used.

InitialisedInjectedService

public InitialisedInjectedService(Logger logger,
                                  String[] startupRequiredServices,
                                  String[] runtimeRequiredServices,
                                  Class<?> cls)

Creates an injected service that can be initialised by the platform. It uses the designated services from the platform.

Parameters:

logger - The logger which to use for this service. This will only be used until initialisation by the platform. Afterwards the logger of the AbstractADEPT2Service will be used.

startupRequiredServices - The service type names of services required at startup time (in init(URI[], URI[]) and start()). This may be null.

runtimeRequiredServices - The service type names of services required at runtime (after startup time). This may be null.

cls - The class which to use for the logger provided by AbstractADEPT2Service, this is usually the interface of the service.

Method Detail

initPlatform

public void initPlatform(org.apache.commons.configuration2.Configuration conf,
                         Registry registry)
                  throws AbortServiceException

Initialises this service by the platform, that is, sets a configuration and a registry thus allowing access to the platform.

Parameters:

conf - The configuration provided by the platform.

registry - The registry allowing to access the platform.

Throws:

AbortServiceException - If there are problems initialising this service, an AbortServiceException will be thrown.

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

Overrides:

init in class InjectedADEPT2Service

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:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

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.

See Also:

InjectedADEPT2Service.init(URI[], URI[]), AbstractADEPT2Service.init(URI[], URI[])

start

public void start()
           throws AbortServiceException

Description copied from interface: ADEPT2Service

Starts the service. This method is executed exactly once by the registry and it must return to start further services. For a stand-alone-service own threads or processes have to be started here.
This method is executed exactly once by the registry.

After returning from ADEPT2Service.start(), the service must be ready to receive any API call. This implicates for instance, that the thread calling this method may not leave the method before a server thread is actually ready to receive requests.

Specified by:

start in interface ADEPT2Service

Overrides:

start in class InjectedADEPT2Service

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

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.

See Also:

InjectedADEPT2Service.start(), AbstractADEPT2Service.start()

shutdown

public void shutdown(boolean emergency)

Description copied from interface: ADEPT2Service

Signals this service that it is being shut down. While this method is called, the service is no longer (remotely) available. It should terminate and close all activities and connections. Since the service is in an inconsistent state while shutting down, access should be restricted to the threads relevant for shutting down. All other requests should be blocked (see ServiceThreadHandling.
All startup required services are available in shutdown, runtime services may already be shut down.
In case of an emergency shutdown, even startup required services may not be available. Additionally, shutting down should be rather fast, so cleanup should concentrate on the really important things and use brief timeouts when waiting.

Specified by:

shutdown in interface ADEPT2Service

Overrides:

shutdown in class InjectedADEPT2Service

Parameters:

emergency - Whether the shutdown will be an emergency shutdown.

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

InjectedADEPT2Service.start(), AbstractADEPT2Service.start()

isInitialised

protected boolean isInitialised()

Gets whether this service has been initialised by the platform.

Returns:

Whether this service has been initialised by the platform.

isActive

public boolean isActive()

Gets whether this service has been initialised by the platform and AbstractADEPT2Service.isActive().

See Also:

AbstractADEPT2Service.isActive()

sessionActive

public void sessionActive(SessionToken session)

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.sessionActive(SessionToken)

sessionActive

protected void sessionActive(SessionToken session,
                             UUID templId,
                             UUID baseTemplId,
                             UUID embdTemplId,
                             UUID instId)

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.sessionActive(SessionToken, UUID, UUID, UUID, UUID)

sessionActive

protected void sessionActive(SessionToken session,
                             UUID templId,
                             UUID embdTemplId,
                             EBPInstanceReference ebpIr)

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.sessionActive(SessionToken, UUID, UUID, EBPInstanceReference)

_sessionActive

protected void _sessionActive(SessionToken session,
                              UUID templId,
                              UUID baseTemplId,
                              UUID embdTemplId,
                              UUID instId,
                              EBPInstanceReference ebpIR,
                              int addStackElems)

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service._sessionActive(SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference, int)

sessionFinished

public void sessionFinished(SessionToken session)

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.sessionFinished(SessionToken)

_sessionFinished

protected void _sessionFinished(SessionToken session,
                                int addStackElems)

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service._sessionFinished(SessionToken, int)

getLogger

public Logger getLogger()

If this service has not been initialised by the platform yet, the logger provided in the constructor will be returned. Otherwise the logger from the ADEPT2 service will be used.

Specified by:

getLogger in interface LogService

Overrides:

getLogger in class InjectedADEPT2Service

Returns:

The logger to be used by subclasses.

getRelease

public SerialisablePair<String,String> getRelease()

If this service has not been initialised by the platform yet, the release will be unknown. Otherwise the release from the ADEPT2 service will be used.

Specified by:

getRelease in interface ADEPT2Service

Overrides:

getRelease in class InjectedADEPT2Service

Returns:

The build version and the build date of this 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.

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.getClassSpecificJulLogger(Class)

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.

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.csvLoggingEnabled()

logMethodEntry

protected void logMethodEntry(String contextString,
                              SessionToken session,
                              String msg,
                              UUID templId,
                              UUID baseTemplId,
                              UUID embdTemplId,
                              UUID instId,
                              EBPInstanceReference ebpIr,
                              int removeElems)

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.logMethodEntry(String, SessionToken, String, UUID, UUID, UUID, UUID, EBPInstanceReference, int)

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.

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.logMethodEntry(String, SessionToken, String)

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.

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.logMethodEntry(String, SessionToken, String, UUID, UUID, UUID, UUID, EBPInstanceReference)

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.

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.changeLogContext(String)

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.

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.changeLogContext(EBPInstanceReference)

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.

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference)

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

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.revertLogContextChanges()

logMethodExit

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

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.logMethodExit(String)

logMethodExit

protected void logMethodExit(String msg,
                             int removeElems)

Throws:

InvalidServiceStateException - If this service has not been initialised by the platform yet, an InvalidServiceStateException will be thrown.

See Also:

AbstractADEPT2Service.logMethodExit(String, int)

privilegeThread

public 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 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

signalStart

public 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

signalShutdown

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