Update the javadocs package description to reflect the new LogFactory

capabilities.


git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/logging/trunk@138864 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/logging/package.html

@@ -17,40 +17,147 @@ prebuilt support for the following:</p>
 <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
+<p>For those impatient to just get on with it, the following example
-properties, which are normally set on the command line that started your
+illustrates the typical declaration and use of a logger that is named (by
-application.  The following system properties are global to all
+convention) after the calling class:
-<a href="Log.html">Log</a> implementations:
+
+<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
+<li>Check for a system property named
-    of the <code>org.apache.commons.logging.Log</code> implementation to be
+   <code>org.apache.commons.logging.LogFactory</code>.</li>
-    used.</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
+<p>If a <code>commons-logging.properties</code> file is found, all of the
-following algorithm is applied:</p>
+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
+<li>At most one <code>Log</code> instance of the same name will be created.
-    <a href="Log4JCategoryLog.html">Log4JCategoryLog</a> that wraps a
+    Subsequent <code>getInstance()</code> calls to the same
-    Log4J Category instance of the specified name.</li>
+    <code>LogFactory</code> instance, with the same name or <code>Class</code>
-<li>If the JDK 1.4 logging APIs are available, return an instance
+    parameter, will return the same <code>Log</code> instance.</li>
-    of <a href="Jdk14Logger.html">Jdk14Logger</a> that wraps an instance of
+<li>When a new <code>Log</code> instance must be created, the default
-    <code>java.util.logging.Logger</code> for the specified name.</li>
+    <code>LogFactory</code> implementation uses the following discovery
-<li>Return an instance of <a href="NoOpLog.html">NoOpLog</a> that
+    process is used:
-    throws away all logged output.</li>
+    <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 @@ 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.</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 @@ component, consists of the following steps:</p>
 <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)">
+    <a href="LogFactory.html#getInstance(java.lang.String)">
-    LogSource.getInstance(String name)</a>.  Your application can contain
+    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 @@ component, consists of the following steps:</p>
 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() {