alma.acs.logging

Class AcsLogger

java.lang.Object

java.util.logging.Logger

alma.acs.logging.AcsLogger

All Implemented Interfaces:

LogConfigSubscriber

public class AcsLogger
extends java.util.logging.Logger
implements LogConfigSubscriber

A Logger that attaches additional information to the produced LogRecords.

This class should be used only by ACS or by similar framework layers in the Operator GUI etc. Normal application code should get the Logger object from the ContainerServices.

Design note: the additional data (thread name, line of code) are really most interesting for the remotely sent log messages. Thus an alternative implementation could put the code from log(LogRecord) into class AcsLoggingHandler, and not use a custom Logger class at all. The main reason we do it anyway is to avoid throwing the dummy exception (that delivers the stack trace) twice.

Author:

hsommer created May 30, 2005 4:09:47 PM

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.logging.Logger	delegate Usually this is null, but factory method #wrapJdkLogger(Logger) could supply this delegate.
protected static int	offValue
AcsLoggerStatistics	stats

Fields inherited from class java.util.logging.Logger

global, GLOBAL_LOGGER_NAME

Constructor Summary

Constructors

Modifier	Constructor and Description
	AcsLogger(java.lang.String name, java.lang.String resourceBundleName, LogConfig logConfig) Standard constructor that configures this logger from logConfig and also registers for log config changes.
protected	AcsLogger(java.lang.String name, java.lang.String resourceBundleName, LogConfig logConfig, boolean allowNullLogConfig, java.util.logging.Logger delegate) Auxiliary ctor.

Method Summary

Modifier and Type	Method and Description
void	addIgnoreLogs(java.lang.String className, java.lang.String methodName) The AcsLogger can be configured to ignore certain logs.
void	addLoggerClass(java.lang.Class<?> loggerClass) Adds a logger class, which will be used to skip entries in the stack trace until the original logging method is found.
void	closeLogger() This method is called when the logger is to be closed and will activate any final action the logger need to perform before liberating resources.
void	configureLogging(LogConfig newLogConfig) Callback method, configures this logger from the data in logConfig.
AcsLogRecord	createAcsLogRecord(java.util.logging.Level level, java.lang.String msg)
static AcsLogger	createUnconfiguredLogger(java.lang.String name, java.lang.String resourceBundleName) Non-standard factory method to be used only for special offline or testing purposes where typically an AcsLogger must be provided by an alternative implementation of ContainerServices.
static AcsLogger	fromJdkLogger(java.util.logging.Logger logger, java.lang.String wrapLoggerName) Client applications that use ACS class ComponentClient may need to turn their own JDK Logger into an AcsLogger.
java.lang.String	getProcessName()
java.lang.String	getSourceObject()
void	log(java.util.logging.LogRecord record) Logs the given LogRecord.
void	logToAudience(java.util.logging.Level level, java.lang.String msg, java.lang.String audience) The audience strings allowed in alma are defined in IDL, but are available as type-safe enums in AudienceLogger, which thus should be preferred over this generic method.
void	logToAudience(java.util.logging.Level level, java.lang.String msg, java.lang.Throwable thr, java.lang.String audience) The audience strings allowed in alma are defined in IDL, but are available as type-safe enums in AudienceLogger, which thus should be preferred over this generic method.

Methods inherited from class java.util.logging.Logger

addHandler, config, config, entering, entering, entering, exiting, exiting, fine, fine, finer, finer, finest, finest, getAnonymousLogger, getAnonymousLogger, getFilter, getGlobal, getHandlers, getLevel, getLogger, getLogger, getName, getParent, getResourceBundle, getResourceBundleName, getUseParentHandlers, info, info, isLoggable, log, log, log, log, log, log, logp, logp, logp, logp, logp, logp, logrb, logrb, logrb, logrb, logrb, logrb, removeHandler, setFilter, setLevel, setParent, setResourceBundle, setUseParentHandlers, severe, severe, throwing, warning, warning

Methods inherited from class java.lang.Object

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

Field Detail

offValue

protected static final int offValue

stats

public AcsLoggerStatistics stats

delegate

protected final java.util.logging.Logger delegate

Usually this is null, but factory method #wrapJdkLogger(Logger) could supply this delegate.

Constructor Detail

AcsLogger

public AcsLogger(java.lang.String name,
                 java.lang.String resourceBundleName,
                 LogConfig logConfig)

Standard constructor that configures this logger from logConfig and also registers for log config changes.

Parameters:

name - the logger's name

resourceBundleName - may be null

logConfig - the ACS logging configuration object, which gives optional access to the CDB.

AcsLogger

protected AcsLogger(java.lang.String name,
                    java.lang.String resourceBundleName,
                    LogConfig logConfig,
                    boolean allowNullLogConfig,
                    java.util.logging.Logger delegate)

Auxiliary ctor. Don't use it directly from outside of this class.

Parameters:

logConfig - may be null if allowNullLogConfig==true

Method Detail

createUnconfiguredLogger

public static AcsLogger createUnconfiguredLogger(java.lang.String name,
                                                 java.lang.String resourceBundleName)

Non-standard factory method to be used only for special offline or testing purposes where typically an AcsLogger must be provided by an alternative implementation of ContainerServices. The returned AcsLogger is just like a JDK Logger obtained from Logger.getLogger(String, String).

Note that we do not supply a LogConfig and therefore the new AcsLogger cannot register itself for initial configuration or later configuration change notifications.
It is the client's responsibility to configure the log level and parent logger of the returned AcsLogger!

Parameters:

name - the logger's name

resourceBundleName -

Returns:

AcsLogger that is as close to a normal JDK Logger as possible.

Throws:

java.lang.IllegalArgumentException - If a Logger of the given name exists but is not an AcsLogger, or if an AcsLogger of the given name exists but has a different resourceBundleName.

fromJdkLogger

public static AcsLogger fromJdkLogger(java.util.logging.Logger logger,
                                      java.lang.String wrapLoggerName)

Client applications that use ACS class ComponentClient may need to turn their own JDK Logger into an AcsLogger.

If logger is itself of sub-type AcsLogger then it is returned directly without being wrapped. The wrapping logger shares the parent logger and the log level with the provided logger.

Parameters:

logger - the JDK logger

wrapperName - Name of the returned AcsLogger. May be null in which case the delegate's name plus "wrapper" is taken.

Returns:

an AcsLogger that delegates to the given logger.

Since:

ACS 8.0

getProcessName

public java.lang.String getProcessName()

getSourceObject

public java.lang.String getSourceObject()

logToAudience

public void logToAudience(java.util.logging.Level level,
                          java.lang.String msg,
                          java.lang.String audience)

The audience strings allowed in alma are defined in IDL, but are available as type-safe enums in AudienceLogger, which thus should be preferred over this generic method.

logToAudience

public void logToAudience(java.util.logging.Level level,
                          java.lang.String msg,
                          java.lang.Throwable thr,
                          java.lang.String audience)

The audience strings allowed in alma are defined in IDL, but are available as type-safe enums in AudienceLogger, which thus should be preferred over this generic method.

createAcsLogRecord

public AcsLogRecord createAcsLogRecord(java.util.logging.Level level,
                                       java.lang.String msg)

log

public void log(java.util.logging.LogRecord record)

Logs the given LogRecord. The record can be modified or dropped by the optional filters provided in #addLogRecordFilter(alma.acs.logging.AcsLogger.LogRecordFilter).

Adding of context information:

• If the LogRecord has a parameter that is a map which contains additional information about the line of code, thread, etc., the log record will be taken as provided, and no context information will be added. This can be useful if
  • the log record was reconstructed from a remote error by the ACS error handling code (see AcsJException), or
  • if in very exceptional cases application code needs to manipulate such information by hand.
• otherwise, context information is inferred, similar to LogRecord.inferCaller(), but additionally including thread name and line of code.

Note that by overloading this method, we intercept all logging activities of the base class.

Overrides:

log in class java.util.logging.Logger

See Also:

Logger.log(java.util.logging.LogRecord)

configureLogging

public void configureLogging(LogConfig newLogConfig)

Callback method, configures this logger from the data in logConfig.

Specified by:

configureLogging in interface LogConfigSubscriber

See Also:

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

addLoggerClass

public void addLoggerClass(java.lang.Class<?> loggerClass)

Adds a logger class, which will be used to skip entries in the stack trace until the original logging method is found. If you have a delegation chain that involves loggers besides AcsLogger and the normal JDK Logger, make sure you call this method for each of them.

Parameters:

loggerClass -

addIgnoreLogs

public void addIgnoreLogs(java.lang.String className,
                          java.lang.String methodName)

The AcsLogger can be configured to ignore certain logs. Note that this feature should not be used as a substitute for properly adjusting log levels and using repeat guards etc throughout the code. A valid use case would be to avoid "positive feedback" when the sending of a log produces one or more log messages, some of which may only be produced under special conditions, e.g. those coming from jacorb.

Parameters:

className - class name where the log comes from. Must not be null.

methodName - method name where the log comes from. Must not be null.

closeLogger

public void closeLogger()

This method is called when the logger is to be closed and will activate any final action the logger need to perform before liberating resources. That method is created because the finalize() method is not reliable for this task. The only task currently to be performed is to print out final statistics of the logger