Author: ceki Date: Fri Apr 17 11:29:28 2009 New Revision: 1307 Modified: slf4j/trunk/slf4j-site/src/site/pages/download.html slf4j/trunk/slf4j-site/src/site/pages/manual.html
Log: - changes of my own to manual.html (kept most of Ralph's changes) One notable exception is that the logger field is not static. - added reference to log4jdbc in download.html Modified: slf4j/trunk/slf4j-site/src/site/pages/download.html ============================================================================== --- slf4j/trunk/slf4j-site/src/site/pages/download.html (original) +++ slf4j/trunk/slf4j-site/src/site/pages/download.html Fri Apr 17 11:29:28 2009 @@ -45,7 +45,7 @@ <li><a href="http://www.jwaresoftware.org/wiki/log4ant/home">Log4Ant</a>, by JWare Software </li> - <li><a href="http://code.google.com/p/log4jdbc/">log4jdbc</a>, a JDBC driver which logs SQL information before delagting to an underlying JDBC driver, by Arthur Blake + <li><a href="http://code.google.com/p/log4jdbc/">log4jdbc</a>, a JDBC driver which logs SQL information before delegating to an underlying JDBC driver, by Arthur Blake </li> <li><a href="http://code.google.com/p/slf4fx/">SLF4Fx</a>, an open Modified: slf4j/trunk/slf4j-site/src/site/pages/manual.html ============================================================================== --- slf4j/trunk/slf4j-site/src/site/pages/manual.html (original) +++ slf4j/trunk/slf4j-site/src/site/pages/manual.html Fri Apr 17 11:29:28 2009 @@ -26,40 +26,46 @@ </p> <h3> - <a name="hello_world" href="#hello_world">Hello World</a> + <a name="hello_world" href="#hello_world">Hello World</a> </h3> - <p>It is traditional to present the simplest possible way to -output the text "Hello World". In order to do so with SLF4J you need to -<a href="download.html">download the slf4j distribution</a>, unpack it, -and add these two jar files to your classpath:</p> - - <ul> - <li>slf4j-api-${project.version}.jar</li> - <li>slf4j-simple-${project.version}.jar</li> - </ul> - <p> - The HelloWorld.java file asks for a logger for HelloWorld.class, which in turn logs "Hello World". - </p> + <p>In accordance with programming tradition, here is an example + illustrating the simplest way to output "Hello world" using SLF4J. + </p> -<pre class="source"> -public class HelloWorld { + <p>The HelloWorld classasks for a logger for the + <code>HelloWorld.class</code>, which in turn logs "Hello World". + </p> + <pre class="source">import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +public class HelloWorld { public static void main(String[] args) { - org.slf4j.LoggerFactory.getLogger(HelloWorld.class).info("Hello World"); + Logger logger = LoggerFactory.getLogger(HelloWorld.class); + logger.info("Hello World"); } -} -</pre> +}</pre> - HelloWorld will output, when compiled and run: + <p>To run this exampple, you must startirst first <a + href="download.html">download the slf4j distribution</a>, and + unpack it. Once that is done, add these two jar files to your + classpath:</p> + + <ul> + <li>slf4j-api-${project.version}.jar</li> + <li>slf4j-simple-${project.version}.jar</li> + </ul> -<pre class="output">0 [main] INFO HelloWorld - Hello World</pre> + <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> + <h3> + <a name="typical_usage" href="#typical_usage">Typical usage + pattern</a> + </h3> <pre class="source"> 1: <b>import org.slf4j.Logger;</b> @@ -67,7 +73,7 @@ 3: 4: public class Wombat { 5: - 6: <b>static final Logger logger = LoggerFactory.getLogger(Wombat.class);</b> + 6: <b>final Logger logger = LoggerFactory.getLogger(Wombat.class);</b> 7: Integer t; 8: Integer oldT; 9: @@ -86,37 +92,69 @@ </pre> <p>The example above 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. + 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> <h3><a name="swapping" href="#binding">Binding with a logging framework at deployment time</a></h3> - <p>SLF4J supports multiple logging frameworks:</p> + <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><a href="http://www.slf4j.org/api/org/slf4j/helpers/NOPLogger.html">NOP</a> - <em>slf4j-nop-${project.version}.jar</em></dt> - <dd>All logging is silently discarded<p/></dd> - <dt><a href="http://www.slf4j.org/apidocs/org/slf4j/impl/SimpleLogger.html">Simple</a> - <em>slf4j-simple-${project.version}.jar</em></dt> - <dd>Very small and simple, outputs all events at WARN level or higher to System.err. Good for small applications.<p/></dd> - <dt><a href="http://logging.apache.org/log4j/1.2/index.html">log4j version 1.2</a> - <em>slf4j-log4j12-${project.version}.jar</em></dt> - <dd>A very widely used logging framework.<p/></dd> - <dt>java.util.logging - <em>slf4j-jdk14-${project.version}.jar</em></dt> - <dd>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><a href="http://commons.apache.org/logging/">Jakarta Commons Logging</a> - <em>slf4j-jcl-${project.version}.jar</em></dt> - <dd>A logging layer intended to solve the same problem as slf4j, but at runtime. Traditionally delegates to log4j or java.util.logging. - Currently at version 1.1. Version 1.0 had problems in discovering the right framework (see the <a - href="http://www.qos.ch/logging/classloader.jsp">thorough analysis</a>). <p/></dd> - <dt><a href="http://logback.qos.ch/"/>logback</a></dt> - <dd>A fork of log4j by the original author which is under active development. Supports slf4j natively.<p/></dd> + + <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. Good for 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.<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>, a logging layer intended to solve the same + problem as slf4j, but using runtime binding.<p/> + </dd> </dl> - <p>Each framework has an indication of which file in the SLF4J distribution - that should be added to the classpath at deployment to let the required - <em>slf4j-api-${project.version}.jar</em> bind to that logging - framework. The figure below illustrates the general idea. + <p>There also exist SLF4J bindings which are external to the + SLF4J project, e.g. <a + href="http://logback.qos.ch/">logback</a>. + </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. Please do not place more than + one binding on your class path because SLF4J can bind with one + and only one logging framework at a time. Here is a graphical + illustration of the general idea. </p> <p> </p> @@ -126,18 +164,7 @@ </a></p> <p> </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. Please do not place more than one binding on your - class path because SLF4J can bind with one and only one logging - framework at a time. - </p> + <p>The SLF4J interfaces and their various adapters are extremely simple. Most developers familiar with the Java language should @@ -147,7 +174,7 @@ logging frameworks to conform to the SLF4J model. </p> - <h3>Libraries</h3> + <h3>Libraries</h3> <p>Authors of widely-distributed components and libraries may code against the SLF4J interface in order to avoid imposing an @@ -185,26 +212,24 @@ logging framework where the application can provided key-value pairs, which can then be inserted by the logging framework in log messages.</p> - <p>As of version 1.4.1, 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, then SLF4J will silently drop MDC information. - </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 upon your users as dependencies. - </p> - - <p>As of SLF4J version 1.5.0, SLF4J provides MDC support for - java.util.logging (JDK 1.4 logging) as well. + 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. + href="http://logback.qos.ch/manual/mdc.html">chapter on MDC</a> + in the logback manual. </p> <h3><a name="gradual" href="#gradual">Gradual migration to SLF4J _______________________________________________ dev mailing list dev@slf4j.org http://www.slf4j.org/mailman/listinfo/dev