The Jakarta Commons Logging (JCL) provides a Log interface that is intended to be both light-weight and independent of numerous logging toolkits. It provides the middleware/tooling developer a simple logging abstraction, that allows the user (application developer) to plug in a specific logging implementation.
Familiarity with high-level details of various Logging implementations is presumed.
The Jakarta Commons Logging provides a Log interface with thin-wrapper implementations for other logging tools, including Log4J, Avalon LogKit, the Avalon Framework's logging infrastructure, JDK 1.4, and an implementation of JDK 1.4 logging APIs (JSR-47) for pre-1.4 systems. The interface maps closely to Log4J and LogKit.
As far as possible, Commons-Logging tries to be as unobtrusive as possible.
In most cases, including the (full) commons-logging.jar in the classpath
should result in Commons-Logging configuring itself in a reasonable manner.
There's a good chance that it'll guess your preferred logging system and you won't
need to do any configuration at all!
There are two base abstractions used by Commons-Logging: Log
(the basic logger) and LogFactory (which knows how to create Log
instances). Using LogFactory implementations other than the default is a
subject for advanced users only, so let's concentrate on configuring the default
implementation.
The default LogFactory implementation uses the following discovery process
to determine what type of Log implementation it should use
(the process terminates when the first positive match - in order - is found):
org.apache.commons.logging.Log (for backwards
compatibility to pre-1.0 versions of this API, an attribute
org.apache.commons.logging.log is also consulted).org.apache.commons.logging.Log (for backwards
compatibility to pre-1.0 versions of this API, a system property
org.apache.commons.logging.log is also consulted).Log
implementations that ship with the component. (The discovery process is also covered in more
detail there.)
To use the JCL SPI from a Java class, include the following import statements:
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
For each class definition, declare and initialize a
log attribute as follows:
public class CLASS
{
private static Log log = LogFactory.getLog(CLASS.class);
...
Messages are logged to a logger, such as log
by invoking a method corresponding to priority.
The org.apache.commons.logging.Log interface defines the
following methods for use
in writing log/trace messages to the log:
log.fatal(Object message);
log.fatal(Object message, Throwable t);
log.error(Object message);
log.error(Object message, Throwable t);
log.warn(Object message);
log.warn(Object message, Throwable t);
log.info(Object message);
log.info(Object message, Throwable t);
log.debug(Object message);
log.debug(Object message, Throwable t);
log.trace(Object message);
log.trace(Object message, Throwable t);
Semantics for these methods are such that it is expected that the severity, from highest to lowest, of messages is ordered as above.
In addition to the logging methods, the following are provided for code guards:
log.isFatalEnabled();
log.isErrorEnabled();
log.isWarnEnabled();
log.isInfoEnabled();
log.isDebugEnabled();
log.isTraceEnabled();
Best practices for programming/planning are presented in two categories: General and Enterprise. The general principles are fairly clear. Enterprise practices are a bit more involved and it is not always as clear as to why they are important.
Enterprise best-practice principles apply to middleware components and tooling that is expected to execute in an "Enterprise" level environment. These issues relate to Logging as Internationalization, and fault detection. Enterprise requires more effort and planning, but are strongly encouraged (if not required) in production level systems. Different corporate enterprises/environments have different requirements, so being flexible always helps.
Code guards are typically used to guard code that
only needs to execute in support of logging,
that otherwise introduces undesirable runtime overhead
in the general case (logging disabled).
Examples are multiple parameters, or expressions (i.e. string + " more") for parameters.
Use the guard methods of the form log.is<Priority>() to verify
that logging should be performed, before incurring the overhead of the logging method call.
Yes, the logging methods will perform the same check, but only after resolving parameters.
By default the message priority should be no lower than info. That is, by default debug message should not be seen in the logs.
External Boundaries - Expected Exceptions.
This classification includes exceptions such as FileNotFoundException
that cross API/SPI boundaries, and are exposed to the user of a component/toolkit.
These are listed in the 'throws' clause of a method signature.
Appropriate handling of these exceptions depends upon the type of code you are developing. API's for utility functions and tools should log these at the debug level, if they are caught at all by internal code.
For higher level frameworks and middleware components, these exceptions should be caught immediatly prior to crossing the API/SPI interface back to user code-space, logged with full stack trace at info level, and rethrown. The assures that the log contains a record of the root cause for future analysis in the event that the exception is not caught and resolved as expected by the user's code.
External Boundaries - Unexpected Exceptions.
This classification includes exceptions such as NullPointerException
that cross API/SPI boundaries, and are exposed to the user of a component/toolkit.
These are runtime exceptions/error that are NOT
listed in the 'throws' clause of a method signature.
Appropriate handling of these exceptions depends upon the type of code you are developing. API's for utility functions and tools should log these at the debug level, if they are caught at all.
For higher level frameworks and middleware components,
these exceptions should be caught immediatly prior to crossing
the API/SPI interface back to user code-space,
logged with full stack trace at info level,
and rethrown/wrapped as ComponentInternalError.
The assures that the log contains a record of the root cause for
future analysis in the event that the exception is not caught and
logged/reported as expected by the user's code.
Internal Boundaries. Exceptions that occur internally and are resolved internally. These should be logged when caught as debug or info messages, at the programmer's discretion.
Significant Internal Boundaries. This typically only applies to middleware components that span networks or runtime processes. Exceptions that cross over significant internal component boundaries, such as networks. These should be logged when caught as info messages. Do not assume that such a (process/network) boundary will deliver exceptions to the 'other side'.
If more control is desired for the level of detail of these 'enterprise' exceptions, then consider creating a special logger just for these exceptions:
Log log = LogFactory.getLog("org.apache.component.enterprise");
NLS internationalization involves looking up messages from a message file by a message key, and using that message for logging. There are various tools in Java, and provided by other components, for working with NLS messages.
NLS enabled components are particularly appreciated (thats an open-source-correct term for 'required by corporate end-users' :-) for tooling and middleware components.
NLS internationalization SHOULD be strongly considered for used for fatal, error, warn, and info messages. It is generally considered optional for debug and trace messages.
Perhaps more direct support for internationalizing log messages
can be introduced in a future or alternate version of the Log interface.
The minimum requirement to integrate with another logger
is to provide an implementation of the
org.apache.commons.logging.Log interface.
In addition, an implementation of the
org.apache.commons.logging.LogFactory interface
can be provided to meet
specific requirements for connecting to, or instantiating, a logger.
The default LogFactory provided by JCL
can be configured to instantiate a specific implementation of the
org.apache.commons.logging.Log interface
by setting the property of the same name (org.apache.commons.logging.Log).
This property can be specified as a system property,
or in the commons-logging.properties file,
which must exist in the CLASSPATH.
The Jakarta Commons Logging SPI uses the
implementation of the org.apache.commons.logging.Log
interface specified by the system property
org.apache.commons.logging.Log.
If the property is not specified or the class is not available then the JCL
provides access to a default logging toolkit by searching the CLASSPATH
for the following toolkits, in order of preference:
If desired, the default implementation of the
org.apache.commons.logging.LogFactory
interface can be overridden,
allowing the JDK 1.3 Service Provider discovery process
to locate and create a LogFactory specific to the needs of the application.
Review the Javadoc for the LogFactoryImpl.java
for details.
Configuration of the behavior of the JCL ultimately depends upon the logging toolkit being used. The JCL SPI uses Log4J by default if it is available (in the CLASSPATH).
Configure Log4J using system properties and/or a properties file:
LogFactory.getLog(logger.name),
used to create the logger instance. Priorities are:
DEBUG,
INFO,
WARN,
ERROR,
or FATAL.
Log4J understands hierarchical names,
enabling control by package or high-level qualifiers:
log4j.logger.org.apache.component=DEBUG
will enable debug messages for all classes in both
org.apache.component
and
org.apache.component.sub.
Likewise, setting
log4j.logger.org.apache.component=DEBUG
will enable debug message for all 'component' classes,
but not for other Jakarta projects.
For example: one can capture DEBUG (and higher) level information in a logfile, while limiting console output to INFO (and higher).
JCL doesn't (and cannot) impose any requirement on thread safety on the underlying implementation and thus its SPI contract doesn't guarantee thread safety. However, JCL can be safely used a multi-threaded environment as long as the underlying implementation is thread-safe.
It would be very unusual for a logging system to be thread unsafe. Certainly, JCL is thread safe when used with the distributed Log implementations.