Return-Path: Delivered-To: apmail-jakarta-commons-dev-archive@apache.org Received: (qmail 89005 invoked from network); 15 Feb 2002 01:59:57 -0000 Received: from unknown (HELO nagoya.betaversion.org) (192.18.49.131) by daedalus.apache.org with SMTP; 15 Feb 2002 01:59:57 -0000 Received: (qmail 22601 invoked by uid 97); 15 Feb 2002 02:00:03 -0000 Delivered-To: qmlist-jakarta-archive-commons-dev@jakarta.apache.org Received: (qmail 22535 invoked by uid 97); 15 Feb 2002 02:00:02 -0000 Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Jakarta Commons Developers List" Reply-To: "Jakarta Commons Developers List" Delivered-To: mailing list commons-dev@jakarta.apache.org Received: (qmail 22524 invoked by uid 97); 15 Feb 2002 02:00:02 -0000 Date: 15 Feb 2002 01:59:48 -0000 Message-ID: <20020215015948.93104.qmail@icarus.apache.org> From: craigmcc@apache.org To: jakarta-commons-cvs@apache.org Subject: cvs commit: jakarta-commons/logging/src/java/org/apache/commons/logging package.html X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N craigmcc 02/02/14 17:59:48 Modified: logging/src/java/org/apache/commons/logging package.html Log: Update the javadocs package description to reflect the new LogFactory capabilities. Revision Changes Path 1.5 +133 -25 jakarta-commons/logging/src/java/org/apache/commons/logging/package.html Index: package.html =================================================================== RCS file: /home/cvs/jakarta-commons/logging/src/java/org/apache/commons/logging/package.html,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- package.html 22 Jan 2002 22:10:45 -0000 1.4 +++ package.html 15 Feb 2002 01:59:48 -0000 1.5 @@ -17,40 +17,147 @@
  • 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:

      -
    • org.apache.commons.logging.log - Fully qualified class name - of the org.apache.commons.logging.Log implementation to be - used.
      • +
    • Check for a system property named + org.apache.commons.logging.LogFactory.
      • +
    • Use the JDK 1.3 JAR Services Discovery mechanism (see + + http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html for + more information) to look for a resource named + META-INF/services/org.apache.commons.logging.LogFactory + whose first line is assumed to contain the desired class name.
      • +
    • Look for a properties file named commons-logging.properties + visible in the application class path, with a property named + org.apache.commons.logging.LogFactory defining the + desired implementation class name.
      • +
    • Fall back to a default implementation, which is described + further below.
    -

    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 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.
      • +
    • At most one Log instance of the same name will be created. + Subsequent getInstance() calls to the same + LogFactory instance, with the same name or Class + parameter, will return the same Log instance.
      • +
    • When a new Log instance must be created, the default + LogFactory implementation uses the following discovery + process is used: +
        +
      • 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).
        • +
      • Look for a configuration attribute of this factory named + org.apache.commons.logging.Log.
        • +
      • If the Log4J logging system is available in the application + class path, use the corresponding wrapper class + (Log4JCategoryLog).
        • +
      • If the application is executing on a JDK 1.4 system, use + the corresponding wrapper class + (Jdk14Logger).
        • +
      • Fall back to the default no-output logging wrapper + (NoOpLog).
        • +
      • +
    • Load the class of the specified name from the thread context class + loader (if any), or from the class loader that loaded the + LogFactory class otherwise.
      • +
    • Instantiate an instance of the selected Log + implementation class, passing the specified name as the single + argument to its constructor.
    +

    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 @@ 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 @@

  • 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 @@ 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() {
  
  
  

--
To unsubscribe, e-mail:   
For additional commands, e-mail: