alma.acs.logging

Class ClientLogManager

java.lang.Object

alma.acs.logging.ClientLogManager

All Implemented Interfaces:

LogConfigSubscriber

public class ClientLogManager
extends java.lang.Object
implements LogConfigSubscriber

This class provides methods for getting the loggers for components and containers. Both the loggers and the handlers are organized in a hierarchical namespace so that children may inherit some properties from their parents in the namespace.

To set the policy for remote logging, either initRemoteLogging(ORB, Manager, int, boolean) or suppressRemoteLogging() must be called. As long as none of these methods are called, it is assumed that remote logging will be initialized at some point later, and all log messages that are meant for remote logging will be stored in a queue. suppressRemoteLogging will throw away this queue, while initRemoteLogging will send all queued log records to the remote logger.

Since ACS 7.0, this class acts pretty much as a replacement for the JDK's LogManager and the AcsLogManager subclass.
If needed, we should investigate how to support the JMX logger management via LoggingMXBean which is useless now.

Author:

hsommer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ClientLogManager.LogAlarmHandler Because of build order problems (acsjlog before jcont), we cannot pass ContainerServices or some other alarm API to ClientLogManager.
static class	ClientLogManager.LoggerOwnerType

Field Summary

Fields

Modifier and Type	Field and Description
protected DispatchingLogQueue	logQueue The log queue can be null if remote logging has been suppressed.
protected LogConfig	sharedLogConfig The logging configurator shared by various classes of this package

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ClientLogManager()

Method Summary

Modifier and Type	Method and Description
protected StdOutConsoleHandler	addLocalHandler(AcsLogger logger) Adds a local logging handler to the provided logger.
void	configureLogging(LogConfig logConfig)
protected DispatchingLogQueue	createDispatchingLogQueue() Factory method broken out from prepareRemoteLogging() to support tests.
protected StdOutConsoleHandler	createStdOutConsoleHandlerWithFormatter(LogConfig logConfig, java.lang.String loggerName, alma.acs.logging.LogThrottle throttle) Factory method broken out to allow tests to easily use an instrumented variant.
protected void	disableRemoteLogging() Removes, closes, and nulls all remote handlers, so that no more records are put into the queue, and queue and remote handlers can be garbage collected.
void	enableLoggingAlarms(ClientLogManager.LogAlarmHandler logAlarmHandler) Enables alarms to be raised by the logging classes.
void	flushAll() Flushes the remote log queue completely and returns only when it's done.
static ClientLogManager	getAcsLogManager() Singleton accessor.
LogConfig	getLogConfig() Gets the LogConfig object that is shared between the ClientLogManager singleton and any other objects in the process (e.g.
AcsLogger	getLoggerByName(java.lang.String loggerName) Gets a logger object from any type.
AcsLogger	getLoggerForApplication(java.lang.String loggerName, boolean enableRemoteLogging) Gets a logger for an application (which is not an ACS component itself), e.g.
AcsLogger	getLoggerForComponent(java.lang.String componentName) Gets a logger object to be used by a component.
AcsLogger	getLoggerForContainer(java.lang.String containerName) Gets a logger to be used by the Java container classes.
AcsLogger	getLoggerForCorba(java.lang.String frameworkName, boolean autoConfigureContextName) Gets a logger to be used by ORB and POA classes, or by hibernate or another 3rd party framework whose logging we redirect.
protected AcsLogServiceOperations	getLogService(Manager manager, int managerHandle) This method is broken out from initRemoteLogging(ORB, Manager, int, boolean) to allow mock implementation by tests without a functional manager object.
protected AcsLogServiceOperations	getLogServiceFromNameSarvice(org.omg.CORBA.ORB orb) Get the log service from the name server.
boolean	initRemoteLogging(org.omg.CORBA.ORB orb, Manager manager, int managerHandle, boolean retry) Enables loggers to send log records to the central ACS logger service.
boolean	initRemoteLoggingForService(org.omg.CORBA.ORB orb, boolean retry) Initialize the remote logging for a ACS service.
protected void	prepareRemoteLogging() If not done already, sets up remote handlers for all loggers using a shared queue.
void	shutdown(boolean wait) Shuts down remote ACS logging and nulls the singleton instance.
void	suppressCorbaRemoteLogging() Allows to suppress remote logging of Corba/ORB logger(s).
void	suppressRemoteLogging() Suppresses remote logging.

Methods inherited from class java.lang.Object

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

Field Detail

sharedLogConfig

protected final LogConfig sharedLogConfig

The logging configurator shared by various classes of this package

logQueue

protected volatile DispatchingLogQueue logQueue

The log queue can be null if remote logging has been suppressed. Otherwise it is non-null even if remote logging is not active, because it stores the records to be sent off later.

Constructor Detail

ClientLogManager

protected ClientLogManager()

Method Detail

getAcsLogManager

public static ClientLogManager getAcsLogManager()

Singleton accessor.

TODO: rename, because now that we have class AcsLogManager, this method name is confusing.

Returns:

ClientLogManager

configureLogging

public void configureLogging(LogConfig logConfig)

Specified by:

configureLogging in interface LogConfigSubscriber

See Also:

alma.acs.logging.config.LogConfigSubscriber#configureLogging(alma.acs.logging.LogConfig)

getLogConfig

public LogConfig getLogConfig()

Gets the LogConfig object that is shared between the ClientLogManager singleton and any other objects in the process (e.g. Java container or manager classes, Loggers, Handlers).

prepareRemoteLogging

protected void prepareRemoteLogging()

If not done already, sets up remote handlers for all loggers using a shared queue.

createDispatchingLogQueue

protected DispatchingLogQueue createDispatchingLogQueue()

Factory method broken out from prepareRemoteLogging() to support tests.

disableRemoteLogging

protected void disableRemoteLogging()

Removes, closes, and nulls all remote handlers, so that no more records are put into the queue, and queue and remote handlers can be garbage collected.

GC of the queue can be an advantage when logs have been queued for remote sending, but then instead of connecting to the remote logger, we get a call to suppressRemoteLogging(). All messages have been logged locally anyway, so in this case we want to clean up all these LogRecords.

addLocalHandler

protected StdOutConsoleHandler addLocalHandler(AcsLogger logger)

Adds a local logging handler to the provided logger. Unlike with remote handlers in prepareRemoteLogging(), for local handlers we don't allow removing and re-adding the handlers later.

Note that this method does not require logger to be already registered in loggers, but if it is, then the new StdOutConsoleHandler is set in the map's AcsLoggerInfo as well.

Parameters:

logger - logger to be set up for local logging

Returns:

the local handler that was added to the logger.

createStdOutConsoleHandlerWithFormatter

protected StdOutConsoleHandler createStdOutConsoleHandlerWithFormatter(LogConfig logConfig,
                                                                       java.lang.String loggerName,
                                                                       alma.acs.logging.LogThrottle throttle)

Factory method broken out to allow tests to easily use an instrumented variant.

initRemoteLoggingForService

public boolean initRemoteLoggingForService(org.omg.CORBA.ORB orb,
                                           boolean retry)

Initialize the remote logging for a ACS service.

The implementation of this method is the same of initRemoteLogging(ORB, Manager, int, boolean) but the reference to the log service is read from the naming service instead of being asked to the Manager.

Note: this method must be called only by ACS services that starts before the manager. ACS services, in fact, do not log into the manager and therefore do not have a handle.
Other ACS tools like containers and component clients must use initRemoteLogging(ORB, Manager, int, boolean) to properly initialize the remote logging.

Parameters:

orb - The not null ORB

retry - if true, a failing connection to the log service will trigger up to 5 other attempts, every 10 seconds.

Returns:

true if remote logging was initialized successfully

See Also:

#initRemoteLogging(ORB, Manager, int, boolean), {@link #internalInitRemoteLogging(ORB, Manager, int, boolean)}

initRemoteLogging

public boolean initRemoteLogging(org.omg.CORBA.ORB orb,
                                 Manager manager,
                                 int managerHandle,
                                 boolean retry)

Enables loggers to send log records to the central ACS logger service. Tries to connect to the log service using the supplied ACS manager. As long as this connection fails, this method can sleep for 10 seconds and then try to connect again, if the parameter retry is true. Total retries are limited to 5, to detect a permanent problem before the log queue overflows.

Execution time can be significant, so consider calling this method in a separate thread (which has no negative effect on the logging since all log records are cached and automatically sent off once the log service is available). Use a daemon thread to avoid shutdown problems if this method still hangs in the login loop.

When the log service is obtained, the log queue used for remote logging will be flushed periodically to the log service unless an otherwise triggered flush has done this already. The default period is 10 seconds, but can be overridden in the CDB.

Parameters:

orb - the ORB used in this JVM

manager - the ACS manager

managerHandle - handle assigned by the ACS Manager for this client

retry - if true, a failing connection to the log service will trigger up to 5 other attempts, every 10 seconds.

Returns:

true if remote logging was initialized successfully

See Also:

shutdown(boolean)

getLogService

protected AcsLogServiceOperations getLogService(Manager manager,
                                                int managerHandle)
                                         throws ComponentNotAlreadyActivatedEx,
                                                CannotGetComponentEx,
                                                NoPermissionEx,
                                                ComponentConfigurationNotFoundEx

This method is broken out from initRemoteLogging(ORB, Manager, int, boolean) to allow mock implementation by tests without a functional manager object. Note that module acsjlog comes before jmanager.

Since ACS 8.0.1 we use an ACS-specific subtype of LogOperations to avoid the marshalling to Corba Any.

Throws:

ComponentNotAlreadyActivatedEx

CannotGetComponentEx

NoPermissionEx

ComponentConfigurationNotFoundEx

getLogServiceFromNameSarvice

protected AcsLogServiceOperations getLogServiceFromNameSarvice(org.omg.CORBA.ORB orb)
                                                        throws org.omg.CORBA.ORBPackage.InvalidName

Get the log service from the name server. It is used by ACS services that do not log into the manager and therefore can't use getLogService(Manager, int).

Parameters:

orb - The not null ORB

Returns:

The log service

Throws:

org.omg.CORBA.ORBPackage.InvalidName

suppressRemoteLogging

public void suppressRemoteLogging()

Suppresses remote logging. If log messages destined for remote logging have not been sent to the central log service yet (e.g. because initRemoteLogging has not been called, or because of sending failures), these log messages will be lost for remote logging. Log messages produced after this call will not even be queued for remote logging.

This method should only be called by special ALMA applications such as the Observation Preparation tool, which runs stand-alone, with all containers, managers, etc. in one JVM. In this case, no central logger is available, and all loggers which normally send their output to the central logger should be limited to local logging (stdout).

It is possible (probably not useful in real life) to re-enable remote logging later, by calling initRemoteLogging.

suppressCorbaRemoteLogging

public void suppressCorbaRemoteLogging()

Allows to suppress remote logging of Corba/ORB logger(s). Internally this suppression is handled using log level changes that cannot be undone by other log level changes. Generally remote logging remains enabled though, which makes this method quite different from suppressRemoteLogging().

Application code such as components must not call this method! It is a very specialized feature provided for the ArchiveLogger infrastructural component.

TODO: Currently we do not distinguish between ORB loggers and other framework loggers. This comes from the now wider use of getLoggerForCorba(String, boolean), which initially was meant only for ORB loggers as the name still suggests. It is not a problem at the moment though, because the archiveLogger component is the only known user, and it does not use any other frameworks whose logs we intercept.

getLoggerForCorba

public AcsLogger getLoggerForCorba(java.lang.String frameworkName,
                                   boolean autoConfigureContextName)

Gets a logger to be used by ORB and POA classes, or by hibernate or another 3rd party framework whose logging we redirect. The logger is connected to the central ACS logger.

Parameters:

frameworkName - e.g. jacorb or laser.

autoConfigureContextName - if true, the context (e.g. container name) will be appended to this logger's name as soon as it is available, changing the logger name to something like jacorb@frodoContainer.

getLoggerForContainer

public AcsLogger getLoggerForContainer(java.lang.String containerName)

Gets a logger to be used by the Java container classes. The logger is connected to the central ACS logger.

getLoggerForComponent

public AcsLogger getLoggerForComponent(java.lang.String componentName)

Gets a logger object to be used by a component.

This method is not supposed to be accessed directly in the component implementation. Instead, the implementation of alma.acs.container.ContainerServices should call this method.

Parameters:

componentName - component name (sufficiently qualified to be unique in the system or log domain)

Returns:

AcsLogger

getLoggerByName

public AcsLogger getLoggerByName(java.lang.String loggerName)

Gets a logger object from any type.

Parameters:

loggerName - name of the logger whose retrieval is wanted

Returns:

AcsLogger if logger is found, null otherwise

getLoggerForApplication

public AcsLogger getLoggerForApplication(java.lang.String loggerName,
                                         boolean enableRemoteLogging)

Gets a logger for an application (which is not an ACS component itself), e.g. a GUI application using the ACS ComponentClient.

Parameters:

loggerName - the logger name, should identify the application or the particular logger that gets requested.

enableRemoteLogging - if true (generally recommended), the returned logger is set up to send the logs to the remote log service, as it always happens for container and component loggers. This will only work if initRemoteLogging(ORB, Manager, int, boolean) is also called, which happens automatically in ComponentClient. For a standalone application that is not ACS-aware (no manager known etc), remote logging is not available even with enableRemoteLogging == true.

Returns:

a configured Logger

enableLoggingAlarms

public void enableLoggingAlarms(ClientLogManager.LogAlarmHandler logAlarmHandler)

Enables alarms to be raised by the logging classes. As of ACS 9.1, there is only one type of alarm, when the log throttle gets activated and logs are lost.

Parameters:

logAlarmHandler - A user-supplied callback that actually raises and clears alarms, so that the logging classes do not get a dependency on the alarm system API.

Since:

ACS 9.1

shutdown

public void shutdown(boolean wait)

Shuts down remote ACS logging and nulls the singleton instance. The loggers can still be used, but will only log locally.

Parameters:

wait -

flushAll

public void flushAll()

Flushes the remote log queue completely and returns only when it's done.