de.aristaflow.adept2.base.service

Interface LogService

All Known Implementing Classes:

AbstractADEPT2Service, AbstractAuthenticatedService, AbstractConfigurableAuthenticatedService, AbstractConfigurableService, AbstractEventManager, AbstractGUIManager, AbstractNonPrivilegedService, AbstractRegistry, AuthenticatedInjectedService, BootstrapRegistry, ClusterNode, DefaultEventManager, DefaultProcessCheckService, EmbdServContHTTPService, EmbeddedServletService, InitialisedInjectedService, InstanceToInstanceRegistry, LocalServiceRegistry, ModelFactoryRegistry, MultiplexingClientService, NullGUIManager, NullHTTPService, PluginRegistry, PVPUpdateManager, RegistryProviderConf, RegistryProviderDb, RemoteHTMLGUIManager, ServiceRegistry, TwoPhaseBootstrap

public interface LogService

A LogService provides logging for an ADEPT2Service with enhanced capabilities. It differentiates between a service logger and class-specific logger. The service logger is the same for the whole service and its subservices. A class-specific logger is a wrapper that logs messages for specific classes or packages. The class-specific logger encapsulates the service logger. So one class being part of different services logs for each service separately. Additionally, the log messages for the class-specific logger will also reach the service logger. The class-specific logger may have a different log level than the service logger. To avoid performance issues, logging classes can rely on Logger.isLoggable(java.util.logging.Level) even if the service logger and the class-specific logger have different log levels.

By providing loggers via this LogService-interface, loggers may supply additional information to log services. For instance log messages can have a log context with various additional information beside the log message. This includes for instance the ID of the used session token, details on the executing user, the template ID, the instance ID and alike. This information is provided in separate columns in a CSV log and thus allows for sophisticated filtering and sorting.
Since this has a great performance impact, such log contexts will only be used if an appropriate logger has been configured and CSV-logging has been enabled for the corresponding ADEPT2Service. However, when not enabling CSV, calling methods of this service will have no impact at all so that the methods can be called even in a normal production environment and just be enabled if needed.

This log service registers a log context for the calling thread and provides a registered log context for all messages this threads logs afterwards. The log context needs to be registered which is usually done when entering a method. To prevent wrong log contexts, the log context needs to be unregistered which should be done in a finally-block when exiting a method. To allow for complex methods, a log context may be changed after it is registered. This can be used for instance for a method loading a hierarchy of process instances where the IDs obviously change while loading the hierarchy. Such changes to the log context can just be removed at once without knowing the changes. This allows to revert the context to the original.
As the log context will be ignored if CSV-logging is disabled, changing and reverting a log context will also be ignored. Therefore there is not much performance impact and calling services usually do not need to know whether CSV-logging is enabled. However, they should check this before creating large log messages like logging the complete content of a worklist. This effort should only be invested when really using CSV-logging.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
void	changeLogContext(EBPInstanceReference ebpIR) Convenience method for changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference).
void	changeLogContext(java.lang.String contextString) Convenience method for changeLogContext(String, SessionToken, UUID, UUID, UUID, UUID, EBPInstanceReference).
void	changeLogContext(java.lang.String arbString, 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.
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.
java.util.logging.Logger	getLogger() Gets the logger specific to this service.
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	logMethodExit(java.lang.String msg) Logs the designated message and unregisters the log context for the current thread (if CSV-logging is configured).
void	revertLogContextChanges() Reverts the current changes of the log context registered for the current thread.

Method Detail

getLogger

java.util.logging.Logger getLogger()

Gets the logger specific to this service. This logger ignores class names and logs in the global service log.

Returns:

The logger for the whole service.

getClassSpecificJulLogger

java.util.logging.Logger getClassSpecificJulLogger(java.lang.Class<?> cls)

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.

Parameters:

cls - The class for which to get a class-specific service logger.

Returns:

The logger of this service specific for the designated class.

csvLoggingEnabled

boolean csvLoggingEnabled()

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.

Returns:

Whether the debug/CSV-logging is being used.

logMethodEntry

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

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

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. 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 logMethodEntry(String, SessionToken, String) but allows for more log context information.

Make sure to call 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.

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.

changeLogContext

void changeLogContext(java.lang.String contextString)

Convenience method for 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.

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.

changeLogContext

void changeLogContext(EBPInstanceReference ebpIR)

Convenience method for 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.

Parameters:

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

changeLogContext

void changeLogContext(java.lang.String arbString,
                      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. 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 revertLogContextChanges(). The changed log context will also be removed (together with the original log context) when unregistering the log context via logMethodExit(String).

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

Parameters:

arbString - 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:

InternalServiceException - If the designated session (or no log context for the current thread) has not been registered yet, an InternalServiceException will be thrown.

revertLogContextChanges

void revertLogContextChanges()

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.

Throws:

InternalServiceException - If no log context for the current thread has been registered yet, an InternalServiceException will be thrown.

logMethodExit

void logMethodExit(java.lang.String msg)

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 logMethodEntry(String, SessionToken, String) or 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.

Parameters:

msg - The message for logging the method exit.