org.apache.commons.logging (SLF4J 1.7.4 API)
Date: 2013-03-18

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package org.apache.commons.logging

Jakarta Commons Logging implemented over SLF4J.

See:
Description

Interface Summary
Log | A simple logging interface abstracting logging APIs.

Class Summary
LogFactory | Factory for creating `Log` instances, which always delegates to an instance of `SLF4JLogFactory`.

Exception Summary
LogConfigurationException | An exception that is thrown only if a suitable `LogFactory` or `Log` instance cannot be created by the corresponding factory methods.

## Package org.apache.commons.logging Description

Jakarta Commons Logging implemented over SLF4J.

### Overview

This package contains the same public user interface as Jakarta Commons Logging (JCL). It is intended as a 100% compatible drop-in replacement for the original JCL version 1.0.4.

As the original JCL version 1.0.4, the present version supports various logging APIs. It differs from the original in implementation but not the public API. This implementation uses SLF4J under the covers. As as such, all the logging systems that SLF4J supports, e.g. NOP, Simple, JDK14, nlog4j are supported by this version of JCL.

### Quick Start Guide

For those impatient to just get on with it, the following example illustrates the typical declaration and use of a logger that is named (by convention) after the calling class:

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

        public class Foo {

            static Log log = LogFactory.getLog(Foo.class);

            public void foo() {
                ...
                try {
                    if (log.isDebugEnabled()) {
                        log.debug("About to do something to object " + name);
                    }
                    name.bar();
                } catch (IllegalStateException e) {
                    log.error("Something bad happened to " + name, e);
                }
                ...
            }

### Configuring the Commons Logging Package

In this version of JCL, the selection of the logging system to use is chosen by the underlying SLF4J API. Consequently, all JCL-specific configration parameters are ignored.

#### Choosing a `LogFactory` Implementation

From an application perspective, the first requirement is to retrieve an object reference to the `LogFactory` instance that will be used to create `Log` instances for this application. This is normally accomplished by calling the static `getFactory()` method. This method always returns the same factory, i.e. a unique instance of the SLF4FLogFactory class.

#### 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 LogFactory.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 (`trace()`, `debug()`, `info()`, `warn()`, `error`, and `fatal()`).

For convenience, `LogFactory` also offers a static method `getLog()` that combines the typical two-step pattern:

      Log log = LogFactory.getFactory().getInstance(Foo.class);

into a single method call:

      Log log = LogFactory.getLog(Foo.class);

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.LogFactory;

    public class MyComponent {

      protected static Log log =
        LogFactory.getLog(MyComponent.class);

      // 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);
        ...
      }

    }

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

Copyright © 2005-2013 QOS.ch. All Rights Reserved.