Log interface that
is intended to be both light-weight and an independent abstraction of other logging toolkits.
It provides the middleware/tooling developer with a simple
logging abstraction, that allows the user (application developer) to plug in
a specific logging implementation.
JCL provides thin-wrapper Log 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.
Familiarity with high-level details of the relevant Logging implementations is presumed.
commons-logging.jar in the classpath
should result in JCL configuring itself in a reasonable manner.
There's a good chance that it'll guess (discover) your preferred logging system and you won't
need to do any configuration of JCL at all!
Note, however, that if you have a particular preference then providing a simple
commons-logging.properties file which specifies the concrete logging library to be
used is recommended, since (in this case) JCL will log only to that system
and will report any configuration problems that prevent that system being used.
When no particular logging library is specified then JCL will silently ignore any logging library
that it finds but cannot initialise and continue to look for other alternatives. This is a deliberate
design decision; no application should fail to run because a "guessed" logging library cannot be
used. To ensure an exception is reported when a particular logging library cannot be used, use one
of the available JCL configuration mechanisms to force that library to be selected (ie disable
JCL's discovery process).
Log
(the basic logger) and LogFactory (which knows how to create Log
instances). Specifying a particular Log implementation is very useful (whether that is
one provided by commons-logging or a user-defined one). Specifying a
LogFactory implementation other than the default is a subject for
advanced users only, so will not be addressed here.
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).
Configuration attributes can be set explicitly by java code, but they are more
commonly set by placing a file named commons-logging.properties in the classpath.
When such a file exists, every entry in the properties file becomes an "attribute"
of the LogFactory. When there is more than one such file in the classpath, releases
of commons-logging prior to 1.1 simply use the first one found. From release 1.1,
each file may define a priority key, and the file with
the highest priority is used (no priority definition implies priority of zero).
When multiple files have the same priority, the first one found is used.
Defining this property in a commons-logging.properties file is the recommended
way of explicitly selecting a Log implementation.
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.)
LogFactory.getLog(logger.name),
used to create the logger instance. Priorities are:
DEBUG,
INFO,
WARN,
ERROR,
or FATAL.
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 Apache projects.
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
log attribute as follows:
public class CLASS
{
private Log log = LogFactory.getLog(CLASS.class);
...
;
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);
log.isFatalEnabled();
log.isErrorEnabled();
log.isWarnEnabled();
log.isInfoEnabled();
log.isDebugEnabled();
log.isTraceEnabled();
commons-logging.jar file includes the JCL API, the default
LogFactory implemenation and thin-wrapper Log
implementations for
Log4J,
Avalon LogKit,
the Avalon Framework's logging infrastructure,
JDK 1.4, as well as an implementation of JDK 1.4 logging APIs (JSR-47) for
pre-1.4 systems.
In most cases, including commons-logging.jar and your preferred
logging implementation in the classpath should be all that is required to
use JCL.
commons-logging-api.jar file includes the JCL API and the
default LogFactory implementation as well as the built-in
Log implementations SimpleLog and NoOpLog. However it does not
include the wrapper Log implementations that require additional
libraries such as Log4j, Avalon and
Lumberjack.
This jar is intended for use by projects that recompile the commons-logging
source using alternate java environments, and cannot compile against all of
the optional libraries that the Apache release of commons-logging supports.
Because of the reduced dependencies of this jarfile, such projects should be
able to create an equivalent of this library with fewer difficulties.
This jar is also useful for build environments that automatically track
dependencies, and thus have difficulty with the concept that the main
commons-logging.jar has "optional" dependencies on various logging
implementations that can safely go unsatisfied at runtime.
commons-logging-adapters.jar file includes only adapters
to third-party logging implementations, and none of the core commons-logging
framework. As such, it cannot be used alone; either commons-logging.jar or
commons-logging-api.jar must also be present in the classpath.
This library will not often be used; it is only intended for situations where
a container has deployed commons-logging-api.jar in a shared classpath but a
webapp wants to bind logging to one of the external logging implementations
that the api jar does not include. In this situation, deploying the
commons-logging.jar file within the webapp can cause problems as this leads to
duplicates of the core commons-logging classes (Log, LogFactory, etc) in
the classpath which in turn can cause unpleasant ClassCastException exceptions
to occur. Deploying only the adapters avoids this problem.
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.
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.
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.
ComponentInternalError.
This ensures 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.
Log log = LogFactory.getLog("org.apache.component.enterprise");
Log interface.
LogFactory discovery process (see
Configuration above) is a fairly expensive
operation, so JCL certainly should not perform it each time user code
invokes:
LogFactory.getLog()
LogFactory implementation created as a result of the discovery
process and uses the cached factory to return Log objects.
Since in J2EE and similar multi-classloader environments, the result of the
discovery process can vary depending on the thread context classloader
(e.g. one webapp in a web container may be configured to use Log4j and
another to use JDK 1.4 logging), JCL internally caches the
LogFactory instances in a static hashtable, keyed by classloader.
While this approach is efficient, it can lead to memory leaks if container implementors are not careful to call
LogFactory.release()
whenever a classloader that has utilized JCL is undeployed. If
release() is not called, a reference to the undeployed
classloader (and thus to all the classes loaded by it) will be
held in LogFactory's static hashtable.
Beginning with JCL 1.1, LogFactory caches factory implementations in a
"WeakHashtable". This class is similar to java.util.WeakHashMap in
that it holds a WeakReference to each key (but a strong reference
to each value), thus allowing classloaders to be GC'd even if
LogFactory.release() is never invoked.
Because WeakHashtable depends on JDK 1.3+ features, it is dynamically
loaded depending on the JVM version; when commons-logging is run on java versions
prior to 1.3 the code defaults to a standard Hashtable instead.
If a custom LogFactory implementation is used, however, then a
WeakHashtable alone can be insufficent to allow garbage collection
of a classloader without a call to release. If the abstract class
LogFactory is loaded by a parent classloader and a concrete
subclass implementation of LogFactory is loaded by a child
classloader, the WeakHashtable's key is a weak reference to the TCCL (child
classloader), but the value is a strong reference to the LogFactory instance,
which in turn contains a strong reference to its class and thus loading
classloader - the child classloader. This chain of strong references prevents
the child loader from being garbage collected.
If use of a custom LogFactory subclass is desired, ensuring that
the custom subclass is loaded by the same classloader as LogFactory
will prevent problems. In normal deployments, the standard implementations
of LogFactory found in package org.apache.commons.logging.impl
will be loaded by the same classloader that loads LogFactory
itself, so use of the standard LogFactory implementation
should not pose problems. Alternatively, use the provided ServletContextCleaner
to ensure this reference is explicitly released on webapp unload.
JCL is designed to encourage extensions to be created that add functionality. Typically, extensions to JCL fall into two categories:
Log implementations that provide new bridges to logging systemsLogFactory implementations that provide alternative discovery strategies
Log and LogFactory,
it is important to understand the implied contract between the factory
and the log implementations:
The JCL LogFactory implementation must assume responsibility for either connecting/disconnecting to a logging toolkit, or instantiating/initializing/destroying a logging toolkit.
The JCL Log interface doesn't specify any exceptions to be handled, the implementation must catch any exceptions.
The JCL Log and LogFactory implementations must ensure that any synchronization required by the logging toolkit is met.
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.
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.
Log implementation named
org.apache.commons.logging.impl.SimpleLog. This is intended to be a minimal
implementation and those requiring a fully functional open source logging system are
directed to Log4J.
SimpleLog sends all (enabled) log messages,
for all defined loggers, to System.err. The following system properties
are supported to configure the behavior of this logger:
tracedebuginfowarnerrorfatalinfo. tracedebuginfowarnerrorfataltrue if you want the Log instance name to be
included in output messages. Defaults to false.true if you want the last component of the name to be
included in output messages. Defaults to true.true if you want the current date and time
to be included in output messages. Default is false.java.text.SimpleDateFormat. If the format is not
specified or is invalid, the default format is used.
The default format is yyyy/MM/dd HH:mm:ss:SSS zzz."simplelog.properties", and includes any matching definitions
from this resource (if it exists).