Simple wrapper API around multiple logging APIs.

Overview

This package provides an API for logging in server-based applications that can be used around a variety of different logging implementations, including prebuilt support for the following:

• Log4J from Apache's Jakarta project. Each named Log instance is connected to a corresponding Log4J Category.
• JDK Logging API, included in JDK 1.4 or later systems. Each named Log instance is connected to a corresponding java.util.logging.Logger instance.
• LogKit from Apache's Jakarta project. Each named Log instance is connected to a corresponding LogKit Logger.
• NoOpLog implementation that simply swallows all log output, for all named Log isntances.
• SimpleLog implementation that writes all log output, for all named Log instances, to System.out.

Configuring the Logging Package APIs

Choosing A Log Implementation

The Logging Package APIs are configured based on the values of system properties, which are normally set on the command line that started your application. The following system properties are global to all Log implementations:

• org.apache.commons.logging.log - Fully qualified class name of the org.apache.commons.logging.Log implementation to be used.

If you do not specify the class name of the Log implementation to use, the following algorithm is applied:

• If Log4J is available, return an instance of Log4JCategoryLog that wraps a Log4J Category instance of the specified name.
• If the JDK 1.4 logging APIs are available, return an instance of Jdk14Logger that wraps an instance of java.util.logging.Logger for the specified name.
• Return an instance of NoOpLog that throws away all logged output.

Configuring the Underlying Logging System

The basic principle is that the user is totally responsible for the configuration of the underlying logging system. Commons-logging should not change the existing configuration.

Each individual Log implementation may support its own configuration properties. These will be documented in the class descriptions for the corresponding implementation class.

Finally, some Log implementations (such as the one for Log4J) require an external configuration file for the entire logging environment. This file should be prepared in a manner that is specific to the actual logging technology being used.

Using the Logging Package APIs

Use of the Logging Package APIs, from the perspective of an application component, consists of the following steps:

1. Acquire a reference to an instance of org.apache.commons.logging.Log, by calling the factory method LogSource.getInstance(String name). Your application can contain references to multiple loggers that are used for different purposes. A typical scenario for a server application is to have each major component of the server use its own Log instance.
2. Cause messages to be logged (if the corresponding detail level is enabled) by calling appropriate methods (debug(), info(), warn(), error, and fatal()).

For example, you might use the following technique to initialize and use a Log instance in an application component:

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogSource;

public class MyComponent {

  protected Log log = LogSource.getInstance("my.component");

  // Called once at startup time
  public void start() {
    ...
    log.info("MyComponent started");
    ...
  }

  // Called once at shutdown time
  public void stop() {
    ...
    log.info("MyComponent stopped");
    ...
  }

  // Called repeatedly to process a particular argument value
  // which you want logged if debugging is enabled
  public void process(String value) {
    ...
    // Do the string concatenation only if logging is enabled
    if (log.isDebugEnabled())
      log.debug("MyComponent processing " + value);
    ...
  }

}