commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-commons/logging/src/java/org/apache/commons/logging package.html
Date Fri, 15 Feb 2002 01:59:48 GMT
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 @@
   <li><a href="http://jakarta.apache.org/avalon/">LogKit</a> from Apache's
       Jakarta project.  Each named <a href="Log.html">Log</a> instance is
       connected to a corresponding LogKit <code>Logger</code>.</li>
  -<li><a href="NoOpLog.html">NoOpLog</a> implementation that simply swallows
  +<li><a href="impl/NoOpLog.html">NoOpLog</a> implementation that simply
swallows
       all log output, for all named <a href="Log.html">Log</a> isntances.</li>
  -<li><a href="SimpleLog.html">SimpleLog</a> implementation that writes
all
  +<li><a href="impl/SimpleLog.html">SimpleLog</a> implementation that writes
all
       log output, for all named <a href="Log.html">Log</a> instances, to
       System.out.</li>
   </ul>
   
  -<h3>Configuring the Logging Package APIs</h3>
   
  -<h4>Choosing A <code>Log</code> Implementation</h4>
  +<h3>Quick Start Guide</h3>
   
  -<p>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
  -<a href="Log.html">Log</a> implementations:
  +<p>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:
  +
  +<pre>
  +    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);
  +            }
  +            ...
  +        }
  +</pre>
  +
  +<p>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.</p>
  +
  +
  +<h3>Configuring the Commons Logging Package</h3>
  +
  +
  +<h4>Choosing A <code>LogFactory</code> Implementation</h4>
  +
  +<p>From an application perspective, the first requirement is to retrieve an
  +object reference to the <code>LogFactory</code> instance that will be used
  +to create <code><a href="Log.html">Log</a> instances for this application.
  +This is normally accomplished by calling the static <code>getFactory()</code>
  +method.  This method implements the following discovery algorithm to select
  +the name of the <code>LogFactory</code> implementation class this application
  +wants to use:</p>
   <ul>
  -<li><code>org.apache.commons.logging.log</code> - Fully qualified class
name
  -    of the <code>org.apache.commons.logging.Log</code> implementation to be
  -    used.</li>
  +<li>Check for a system property named
  +   <code>org.apache.commons.logging.LogFactory</code>.</li>
  +<li>Use the JDK 1.3 JAR Services Discovery mechanism (see
  +    <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html">
  +    http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html</a> for
  +    more information) to look for a resource named
  +    <code>META-INF/services/org.apache.commons.logging.LogFactory</code>
  +    whose first line is assumed to contain the desired class name.</li>
  +<li>Look for a properties file named <code>commons-logging.properties</code>
  +    visible in the application class path, with a property named
  +    <code>org.apache.commons.logging.LogFactory</code> defining the
  +    desired implementation class name.</li>
  +<li>Fall back to a default implementation, which is described
  +    further below.</li>
   </ul>
   
  -<p>If you do not specify the class name of the Log implementation to use, the
  -following algorithm is applied:</p>
  +<p>If a <code>commons-logging.properties</code> file is found, all of
the
  +properties defined there are also used to set configuration attributes on
  +the instantiated <code>LogFactory</code> instance.</p>
  +
  +<p>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 <code>LogFactory</code> class itself
  +otherwise.  This allows a copy of <code>commons-logging.jar</code> to be
  +shared in a multiple class loader environment (such as a servlet container),
  +but still allow each web application to provide its own <code>LogFactory</code>
  +implementation, if it so desires.  An instance of this class will then be
  +created, and
  +
  +
  +<h4>The Default <code>LogFactory</code> Implementation</h4>
  +
  +<p>The Logging Package APIs include a default <code>LogFactory</code>
  +implementation class (<a href="impl/LogFactoryImpl.html">
  +org.apache.commons.logging.impl.LogFactoryImpl</a>) that is selected if no
  +other implementation class name can be discovered.  Its primary purpose is
  +to create (as necessary) and return <a href="Log.html">Log</a> instances
  +in response to calls to the <code>getInstance()</code> method.  The default
  +implementation uses the following rules:</p>
   <ul>
  -<li>If Log4J is available, return an instance of
  -    <a href="Log4JCategoryLog.html">Log4JCategoryLog</a> that wraps a
  -    Log4J Category instance of the specified name.</li>
  -<li>If the JDK 1.4 logging APIs are available, return an instance
  -    of <a href="Jdk14Logger.html">Jdk14Logger</a> that wraps an instance of
  -    <code>java.util.logging.Logger</code> for the specified name.</li>
  -<li>Return an instance of <a href="NoOpLog.html">NoOpLog</a> that
  -    throws away all logged output.</li>
  +<li>At most one <code>Log</code> instance of the same name will be created.
  +    Subsequent <code>getInstance()</code> calls to the same
  +    <code>LogFactory</code> instance, with the same name or <code>Class</code>
  +    parameter, will return the same <code>Log</code> instance.</li>
  +<li>When a new <code>Log</code> instance must be created, the default
  +    <code>LogFactory</code> implementation uses the following discovery
  +    process is used:
  +    <ul>
  +    <li>Look for a system property named
  +        <code>org.apache.commons.logging.Log</code> (for backwards
  +        compatibility to pre-1.0 versions of this API, a system property
  +        <code>org.apache.commons.logging.log</code> is also consulted).</li>
  +    <li>Look for a configuration attribute of this factory named
  +        <code>org.apache.commons.logging.Log</code>.</li>
  +    <li>If the Log4J logging system is available in the application
  +        class path, use the corresponding wrapper class
  +        (<a href="impl/Log4JCategoryLog.html">Log4JCategoryLog</a>).</li>
  +    <li>If the application is executing on a JDK 1.4 system, use
  +        the corresponding wrapper class
  +        (<a href="impl/Jdk14Logger.html">Jdk14Logger</a>).</li>
  +    <li>Fall back to the default no-output logging wrapper
  +        (<a href="impl/NoOpLog.html">NoOpLog</a>).</li>
  +    </ul></li>
  +<li>Load the class of the specified name from the thread context class
  +    loader (if any), or from the class loader that loaded the
  +    <code>LogFactory</code> class otherwise.</li>
  +<li>Instantiate an instance of the selected <code>Log</code>
  +    implementation class, passing the specified name as the single
  +    argument to its constructor.</li>
   </ul>
   
  +<p>If you wish to receive logging output to <code>System.out</code>,
but have
  +not installed one of the three supported logging packages, a simple
  +<code>Log</code> implementation named <a href="impl/SimpleLog.html">
  +SimpleLog</a> 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:</p>
  +<pre>
  +    java \
  +      -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog \
  +      MyApplication
  +</pre>
  +
  +<p>See the <a href="impl/SimpleLog.html">SimpleLog</a> JavaDocs for detailed
  +configuration information for this implementation.</p>
  +
  +
   <h4>Configuring the Underlying Logging System</h4>
   
   <p>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.</p>
   
  +
   <h3>Using the Logging Package APIs</h3>
   
   <p>Use of the Logging Package APIs, from the perspective of an application
  @@ -74,8 +182,8 @@
   <li>Acquire a reference to an instance of
       <a href="Log.html">org.apache.commons.logging.Log</a>, by calling the
       factory method
  -    <a href="LogSource.html#getInstance(java.lang.String)">
  -    LogSource.getInstance(String name)</a>.  Your application can contain
  +    <a href="LogFactory.html#getInstance(java.lang.String)">
  +    LogFactory.getInstance(String name)</a>.  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.</li>
  @@ -88,11 +196,11 @@
   use a <a href="Log.html">Log</a> instance in an application component:</p>
   <pre>
   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:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message