org.clapper.util.logging
Class Logger

java.lang.Object
  org.clapper.util.logging.Logger

public class Logger
extends java.lang.Object

Logger wraps the Jakarta Commons Logging API and provides a slightly simpler, but similar, interface. This class supports most of the logging methods, but it doesn't actually instantiate an underlying java.util.logging.Logger object until (or unless) a thread explicitly calls the enableLogging() method. The first call to enableLogging() traverses the list of instantiated org.clapper.util.Logger objects and creates underlying java.util.logging.Logger objects for each one. Any Logger objects created after enableLogging() is called are automatically enabled.

This approach prevents any interaction with the real logging layer, unless logging is explicitly enabled (e.g., because a command-line option has been specified). This approach was originally taken to avoid annoying startup messages from the Log4J logging implementation, which insists on writing warning messages to the console when it can't find a configuration file.

However, this class can be reimplemented in terms of other logging layers (and, in fact, has been implemented solely in terms of the JDK 1.4 native logging library in the past).

This object's main purpose now is to insulate applications from the underlying logging technology, so that technology can be changed, if necessary, without having an impact on applications that use this class.

The level mappings used by this class are identical to those used by Commons Logging. (e.g.,, a "debug" message uses the same level as a Commons Logging "debug" message.) Those mappings are:

org.clapper.util.logging.Logger method	Corresponding java.util.logging.Level value
debug()	FINE
error()	SEVERE
fatal()	SEVERE
info()	INFO
trace()	FINEST
warn()	WARNING

If you prefer to use Commons Logging directly, then, by all means, use it for your applications.

WARNING: If your application installs its own class loader (e.g., as the thread context class loader), you may have problems with both Jakarta Commons Logging and java.util.logging (which Jakarta Commons Logging uses as its default logging implementation).

• The java.util.logging layer explicitly bootstraps itself using the system class loader (i.e., the class loader that examines the CLASSPATH setting). In some cases, this can cause problems. For instance, an application that installs its own class loader and expects to use that class loader to find a custom-built java.util.logging formatter will not end up using its own formatter, because the formatter class is not available in the CLASSPATH, and that's where java.util.logging expects to find it. In situations like that, the best bet is to substitute a better-behaved underlying logging layer such as Log4J.
• Jakarta Commons Logging uses a "discovery" process that plays class loader games. You can solve the problem with Commons Logging by explicitly specifying the underlying logging API to use. For example:

   java -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger -Dlog4j.configuration=file:/path/to/log4j-debug.properties

Version:

$Revision: 6735 $

Author:

Copyright © 2004-2007 Brian M. Clapper

See Also:

enableLogging(), Jakarta Commons Logging API

Field Summary

static LogLevel	LEVEL_DEBUG Log level constant for debug messages.
static LogLevel	LEVEL_ERROR Log level constant for error messages.
static LogLevel	LEVEL_FATAL Log level constant for fatal-error messages.
static LogLevel	LEVEL_INFO Log level constant for informational messages.
static LogLevel	LEVEL_TRACE Log level constant for trace messages.
static LogLevel	LEVEL_WARNING Log level constant for warning messages.

Constructor Summary

Logger(java.lang.Class cls)
Construct a new Logger object

Logger(java.lang.String className)
Construct a new Logger object

Method Summary

void	debug(java.lang.Object message) Log a message with debug log level.
void	debug(java.lang.Object message, java.lang.Throwable ex) Log an error with debug log level.
static void	enableLogging() Enable logging by instantiating the underlying Log objects.
void	error(java.lang.Object message) Log a message with error log level.
void	error(java.lang.Object message, java.lang.Throwable ex) Log an error with error log level.
void	fatal(java.lang.Object message) Log a message with fatal log level.
void	fatal(java.lang.Object message, java.lang.Throwable ex) Log an error with fatal log level.
void	info(java.lang.Object message) Log a message with info log level.
void	info(java.lang.Object message, java.lang.Throwable ex) Log an error with info log level.
boolean	isDebugEnabled() Determine whether debug logging is currently enabled.
boolean	isErrorEnabled() Determine whether error logging is currently enabled.
boolean	isFatalEnabled() Determine whether fatal logging is currently enabled.
boolean	isInfoEnabled() Determine whether info logging is currently enabled.
boolean	isTraceEnabled() Determine whether trace logging is currently enabled.
boolean	isWarningEnabled() Determine whether warn logging is currently enabled.
void	message(LogLevel level, java.lang.Object message) Log a message at a specified log level.
void	message(LogLevel level, java.lang.Object message, java.lang.Throwable ex) Log a message at a specified log level.
void	trace(java.lang.Object message) Log a message with trace log level.
void	trace(java.lang.Object message, java.lang.Throwable ex) Log an error with trace log level.
void	warn(java.lang.Object message) Log a message with warn log level.
void	warn(java.lang.Object message, java.lang.Throwable ex) Log an error with warn log level.

Methods inherited from class java.lang.Object

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

Field Detail

LEVEL_DEBUG

public static LogLevel LEVEL_DEBUG

Log level constant for debug messages. Defined here for backward compatibility.

See Also:

LogLevel.DEBUG

LEVEL_ERROR

public static LogLevel LEVEL_ERROR

Log level constant for error messages. Defined here for backward compatibility.

See Also:

LogLevel.ERROR

LEVEL_FATAL

public static LogLevel LEVEL_FATAL

Log level constant for fatal-error messages. Defined here for backward compatibility.

See Also:

LogLevel.FATAL

LEVEL_INFO

public static LogLevel LEVEL_INFO

Log level constant for informational messages. Defined here for backward compatibility.

See Also:

LogLevel.INFO

LEVEL_TRACE

public static LogLevel LEVEL_TRACE

Log level constant for trace messages. Defined here for backward compatibility.

See Also:

LogLevel.TRACE

LEVEL_WARNING

public static LogLevel LEVEL_WARNING

Log level constant for warning messages. Defined here for backward compatibility.

See Also:

LogLevel.WARNING

Constructor Detail

Logger

public Logger(java.lang.String className)

Construct a new Logger object

Parameters:

className - the class name to associate with the object

Logger

public Logger(java.lang.Class cls)

Construct a new Logger object

Parameters:

cls - the class whose name should be associated with the object

Method Detail

enableLogging

public static void enableLogging()
                          throws java.lang.UnsupportedOperationException

Enable logging by instantiating the underlying Log objects. Enables logging for all instantiated Logger objects, and ensures that any subsequently instantiated Logger objects will be enabled.

Throws:

java.lang.UnsupportedOperationException - could not find Commons Logging API

debug

public void debug(java.lang.Object message)

Log a message with debug log level.

Parameters:

message - The message to convert to a string and log

debug

public void debug(java.lang.Object message,
                  java.lang.Throwable ex)

Log an error with debug log level.

Parameters:

message - The message to convert to a string and log

ex - The exception to log with the message

error

public void error(java.lang.Object message)

Log a message with error log level.

Parameters:

message - The message to convert to a string and log

error

public void error(java.lang.Object message,
                  java.lang.Throwable ex)

Log an error with error log level.

Parameters:

message - The message to convert to a string and log

ex - The exception to log with the message

fatal

public void fatal(java.lang.Object message)

Log a message with fatal log level.

Parameters:

message - The message to convert to a string and log

fatal

public void fatal(java.lang.Object message,
                  java.lang.Throwable ex)

Log an error with fatal log level.

Parameters:

message - The message to convert to a string and log

ex - The exception to log with the message

info

public void info(java.lang.Object message)

Log a message with info log level.

Parameters:

message - The message to convert to a string and log

info

public void info(java.lang.Object message,
                 java.lang.Throwable ex)

Log an error with info log level.

Parameters:

message - The message to convert to a string and log

ex - The exception to log with the message

message

public void message(LogLevel level,
                    java.lang.Object message)

Log a message at a specified log level.

Parameters:

level - the log level

message - the message

message

public void message(LogLevel level,
                    java.lang.Object message,
                    java.lang.Throwable ex)

Log a message at a specified log level.

Parameters:

level - the log level

message - the message

ex - The exception to log with the message

trace

public void trace(java.lang.Object message)

Log a message with trace log level.

Parameters:

message - The message to convert to a string and log

trace

public void trace(java.lang.Object message,
                  java.lang.Throwable ex)

Log an error with trace log level.

Parameters:

message - The message to convert to a string and log

ex - The exception to log with the message

warn

public void warn(java.lang.Object message)

Log a message with warn log level.

Parameters:

message - The message to convert to a string and log

warn

public void warn(java.lang.Object message,
                 java.lang.Throwable ex)

Log an error with warn log level.

Parameters:

message - The message to convert to a string and log

ex - The exception to log with the message

isDebugEnabled

public boolean isDebugEnabled()

Determine whether debug logging is currently enabled.

Returns:

true if debug logging is enabled, false otherwise

isErrorEnabled

public boolean isErrorEnabled()

Determine whether error logging is currently enabled.

Returns:

true if error logging is enabled, false otherwise

isFatalEnabled

public boolean isFatalEnabled()

Determine whether fatal logging is currently enabled.

Returns:

true if fatal logging is enabled, false otherwise

isInfoEnabled

public boolean isInfoEnabled()

Determine whether info logging is currently enabled.

Returns:

true if info logging is enabled, false otherwise

isTraceEnabled

public boolean isTraceEnabled()

Determine whether trace logging is currently enabled.

Returns:

true if trace logging is enabled, false otherwise

isWarningEnabled

public boolean isWarningEnabled()

Determine whether warn logging is currently enabled.

Returns:

true if warn logging is enabled, false otherwise