Home | History | Annotate | Download | only in pages
      1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
      2   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
      3 <html xmlns="http://www.w3.org/1999/xhtml">
      4 <head>
      5   <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
      6   <title>Log4j Bridge</title>
      7   <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
      8   <link rel="stylesheet" type="text/css" media="print" href="css/print.css" />
      9   
     10 </head>
     11 
     12 <body onload="decorate();">
     13   <script type="text/javascript">prefix='';</script>
     14 
     15   <script type="text/javascript" src="templates/header.js"></script>
     16   <script type="text/javascript" src="js/jquery-min.js"></script>
     17   <script type="text/javascript" src="js/decorator.js"></script>
     18 
     19   <div id="left">
     20     <script src="templates/left.js" type="text/javascript"></script>
     21   </div>
     22   <div id="content">
     23 	
     24 
     25     <h2>Bridging legacy APIs</h2>
     26     
     27     <p>Often, some of the components you depend on rely on a logging
     28     API other than SLF4J. You may also assume that these components
     29     will not switch to SLF4J in the immediate future. To deal with
     30     such circumstances, SLF4J ships with several bridging modules
     31     which redirect calls made to log4j, JCL and java.util.logging APIs
     32     to behave as if they were made to the SLF4J API instead. The
     33     figure below illustrates the idea.
     34     </p>
     35 
     36     <p>Please note that for source code under your control, you really
     37     should use the <a href="migrator.html">slf4j-migrator</a>. The
     38     binary-based solutions described in this page are appropriate for
     39     software beyond your control.
     40     </p>
     41 
     42     <p></p>
     43     <p></p>
     44     
     45     
     46     <p><a href="images/legacy.png">
     47     <img src="images/legacy.png" alt="click to enlarge" width="800"/>
     48     </a></p>
     49     
     50     <p>
     51     </p>
     52     
     53     <h2 class="doAnchor" name="jcl-over-slf4j">Gradual migration to
     54     SLF4J from Jakarta Commons Logging (JCL)</h2>
     55     
     56     <h4 class="doAnchor" name="jclOverSLF4J"><em>jcl-over-slf4j.jar</em></h4>
     57     
     58     <p>To ease migration to SLF4J from JCL, SLF4J distributions
     59     include the jar file <em>jcl-over-slf4j.jar</em>. This jar file is
     60     intended as a drop-in replacement for JCL version 1.1.1. It
     61     implements the public API of JCL but using SLF4J underneath, hence
     62     the name "JCL over SLF4J."
     63     </p>
     64     
     65     <p>Our JCL over SLF4J implementation will allow you to migrate to
     66     SLF4J gradually, especially if some of the libraries your software
     67     depends on continue to use JCL for the foreseeable future. You can
     68     immediately enjoy the benefits of SLF4J's reliability and preserve
     69     backward compatibility at the same time. Just replace
     70     <em>commons-logging.jar</em> with
     71     <em>jcl-over-slf4j.jar</em>. Subsequently, the selection of the
     72     underlying logging framework will be done by SLF4J instead of JCL
     73     <a href="http://articles.qos.ch/classloader.html">but without the
     74     class loader headaches plaguing JCL</a>. The underlying logging
     75     framework can be any of the frameworks supported by SLF4J. Often
     76     times, replacing <em>commons-logging.jar</em> with
     77     <em>jcl-over-slf4j.jar</em> will immediately and permanently solve
     78     class loader issues related to commons logging.
     79     </p>
     80     
     81     <h3  class="doAnchor" name="slf4jJCL"><em>slf4j-jcl.jar</em></h3>
     82     
     83     <p>Some of our users after having switched to SLF4J API realize that
     84     in some contexts the use of JCL is mandatory and their use of SLF4J
     85     can be a problem. For this uncommon but important case, SLF4J offers
     86     a JCL binding, found in the file <em>slf4j-jcl.jar</em>. The JCL
     87     binding will delegate all logging calls made through SLF4J API to
     88     JCL. Thus, if for some reason an existing application <em>must</em>
     89     use JCL, your part of that application can still code against the
     90     SLF4J API in a manner transparent to the larger application
     91     environment. Your choice of SLF4J API will be invisible to the rest
     92     of the application which can continue to use JCL.
     93     </p>
     94     
     95     <h3 class="doAnchor"
     96     name="jclRecursion"><em>jcl-over-slf4j.jar</em> should not be
     97     confused with <em>slf4j-jcl.jar</em></h3>
     98     
     99     
    100     <p>JCL-over-SLF4J, i.e. <em>jcl-over-slf4j.jar</em>, comes in handy
    101     in situations where JCL needs to be supported for backward
    102     compatibility reasons. It can be used to fix problems associated
    103     with JCL, without necessarily adopting the SLF4J API, a decision
    104     which can be deferred to a later time.
    105     </p>
    106     
    107     <p>On the other hand, <em>slf4j-jcl.jar</em> is useful
    108     <strong>after</strong> you have already adopted the SLF4J API for
    109     your component which needs to be embedded in a larger application
    110     environment where JCL is a formal requirement. Your software
    111     component can still use SLF4J API without disrupting the larger
    112     application. Indeed, <em>slf4j-jcl.jar</em> will delegate all
    113     logging decisions to JCL so that the dependency on SLF4J API by your
    114     component will be transparent to the larger whole.
    115     </p>
    116     
    117     <p>Please note that <em>jcl-over-slf4j.jar</em> and
    118     <em>slf4j-jcl.jar</em> cannot be deployed at the same time. The
    119     former jar file will cause JCL to delegate the choice of the
    120     logging system to SLF4J and the latter jar file will cause SLF4J
    121     to delegate the choice of the logging system to JCL, resulting in
    122     an <a href="codes.html#jclDelegationLoop">infinite loop</a>.
    123     </p>
    124     
    125     
    126     <h2 class="doAnchor" name="log4j-over-slf4j">log4j-over-slf4j</h2>
    127     
    128     <p>SLF4J ship with a module called <em>log4j-over-slf4j</em>.  It
    129     allows log4j users to migrate existing applications to SLF4J without
    130     changing <em>a single line of code</em> but simply by replacing the
    131     <em>log4j.jar</em> file with <em>log4j-over-slf4j.jar</em>, as
    132     described below.
    133     </p>
    134     
    135     <h4 class="doAnchor" name="losHow">How does it work?</h4>
    136     
    137     <p>The log4j-over-slf4j module contains replacements of most widely
    138     used log4j classes, namely <code>org.apache.log4j.Category</code>,
    139     <code>org.apache.log4j.Logger</code>,
    140     <code>org.apache.log4j.Priority</code>,
    141     <code>org.apache.log4j.Level</code>,
    142     <code>org.apache.log4j.MDC</code>, and
    143     <code>org.apache.log4j.BasicConfigurator</code>. These replacement
    144     classes redirect all work to their corresponding SLF4J classes.
    145     </p>
    146     
    147     <p>To use log4j-over-slf4j in your own application, the first step
    148     is to locate and then to replace <em>log4j.jar</em> with
    149     <em>log4j-over-slf4j.jar</em>. Note that you still need an SLF4J
    150     binding and its dependencies for log4j-over-slf4j to work properly.
    151     </p>
    152     
    153     <p>In most situations, replacing a jar file is all it takes in
    154     order to migrate from log4j to SLF4J.
    155     </p>
    156 
    157     <p>Note that as a result of this migration, log4j configuration
    158     files will no longer be picked up. If you need to migrate your
    159     log4j.properties file to logback, the <a
    160     href="http://logback.qos.ch/translator/">log4j translator</a> might
    161     be of help. For configuring logback, please refer to <a
    162     href="http://logback.qos.ch/manual/index.html">its manual</a>.
    163     </p>
    164     
    165     <h4 class="doAnchor" name="losFail">When does it not work?</h4>
    166     
    167     <p>The <em>log4j-over-slf4j</em> module will not work when the
    168     application calls log4j components that are not present in the
    169     bridge.  For example, when application code directly references
    170     log4j appenders, filters or the PropertyConfigurator, then
    171     log4j-over-slf4j would be an insufficient replacement for
    172     log4j. However, when log4j is configured through a configuration
    173     file, be it <em>log4j.properties</em> or <em>log4j.xml</em>, the
    174     log4j-over-slf4j module should just work fine.
    175     </p>
    176 
    177     
    178     
    179     <h4 class="doAnchor" name="losOverhead">What about the
    180     overhead?</h4>
    181     
    182     <p>There overhead of using log4j-over-slf4j instead of log4j
    183     directly is relatively small. Given that log4j-over-slf4j
    184     immediately delegates all work to SLF4J, the CPU overhead should be
    185     negligible, in the order of a few <em>nanoseconds</em>. There is a
    186     memory overhead corresponding to an entry in a hashmap per logger,
    187     which should be usually acceptable even for very large applications
    188     consisting of several thousand loggers.  Moreover, if you choose
    189     logback as your underlying logging system, and given that logback is
    190     both much faster and more memory-efficient than log4j, the gains
    191     made by using logback should compensate for the overhead of using
    192     log4j-over-slf4j instead of log4j directly.
    193     </p>
    194     
    195     <h4 class="doAnchor" name="log4jRecursion">log4j-over-slf4j.jar
    196     and slf4j-log4j12.jar cannot be present simultaneously
    197     </h4>
    198     
    199     <p>The presence of <em>slf4j-log4j12.jar</em>, that is the log4j
    200     binding for SLF4J, will force all SLF4J calls to be delegated to
    201     log4j. The presence of <em>log4j-over-slf4j.jar</em> will in turn
    202     delegate all log4j API calls to their SLF4J equivalents. If both
    203     are present simultaneously, slf4j calls will be delegated to
    204     log4j, and log4j calls redirected to SLF4j, resulting in an <a
    205     href="codes.html#log4jDelegationLoop">endless loop</a>.
    206     </p>
    207 
    208 
    209     
    210     <h2 class="doAnchor" name="jul-to-slf4j">jul-to-slf4j bridge</h2>
    211     
    212     <p>The jul-to-slf4j module includes a java.util.logging (jul)
    213     handler, namely <code>SLF4JBridgeHandler</code>, which routes all
    214     incoming jul records to the SLF4j API. Please see <a
    215     href="api/org/slf4j/bridge/SLF4JBridgeHandler.html">SLF4JBridgeHandler
    216     javadocs</a> for usage instructions.
    217     </p>
    218 
    219     <p><span class="label notice">Note on performance</span> Contrary
    220     to other bridging modules, namely jcl-over-slf4j and
    221     log4j-over-slf4j, which reimplement JCL and respectively log4j,
    222     the jul-to-slf4j module does not reimplement the java.util.logging
    223     because packages under the java.* namespace cannot be
    224     replaced. Instead, jul-to-slf4j translates <a
    225     href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/logging/LogRecord.html?is-external=true">LogRecord</a>
    226     objects into their SLF4J equivalent.  Please note this translation
    227     process incurs the cost of constructing a <code>LogRecord</code>
    228     instance regardless of whether the SLF4J logger is disabled for
    229     the given level or nor. <b>Consequently, j.u.l. to SLF4J
    230     translation can seriously increase the cost of disabled logging
    231     statements (60 fold or 6000%) and measurably impact the
    232     performance of enabled log statements (20% overall increase).</b>
    233     As of logback version 0.9.25, it is possible to completely
    234     eliminate the 60 fold translation overhead for disabled log
    235     statements with the help of <a
    236     href="http://logback.qos.ch/manual/configuration.html#LevelChangePropagator">LevelChangePropagator</a>.
    237     </p>
    238 
    239     <p>If you are concerned about application performance, then use of
    240     <code>SLF4JBridgeHandler</code> is appropriate only if any one of
    241     the following two conditions is true:
    242     </p>
    243     <ol>
    244       <li>few j.u.l. logging statements are in play </li>
    245       <li><code>LevelChangePropagator</code> has been installed</li>
    246     </ol>
    247     
    248     
    249     <h4 class="doAnchor" name="julRecursion">jul-to-slf4j.jar and slf4j-jdk14.jar cannot be present
    250     simultaneously
    251     </h4>
    252     
    253     <p>The presence of slf4j-jdk14.jar, that is the jul binding for
    254     SLF4J, will force SLF4J calls to be delegated to jul. On the other
    255     hand, the presence of jul-to-slf4j.jar, plus the installation of
    256     SLF4JBridgeHandler, by invoking "SLF4JBridgeHandler.install()" will
    257     route jul records to SLF4J. Thus, if both jar are present
    258     simultaneously (and SLF4JBridgeHandler is installed), slf4j calls
    259     will be delegated to jul and jul records will be routed to SLF4J,
    260     resulting in an endless loop.
    261     </p> 
    262     
    263 
    264     <script  src="templates/footer.js" type="text/javascript"></script> 
    265   </div> 
    266 </body> 
    267 </html>
    268