mirror of https://github.com/qos-ch/slf4j
- preparing release 1.5.2
- improvements to documentation
This commit is contained in:
Ceki Gulcu
parent
6e328032ef
commit
0fd329eecb
|
|
@ -3,7 +3,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -63,8 +63,8 @@ import org.slf4j.spi.LocationAwareLogger;
|
|||
* Usage:
|
||||
*
|
||||
* <pre>
|
||||
* // once during initialization time of your application
|
||||
* SLF4JHandler.install(handler);
|
||||
* // call only once during initialization time of your application
|
||||
* SLF4JHandler.install();
|
||||
*
|
||||
* // usual pattern: get a Logger and then log a message
|
||||
* java.util.logging.Logger julLogger = java.util.logging.Logger.getLogger("org.wombat");
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
2
pom.xml
2
pom.xml
|
|
@ -5,7 +5,7 @@
|
|||
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
|
||||
<packaging>pom</packaging>
|
||||
<name>SLF4J</name>
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
<parent>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-parent</artifactId>
|
||||
<version>1.5.1</version>
|
||||
<version>1.5.2</version>
|
||||
</parent>
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 38 KiB |
|
|
@ -27,6 +27,7 @@ prefix='';
|
|||
<ul>
|
||||
<li><a href="manual.html">User manual</a></li>
|
||||
<li><a href="faq.html">FAQ</a></li>
|
||||
<li><a href="legacy.html">Bridging legacy APIs</a></li>
|
||||
<li><a href="migrator.html">SLF4J migrator</a></li>
|
||||
<li><a href="log4j-over-slf4j.html">log4j-over-slf4j</a></li>
|
||||
<li><a href="api/index.html">javadocs</a></li>
|
||||
|
|
|
|||
|
|
@ -25,9 +25,10 @@ prefix='';
|
|||
<p>The Simple Logging Facade for Java or (SLF4J) is intended to
|
||||
serve as a simple facade for various logging APIs allowing to the
|
||||
end-user to plug in the desired implementation at
|
||||
<em>deployment</em> time. SLF4J also allows for a <a
|
||||
href="manual.html#gradual">gradual migration path</a> away from
|
||||
Jakarta Commons Logging (JCL).
|
||||
<em>deployment</em> time. SLF4J also supports a <a
|
||||
href="legacy.html">bridging legacy APIs</a> as well as a <a
|
||||
href="migrator.html">source code migration tool</a>.
|
||||
|
||||
</p>
|
||||
|
||||
<p>SLF4J API offers an advanced abstraction of various logging
|
||||
|
|
|
|||
|
|
@ -23,80 +23,10 @@ prefix='';
|
|||
|
||||
<h2>Log4j over SLF4J</h2>
|
||||
|
||||
<p>Recent versions of SLF4J ship with a module called
|
||||
<em>log4j-over-slf4j</em>. It allows log4j users to migrate
|
||||
existing applications to SLF4J without changing <em>a single line
|
||||
of code</em> but simply by replacing the <em>log4j.jar</em> file
|
||||
with <em>log4j-over-slf4j.jar</em>, as described below.
|
||||
</p>
|
||||
|
||||
<h3>How does it work?</h3>
|
||||
|
||||
<p>The log4j-over-slf4j module contains replacements of most
|
||||
widely used log4j classes, namely
|
||||
<code>org.apache.log4j.Category</code>,
|
||||
<code>org.apache.log4j.Logger</code>,
|
||||
<code>org.apache.log4j.Priority</code>,
|
||||
<code>org.apache.log4j.Level</code>,
|
||||
<code>org.apache.log4j.MDC</code>, and
|
||||
<code>org.apache.log4j.BasicConfigurator</code>. These replacement
|
||||
classes redirect all work to their corresponding SLF4J classes.
|
||||
</p>
|
||||
<p>This chapter has been moved <a
|
||||
href="legacy.html#log4j-over-slf4j">elsewhhere</a>.</p>
|
||||
|
||||
<p>To use log4j-over-slf4j in your own application, the first step
|
||||
is to locate and then to replace <em>log4j.jar</em> with
|
||||
<em>log4j-over-slf4j.jar</em>. Note that you still need an SLF4J
|
||||
binding and its dependencies for log4j-over-slf4j to work
|
||||
properly.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In most situtations, replacing a jar file is all it takes in
|
||||
order to migrate from log4j to SLF4J.
|
||||
</p>
|
||||
|
||||
<p>Note that as a result of this migration, log4j configuration
|
||||
files will no longer be picked up. If you need to migrate your
|
||||
log4j.properties file to logback, the <a
|
||||
href="http://logback.qos.ch/translator/">log4j translator</a>
|
||||
might be of help. For configuring logback, please refer to <a
|
||||
href="http://logback.qos.ch/manual/index.html">its manual</a>.
|
||||
</p>
|
||||
|
||||
<p>We are happy to report that several applications are
|
||||
successfully using log4j-over-slf4j in production.
|
||||
</p>
|
||||
|
||||
|
||||
<h3>When does it not work?</h3>
|
||||
|
||||
<p>The <em>log4j-over-slf4j</em> module will not work when the
|
||||
application calls log4j components that are not present in the
|
||||
bridge. For example, direct references to log4j appenders,
|
||||
filters or PropertyConfigurator are not supported by
|
||||
log4j-over-slf4j. While the number of cases where
|
||||
log4j-over-slf4j is insufficient is not completely negligible, in
|
||||
the vast majority of cases where log4j is configured through a
|
||||
configuration file, be it <em>log4j.properties</em> or
|
||||
<em>log4j.xml</em>, log4j-over-slf4j is enough in order to migrate
|
||||
your application to SLF4J.
|
||||
</p>
|
||||
|
||||
<h3>What about the overhead?</h3>
|
||||
|
||||
<p>There overhead of using log4j-over-slf4j instead of log4j
|
||||
directly is relatively small. Given that log4j-over-slf4j
|
||||
immediately delegates all work to SLF4J, the CPU overhead should
|
||||
be negligible, in the order of a few <em>nanoseconds</em>. There
|
||||
is a memory overhead corresponding to an entry in a hashmap per
|
||||
logger, which should be usually acceptable even for very large
|
||||
applications consisting of several thousand loggers. Moreover, if
|
||||
you choose logback as your underlying logging system, and given
|
||||
that logback is both much faster and more memory-efficient than
|
||||
log4j, the gains made by using logback should compensate for the
|
||||
overhead of using log4j-over-slf4j instead of log4j directly.
|
||||
</p>
|
||||
|
||||
|
||||
<script src="templates/footer.js"></script>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -61,36 +61,47 @@ prefix='';
|
|||
|
||||
<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>
|
||||
<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> The figure below illustrates the
|
||||
general idea.
|
||||
</p>
|
||||
|
||||
<p> </p>
|
||||
|
||||
<p><a href="images/bindings.png">
|
||||
<img border="1" src="images/bindings.png" alt="click to enlarge" width="500"/>
|
||||
</a></p>
|
||||
|
||||
<p> </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>
|
||||
<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.
|
||||
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>
|
||||
|
|
@ -131,10 +142,9 @@ prefix='';
|
|||
computational overhead.
|
||||
</p>
|
||||
|
||||
<a name="mdc">
|
||||
</a>
|
||||
|
||||
<h2>Mapped Diagnostic Context (MDC) support</h2>
|
||||
|
||||
<h2><a name="mdc" href="#mdc">Mapped Diagnostic Context (MDC)
|
||||
support</a></h2>
|
||||
|
||||
<p>As of version 1.4.1, SLF4J supports MDC, or mapped
|
||||
diagnosic context. If the underlying logging system offers MDC
|
||||
|
|
@ -156,80 +166,18 @@ prefix='';
|
|||
<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.
|
||||
</p>
|
||||
|
||||
<a name="gradual">
|
||||
</a>
|
||||
<h2><a name="gradual" href="#gradual">Gradual migration to
|
||||
SLF4J from Jakarta Commons Logging (JCL)</a></h2>
|
||||
|
||||
<h2>Gradual migration to SLF4J from Jakarta Commons Logging
|
||||
(JCL)</h2>
|
||||
|
||||
<p>This section has been moved <a
|
||||
href="legacy.html#jcl-over-slf4j">elsewhere</a>.</p>
|
||||
|
||||
<h2><em>jcl-over-slf4j.jar</em></h2>
|
||||
|
||||
<p>To ease migration to SLF4J from JCL, recent SLF4J
|
||||
distributions include the jar file
|
||||
<em>jcl-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>jcl-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>jcl-over-slf4j.jar</em> should not be confused with
|
||||
<em>slf4j-jcl.jar</em></h2>
|
||||
|
||||
|
||||
<p>JCL-over-SLF4J, i.e. <em>jcl-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>jcl-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>
|
||||
<h2><a name="summary" href="#summary">Executive
|
||||
summary</a>
|
||||
</h2>
|
||||
|
||||
<table class="bodyTable" cellspacing="4" cellpadding="4">
|
||||
<tr>
|
||||
|
|
@ -246,7 +194,7 @@ prefix='';
|
|||
</tr>
|
||||
|
||||
|
||||
<tr class="b">
|
||||
<tr class="alt">
|
||||
<td>Fail-fast operation</td>
|
||||
<td>Assuming the appropriate jar file is available on the
|
||||
classpath, under no circumstances will SLF4J cause your
|
||||
|
|
@ -277,19 +225,31 @@ prefix='';
|
|||
|
||||
</tr>
|
||||
|
||||
<tr class="b">
|
||||
<td>Easy migration path</td>
|
||||
<tr class="alt">
|
||||
<td>Bridging legacy logging APIs</td>
|
||||
|
||||
<td>
|
||||
<p>The implementation of JCL over SLF4J, i.e
|
||||
<em>jcl-over-slf4j.jar</em>, will allow your project to
|
||||
migrate to SLF4J piecemeal, without breaking
|
||||
compatibility with existing software using JCL.
|
||||
compatibility with existing software using
|
||||
JCL. Similarly, log4j-over-slf4j.jar and jul-to-slf4j
|
||||
modules will allow you to redirect log4j and
|
||||
respectively java.util.logging calls to SLF4J.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr class="a">
|
||||
<td>Migrate your source code</td>
|
||||
<td>The <a href="migrator.html">slf4j-migrator</a> utility
|
||||
can help you migrate your source to use SLF4J.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
|
||||
|
||||
<tr class="alt">
|
||||
<td>Support for formated log messages</td>
|
||||
|
||||
<td>All SLF4J adapters support formated log messages with
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
|
||||
|
||||
document.write('<p class="footer">')
|
||||
document.write('Copyright © 2004-2007 <a href="http://www.qos.ch/">QOS.ch</a>')
|
||||
document.write('Copyright © 2004-2008 <a href="http://www.qos.ch/">QOS.ch</a>')
|
||||
document.write('</p>')
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 105 KiB After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 38 KiB |
Loading…
Reference in New Issue