mirror of https://github.com/qos-ch/slf4j
307 lines
12 KiB
HTML
307 lines
12 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
|
|
<title>SLF4J Manual</title>
|
|
<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
|
|
</head>
|
|
<body>
|
|
<script>
|
|
prefix='';
|
|
</script>
|
|
|
|
<script src="templates/header.js"></script>
|
|
<div id="left">
|
|
<script src="templates/left.js"></script>
|
|
</div>
|
|
<div id="right">
|
|
<script src="templates/right.js"></script>
|
|
</div>
|
|
<div id="content">
|
|
|
|
|
|
<h1>SLF4J User manual</h1>
|
|
|
|
<p>The Simple Logging Facade for Java or (SLF4J) is intended to
|
|
serve as a simple facade for various logging APIs allowing to plug
|
|
in the desired implementation at deployment time.
|
|
</p>
|
|
|
|
<h2>Typical usage pattern</h2>
|
|
|
|
<pre class="source">
|
|
1: <b>import org.slf4j.Logger;</b>
|
|
2: <b>import org.slf4j.LoggerFactory;</b>
|
|
3:
|
|
4: public class Wombat {
|
|
5:
|
|
6: <b>final Logger logger = LoggerFactory.getLogger(Wombat.class);</b>
|
|
7: Integer t;
|
|
8: Integer oldT;
|
|
9:
|
|
10: public void setTemperature(Integer temperature) {
|
|
11:
|
|
12: oldT = t;
|
|
13: t = temperature;
|
|
14:
|
|
15: <b>logger.debug("Temperature set to {}. Old temperature was {}.", t, oldT);</b>
|
|
16:
|
|
17: if(temperature.intValue() > 50) {
|
|
18: <b>logger.info("Temperature has risen above 50 degrees.");</b>
|
|
19: }
|
|
20: }
|
|
21: }
|
|
</pre>
|
|
|
|
<p>The example above illustrates the typical usage pattern for
|
|
SLF4j. Note the use of formatted log messages on line 15. See
|
|
the question <a href="faq.html#2.3">"What is the fastest way of
|
|
logging?"</a> in the FAQ for more details.
|
|
</p>
|
|
|
|
<h2>Swapping implementations at deployment time</h2>
|
|
|
|
<p>SLF4J supports multiple logging systems, namely, NOP,
|
|
Simple, log4j version 1.2, JDK 1.4 logging,
|
|
JCL and logback. The SLF4J distribution ships with several jar
|
|
files <em>slf4j-nop.jar</em>, <em>slf4j-simple.jar</em>,
|
|
<em>slf4j-log4j12.jar</em>, <em>slf4j-log4j13.jar</em>,
|
|
<em>slf4j-jdk14.jar</em> and <em>slf4j-jcl.jar</em>. Each of
|
|
these jar files is hardwired <em>at compile-time</em> to use
|
|
just one implementation, that is NOP, Simple, log4j version
|
|
1.2, JDK 1.4 logging, and repectively
|
|
JCL. <span style="color:#D22">As of SLF4J version 1.1.0, all of the
|
|
bindings shipped with SLF4J depend on <em>slf4j-api.jar</em>
|
|
which must be present on the class path for the binding to
|
|
function properly.</span> </p>
|
|
|
|
<h2>Small applications</h2>
|
|
|
|
<p>Small applications where configuring a fully-fledged
|
|
logging systems can be somewhat of an overkill, can drop in
|
|
<em> <em>slf4j-api.jar+</em>slf4j-simple.jar</em> instead of a binding for a
|
|
fully-fledged logging system. </p>
|
|
|
|
<h2>Libraries</h2>
|
|
|
|
<p>Authors of widely-distributed components and libraries may
|
|
code against the SLF4J interface in order to avoid imposing an
|
|
logging system on the end-user. At deployment
|
|
time, the end-user may choose the desired logging system by inserting the corresponding jar file in her
|
|
classpath. This stupid, simple and robust approach avoids many
|
|
of the painful bugs associated with dynamic discovery
|
|
processes.
|
|
</p>
|
|
|
|
<h2>Simplicity</h2>
|
|
|
|
<p>The SLF4J interfaces and their various adapters are
|
|
extremely simple. Most developers familiar with the Java
|
|
language should be able to read and fully understand the code
|
|
in less than one hour.
|
|
</p>
|
|
|
|
<p>As noted earlier, SLF4J does not rely on any special class
|
|
loader machinery. Every variant of
|
|
<em>slf4j-<impl>.jar</em> is statically hardwired <em>at
|
|
compile time</em> to use one and only specific
|
|
implementation. Thus, SLF4J suffers from none of the <a
|
|
href="http://www.qos.ch/logging/classloader.jsp">class loader
|
|
problems observed when using JCL</a>.</p>
|
|
|
|
<p>Hopefully, the simplicity of the SLF4J interfaces and the
|
|
deployment model will make it easy for developers of other
|
|
logging APIs to conform to the SLF4J model.
|
|
</p>
|
|
|
|
<h2>Built-in support in logback</h2>
|
|
|
|
<p>The <code>ch.qos.logback.classic.Logger</code> class in
|
|
logback directly implements SLF4J's
|
|
<code>org.slf4j.Logger</code> interface.
|
|
</p>
|
|
|
|
<p>Logback's built-in (a.k.a. native) support for SLF4J means
|
|
that the adapter for does not need to wrap logback objects in
|
|
order to make them conform to SLF4J's <code>Logger</code>
|
|
interface. A logback
|
|
<code>ch.qos.logback.classic.Logger</code> <em>is</em> a
|
|
<code>org.slf4j.Logger</code>. Thus, using SLF4J in
|
|
conjunction with logback involves strictly zero memory and
|
|
computational overhead.
|
|
</p>
|
|
|
|
<a name="mdc">
|
|
</a>
|
|
|
|
<h2>Mapped Diagnostic Context (MDC) support</h2>
|
|
|
|
<p>As of version 1.4.1, SLF4J supports MDC, or mapped
|
|
diagnosic context. If the underlying logging system offers MDC
|
|
functionality, then SLF4J will delegate to the underlying
|
|
system's MDC. Note that at this time, only log4j and logback
|
|
offer MDC functionality. If the undelying system does not
|
|
offer MDC, then SLF4J will silently drop MDC information.
|
|
</p>
|
|
|
|
<p>Thus, as a SLF4J user, you can take advantage of MDC
|
|
information in the presence of log4j or logback, but without
|
|
forcing these upon your users as dependencies.
|
|
</p>
|
|
|
|
<p>As of SLF4J version 1.5.0, SLF4J provides MDC support for
|
|
java.util.logging (JDK 1.4 logging) as well.
|
|
</p>
|
|
|
|
<p>For more information on MDC please see the <a
|
|
href="http://logback.qos.ch/manual/mdc.html">chapter on
|
|
MDC</a> in the logback manual.
|
|
|
|
<a name="gradual">
|
|
</a>
|
|
|
|
<h2>Gradual migration to SLF4J from Jakarta Commons Logging
|
|
(JCL)</h2>
|
|
|
|
<h2><em>jcl104-over-slf4j.jar</em></h2>
|
|
|
|
<p>To ease migration to SLF4J from JCL, recent SLF4J
|
|
distributions include the jar file
|
|
<em>jcl104-over-slf4j.jar</em>. This jar file is intended as a
|
|
drop-in replacement for JCL version 1.0.4. It implements the
|
|
public API of JCL but using SLF4J underneath, hence the name
|
|
"JCL over SLF4J."
|
|
</p>
|
|
|
|
<p>Our JCL over SLF4J implementation will allow you to migrate
|
|
to SLF4J gradually, especially if some of the libraries your
|
|
software depends on continue to use JCL for the foreseeable
|
|
future. You can immediately enjoy the benefits of SLF4J's
|
|
reliability and preserve backward compatibility at the same
|
|
time. Just replace <em>commons-logging.jar</em> with
|
|
<em>jcl104-over-slf4j.jar</em>. Subsequently, the selection of
|
|
the underlying logging system will be done by SLF4J instead of
|
|
JCL but without the class loader headaches. The underlying
|
|
logging system can be any of NOP, simple, jdk14 logging, log4j
|
|
or logback. Any existing dependency on commons-logging
|
|
therefore becomes less of an issue.
|
|
</p>
|
|
|
|
<h2><em>slf4j-jcl.jar</em></h2>
|
|
|
|
<p>Some of our users after having switched to SLF4J API
|
|
realize that in some contexts the use of JCL is mandatory and
|
|
their use of SLF4J can be a problem. For this uncommon but
|
|
important case, SLF4J offers a JCL binding, found in the file
|
|
<em>slf4j-jcl.jar</em>. The JCL binding will delegate all
|
|
logging calls made through SLF4J API to JCL. Thus, if for some
|
|
reason an existing application <em>must</em> use JCL, your
|
|
part of that application can still code against the SLF4J API
|
|
in a manner transparent to the larger application
|
|
environment. Your choice of SLF4J API will be invisible to the
|
|
rest of the application which can continue to use JCL.
|
|
</p>
|
|
|
|
<h2><em>jcl104-over-slf4j.jar</em> should not be confused with
|
|
<em>slf4j-jcl.jar</em></h2>
|
|
|
|
|
|
<p>JCL-over-SLF4J, i.e. <em>jcl104-over-slf4j.jar</em>, comes
|
|
in handy in situations where JCL needs to be supported for
|
|
backward compatibility reasons. It can be used to fix problems
|
|
associated with JCL, without necessarily adopting the SLF4J
|
|
API, a decision which can be deferred to a later time.
|
|
</p>
|
|
|
|
<p>On the other hand, <em>slf4j-jcl.jar</em> is useful <strong>after</strong> you have already adopted the SLF4J API for your component
|
|
which needs to be embedded in a larger application environment
|
|
where JCL is a formal requirement. Your software component can
|
|
still use SLF4J API without disrupting the larger
|
|
application. Indeed, <em>slf4j-jcl.jar</em> will delegate all
|
|
logging decisions to JCL so that the dependency on SLF4J API
|
|
by your component will be transparent to the larger whole. </p>
|
|
|
|
<p>Please note that <em>jcl104-over-slf4j.jar</em> and
|
|
<em>slf4j-jcl.jar</em> cannot be deployed at the same
|
|
time. The former jar file will cause JCL to delegate the
|
|
choice of the logging system to SLF4J and the latter jar file
|
|
will cause SLF4J to delegate the choice of the logging system
|
|
to JCL, resulting in an infinite loop.
|
|
</p>
|
|
|
|
<a name="summary"><h2>Executive summary</h2></a>
|
|
|
|
<table class="bodyTable" cellspacing="4" cellpadding="4">
|
|
<tr>
|
|
<th align="left">Advantage</th>
|
|
<th align="left">Description</th>
|
|
</tr>
|
|
|
|
<tr class="a">
|
|
<td>Swappable logging API implementations</td>
|
|
<td>The desired logging API can be plugged in at
|
|
deployment time by inserting the appropriate jar file on
|
|
your classpath.
|
|
</td>
|
|
</tr>
|
|
|
|
|
|
<tr class="b">
|
|
<td>Fail-fast operation</td>
|
|
<td>Assuming the appropriate jar file is available on the
|
|
classpath, under no circumstances will SLF4J cause your
|
|
application to fail. SLF4J's simple and robust design
|
|
ensures that SLF4J never causes exceptions to be thrown.
|
|
|
|
<p>Contrast this with
|
|
<code>LogConfigurationException</code> thrown by JCL which
|
|
will cause your otherwise functioning application to
|
|
fail. JCL-logging will throw a
|
|
<code>LogConfigurationException</code> in case the <a
|
|
href="http://jakarta.apache.org/commons/logging/api/org/apache/commons/logging/Log.html">Log</a>
|
|
interface and its dynamically discovered implementation
|
|
are loaded by different class loaders.
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
|
|
|
|
<tr class="a">
|
|
<td>Adapter implementations for popular logging systems
|
|
</td>
|
|
|
|
<td>SLF4J supports popular logging systems, namely log4j,
|
|
JDK 1.4 logging, Simple logging and NOP. The <a
|
|
href="http://logback.qos.ch">logback</a> project supports
|
|
SLF4J natively. </td>
|
|
|
|
</tr>
|
|
|
|
<tr class="b">
|
|
<td>Easy migration path</td>
|
|
|
|
<td>
|
|
<p>The implementation of JCL over SLF4J, i.e
|
|
<em>jcl104-over-slf4j.jar</em>, will allow your project
|
|
to migrate to SLF4J piecemeal, without breaking
|
|
compatibility with existing software using
|
|
JCL.
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr class="a">
|
|
<td>Support for formated log messages</td>
|
|
|
|
<td>All SLF4J adapters support formated log messages with
|
|
significantly improved performace results.</td>
|
|
</tr>
|
|
|
|
|
|
</table>
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|