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