org.apache.avalon.excalibur.logger
Class LogKitLoggerManager

java.lang.Object
  org.apache.avalon.excalibur.logger.AbstractLoggerManager
      org.apache.avalon.excalibur.logger.LogKitLoggerManager

All Implemented Interfaces:

Configurable, Contextualizable, Disposable, LogEnabled, LoggerManager

public class LogKitLoggerManager

extends AbstractLoggerManager

implements LoggerManager, Contextualizable, Configurable, Disposable

LogKitLoggerManager implementation. It populates the LoggerManager from a configuration file.

Since:

4.0

Version:

SVN $Id$

Author:

Avalon Development Team

Field Summary

Fields inherited from class org.apache.avalon.excalibur.logger.AbstractLoggerManager

m_loggers, m_prefix

Fields inherited from interface org.apache.avalon.excalibur.logger.LoggerManager

ROLE

Constructor Summary

LogKitLoggerManager()
Creates a new LogKitLoggerManager; one of the preferred constructors.

LogKitLoggerManager(Hierarchy hierarchy)
Creates a new LogKitLoggerManager with an existing Hierarchy; use with caution.

LogKitLoggerManager(java.lang.String prefix)
Creates a new LogKitLoggerManager; one of the preferred constructors.

LogKitLoggerManager(java.lang.String prefix, Hierarchy hierarchy)
Creates a new LogKitLoggerManager with an existing Hierarchy; use with caution.

LogKitLoggerManager(java.lang.String prefix, Hierarchy hierarchy, Logger defaultOverrideAndFallback)
Creates a new LogKitLoggerManager with an existing Hierarchy using specified logger name as a fallback logger and to forcibly override the root logger; compatibility constructor.

LogKitLoggerManager(java.lang.String prefix, Hierarchy hierarchy, Logger defaultLoggerOverride, Logger fallbackLogger)
Creates a new LogKitLoggerManager with an existing Hierarchy using specified loggers to forcibly override the default logger and to provide a fallback logger; compatibility constructor.

LogKitLoggerManager(java.lang.String prefix, Hierarchy hierarchy, java.lang.String switchToCategory)
Creates a new LogKitLoggerManager with an existing Hierarchy; use with caution.

LogKitLoggerManager(java.lang.String prefix, Hierarchy hierarchy, java.lang.String switchToCategory, Logger defaultLoggerOverride, Logger fallbackLogger)
Creates a new LogKitLoggerManager; "root" constructor invoked by all other constructors.

LogKitLoggerManager(java.lang.String prefix, java.lang.String switchToCategory)
Creates a new LogKitLoggerManager; one of the preferred constructors, intended for the widest usage.

Method Summary

void	configure(Configuration configuration) Reads a configuration object and creates the category mapping.
void	contextualize(Context context) Reads a context object that will be supplied to the log target factory manager.
void	dispose() Closes all our LogTargets.
protected Logger	doGetLoggerForCategory(java.lang.String fullCategoryName) Actually create a logger for the given category.

Methods inherited from class org.apache.avalon.excalibur.logger.AbstractLoggerManager

enableLogging, getDefaultLogger, getLogger, getLoggerForCategory, start, stop

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.avalon.excalibur.logger.LoggerManager

getDefaultLogger, getLoggerForCategory

Constructor Detail

LogKitLoggerManager

public LogKitLoggerManager()

Creates a new LogKitLoggerManager; one of the preferred constructors. Please also invoke enableLogging() to supply a fallback logger.

LogKitLoggerManager

public LogKitLoggerManager(java.lang.String prefix)

Creates a new LogKitLoggerManager; one of the preferred constructors. Please also invoke enableLogging() to supply a fallback logger.

Parameters:

prefix - to prepended to category name on each invocation of getLoggerForCategory().

LogKitLoggerManager

public LogKitLoggerManager(java.lang.String prefix,
                           java.lang.String switchToCategory)

Creates a new LogKitLoggerManager; one of the preferred constructors, intended for the widest usage. Please also invoke enableLogging() to supply a fallback logger.

Example:

 LogKitLoggerManager l = new LogKitLoggerManager( "fortress", "system.logkit" );
 l.enableLogging( bootstrapLogger );
 l.configure( loggerManagerConfiguration );
 

Parameters:

prefix - to prepended to category name on each invocation of getLoggerForCategory().

switchToCategory - if this parameter is not null after start() LogKitLoggerManager will start to log its own debug and error messages to a logger obtained via this.getLoggerForCategory( switchToCategory ). Note that prefix will be prepended to the value of switchToCategory also.

LogKitLoggerManager

public LogKitLoggerManager(java.lang.String prefix,
                           Hierarchy hierarchy,
                           java.lang.String switchToCategory)

Creates a new LogKitLoggerManager with an existing Hierarchy; use with caution. Please also invoke enableLogging() to supply a fallback logger. See comments on the root constructor for details on why constructors supplying an existing hierarchy should be used with caution.

Parameters:

prefix - to prepended to category name on each invocation of getLoggerForCategory().

switchToCategory - if this parameter is not null after start() LogKitLoggerManager will start to log its own debug and error messages to a logger obtained via this.getLoggerForCategory( switchToCategory ). Note that prefix will be prepended to the value of switchToCategory also.

LogKitLoggerManager

public LogKitLoggerManager(Hierarchy hierarchy)

Creates a new LogKitLoggerManager with an existing Hierarchy; use with caution. Please also invoke enableLogging() to supply a fallback logger. See comments on the root constructor for details on why constructors supplying an existing hierarchy should be used with caution.

LogKitLoggerManager

public LogKitLoggerManager(java.lang.String prefix,
                           Hierarchy hierarchy)

Creates a new LogKitLoggerManager with an existing Hierarchy; use with caution. Please also invoke enableLogging() to supply a fallback logger. See comments on the root constructor for details on why constructors supplying an existing hierarchy should be used with caution.

Parameters:

prefix - to prepended to category name on each invocation of getLoggerForCategory().

LogKitLoggerManager

public LogKitLoggerManager(java.lang.String prefix,
                           Hierarchy hierarchy,
                           Logger defaultOverrideAndFallback)

Creates a new LogKitLoggerManager with an existing Hierarchy using specified logger name as a fallback logger and to forcibly override the root logger; compatibility constructor. The configuration for the "" category in the configuration will supply the defaults for all other categories, but getDefaultLogger() and getLoggerForCategory() will still use logger supplied by this constructor.

See comments on the root constructor for details on why constructors supplying an existing hierarchy should be used with caution.

As this constructor provides a logger to be used as a fallback a subsequent enableLogging() stage is unnecessary. Moreover, it will fail.

Parameters:

prefix - to prepended to category name on each invocation of getLoggerForCategory().

defaultOverrideAndFallback - the logger used to a) forcibly override the root logger that will further be obtained from the configuration and b) as the fallback logger. Note that specifying a logger as this parameter crucially differs from supplying it via enableLogging(). The logger supplied via enableLogging will only be used as the fallback logger and to log messages during initialization while this constructor argument also has the described override semantics.

LogKitLoggerManager

public LogKitLoggerManager(java.lang.String prefix,
                           Hierarchy hierarchy,
                           Logger defaultLoggerOverride,
                           Logger fallbackLogger)

Creates a new LogKitLoggerManager with an existing Hierarchy using specified loggers to forcibly override the default logger and to provide a fallback logger; compatibility constructor. See comments on the root constructor for details on why constructors supplying an existing hierarchy should be used with caution.

As this constructor provides a logger to be used as a fallback a subsequent enableLogging() stage is unnecessary. Moreover, it will fail.

Parameters:

prefix - to prepended to category name on each invocation of getLoggerForCategory().

defaultLoggerOverride - the logger to be used to forcibly override the root logger that will further be obtained from the configuration

fallbackLogger - the logger to as a fallback logger (passing non-null as this argument eliminates the need to invoke enableLogging())

LogKitLoggerManager

public LogKitLoggerManager(java.lang.String prefix,
                           Hierarchy hierarchy,
                           java.lang.String switchToCategory,
                           Logger defaultLoggerOverride,
                           Logger fallbackLogger)

Creates a new LogKitLoggerManager; "root" constructor invoked by all other constructors.

If the hierarchy parameter is not null this instructs this constructor to use an existing hierarchy instead of creating a new one. This also disables removing the default log target configured by the Hierarchy() constructor (this target logs to System.out) and installing our own ErrorHandler for our Hierarchy (the default ErrorHandler writes to System.err).

The configuration of the resulting Hierarchy is a combination of the original configuraiton that existed when this Hierarchy was handled to us and the configuration supplied to use via configure(). LogTargets for those categories for which a configuration node has been supplied in the configuration supplied via configure() are replaced during the configure() process. LogTargets for those categories for which configuration nodes have not been supplied are left as they were. A special case is when a node in configuration for a category exists but it does not enlist log targets. In this case the original targets if any are left as they were.

Generally it is preferrable to

• have the Hierarchy be configured from top to bottom via the configuration
• have our custom ErrorHandler reporting errors via the fallback logger (supplied either as the fallbackLogger to this constructor or via the enableLogging() method) installed

That's why it is preferrable to pass null for the hierarchy parameter of this constructor or, which is easier to read but has the same effect, to invoke a constructor which does not accept a Hierarchy argument.

The defaultLoggerOverride and fallbackLogger are a special case too. defaultLoggerOverride forcibly overrides the root logger configured via configure(). As there is little reason to take away users's freedom to configure whatever he likes as the default logger, it is preferrable to pass null for this parameter or better still to invoke a constructor without Logger parameters at all.

There is nothing wrong with passing fallbackLogger via this constructor, but as this constructor is not convinient to be invoked (too many arguments, some of them likely to be null) and the LogKitLoggerManager(String,Hierarchy,Logger) constructor is broken in using its Logger argument both as fallbackLogger (which is okay) and as a defaultLoggerOverride (which is probably not desired for the reasons given above) it is preferrable not to specify a logger as a constructor argument but rather supply it via enableLogging() call, like this happens with all other normal Avalon components after all.

Parameters:

prefix - to prepended to category name on each invocation of getLoggerForCategory().

switchToCategory - if this parameter is not null after start() LogKitLoggerManager will start to log its own debug and error messages to a logger obtained via this.getLoggerForCategory( switchToCategory ). Note that prefix will be prepended to the value of switchToCategory also.

defaultLoggerOverride - the logger to be used to forcibly override the root logger that would further be obtained from the configuration

fallbackLogger - the logger to as a fallback logger (passing non-null as this argument eliminates the need to invoke enableLogging())

Method Detail

contextualize

public final void contextualize(Context context)
                         throws ContextException

Reads a context object that will be supplied to the log target factory manager.

Specified by:

contextualize in interface Contextualizable

Parameters:

context - The context object.

Throws:

ContextException - if the context is malformed

doGetLoggerForCategory

protected Logger doGetLoggerForCategory(java.lang.String fullCategoryName)

Actually create a logger for the given category. The result will be cached by AbstractLoggerManager.getLoggerForCategory().

Specified by:

doGetLoggerForCategory in class AbstractLoggerManager

configure

public void configure(Configuration configuration)
               throws ConfigurationException

Reads a configuration object and creates the category mapping.

Specified by:

configure in interface Configurable

Parameters:

configuration - The configuration object.

Throws:

ConfigurationException - if the configuration is malformed

dispose

public void dispose()

Closes all our LogTargets.

Specified by:

dispose in interface Disposable