There are two base abstractions used by JCL: 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):

1. Look for a configuration attribute of this factory named 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 in each file, 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.

2. Look for a system property named 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).
3. If the Log4J logging system is available in the application class path, use the corresponding wrapper class (Log4JLogger).
4. If the application is executing on a JDK 1.4 system, use the corresponding wrapper class (Jdk14Logger).
5. Fall back to the default simple logging wrapper (SimpleLog).

Consult the JCL javadocs for details of the various Log implementations that ship with the component. (The discovery process is also covered in more detail there.)

The JCL SPI can be configured to use different logging toolkits (see above). JCL provides only a bridge for writing log messages. It does not (and will not) support any sort of configuration API for the underlying logging system.

Configuration of the behavior of the JCL ultimately depends upon the logging toolkit being used. Please consult the documentation for the chosen logging system.

The 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.

The optional jar includes, oddly enough, optional classes that are useful but not strictly required to make JCL functional. As these classes introduce dependencies on JDK 1.3+ JVMs and a goal of JCL is to be usable on JDK 1.2 and earlier JVMs, these optional classes are not included in the main commons-logging.jar.

Included in the optional jar are classes which allow JCL to (potentially) improve it's memory utilization (see Classloader and Memory Management below). It is therefore recommended that (when running on a 1.3+ JDK) the optional jar be deployed alongside the main commons-logging.jar. It should be deployed such that it will be loaded by the same classloader that loads LogFactory. When so deployed, JCL will discover the appropriate classes and configure itself to use them.

The commons-logging-api.jar file includes the JCL API and the default LogFactory implementation, but does not include the wrapper Log implementations for Log4j, Avalon and Lumberjack. This jar is intended for use in specialized containers such as Tomcat that wish to use JCL internally but also need to make JCL available for use by deployed applications.

If this jar is used, in order to benefit from improved memory management in modern JVMs (1.3+), it is recommended that the commons-logging-optional.jar is deployed in the same classloader as this jar.

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.

It is important to ensure that log message are appropriate in content and severity. The following guidelines are suggested:

• fatal - Severe errors that cause premature termination. Expect these to be immediately visible on a status console. See also Internationalization.
• error - Other runtime errors or unexpected conditions. Expect these to be immediately visible on a status console. See also Internationalization.
• warn - Use of deprecated APIs, poor use of API, 'almost' errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong". Expect these to be immediately visible on a status console. See also Internationalization.
• info - Interesting runtime events (startup/shutdown). Expect these to be immediately visible on a console, so be conservative and keep to a minimum. See also Internationalization.
• debug - detailed information on the flow through the system. Expect these to be written to logs only.
• trace - more detailed information. Expect these to be written to logs only.

By default the message priority should be no lower than info. That is, by default debug message should not be seen in the logs.

The general rule in dealing with exceptions is to assume that the user (developer using a tooling/middleware API) isn't going to follow the rules. Since any problems that result are going to be assigned to you, it's in your best interest to be prepared with the proactive tools necessary to demonstrate that your component works correctly, or at worst that the problem can be analyzed from your logs. For this discussion, we must make a distinction between different types of exceptions based on what kind of boundaries they cross:

• 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'.

You want to have exception/problem information available for first-pass problem determination in a production level enterprise application without turning on debug as a default log level. There is simply too much information in debug to be appropriate for day-to-day operations.

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");

This allows the 'enterprise' level information to be turned on/off explicitly by most logger implementations.

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 (that's 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 LogFactory discovery process (see Configuration above) is a fairly expensive operation, so JCL certainly should not perform it each time user code invokes:

Instead JCL caches the 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

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.0.5, LogFactory will attempt to cache factory implementations in a WeakHashtable. This class is analogous to java.util.WeakHashMap in that it holds WeakReferences to its keys, thus allowing classloaders to be GC'd even if LogFactory.release() is never invoked.

Because WeakHashtable depends on JDK 1.3+ features, it cannot be included in the main commons-logging.jar file. It is found in commons-logging-optional.jar. J2EE container implementors who distribute JCL with their application are strongly encouraged to place commons-logging-optional.jar on the classpath in the same location where LogFactory is loaded.

In a particular usage scenario, WeakHashtable alone will 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 concrete implementation will have a strong reference to the child classloader via the chain getClass().getClassLoader(). The WeakHashtable will have a strong reference to the LogFactory implementation as one of the values in its map. This chain of references will prevent collection of the child classloader.

Such a situation would typically only occur if commons-logging.jar were loaded by a parent classloader (e.g. a server level classloader in a servlet container) and a custom LogFactory implementation were loaded by a child classloader (e.g. a web app classloader). 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.

When creating new implementations for Log and LogFactory, it is important to understand the implied contract between the factory and the log implementations:

• Life cycle

  The JCL LogFactory implementation must assume responsibility for either connecting/disconnecting to a logging toolkit, or instantiating/initializing/destroying a logging toolkit.

• Exception handling

  The JCL Log interface doesn't specify any exceptions to be handled, the implementation must catch any exceptions.

• Multiple threads

  The JCL Log and LogFactory implementations must ensure that any synchronization required by the logging toolkit is met.

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.

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.

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 in 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.

Upon application startup (especially in a container environment), an exception is thrown with message 'xxxLogger does not implement Log'! What's the cause and how can I fix this problem?

This almost always a classloader issue. Log has been loaded by a different classloader from the logging implementation. Please ensure that:

• all the logging classes (both Log and the logging implementations) are deployed by the same classloader

• there is only copy of the classes to be found within the classloader hierarchy. In application container environments this means ensuring that if the classes are found in a parent classloader, they are not also present in the leaf classloader associated with the application. So, if the jar is deployed within the root classloader of the container then it should be removed from the application's library.

See How Can I Change The Logging System Configuration?

The configuration supported by JCL is limited to choosing the underlying logging system. JCL does not (and will never) support changing the configuration of the wrapped logging system. Please use the mechanisms provided by the underlying logging system.