| 1 |
<!-- |
| 2 |
|
| 3 |
Copyright 2001-2004 The Apache Software Foundation. |
| 4 |
|
| 5 |
Licensed under the Apache License, Version 2.0 (the "License"); |
| 6 |
you may not use this file except in compliance with the License. |
| 7 |
You may obtain a copy of the License at |
| 8 |
|
| 9 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 10 |
|
| 11 |
Unless required by applicable law or agreed to in writing, software |
| 12 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 13 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 |
See the License for the specific language governing permissions and |
| 15 |
limitations under the License. |
| 16 |
|
| 17 |
--> |
| 18 |
|
| 19 |
<body> |
| 20 |
<p>Jakarta Commons Logging implemented over SLF4J.</p> |
| 21 |
|
| 22 |
|
| 23 |
<h3>Overview</h3> |
| 24 |
|
| 25 |
<p>This package contains the same public user interface as <a |
| 26 |
href="http://jakarta.apache.org/commons/logging/">Jakarta Commons |
| 27 |
Logging (JCL)</a>. It is intended as a 100% compatible drop-in |
| 28 |
replacement for the original JCL version 1.0.4. |
| 29 |
</p> |
| 30 |
|
| 31 |
<p>As the original JCL version 1.0.4, the present version supports |
| 32 |
various logging APIs. It differs from the original in implementation |
| 33 |
but not the public API. This implementation uses SLF4J under the |
| 34 |
covers. As as such, all the logging systems that SLF4J supports, |
| 35 |
e.g. NOP, Simple, JDK14, nlog4j are supported by this version of JCL. |
| 36 |
</p> |
| 37 |
|
| 38 |
<h3>Quick Start Guide</h3> |
| 39 |
|
| 40 |
<p>For those impatient to just get on with it, the following example |
| 41 |
illustrates the typical declaration and use of a logger that is named (by |
| 42 |
convention) after the calling class: |
| 43 |
|
| 44 |
<pre> |
| 45 |
import org.apache.commons.logging.Log; |
| 46 |
import org.apache.commons.logging.LogFactory; |
| 47 |
|
| 48 |
public class Foo { |
| 49 |
|
| 50 |
static Log log = LogFactory.getLog(Foo.class); |
| 51 |
|
| 52 |
public void foo() { |
| 53 |
... |
| 54 |
try { |
| 55 |
if (log.isDebugEnabled()) { |
| 56 |
log.debug("About to do something to object " + name); |
| 57 |
} |
| 58 |
name.bar(); |
| 59 |
} catch (IllegalStateException e) { |
| 60 |
log.error("Something bad happened to " + name, e); |
| 61 |
} |
| 62 |
... |
| 63 |
} |
| 64 |
</pre> |
| 65 |
|
| 66 |
<h3>Configuring the Commons Logging Package</h3> |
| 67 |
|
| 68 |
<p>In this version of JCL, the selection of the logging system to use |
| 69 |
is chosen by the underlying SLF4J API. Consequently, all JCL-specific |
| 70 |
configuration parameters are ignored. |
| 71 |
</p> |
| 72 |
|
| 73 |
<h4>Choosing a <code>LogFactory</code> Implementation</h4> |
| 74 |
|
| 75 |
<p>From an application perspective, the first requirement is to |
| 76 |
retrieve an object reference to the <code>LogFactory</code> instance |
| 77 |
that will be used to create <code><a href="Log.html">Log</a></code> |
| 78 |
instances for this application. This is normally accomplished by |
| 79 |
calling the static <code>getFactory()</code> method. This method |
| 80 |
always returns the same factory, i.e. a unique instance of the <a |
| 81 |
href="impl/SLF4FLogFactory.html">SLF4FLogFactory</a> class. |
| 82 |
</p> |
| 83 |
|
| 84 |
|
| 85 |
|
| 86 |
<h4>Configuring the Underlying Logging System</h4> |
| 87 |
|
| 88 |
<p>The basic principle is that the user is totally responsible for the |
| 89 |
configuration of the underlying logging system. |
| 90 |
Commons-logging should not change the existing configuration.</p> |
| 91 |
|
| 92 |
<p>Each individual <a href="Log.html">Log</a> implementation may |
| 93 |
support its own configuration properties. These will be documented in the |
| 94 |
class descriptions for the corresponding implementation class.</p> |
| 95 |
|
| 96 |
<p>Finally, some <code>Log</code> implementations (such as the one for Log4J) |
| 97 |
require an external configuration file for the entire logging environment. |
| 98 |
This file should be prepared in a manner that is specific to the actual logging |
| 99 |
technology being used.</p> |
| 100 |
|
| 101 |
|
| 102 |
<h3>Using the Logging Package APIs</h3> |
| 103 |
|
| 104 |
<p>Use of the Logging Package APIs, from the perspective of an application |
| 105 |
component, consists of the following steps:</p> |
| 106 |
<ol> |
| 107 |
<li>Acquire a reference to an instance of |
| 108 |
<a href="Log.html">org.apache.commons.logging.Log</a>, by calling the |
| 109 |
factory method |
| 110 |
<a href="LogFactory.html#getInstance(java.lang.String)"> |
| 111 |
LogFactory.getInstance(String name)</a>. Your application can contain |
| 112 |
references to multiple loggers that are used for different |
| 113 |
purposes. A typical scenario for a server application is to have each |
| 114 |
major component of the server use its own Log instance.</li> |
| 115 |
<li>Cause messages to be logged (if the corresponding detail level is enabled) |
| 116 |
by calling appropriate methods (<code>trace()</code>, <code>debug()</code>, |
| 117 |
<code>info()</code>, <code>warn()</code>, <code>error</code>, and |
| 118 |
<code>fatal()</code>).</li> |
| 119 |
</ol> |
| 120 |
|
| 121 |
<p>For convenience, <code>LogFactory</code> also offers a static method |
| 122 |
<code>getLog()</code> that combines the typical two-step pattern:</p> |
| 123 |
<pre> |
| 124 |
Log log = LogFactory.getFactory().getInstance(Foo.class); |
| 125 |
</pre> |
| 126 |
<p>into a single method call:</p> |
| 127 |
<pre> |
| 128 |
Log log = LogFactory.getLog(Foo.class); |
| 129 |
</pre> |
| 130 |
|
| 131 |
<p>For example, you might use the following technique to initialize and |
| 132 |
use a <a href="Log.html">Log</a> instance in an application component:</p> |
| 133 |
<pre> |
| 134 |
import org.apache.commons.logging.Log; |
| 135 |
import org.apache.commons.logging.LogFactory; |
| 136 |
|
| 137 |
public class MyComponent { |
| 138 |
|
| 139 |
protected static Log log = |
| 140 |
LogFactory.getLog(MyComponent.class); |
| 141 |
|
| 142 |
// Called once at startup time |
| 143 |
public void start() { |
| 144 |
... |
| 145 |
log.info("MyComponent started"); |
| 146 |
... |
| 147 |
} |
| 148 |
|
| 149 |
// Called once at shutdown time |
| 150 |
public void stop() { |
| 151 |
... |
| 152 |
log.info("MyComponent stopped"); |
| 153 |
... |
| 154 |
} |
| 155 |
|
| 156 |
// Called repeatedly to process a particular argument value |
| 157 |
// which you want logged if debugging is enabled |
| 158 |
public void process(String value) { |
| 159 |
... |
| 160 |
// Do the string concatenation only if logging is enabled |
| 161 |
if (log.isDebugEnabled()) |
| 162 |
log.debug("MyComponent processing " + value); |
| 163 |
... |
| 164 |
} |
| 165 |
|
| 166 |
} |
| 167 |
</pre> |
| 168 |
|
| 169 |
</body> |