diff --git a/src/java/org/apache/commons/logging/package.html b/src/java/org/apache/commons/logging/package.html index 91fcd1b..1ef7a9c 100644 --- a/src/java/org/apache/commons/logging/package.html +++ b/src/java/org/apache/commons/logging/package.html @@ -17,40 +17,147 @@ prebuilt support for the following:

  • LogKit from Apache's Jakarta project. Each named Log instance is connected to a corresponding LogKit Logger.
    • -
  • NoOpLog implementation that simply swallows +
  • NoOpLog implementation that simply swallows all log output, for all named Log isntances.
    • -
  • SimpleLog implementation that writes all +
  • SimpleLog implementation that writes all log output, for all named Log instances, to System.out.
    • -

    Configuring the Logging Package APIs

    -

    Choosing A Log Implementation

    +

    Quick Start Guide

    -

    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: +

    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 {
+
+        Log log = LogFactory.getLog(this.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);
+            }
+            ...
+        }
+
    + +

    Unless you configure things differently, all log output will be thrown +away. Therefore, you really will want to review the remainder of this page +in order to understand how to configure logging for your application.

    + + +

    Configuring the Commons Logging Package

    + + +

    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 implements the following discovery algorithm to select +the name of the LogFactory implementation class this application +wants to use:

    -

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

    +

    If a commons-logging.properties file is found, all of the +properties defined there are also used to set configuration attributes on +the instantiated LogFactory instance.

    + +

    Once an implementation class name is selected, the corresponding class is +loaded from the current Thread context class loader (if there is one), or +from the class loader that loaded the LogFactory class itself +otherwise. This allows a copy of commons-logging.jar to be +shared in a multiple class loader environment (such as a servlet container), +but still allow each web application to provide its own LogFactory +implementation, if it so desires. An instance of this class will then be +created, and + + +

    The Default LogFactory Implementation

    + +

    The Logging Package APIs include a default LogFactory +implementation class ( +org.apache.commons.logging.impl.LogFactoryImpl) that is selected if no +other implementation class name can be discovered. Its primary purpose is +to create (as necessary) and return Log instances +in response to calls to the getInstance() method. The default +implementation uses the following rules:

    +

    If you wish to receive logging output to System.out, but have +not installed one of the three supported logging packages, a simple +Log implementation named +SimpleLog is available. You can select it, based on the above rules, +by including a system property definition on the command line that starts +your application:

    +
    +    java \
+      -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog \
+      MyApplication
+
    + +

    See the SimpleLog JavaDocs for detailed +configuration information for this implementation.

    + +

    Configuring the Underlying Logging System

    The basic principle is that the user is totally responsible for the @@ -66,6 +173,7 @@ 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 @@ -74,8 +182,8 @@ component, consists of the following steps:

  • 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 + + 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.
    • @@ -88,11 +196,11 @@ component, consists of the following steps:

    use a Log instance in an application component:

     import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogSource;
+import org.apache.commons.logging.LogFactory;
 
 public class MyComponent {
 
-  protected Log log = LogSource.getInstance("my.component");
+  protected Log log = LogFactory.getLog("my.component");
 
   // Called once at startup time
   public void start() {