slf4j-site/src/site/pages/manual.html - platform/external/slf4j - Gitiles

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
     <title>SLF4J Manual</title>
     <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
     <link rel="stylesheet" type="text/css" href="css/prettify.css" />
   </head>
   <body onload="prettyPrint()">
     <script type="text/javascript">prefix='';</script>

     <script type="text/javascript" src="js/prettify.js"></script>
     <script src="templates/header.js" type="text/javascript"></script>
     <div id="left">
       <script src="templates/left.js" type="text/javascript"></script>
     </div>
     <div id="content">


     <h2>SLF4J user manual</h2>

     <p>The Simple Logging Facade for Java or (SLF4J) serves as a
     simple facade or abstraction for various logging frameworks, e.g.
     java.util.logging, log4j and logback, allowing the end-user to
     plug in the desired logging framework at <em>deployment</em> time.
     </p>

     <h3>
       <a name="hello_world" href="#hello_world">Hello World</a>
     </h3>

     <p>In accordance with programming tradition, here is an example
     illustrating the simplest way to output "Hello world" using SLF4J.
     It begins by getting a logger with the name "HelloWorld". This
     logger is in turn used to log the message "Hello World".
     </p>

 <pre class="prettyprint source">import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;

 public class HelloWorld {
   public static void main(String[] args) {
     Logger logger = LoggerFactory.getLogger(HelloWorld.class);
     logger.info("Hello World");
   }
 }</pre>

      <p>To run this example, you first need to <a
      href="download.html">download the slf4j distribution</a>, and
      then to unpack it. Once that is done, add these two jar files to
      your class path:</p>

      <ul>
        <li>slf4j-api-${project.version}.jar</li>
        <li>slf4j-simple-${project.version}.jar</li>
      </ul>

      <p>Compiling and running <em>HelloWorld</em> will result in the
      following output being printed on the console.</p>

      <pre class="output">0 [main] INFO HelloWorld - Hello World</pre>

      <h3>
        <a name="typical_usage" href="#typical_usage">Typical usage
        pattern</a>
      </h3>

      <p>The sample code below illustrates the typical usage pattern
      for SLF4J. Note the use of {}-placeholders on line 15. See the
      question <a href="faq.html#logging_performance">"What is the
      fastest way of logging?"</a> in the FAQ for more details.
      </p>

      <p></p>

       <pre class="prettyprint source"> 1: <b>import org.slf4j.Logger;</b>
  2: <b>import org.slf4j.LoggerFactory;</b>
  3:
  4: public class Wombat {
  5:
  6:   <b>final Logger logger = LoggerFactory.getLogger(Wombat.class);</b>
  7:   Integer t;
  8:   Integer oldT;
  9:
 10:   public void setTemperature(Integer temperature) {
 11:
 12:     oldT = t;
 13:     t = temperature;
 14:
 15:     <b>logger.debug("Temperature set to {}. Old temperature was {}.", t, oldT);</b>
 16:
 17:     if(temperature.intValue() > 50) {
 18:       <b>logger.info("Temperature has risen above 50 degrees.");</b>
 19:     }
 20:   }
 21: } </pre>


       <h3><a name="swapping" href="#binding">Binding with a logging
       framework at deployment time</a></h3>

       <p>As mentioned previously, SLF4J supports multiple logging
       frameworks. The SLF4J distribution ships with several jar files
       referred to as "SLF4J bindings".  </p>

       <dl>

         <dt><em>slf4j-nop-${project.version}.jar</em></dt>
         <dd>Binding for <a
         href="http://www.slf4j.org/api/org/slf4j/helpers/NOPLogger.html">NOP</a>,
         silently discarding all logging.<p/></dd>


         <dt><em>slf4j-simple-${project.version}.jar</em></dt>
         <dd>Binding for <a
         href="http://www.slf4j.org/apidocs/org/slf4j/impl/SimpleLogger.html">Simple
         </a> implementation, which outputs all events to
         System.err. Only messages of level INFO and higher are
         printed. This binding may be useful in the context of small
         applications.<p/></dd>

         <dt><em>slf4j-log4j12-${project.version}.jar</em>
         </dt>
         <dd>Binding for <a
         href="http://logging.apache.org/log4j/1.2/index.html">log4j
         version 1.2</a>, a widely used logging framework. You also
         need to place <em>log4j.jar</em> on your class path.<p/></dd>

         <dt><em>slf4j-jdk14-${project.version}.jar</em> </dt>
         <dd>Binding for java.util.logging, also referred to as JDK 1.4
         logging (<a
         href="http://www.exampledepot.com/egs/java.util.logging/pkg.html">examples</a>)<p/></dd>

         <dt><em>slf4j-jcl-${project.version}.jar</em></dt>

         <dd>Binding for <a
         href="http://commons.apache.org/logging/">Jakarta Commons
         Logging</a>. This binding will delegate all SLF4J logging to
         JCL.<p/>
         </dd>
       </dl>

       <p>There are also SLF4J bindings external to the SLF4J project,
       e.g. <a href="http://logback.qos.ch/">logback</a> which
       implements SLF4J natively.  Logback's
       <a href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/Logger.html">
       <code>ch.qos.logback.classic.Logger</code></a> class is a direct
       implementation of SLF4J's
       <a href="http://www.slf4j.org/apidocs/org/slf4j/Logger.html">
       <code>org.slf4j.Logger</code></a> interface. Thus, using SLF4J
       in conjunction with logback involves strictly zero memory and
       computational overhead.
       </p>


       <p>To switch logging frameworks, just replace slf4j bindings on
       your class path. For example, to switch from java.util.logging
       to log4j, just replace slf4j-jdk14-${project.version}.jar with
       slf4j-log4j12-${project.version}.jar.
       </p>

       <p>SLF4J does not rely on any special class loader machinery. In
       fact, the each SLF4J binding is hardwired <em>at compile
       time</em> to use one and only one specific logging framework.
       For example, the slf4j-log12-${project.version}.jar binding is
       bound at compile time to use log4j.  In your code, in addition
       to <em>slf4j-api-${project.version}.jar</em>, you simply drop
       <b>one and only one</b> binding of your choice onto the
       appropriate class path location. Do not place more than one
       binding on your class path. Here is a graphical illustration of
       the general idea.
       </p>

       <p>&nbsp;</p>

       <p><a href="images/bindings.png">
       <img border="1" src="images/bindings.png" alt="click to enlarge" width="500"/>
       </a></p>

       <p>&nbsp;</p>


       <p>The SLF4J interfaces and their various adapters are extremely
       simple. Most developers familiar with the Java language should
       be able to read and fully understand the code in less than one
       hour.  No knowledge of class loaders is necessary as SLF4J does
       not make use nor does it directly access any class loaders. As a
       consequence, SLF4J suffers from none of the class loader
       problems or memory leaks observed with Jakarta Commons Logging
       (JCL).
       </p>

       <p>Hopefully, the simplicity of the SLF4J interfaces and the
       deployment model will make it easy for developers of other
       logging frameworks to conform to the SLF4J model.
       </p>

       <h3><a name="libraries" href="#libraries">Libraries</a></h3>

       <p>Authors of widely-distributed components and libraries may
       code against the SLF4J interface in order to avoid imposing an
       logging framework on the end-user of the component or library.
       He or she may choose the desired logging framework at deployment
       time by inserting the desired slf4j binding on the classpath,
       which may be changed later by replacing an existing binding with
       another on the class path and restarting the application.  This
       approach has proven to be simple and very robust.
       </p>


       <h3><a name="consolidate" href="#consolidate">Consolidate
       logging via SLF4J</a></h3>

       <p>Often times, a given project will depend on various
       components which rely on logging APIs other than SLF4J. It is
       common to find projects depending on a combination of JCL,
       java.util.logging, log4j and SLF4J. It then becomes desirable to
       consolidate logging through a single channel. SLF4J caters for
       this common use-case by providing bridging modules for JCL,
       java.util.logging and log4j. For more details, please refer to
       the page on <a href="legacy.html"><b>Bridging legacy
       APIs</b></a>.
       </p>

       <h3><a name="mdc" href="#mdc">Mapped Diagnostic Context (MDC)
       support</a></h3>
       <p>"Mapped Diagnostic Context" is essentially a map maintained by the
       logging framework where the application can provided key-value pairs,
       which can then be inserted by the logging framework in log messages.</p>

       <p>SLF4J supports MDC, or mapped diagnostic context. If the
       underlying logging framework offers MDC functionality, then
       SLF4J will delegate to the underlying framework's MDC. Note that
       at this time, only log4j and logback offer MDC functionality. If
       the underlying framework does not offer MDC, for example
       java.util.logging, then SLF4J will still store MDC data but the
       information therein will need to be retrieved by custom user
       code.</p>

       <p>Thus, as a SLF4J user, you can take advantage of MDC
       information in the presence of log4j or logback, but without
       forcing these logging frameworks upon your users as
       dependencies.
       </p>

       <p>For more information on MDC please see the <a
       href="http://logback.qos.ch/manual/mdc.html">chapter on MDC</a>
       in the logback manual.
       </p>


       <h3><a name="summary" href="#summary">Executive
       summary</a>
       </h3>

       <table  class="bodyTable" cellspacing="4" cellpadding="4">
         <tr>
           <th align="left">Advantage</th>
           <th align="left">Description</th>
         </tr>

         <tr  class="a">

           <td>Select your logging framework at deployment time</td>

           <td>The desired logging framework can be plugged in at
           deployment time by inserting the appropriate jar file
           (binding) on your class path.
           </td>
         </tr>


         <tr class="alt">
           <td>Fail-fast operation</td>

           <td>Due to the way that classes are loaded by the JVM, the
           framework binding will be verified automatically very early
           on.  SLF4J will abort execution with a warning if no binding
           is present.
           </td>
         </tr>


         <tr class="a">
           <td>Bindings for popular logging frameworks
           </td>

           <td>SLF4J supports popular logging frameworks, namely log4j,
           java.util.logging, Simple logging and NOP. The <a
           href="http://logback.qos.ch">logback</a> project supports
           SLF4J natively.  </td>

         </tr>

         <tr class="alt">
           <td>Bridging legacy logging APIs</td>

           <td>
             <p>The implementation of JCL over SLF4J, i.e
             <em>jcl-over-slf4j.jar</em>, will allow your project to
             migrate to SLF4J piecemeal, without breaking compatibility
             with existing software using JCL. Similarly,
             log4j-over-slf4j.jar and jul-to-slf4j modules will allow
             you to redirect log4j and respectively java.util.logging
             calls to SLF4J. See the page on <a
             href="legacy.html">Bridging legacy APIs</a> for more
             details.
             </p>
           </td>
         </tr>

         <tr class="a">
           <td>Migrate your source code</td>
           <td>The <a href="migrator.html">slf4j-migrator</a> utility
           can help you migrate your source to use SLF4J.
           </td>
         </tr>


         <tr class="alt">
           <td>Support for parameterized log messages</td>

           <td>All SLF4J bindings support parameterized log messages
           with significantly <a
           href="faq.html#logging_performance">improved performance</a>
           results.</td>
         </tr>


   </table>

   <script src="templates/footer.js" type="text/javascript"></script>

 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
	<title>SLF4J Manual</title>
	<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
	<link rel="stylesheet" type="text/css" href="css/prettify.css" />
	</head>
	<body onload="prettyPrint()">
	<script type="text/javascript">prefix='';</script>

	<script type="text/javascript" src="js/prettify.js"></script>
	<script src="templates/header.js" type="text/javascript"></script>
	<div id="left">
	<script src="templates/left.js" type="text/javascript"></script>
	</div>
	<div id="content">


	<h2>SLF4J user manual</h2>

	<p>The Simple Logging Facade for Java or (SLF4J) serves as a
	simple facade or abstraction for various logging frameworks, e.g.
	java.util.logging, log4j and logback, allowing the end-user to
	plug in the desired logging framework at <em>deployment</em> time.
	</p>

	<h3>
	<a name="hello_world" href="#hello_world">Hello World</a>
	</h3>

	<p>In accordance with programming tradition, here is an example
	illustrating the simplest way to output "Hello world" using SLF4J.
	It begins by getting a logger with the name "HelloWorld". This
	logger is in turn used to log the message "Hello World".
	</p>

	<pre class="prettyprint source">import org.slf4j.Logger;
	import org.slf4j.LoggerFactory;

	public class HelloWorld {
	public static void main(String[] args) {
	Logger logger = LoggerFactory.getLogger(HelloWorld.class);
	logger.info("Hello World");
	}
	}</pre>

	<p>To run this example, you first need to <a
	href="download.html">download the slf4j distribution</a>, and
	then to unpack it. Once that is done, add these two jar files to
	your class path:</p>

	<ul>
	<li>slf4j-api-${project.version}.jar</li>
	<li>slf4j-simple-${project.version}.jar</li>
	</ul>

	<p>Compiling and running <em>HelloWorld</em> will result in the
	following output being printed on the console.</p>

	<pre class="output">0 [main] INFO HelloWorld - Hello World</pre>

	<h3>
	<a name="typical_usage" href="#typical_usage">Typical usage
	pattern</a>
	</h3>

	<p>The sample code below illustrates the typical usage pattern
	for SLF4J. Note the use of {}-placeholders on line 15. See the
	question <a href="faq.html#logging_performance">"What is the
	fastest way of logging?"</a> in the FAQ for more details.
	</p>

	<p></p>

	<pre class="prettyprint source"> 1: <b>import org.slf4j.Logger;</b>
	2: <b>import org.slf4j.LoggerFactory;</b>
	3:
	4: public class Wombat {
	5:
	6: <b>final Logger logger = LoggerFactory.getLogger(Wombat.class);</b>
	7: Integer t;
	8: Integer oldT;
	9:
	10: public void setTemperature(Integer temperature) {
	11:
	12: oldT = t;
	13: t = temperature;
	14:
	15: <b>logger.debug("Temperature set to {}. Old temperature was {}.", t, oldT);</b>
	16:
	17: if(temperature.intValue() > 50) {
	18: <b>logger.info("Temperature has risen above 50 degrees.");</b>
	19: }
	20: }
	21: } </pre>



	<h3><a name="swapping" href="#binding">Binding with a logging
	framework at deployment time</a></h3>

	<p>As mentioned previously, SLF4J supports multiple logging
	frameworks. The SLF4J distribution ships with several jar files
	referred to as "SLF4J bindings". </p>

	<dl>

	<dt><em>slf4j-nop-${project.version}.jar</em></dt>
	<dd>Binding for <a
	href="http://www.slf4j.org/api/org/slf4j/helpers/NOPLogger.html">NOP</a>,
	silently discarding all logging.<p/></dd>


	<dt><em>slf4j-simple-${project.version}.jar</em></dt>
	<dd>Binding for <a
	href="http://www.slf4j.org/apidocs/org/slf4j/impl/SimpleLogger.html">Simple
	</a> implementation, which outputs all events to
	System.err. Only messages of level INFO and higher are
	printed. This binding may be useful in the context of small
	applications.<p/></dd>

	<dt><em>slf4j-log4j12-${project.version}.jar</em>
	</dt>
	<dd>Binding for <a
	href="http://logging.apache.org/log4j/1.2/index.html">log4j
	version 1.2</a>, a widely used logging framework. You also
	need to place <em>log4j.jar</em> on your class path.<p/></dd>

	<dt><em>slf4j-jdk14-${project.version}.jar</em> </dt>
	<dd>Binding for java.util.logging, also referred to as JDK 1.4
	logging (<a
	href="http://www.exampledepot.com/egs/java.util.logging/pkg.html">examples</a>)<p/></dd>

	<dt><em>slf4j-jcl-${project.version}.jar</em></dt>

	<dd>Binding for <a
	href="http://commons.apache.org/logging/">Jakarta Commons
	Logging</a>. This binding will delegate all SLF4J logging to
	JCL.<p/>
	</dd>
	</dl>

	<p>There are also SLF4J bindings external to the SLF4J project,
	e.g. <a href="http://logback.qos.ch/">logback</a> which
	implements SLF4J natively. Logback's
	<a href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/Logger.html">
	<code>ch.qos.logback.classic.Logger</code></a> class is a direct
	implementation of SLF4J's
	<a href="http://www.slf4j.org/apidocs/org/slf4j/Logger.html">
	<code>org.slf4j.Logger</code></a> interface. Thus, using SLF4J
	in conjunction with logback involves strictly zero memory and
	computational overhead.
	</p>


	<p>To switch logging frameworks, just replace slf4j bindings on
	your class path. For example, to switch from java.util.logging
	to log4j, just replace slf4j-jdk14-${project.version}.jar with
	slf4j-log4j12-${project.version}.jar.
	</p>

	<p>SLF4J does not rely on any special class loader machinery. In
	fact, the each SLF4J binding is hardwired <em>at compile
	time</em> to use one and only one specific logging framework.
	For example, the slf4j-log12-${project.version}.jar binding is
	bound at compile time to use log4j. In your code, in addition
	to <em>slf4j-api-${project.version}.jar</em>, you simply drop
	<b>one and only one</b> binding of your choice onto the
	appropriate class path location. Do not place more than one
	binding on your class path. Here is a graphical illustration of
	the general idea.
	</p>

	<p> </p>

	<p><a href="images/bindings.png">
	<img border="1" src="images/bindings.png" alt="click to enlarge" width="500"/>
	</a></p>

	<p> </p>


	<p>The SLF4J interfaces and their various adapters are extremely
	simple. Most developers familiar with the Java language should
	be able to read and fully understand the code in less than one
	hour. No knowledge of class loaders is necessary as SLF4J does
	not make use nor does it directly access any class loaders. As a
	consequence, SLF4J suffers from none of the class loader
	problems or memory leaks observed with Jakarta Commons Logging
	(JCL).
	</p>

	<p>Hopefully, the simplicity of the SLF4J interfaces and the
	deployment model will make it easy for developers of other
	logging frameworks to conform to the SLF4J model.
	</p>

	<h3><a name="libraries" href="#libraries">Libraries</a></h3>

	<p>Authors of widely-distributed components and libraries may
	code against the SLF4J interface in order to avoid imposing an
	logging framework on the end-user of the component or library.
	He or she may choose the desired logging framework at deployment
	time by inserting the desired slf4j binding on the classpath,
	which may be changed later by replacing an existing binding with
	another on the class path and restarting the application. This
	approach has proven to be simple and very robust.
	</p>


	<h3><a name="consolidate" href="#consolidate">Consolidate
	logging via SLF4J</a></h3>

	<p>Often times, a given project will depend on various
	components which rely on logging APIs other than SLF4J. It is
	common to find projects depending on a combination of JCL,
	java.util.logging, log4j and SLF4J. It then becomes desirable to
	consolidate logging through a single channel. SLF4J caters for
	this common use-case by providing bridging modules for JCL,
	java.util.logging and log4j. For more details, please refer to
	the page on <a href="legacy.html"><b>Bridging legacy
	APIs</b></a>.
	</p>

	<h3><a name="mdc" href="#mdc">Mapped Diagnostic Context (MDC)
	support</a></h3>
	<p>"Mapped Diagnostic Context" is essentially a map maintained by the
	logging framework where the application can provided key-value pairs,
	which can then be inserted by the logging framework in log messages.</p>

	<p>SLF4J supports MDC, or mapped diagnostic context. If the
	underlying logging framework offers MDC functionality, then
	SLF4J will delegate to the underlying framework's MDC. Note that
	at this time, only log4j and logback offer MDC functionality. If
	the underlying framework does not offer MDC, for example
	java.util.logging, then SLF4J will still store MDC data but the
	information therein will need to be retrieved by custom user
	code.</p>

	<p>Thus, as a SLF4J user, you can take advantage of MDC
	information in the presence of log4j or logback, but without
	forcing these logging frameworks upon your users as
	dependencies.
	</p>

	<p>For more information on MDC please see the <a
	href="http://logback.qos.ch/manual/mdc.html">chapter on MDC</a>
	in the logback manual.
	</p>



	<h3><a name="summary" href="#summary">Executive
	summary</a>
	</h3>

	<table class="bodyTable" cellspacing="4" cellpadding="4">
	<tr>
	<th align="left">Advantage</th>
	<th align="left">Description</th>
	</tr>

	<tr class="a">

	<td>Select your logging framework at deployment time</td>

	<td>The desired logging framework can be plugged in at
	deployment time by inserting the appropriate jar file
	(binding) on your class path.
	</td>
	</tr>


	<tr class="alt">
	<td>Fail-fast operation</td>

	<td>Due to the way that classes are loaded by the JVM, the
	framework binding will be verified automatically very early
	on. SLF4J will abort execution with a warning if no binding
	is present.
	</td>
	</tr>


	<tr class="a">
	<td>Bindings for popular logging frameworks
	</td>

	<td>SLF4J supports popular logging frameworks, namely log4j,
	java.util.logging, Simple logging and NOP. The <a
	href="http://logback.qos.ch">logback</a> project supports
	SLF4J natively. </td>

	</tr>

	<tr class="alt">
	<td>Bridging legacy logging APIs</td>

	<td>
	<p>The implementation of JCL over SLF4J, i.e
	<em>jcl-over-slf4j.jar</em>, will allow your project to
	migrate to SLF4J piecemeal, without breaking compatibility
	with existing software using JCL. Similarly,
	log4j-over-slf4j.jar and jul-to-slf4j modules will allow
	you to redirect log4j and respectively java.util.logging
	calls to SLF4J. See the page on <a
	href="legacy.html">Bridging legacy APIs</a> for more
	details.
	</p>
	</td>
	</tr>

	<tr class="a">
	<td>Migrate your source code</td>
	<td>The <a href="migrator.html">slf4j-migrator</a> utility
	can help you migrate your source to use SLF4J.
	</td>
	</tr>



	<tr class="alt">
	<td>Support for parameterized log messages</td>

	<td>All SLF4J bindings support parameterized log messages
	with significantly <a
	href="faq.html#logging_performance">improved performance</a>
	results.</td>
	</tr>


	</table>

	<script src="templates/footer.js" type="text/javascript"></script>

	</div>
	</body>
	</html>