[LOGBack-dev] svn commit: r380 - in logback/classic/trunk/src: main/java/ch/qos/logback/classic/examples site/xdocTemplates
noreply.seb at qos.ch
noreply.seb at qos.ch
Fri Jul 28 15:07:17 CEST 2006
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>
More information about the logback-dev
mailing list