Author: seb Date: Fri Jul 28 15:07:16 2006 New Revision: 380 Added: logback/classic/trunk/src/main/java/ch/qos/logback/classic/examples/ logback/classic/trunk/src/main/java/ch/qos/logback/classic/examples/BabySteps1.java logback/classic/trunk/src/main/java/ch/qos/logback/classic/examples/BabySteps2.java logback/classic/trunk/src/main/java/ch/qos/logback/classic/examples/BabySteps3.java Modified: logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml Log: added the first baby steps to the intro, with associated classes Added: logback/classic/trunk/src/main/java/ch/qos/logback/classic/examples/BabySteps1.java ============================================================================== --- (empty file) +++ logback/classic/trunk/src/main/java/ch/qos/logback/classic/examples/BabySteps1.java Fri Jul 28 15:07:16 2006 @@ -0,0 +1,15 @@ +package ch.qos.logback.classic.examples; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +public class BabySteps1 { + + final static Logger logger = LoggerFactory.getLogger(BabySteps1.class); + + public static void main(String[] args) { + + logger.debug("Hello world."); + + } +} Added: logback/classic/trunk/src/main/java/ch/qos/logback/classic/examples/BabySteps2.java ============================================================================== --- (empty file) +++ logback/classic/trunk/src/main/java/ch/qos/logback/classic/examples/BabySteps2.java Fri Jul 28 15:07:16 2006 @@ -0,0 +1,18 @@ +package ch.qos.logback.classic.examples; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import ch.qos.logback.classic.util.LoggerStatusPrinter; + +public class BabySteps2 { + + final static Logger logger = LoggerFactory.getLogger(BabySteps1.class); + + public static void main(String[] args) { + + logger.debug("Hello world."); + LoggerStatusPrinter.printStatusInDefaultContext(); + + } +} Added: logback/classic/trunk/src/main/java/ch/qos/logback/classic/examples/BabySteps3.java ============================================================================== --- (empty file) +++ logback/classic/trunk/src/main/java/ch/qos/logback/classic/examples/BabySteps3.java Fri Jul 28 15:07:16 2006 @@ -0,0 +1,20 @@ +package ch.qos.logback.classic.examples; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import ch.qos.logback.BasicConfigurator; +import ch.qos.logback.classic.util.LoggerStatusPrinter; + +public class BabySteps3 { + + final static Logger logger = LoggerFactory.getLogger(BabySteps1.class); + + public static void main(String[] args) { + + BasicConfigurator.configureDefaultContext(); + logger.debug("Hello world."); + LoggerStatusPrinter.printStatusInDefaultContext(); + + } +} Modified: logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml ============================================================================== --- logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml (original) +++ logback/classic/trunk/src/site/xdocTemplates/shortIntro.xml Fri Jul 28 15:07:16 2006 @@ -1,4 +1,13 @@ <document> + <!-- + + Warning: do not use any auto-format function on this file. + Since "source" divs use pre as white-space, it affects the + look of the code parts in this document. + + --> + + <body> <div class="section"> <h2>Short introduction</h2> @@ -7,27 +16,34 @@ Authors: Ceki Gülcü, Sébastien Pennec </div> - - <table> - <tr> - <td valign="top" align="top"> - <a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/2.5/"> - <img alt="Creative Commons License" border="0" valign="top" align="top" - src="http://creativecommons.org/images/public/somerights20.png"/> - </a> - </td> - <td> - <p>Copyright © 2000-2006, QOS.ch </p> - - <p>This work is licensed under a <a rel="license" - href="http://creativecommons.org/licenses/by-nc-nd/2.5/">Creative - Commons Attribution-Noncommercial-No Derivative Works 2.5 - License</a>. - </p> - </td> - </tr> - </table> - + + <table> + <tr> + <td valign="top" align="top"> + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-nd/2.5/"> + <img alt="Creative Commons License" border="0" + valign="top" align="top" + src="http://creativecommons.org/images/public/somerights20.png" /> + </a> + </td> + <td> + <p>Copyright © 2000-2006, QOS.ch</p> + + <p> + This work is licensed under a + <a rel="license" + href="http://creativecommons.org/licenses/by-nc-nd/2.5/"> + Creative Commons + Attribution-Noncommercial-No Derivative + Works 2.5 License + </a> + . + </p> + </td> + </tr> + </table> + <div class="section"> <h2>Introduction</h2> </div> @@ -47,25 +63,6 @@ back as far as 1999. </p> <p> - Logback's basic architecture is sufficiently generic so as - to apply under different circumstances. At present time, - logback is divided into three modules, Core, Classic and - Access. - </p> - <p> - The Core module lays the groundwork for the other two - modules. The Classic module can be assimilated to an - improved version of log4j. Logback Classic natively - implements the - <a href="http://www.slf4j.org">SLF4J API</a> - so that you can readily switch back and forth between - logback and other logging systems such as log4j or JDK14 - Logging. The Access module integrates with Servlet - containers to provide HTPP-access log functionality. Note - that you can easily build your own modules on top of the - Core module. - </p> - <p> Before rushing to install and configure logback classic on your own application, here is a presentation of how things work. @@ -98,6 +95,150 @@ </div> <div class="section"> + <h2>First Baby Steps</h2> + </div> + <p> + After you have added the logback classic jar to your classpath, + you can test a small program that uses its functionalities. + </p> + +<div class="source"> +package ch.qos.logback.classic.examples; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +public class BabySteps1 { + + final static Logger logger = LoggerFactory.getLogger(BabySteps1.class); + + public static void main(String[] args) { + + logger.debug("Hello world."); + + } +} +</div> + <p> + This is the basic, yet usual way of using logback classic. + It starts by importing the Logger and LoggerFactory from SLF4J. + You will note that, for the sake of compatibility with SLF4J and + implementation-freedom, no actual reference to any of the logback + classic classes is required. + You only import and use SLF4J classes for usual logging. + </p> + <p> + Then a static variable gets a Logger that is initialised with the + <code>BabySteps.class</code>. + The main method then invokes the debug method of the received Logger. + It gives the method a simple String with the message to log. + Put differently, the main method contains a logging statement of + level debug containing the message “Hello world”. + </p> + <p> + You can compile and run this class as follows: + </p> + <div class="source">java ch.qos.logback.classic.examples.BabySteps1</div> + <p> + This will not produce any logging output. What happened? + Well, a powerful tool in logback is the Status and associated classes. + It keeps track of any events of importance that happen during the use + of logback. A simple statement can help us see why nothing was logged: + </p> +<div class="source"> +package ch.qos.logback.classic.examples; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import ch.qos.logback.classic.util.LoggerStatusPrinter; + +public class BabySteps2 { + + final static Logger logger = LoggerFactory.getLogger(BabySteps1.class); + + public static void main(String[] args) { + + logger.debug("Hello world."); + LoggerStatusPrinter.printStatusInDefaultContext(); + + } +} +</div> + <p> + The LoggerStatusPrinter will print whatever Statuses were sent to the + StatusManager. Running again the class with the new statement will + output to the console the next lines: + </p> +<div class="source"> +ERROR in Logger[ch.qos.logback.classic.examples.BabySteps2] - No appenders present \\ +in the hierarchy [default] for logger [ch.qos.logback.classic.examples.BabySteps2]. +</div> + <p> + We now know why nothing was logged: no Appenders are configured. + An Appender is a class that can be seen as an output destination. + Appenders exist for many different destinations including the console, + files, and many more. Users can also easily create their own Appenders + for any specific situation. + </p> + <p> + Configuring logback classic can be done a different ways. + The simplest but less flexible way is by calling the <code>BasicConfigurator</code> + class, like in the following code snippet. + </p> +<div class="source"> +package ch.qos.logback.classic.examples; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import ch.qos.logback.BasicConfigurator; +import ch.qos.logback.classic.util.LoggerStatusPrinter; + +public class BabySteps3 { + + final static Logger logger = LoggerFactory.getLogger(BabySteps1.class); + + public static void main(String[] args) { + + BasicConfigurator.configureDefaultContext(); + logger.debug("Hello world."); + LoggerStatusPrinter.printStatusInDefaultContext(); + + } +} +</div> + <p> + Let’s run the BabySteps class again. Now, the BasicConfigurator will create + a simple console Appender. The logging request will then be propagated to + the Appender and the console will output the following: + </p> +<div class="source"> +Hello world. +This status manager contains no errors. +</div> + <p> + This example is very simple. However, actual logging in a bigger + application is not much more complicated. The logging statement will barely + change. Only the configuration process will be different, since you don't + need (nor should) configure the logging context in each and every class that + will require logging. As well, the LoggerStatusPrinter will certainly not be + used after all the logging statements. + </p> + <p> + These are the three steps that are required to allow full logging in any application. + </p> + <ol> + <li>Configure the logback classic environment. You can do it using several + sophisticated ways. The BasicConfigurator is the simplest but also least flexible.</li> + <li>In every class where you wish to perform logging, retrieve a Logger + instance by invoking the LoggerFactory and passing the current class as the parameter.</li> + <li>Use this logger instance by invoking its printing methods, namely + the debug(), info() and error() methods. This will produce logging on the + configured devices.</li> + </ol> + + <div class="section"> <h2>Logger, Appenders and Layouts</h2> </div> <p> @@ -141,48 +282,51 @@ </div> <p> - For example, the logger named <code>"com.foo"</code> is a parent - of the logger named <code>"com.foo.Bar"</code> . Similarly, - <code>"java"</code> is a parent of <code>"java.util"</code> and - an ancestor of <code>"java.util.Vector"</code> . This naming - scheme should be familiar to most developers. + For example, the logger named + <code>"com.foo"</code> + is a parent of the logger named + <code>"com.foo.Bar"</code> + . Similarly, + <code>"java"</code> + is a parent of + <code>"java.util"</code> + and an ancestor of + <code>"java.util.Vector"</code> + . This naming scheme should be familiar to most developers. </p> <p> The root logger resides at the top of the logger hierarchy. - It is exceptional in two ways: + It is exceptional in a way that is always exists. Like every + logger, it can be retrieved by its name, like this: </p> - <ol> - <li>it always exists,</li> - <li>it cannot be retrieved by name.</li> - </ol> + <div class="source">Logger rootLogger = LoggerFactory.getLogger("root");</div> + + <p> + All other loggers are retrieved with the class static + LoggerFactory.getLogger method. This method takes the name + of the desired logger as a parameter. Some of the basic + methods in the Logger interface are listed below. + </p> + + <div class="source">package org.slf4j; public interface Logger { + +// Creation and retrieval method: +public static LoggergetLogger(String name); - <p>All other loggers are retrieved with the class static - LoggerFactory.getLogger method. This method takes the name of - the desired logger as a parameter. Some of the basic methods in - the Logger interface are listed below. - </p> - - <div class="source">package org.slf4j; - -public interface Logger { - - // Creation and retrieval method: - public static Logger getLogger(String name); - - // printing methods: - public void debug(Object message); - public void info(Object message); - public void warn(Object message); - public void error(Object message); - public void fatal(Object message); +// Printing methods: +public void debug(Object message); +public void info(Object message); +public void warn(Object message); +public void error(Object message); +public void fatal(Object message); }</div> - - <p> - Loggers may be assigned levels. The set of possible levels, that - is DEBUG, INFO, WARN and ERROR are defined in the - org.apache.log4j.Level class. The level class cannot be - sub-classed as a much better approach exist in the form of - Marker objects. + + <p> + Loggers may be assigned levels. The set of possible levels, + that is DEBUG, INFO, WARN and ERROR are defined in the + ch.qos.logback.classic.Level class. The level class cannot + be sub-classed as a much better approach exist in the form + of Marker objects. </p> <p> @@ -194,10 +338,13 @@ <div class="definition"> <div class="deftitle">Level Inheritance</div> <p> - The inherited level for a given logger <em>L</em>, is equal to - the first non-null level in the logger hierarchy, starting at - <em>L</em> and proceeding upwards in the hierarchy towards the - root logger. + The inherited level for a given logger + <em>L</em> + , is equal to the first non-null level in the logger + hierarchy, starting at + <em>L</em> + and proceeding upwards in the hierarchy towards the root + logger. </p> </div> <p> @@ -412,13 +559,22 @@ </table> <p> - In example 4, the loggers <code>root</code> and <code>X</code> - and are assigned the levels <code>Proot</code> and + In example 4, the loggers + <code>root</code> + and + <code>X</code> + and are assigned the levels + <code>Proot</code> + and <code>Px</code> - respectively. The loggers <code>X.Y</code> and - <code>X.Y.Z</code> inherits their level value from their nearest - parent <code>X</code> having an assigned level. + respectively. The loggers + <code>X.Y</code> + and + <code>X.Y.Z</code> + inherits their level value from their nearest parent + <code>X</code> + having an assigned level. </p> <p> @@ -429,16 +585,20 @@ <p> By definition, the printing method determines the level of a - logging request. For example, if <code>c</code> is a logger - instance, then the statement <code>c.info("..")</code> is a - logging request of level INFO. + logging request. For example, if + <code>L</code> + is a logger instance, then the statement + <code>L.info("..")</code> + is a logging request of level INFO. </p> <p> - A logging request is said to be <em>enabled</em> if its level is - higher than or equal to the level of its logger. Otherwise, the - request is said to be <em>disabled</em>. A logger without an - assigned level will inherit one from the hierarchy. This rule is - summarized below. + A logging request is said to be + <em>enabled</em> + if its level is higher than or equal to the level of its + logger. Otherwise, the request is said to be + <em>disabled</em> + . A logger without an assigned level will inherit one from + the hierarchy. This rule is summarized below. </p> <div class="definition"> <div class="deftitle">Basic Selection Rule</div> @@ -464,26 +624,25 @@ </p> <p>Here is an example of this rule.</p> - <div class="source">// get a logger instance named "com.foo", with an <span class="blue">INFO</span> level. - Logger logger = LoggerFactory.getLogger("com.foo"); - - Logger barlogger = LoggerFactory.getLogger("com.foo.Bar"); - - // This request is enabled, because <span class="green">WARN</span> >= <span class="blue">INFO</span> - logger.<span class="green">warn</span>("Low fuel level."); - - - // This request is disabled, because <span class="green">DEBUG</span> < <span class="blue">INFO</span>. - logger.<span class="green">debug</span>("Starting search for nearest gas station."); - // The logger instance barlogger, named "com.foo.Bar", - // will inherit its level from the logger named - // "com.foo" Thus, the following request is enabled - // because <span class="green">INFO</span> >= <span class="blue">INFO</span>. - barlogger.<span class="green">info</span>("Located nearest gas station."); - - // This request is disabled, because <span class="green">DEBUG</span> < <span class="blue">INFO</span>. - barlogger.<span class="green">debug</span>("Exiting gas station search"); - </div> + <div class="source">// get a logger instance named "com.foo", with an <span class="blue">INFO</span>level. +Logger logger = LoggerFactory.getLogger("com.foo"); +Logger barlogger = LoggerFactory.getLogger("com.foo.Bar"); + +// This request is enabled, because <span class="green">WARN</span> >= <span class="blue">INFO</span> +logger.<span class="green">warn</span>("Low fuel level."); + +// This request is disabled, because <span class="green">DEBUG</span> < <span class="blue">INFO</span>. +logger.<span class="green">debug</span>("Starting search for nearest gas station."); + +// The logger instance barlogger, named "com.foo.Bar", +// will inherit its level from the logger named +// "com.foo" Thus, the following request is enabled +// because <span class="green">INFO</span> >= <span class="blue">INFO</span>. +barlogger.<span class="green">info</span>("Located nearest gas station."); + +// This request is disabled, because<span class="green">DEBUG</span> < <span class="blue">INFO</span>. +barlogger.<span class="green">debug</span>("Exiting gas station search"); +</div> <p> Calling the @@ -493,21 +652,27 @@ </p> <p>For example, in</p> - <div class="source">Logger x = LoggerFactory.getLogger("wombat"); + <div class="source">Logger x = LoggerFactory.getLogger("wombat"); Logger y = LoggerFactory.getLogger("wombat");</div> - <p><code>x</code> and <code>y</code> refer to <em>exactly</em> the - same logger object. - </p> + <p> + <code>x</code> + and + <code>y</code> + refer to + <em>exactly</em> + the same logger object. + </p> <p> - Thus, it is possible to configure a logger and then to retrieve - the same instance somewhere else in the code without passing - around references. In fundamental contradiction to biological - parenthood, where parents always preceed their children, logback - classic loggers can be created and configured in any order. In - particular, a "parent" logger will find and link to its - descendants even if it is instantiated after them. + Thus, it is possible to configure a logger and then to + retrieve the same instance somewhere else in the code + without passing around references. In fundamental + contradiction to biological parenthood, where parents always + preceed their children, logback classic loggers can be + created and configured in any order. In particular, a + "parent" logger will find and link to its descendants even + if it is instantiated after them. </p> <p> Configuration of the logback environment is typically done @@ -516,16 +681,18 @@ discussed shortly. </p> <p> - Logback makes it easy to name loggers by <em>software - component</em>. This can be accomplished by statically - instantiating a logger in each class, with the logger name equal - to the fully qualified name of the class. This is a useful and - straightforward method of defining loggers. As the log output - bears the name of the generating logger, this naming strategy - makes it easy to identify the origin of a log message. However, - this is only one possible, albeit common, strategy for naming - loggers. Logback does not restrict the possible set of - loggers. The developer is free to name the loggers as desired. + Logback makes it easy to name loggers by + <em>software component</em> + . This can be accomplished by statically instantiating a + logger in each class, with the logger name equal to the + fully qualified name of the class. This is a useful and + straightforward method of defining loggers. As the log + output bears the name of the generating logger, this naming + strategy makes it easy to identify the origin of a log + message. However, this is only one possible, albeit common, + strategy for naming loggers. Logback does not restrict the + possible set of loggers. The developer is free to name the + loggers as desired. </p> <p> Nevertheless, naming loggers after the class where they are @@ -536,29 +703,36 @@ <h3>Appenders and Layouts</h3> </div> - <p> The ability to selectively enable or disable logging requests - based on their logger is only part of the picture. Logback allows - logging requests to print to multiple destinations. In logback - speak, an output destination is called an appender. Currently, - appenders exist for the console, files, remote socket servers, - JMS, and remote UNIX Syslog daemons. It is also possible to log - asynchronously. + <p> + The ability to selectively enable or disable logging + requests based on their logger is only part of the picture. + Logback allows logging requests to print to multiple + destinations. In logback speak, an output destination is + called an appender. Currently, appenders exist for the + console, files, remote socket servers, JMS, and remote UNIX + Syslog daemons. It is also possible to log asynchronously. </p> <p>More than one appender can be attached to a logger.</p> <p> - The addAppender method adds an appender to a given logger. Each - enabled logging request for a given logger will be forwarded to - all the appenders in that logger as well as the appenders higher - in the hierarchy. In other words, appenders are inherited - additively from the logger hierarchy. For example, if a console - appender is added to the root logger, then all enabled logging - requests will at least print on the console. If in addition a - file appender is added to a logger, say <em>L</em>, then enabled - logging requests for <em>L</em> and <em>L</em>'s children will - print on a file and on the console. It is possible to override - this default behavior so that appender accumulation is no longer - additive by setting the additivity flag to false. + The addAppender method adds an appender to a given logger. + Each enabled logging request for a given logger will be + forwarded to all the appenders in that logger as well as the + appenders higher in the hierarchy. In other words, appenders + are inherited additively from the logger hierarchy. For + example, if a console appender is added to the root logger, + then all enabled logging requests will at least print on the + console. If in addition a file appender is added to a + logger, say + <em>L</em> + , then enabled logging requests for + <em>L</em> + and + <em>L</em> + 's children will print on a file and on the console. It is + possible to override this default behavior so that appender + accumulation is no longer additive by setting the additivity + flag to false. </p> <p> @@ -568,22 +742,35 @@ <div class="definition"> <div class="deftitle">Appender Additivity</div> - - <p> - The output of a log statement of logger <em>L</em> will go to - all the appenders in <em>L</em> and its ancestors. This is the - meaning of the term "appender additivity". + + <p> + The output of a log statement of logger + <em>L</em> + will go to all the appenders in + <em>L</em> + and its ancestors. This is the meaning of the term + "appender additivity". </p> - <p> However, if an ancestor of logger <em>L</em> , say - <em>P</em>, has the additivity flag set to false, then - <em>L</em>'s output will be directed to all the appenders in - <em>L</em> and it's ancestors upto and including <em>P</em> but - not the appenders in any of the ancestors of <em>P</em> . + <p> + However, if an ancestor of logger + <em>L</em> + , say + <em>P</em> + , has the additivity flag set to false, then + <em>L</em> + 's output will be directed to all the appenders in + <em>L</em> + and it's ancestors upto and including + <em>P</em> + but not the appenders in any of the ancestors of + <em>P</em> + . </p> <p> - Loggers have their additivity flag set to true by default. + Loggers have their additivity flag set to true by + default. </p> </div> @@ -657,15 +844,19 @@ <p> - More often than not, users wish to customize not only the output - destination but also the output format. This is accomplished by - associating a <em>layout</em> with an appender. The layout is - responsible for formatting the logging request according to the - user's wishes, whereas an appender takes care of sending the - formatted output to its destination. The PatternLayout, part of - the standard logback distribution, lets the user specify the - output format according to conversion patterns similar to the C - language <code>printf</code> function. + More often than not, users wish to customize not only the + output destination but also the output format. This is + accomplished by associating a + <em>layout</em> + with an appender. The layout is responsible for formatting + the logging request according to the user's wishes, whereas + an appender takes care of sending the formatted output to + its destination. The PatternLayout, part of the standard + logback distribution, lets the user specify the output + format according to conversion patterns similar to the C + language + <code>printf</code> + function. </p> <p> @@ -673,9 +864,7 @@ "%r [%t] %-5p %c - %m%n" will output something akin to: </p> - <div class="source"> - 176 [main] INFO org.foo.Bar - Located nearest gas station. - </div> + <div class="source">176 [main] INFO org.foo.Bar - Located nearest gas station.</div> <p> The first field is the number of milliseconds elapsed since @@ -690,45 +879,53 @@ <p> If you are a SLF4J user (if not, you should be...), you'll - notice that the methods used to request logging do not only take - a String as a parameter. Some methods allow more sophisticated - parameter configurations. + notice that the methods used to request logging do not only + take a String as a parameter. Some methods allow more + sophisticated parameter configurations. </p> - <p> For some Logger <code>logger</code>, writing, </p> + <p> + For some Logger + <code>logger</code> + , writing, + </p> - <div class="source"> - logger.debug("Entry number: " + i + " is " + - String.valueOf(entry[i])); - </div> + <div class="source">logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));</div> - <p> incurs the cost of constructing the message parameter, that is - converting both integer <code>i</code> and <code>entry[i]</code> - to a String, and concatenating intermediate strings. This, - regardless of whether the message will be logged or not. + <p> + incurs the cost of constructing the message parameter, that + is converting both integer + <code>i</code> + and + <code>entry[i]</code> + to a String, and concatenating intermediate strings. This, + regardless of whether the message will be logged or not. </p> <p> - One possible way to avoid the cost of parameter construction is - by surrounding the log statement with a test. Here is an + One possible way to avoid the cost of parameter construction + is by surrounding the log statement with a test. Here is an example. </p> - <div class="source"> -if(logger.isDebugEnabled()) { - logger.debug("Entry number: " + i + " is " + - String.valueOf(entry[i])); -} </div> + <div class="source">if(logger.isDebugEnabled()) { + logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i])); +}</div> - <p> This way you will not incur the cost of parameter construction - if debugging is disabled for <code>logger</code> . On the other - hand, if the logger is enabled for the DEBUG level, you will incur - the cost of evaluating whether the logger is enabled or not, - twice: once in <code>debugEnabled</code> and once in - <code>debug</code> . This is an insignificant overhead because - evaluating a logger takes less than 1% of the time it takes to - actually log a statement. + <p> + This way you will not incur the cost of parameter + construction if debugging is disabled for + <code>logger</code> + . On the other hand, if the logger is enabled for the DEBUG + level, you will incur the cost of evaluating whether the + logger is enabled or not, twice: once in + <code>debugEnabled</code> + and once in + <code>debug</code> + . This is an insignificant overhead because evaluating a + logger takes less than 1% of the time it takes to actually + log a statement. </p> <h4>Better alternative based on format messages</h4> @@ -741,11 +938,7 @@ </p> - <div class="source"> - Object entry = new SomeObject(); - <br /> - logger.debug("The entry is {}.", entry); - </div> + <div class="source">Object entry = new SomeObject(); logger.debug("The entry is {}.", entry);</div> <p> After evaluting whether to log or not, and only if the @@ -767,11 +960,8 @@ logging statement. </p> - <div class="source"> - logger.debug("The new entry is "+entry+"."); - <br /> - logger.debug("The new entry is {}.", entry); - </div> + <div class="source">logger.debug("The new entry is "+entry+"."); +logger.debug("The new entry is {}.", entry);</div> <p> @@ -779,10 +969,7 @@ can write: </p> - <div class="source"> - logger.debug("The new entry is {}. It replaces {}.", entry, - oldEntry); - </div> + <div class="source">logger.debug("The new entry is {}. It replaces {}.", entry, oldEntry);</div> <p> If three or more arguments need to be passed, an @@ -791,10 +978,7 @@ </p> - <div class="source"> - logger.debug("Value {} was inserted between {} and {}.", new - Object[] {newVal, below, above}); - </div> + <div class="source">logger.debug("Value {} was inserted between {} and {}.", new Object[] {newVal, below, above});</div>