[slf4j-dev] svn commit: r1202 - slf4j/trunk/slf4j-site/src/site/pages
ceki at slf4j.org
ceki at slf4j.org
Thu Oct 16 18:59:53 CEST 2008
Author: ceki
Date: Thu Oct 16 18:59:53 2008
New Revision: 1202
Added:
slf4j/trunk/slf4j-site/src/site/pages/legacy.html
Log:
added missing file
Added: slf4j/trunk/slf4j-site/src/site/pages/legacy.html
==============================================================================
--- (empty file)
+++ slf4j/trunk/slf4j-site/src/site/pages/legacy.html Thu Oct 16 18:59:53 2008
@@ -0,0 +1,228 @@
+<!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>Log4j Bridge</title>
+<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+<link rel="stylesheet" type="text/css" media="print" href="css/print.css" />
+
+</head>
+<body>
+ <script>
+prefix='';
+</script>
+
+<script src="templates/header.js"></script>
+<div id="left">
+ <script src="templates/left.js"></script>
+</div>
+<div id="content">
+
+
+ <h1>Bridging legacy APIs</h1>
+
+ <p>Often, some of the components you depend on rely on a logging API
+ other than SLF4J. These components presumably will not switch to
+ SLF4J in the near future. SLF4J ships with several bridging modules
+ which redirect calls to log4j, JCL and j.u.l APIs to behave as if
+ they were made to the SLF4J API. The figure below illustrates the
+ idea.
+ </p>
+
+ <p></p>
+ <p></p>
+
+
+ <p><a href="images/bridging.png">
+ <img src="images/bridging.png" alt="click to enlarge" width="800"/>
+ </a></p>
+
+ <p>
+ </p>
+
+ <h2><a name="jcl-over-slf4j" href="#jcl-over-slf4j">Gradual migration to
+ SLF4J from Jakarta Commons Logging (JCL)</a></h2>
+
+ <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.1.1. 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>
+
+
+ <h2><a name="log4j-over-slf4j" href="#log4j-over-slf4j">Log4j over
+ SLF4J</a></h2>
+
+ <p>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>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>
+
+ <h3>log4j-over-slf4j.jar and slf4j-logj12.jar cannot be present
+ simultaneously
+ </h3>
+
+ <p>The presence of <em>slf4j-logj12.jar</em>, that is the log4j
+ binding for SLF4J, will force all SLF4J calls to be delegated to
+ log4j. The presence of <em>log4j-over-slf4j.jar</em> will in turn
+ delegate all log4j API calls to their SLF4J equivalents. If both are
+ present simulatenously, slf4j calls will be delegated to log4j, and
+ log4j calls redirected to SLF4j, resulting in an endless recursion.
+ </p>
+
+ <h2><a name="jul-to-slf4j" href="jul-to-slf4j">JUL to SLF4J</a></h2>
+
+ <p>The jul-to-slf4j module includes a jul handler, namely
+ SLF4JBridgeHandler, that routes all incoming jul records to the
+ SLF4j API. See also <a
+ href="api/org/slf4j/bridge/SLF4JBridgeHandler.html">SLF4JBridgeHandler
+ javadocs</a>. Contrary to other bridging modules such as
+ jcl-over-slfj and log4j-over-slf4h, which re-implement JCL and
+ respectively log4j, the jul-to-slf4j modules does not re-implement
+ the java.util.logging package because packages under the java.*
+ namespace cannot be replaced.
+ </p>
+
+ <h3>jul-to-slf4j.jar and slf4j-jdk14.jar cannot be present
+ simultaneously
+ </h3>
+
+ <p>The presence of slf4j-jdk14.jar, that is the jul binding for
+ SLF4J, will force SLF4J calls to be delegated to jul. On the other
+ hand, the presence of jul-to-slf4j.jar, plus the installation of
+ SLF4JBridgeHandler, by invoking "SLF4JBridgeHandler.install()" will
+ route jul records to SLF4J. Thus, if both jar are present
+ simultanesouly (and SLF4JBridgeHandler is installed), slf4j calls
+ will be delegated to jul and jul records will be routed to SLF4J,
+ resulting in an endless recursion.
+ </p>
+
+
+<script
+ src="templates/footer.js"></script> </div> </body> </html>
More information about the slf4j-dev
mailing list