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
