[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>&nbsp;</p>
@@ -126,18 +164,7 @@
       </a></p>
 
       <p>&nbsp;</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