diff options
Diffstat (limited to 'src/org/apache/commons/logging/package.html')
| -rw-r--r-- | src/org/apache/commons/logging/package.html | 254 |
1 files changed, 0 insertions, 254 deletions
diff --git a/src/org/apache/commons/logging/package.html b/src/org/apache/commons/logging/package.html deleted file mode 100644 index cfde4f0..0000000 --- a/src/org/apache/commons/logging/package.html +++ /dev/null @@ -1,254 +0,0 @@ -<!-- - - Copyright 2001-2004 The Apache Software Foundation. - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - ---> - -<body> -<p>Simple wrapper API around multiple logging APIs.</p> - - -<h3>Overview</h3> - -<p>This package provides an API for logging in server-based applications that -can be used around a variety of different logging implementations, including -prebuilt support for the following:</p> -<ul> -<li><a href="http://logging.apache.org/log4j/">Log4J</a> (version 1.2 or later) - from Apache's Jakarta project. Each named <a href="Log.html">Log</a> - instance is connected to a corresponding Log4J Logger.</li> -<li><a href="http://java.sun.com/j2se/1.4/docs/guide/util/logging/index.html"> - JDK Logging API</a>, included in JDK 1.4 or later systems. Each named - <a href="Log.html">Log</a> instance is connected to a corresponding - <code>java.util.logging.Logger</code> instance.</li> -<li><a href="http://avalon.apache.org/logkit/">LogKit</a> from Apache's - Avalon project. Each named <a href="Log.html">Log</a> instance is - connected to a corresponding LogKit <code>Logger</code>.</li> -<li><a href="impl/NoOpLog.html">NoOpLog</a> implementation that simply swallows - all log output, for all named <a href="Log.html">Log</a> instances.</li> -<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.err.</li> -</ul> - - -<h3>Quick Start Guide</h3> - -<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 { - - private Log log = LogFactory.getLog(Foo.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 written -to System.err. 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></code> 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>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 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 cached per class loader. - - -<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>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: - <ul> - <li>Look for a configuration attribute of this factory named - <code>org.apache.commons.logging.Log</code> (for backwards - compatibility to pre-1.0 versions of this API, an attribute - <code>org.apache.commons.logging.log</code> is also consulted).</li> - <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>If the Log4J logging system is available in the application - class path, use the corresponding wrapper class - (<a href="impl/Log4JLogger.html">Log4JLogger</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 simple logging implementation - (<a href="impl/SimpleLog.html">SimpleLog</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>See the <a href="impl/SimpleLog.html">SimpleLog</a> JavaDocs for detailed -configuration information for this default implementation.</p> - - -<h4>Configuring the Underlying Logging System</h4> - -<p>The basic principle is that the user is totally responsible for the -configuration of the underlying logging system. -Commons-logging should not change the existing configuration.</p> - -<p>Each individual <a href="Log.html">Log</a> implementation may -support its own configuration properties. These will be documented in the -class descriptions for the corresponding implementation class.</p> - -<p>Finally, some <code>Log</code> implementations (such as the one for Log4J) -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 -component, consists of the following steps:</p> -<ol> -<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="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> -<li>Cause messages to be logged (if the corresponding detail level is enabled) - by calling appropriate methods (<code>trace()</code>, <code>debug()</code>, - <code>info()</code>, <code>warn()</code>, <code>error</code>, and - <code>fatal()</code>).</li> -</ol> - -<p>For convenience, <code>LogFactory</code> also offers a static method -<code>getLog()</code> that combines the typical two-step pattern:</p> -<pre> - Log log = LogFactory.getFactory().getInstance(Foo.class); -</pre> -<p>into a single method call:</p> -<pre> - Log log = LogFactory.getLog(Foo.class); -</pre> - -<p>For example, you might use the following technique to initialize and -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.LogFactory; - -public class MyComponent { - - protected Log log = - LogFactory.getLog(MyComponent.class); - - // Called once at startup time - public void start() { - ... - log.info("MyComponent started"); - ... - } - - // Called once at shutdown time - public void stop() { - ... - log.info("MyComponent stopped"); - ... - } - - // Called repeatedly to process a particular argument value - // which you want logged if debugging is enabled - public void process(String value) { - ... - // Do the string concatenation only if logging is enabled - if (log.isDebugEnabled()) - log.debug("MyComponent processing " + value); - ... - } - -} -</pre> - -</body> |