[slf4j-dev] svn commit: r1307 - slf4j/trunk/slf4j-site/src/site/pages
ceki at slf4j.org
ceki at slf4j.org
Fri Apr 17 11:29:29 CEST 2009
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
More information about the slf4j-dev
mailing list