Siphalor/tweed5-commons-logging
1
0
Fork 0
Code Activity

Update the javadocs package description to reflect the new LogFactory

Browse Source 
capabilities.


git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/logging/trunk@138864 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Craig R. McClanahan
2002-02-15 01:59:48 +00:00
parent 7bf2ea493d
commit aa4b2e1a80
1 changed files with 133 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
src/java/org/apache/commons/logging/package.html
View File

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