[slf4j-dev] svn commit: r641 - in slf4j/trunk: slf4j-simple/src/main/java/org/slf4j/impl slf4j-site/src/site/fml slf4j-site/src/site/xdocs
ceki at slf4j.org
ceki at slf4j.org
Wed Sep 6 23:37:33 CEST 2006
Author: ceki
Date: Wed Sep 6 23:37:33 2006
New Revision: 641
Modified:
slf4j/trunk/slf4j-simple/src/main/java/org/slf4j/impl/SimpleLogger.java
slf4j/trunk/slf4j-site/src/site/fml/faq.fml
slf4j/trunk/slf4j-site/src/site/xdocs/index.xml
slf4j/trunk/slf4j-site/src/site/xdocs/manual.xml
slf4j/trunk/slf4j-site/src/site/xdocs/news.xml
Log:
updated documentation
Modified: slf4j/trunk/slf4j-simple/src/main/java/org/slf4j/impl/SimpleLogger.java
==============================================================================
--- slf4j/trunk/slf4j-simple/src/main/java/org/slf4j/impl/SimpleLogger.java (original)
+++ slf4j/trunk/slf4j-simple/src/main/java/org/slf4j/impl/SimpleLogger.java Wed Sep 6 23:37:33 2006
@@ -326,5 +326,4 @@
public void error(String msg, Throwable t) {
log(ERROR_STR, msg, t);
}
-
}
Modified: slf4j/trunk/slf4j-site/src/site/fml/faq.fml
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/fml/faq.fml (original)
+++ slf4j/trunk/slf4j-site/src/site/fml/faq.fml Wed Sep 6 23:37:33 2006
@@ -505,6 +505,11 @@
</question>
<answer>
+ <p>Please note that all new development effort in NLOG4J is now
+ redirected into <a href="http://logback.qos.ch">logback</a>,
+ the proposed sucessor of log4j.
+ </p>
+
<p>NLOG4J is almost identical to log4j. NLOG4J natively supports
the SLF4J API while vanilla log4j is supported through a
wrapper, i.e <em>slf4j-log4j12.jar</em> or
@@ -550,53 +555,61 @@
</question>
<answer>
- <p>We suggest that the <code>Logger</code> class in your
- framework directly implement the <a
- href="api/org/slf4j/Logger.html"><code>org.slf4j.Logger</code></a>
- interface.
- </p>
-
- <p>We further recommend that your framework copy the SLF4J
- java source files (.java files) into your source tree. This
- can be accomplished by checking out SLF4J files from its
- source code repository using Subversion, more on this later.
- </p>
-
- <p>Client code will only refer to <a
- href="api/org/slf4j/LoggerFactory.html">LoggerFactory</a> to
- retreive org.slf4j.Logger instances, your framework needs to
- instruct <code>LoggerFactory</code> to return your framework's
- <code>Logger</code> instances. This step is usually reffered
- to as binding SLF4J with your framework. In recent versions of
- SLF4J, the binding information has been isolated into a small
- class named <a
- href="api/org/slf4j/impl/StaticLoggerBinder.html">StaticLoggerBinder</a>.
- </p>
-
-
- <p>With the static binding approach we recommend, your
- framework's copy of <code>StaticBinder</code> class needs to
- be customized before compile time. You should be able to
- easily adapt NLOG4J's copy of <a
- href="http://svn.slf4j.org/viewcvs/nlog4j/trunk/src/java/org/slf4j/impl/StaticLoggerBinder.java?view=markup">StaticLoggerBinder.java</a>
- to your framework. Note that you do not need to change any
- other classes to ensure correct binding.
- </p>
-
- <p>Just as importantly, adapting SLF4J to your system can be an
- entirely automated process. Thus, when there are small changes
- to the SLF4J API, you can update to the latest SLF4J version
- without needing to edit any java files. For example, NLOG4J
- uses an entirely automated build procedure to synchronize with
- SLF4J changes.
- </p>
-
- <p>For a complete example of an automated build file, please
- refer to the <a
- href="http://svn.slf4j.org/viewcvs/nlog4j/trunk/slf4j.xml?view=markup">slf4j.xml</a>
- build file in the NLOG4J project.
- </p>
+ <p>Adding supporting for the SLF4J is suprisingly
+ easy. Essentialy, you coping an existing binding and tailoring
+ it a little (as explained below) does the trick.
+ </p>
+
+ <p>If you are a Maven2 user, you can use the
+ slf4j-archetype. Invoke the following command to create a new
+ module called <em>slf4j-MY</em> with much of the plumbing
+ alredy in place. </p>
+
+ <p class="source">mvn archetype:create -DgroupId=org.slf4j -DartifactId=slf4j-MY \
+ -DarchetypeGroupId=org.slf4j -DarchetypeArtifactId=slf4j-archetype -DarchetypeVersion=1.1.0</p>
+
+ <p>At this stage, assuming your logging system has notion of a
+ logger, called say <code>MyLogger</code>, you need to provide
+ an adapter for <code>MyLogger</code> to
+ <code>org.slf4j.Logger</code> interface. Refer to slf4j-jcl,
+ slf4j-jdk14, and slf4j-log4j12 modules for examples of
+ adapters.
+ </p>
+
+ <p>Once you have written an appropriate adapter, say
+ <code>MyLoggerAdapter</code>, you need to provide a factory
+ class implementing the <code>org.slf4j.ILoggerFactory</code>
+ interface. This factory should return instances
+ <code>MyLoggerAdapter</code>. Let <code>MyLoggerFactory</code>
+ be the name of your factory class.
+ </p>
+
+ <p>Once you have the adapter, namely
+ <code>MyLoggerAdapter</code>, and a factory, namely
+ <code>MyLoggerFactory</code>, the last remaining step is to
+ modify the <code>StaticLoggerBinder</code> class so that it
+ reurns an new instance of <code>MyLoggerFactory</code>. You
+ will also need to modify the
+ <code>loggerFactoryClassStr</code> variable.
+ </p>
+
+ <p>That's it. You don't need to modify any other files.</p>
+
+ <p>In summary, to create an SLF4J binding for your logging
+ system, follow these steps:</p>
+
+ <ol>
+ <li>start with a copy of an existing module, or create a new
+ binding using slf4j-archetype as discussed above</li>
+ <li>create an adapter between your logging system and
+ <code>org.slf4j.Logger</code> interface
+ </li>
+ <li>create a factory for the adapter created in the previous step,</li>
+ <li>>modify <code>StaticLoggerBinder</code> class to use the
+ factory you created in the previous step</li>
+ </ol>
+
</answer>
</faq>
Modified: slf4j/trunk/slf4j-site/src/site/xdocs/index.xml
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/xdocs/index.xml (original)
+++ slf4j/trunk/slf4j-site/src/site/xdocs/index.xml Wed Sep 6 23:37:33 2006
@@ -14,7 +14,7 @@
<p>The Simple Logging Facade for Java or (SLF4J) is intended to
serve as a simple facade for various logging APIs allowing to the
end-user to plug in the desired implementation at
- <em>deployment</em> time. SLF4J also allows for a <a
+ <em>deployment</em> time. SLF4J also allows for a <a
href="manual.html#gradual">gradual migration path</a> away from
Jakarta Commons Logging (JCL).
</p>
@@ -40,11 +40,11 @@
<p>SLF4J does not rely on any special class loader machinery. In
fact, the binding between SLF4J and a given logging API
- implementation is performed <em>statically</em> at compile
- time. Each binding is hardwired to use one and only specific logging
- API implementation. Each binding corresponds to one jar file. At
- deployment time, you simply drop the binding of your choice, that is
- a jar file, onto the appropriate class path location. As a
+ implementation is performed <em>statically</em> at compile time of
+ each binding. Each binding is hardwired to use one and only specific
+ logging API implementation. Each binding corresponds to one jar
+ file. In your code, you simply drop the binding of your choice, that
+ is a jar file, onto the appropriate class path location. As a
consequence of this simple approach, SLF4J suffers from none of the
class loader problems or memory leaks observed with Jakarta Commons
Logging (JCL).
Modified: slf4j/trunk/slf4j-site/src/site/xdocs/manual.xml
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/xdocs/manual.xml (original)
+++ slf4j/trunk/slf4j-site/src/site/xdocs/manual.xml Wed Sep 6 23:37:33 2006
@@ -61,12 +61,31 @@
logging, JCL and LOGBack, respectively.
</p>
+ <p>SLF4J supports multiple logging systems, namely, NOP,
+ Simple, log4j version 1.2, log4j version 1.3, JDK 1.4 logging,
+ JCL and logback. The SLF4J distribution ships with several jar
+ files <em>slf4j-nop.jar</em>, <em>slf4j-simple.jar</em>,
+ <em>slf4j-log4j12.jar</em>, <em>slf4j-log4j13.jar</em>,
+ <em>slf4j-jdk14.jar</em> and <em>slf4j-jcl.jar</em>. Each of
+ these jar files is hardwired <em>at compile-time</em> to use
+ just one implementation, that is NOP, Simple, log4j version
+ 1.2, log4j version 1.3, JDK 1.4 logging, JCL and logback,
+ respectively. As of version SLF4J 1.1.0, all of the bindings
+ shipped with SLF4J depend on <em>slf4j-api.jar</em> which must
+ be present on the class path for the binding to function
+ properly.
+ </p>
+
+ <h2>Small applications</h2>
+
<p>Small applications where configuring a fully-fledged
logging systems can be somewhat of an overkill can drop in
<em>slf4j-simple.jar</em> instead of a binding for the
fully-fledged logging system.
</p>
+ <h2>Libraries</h2>
+
<p>Authors of widely-distributed components and libraries may
code against the SLF4J interface in order to avoid imposing an
logging API implementation on the end-user. At deployment
@@ -98,25 +117,26 @@
logging APIs to conform to the SLF4J model.
</p>
- <h2>Built-in support in LOGBack</h2>
+ <h2>Built-in support in logback</h2>
- <p>The <code>Logger</code> class in LOGBack directly
+ <p>The <code>Logger</code> class in logback directly
implements SLF4J's <code>Logger</code> interface. Moreover,
- LOGBack makes extensive use of SLF4J internally.
+ logback makes extensive use of SLF4J internally.
</p>
-
- <p>LOGBack's built-in support for SLF4J means that the adapter
- for does not need to wrap LOGBack objects in order to
- make them conform to SLF4J's <code>Logger</code> interface. A
- LOGBack <code>Logger</code> <em>is</em> a
+
+ <p>Logback's built-in (a.k.a. native) support for SLF4J means
+ that the adapter for does not need to wrap logback objects in
+ order to make them conform to SLF4J's <code>Logger</code>
+ interface. A logback
+ <code>ch.qos.logback.classic.Logger</code> <em>is</em> a
<code>org.slf4j.Logger</code>. Thus, using SLF4J in
- conjunction with LOGBack involves strictly zero memory overhead
- and near-zero computational overhead.
+ conjunction with logback involves strictly zero memory and
+ computational overhead.
</p>
-
+
<a name="gradual"><h2>Gradual migration to SLF4J from Jakarta
- Commons Logging (JCL)</h2></a>
+ Commons Logging (JCL) and/or log4j</h2></a>
<h2><em>jcl104-over-slf4j.jar</em></h2>
@@ -142,6 +162,16 @@
therefore becomes less of an issue.
</p>
+ <h2><em>log4j-over-slf4j.jar</em></h2>
+
+ <p>If migrating log4j logging calls to SLF4J is not something
+ you particularly relish, just drop in our implementation of
+ log4j over SLF4J, i.e. <em>log4j-over-slf4j.jar</em>, on your
+ class path. All logging calls made to the log4j API will be
+ redirected to SLF4J which in turn will deletage to the
+ underlying logging system.
+ </p>
+
<h2><em>slf4j-jcl.jar</em></h2>
<p>Some of our users after having switched to SLF4J API
@@ -185,8 +215,12 @@
will cause SLF4J to delegate the choice of the logging system
to JCL, resulting in an infinite loop.
</p>
+
+ <p>For very similar reasons, <em>log4j-over-slf4j.jar</em> and
+ <em>slf4j-log4j12.jar</em> cannot be deployed simultaneously.
+ </p>
- <a name="summary"><h2>Summary</h2></a>
+ <a name="summary"><h2>Summary</h2></a>
<table class="ls" cellspacing="4" cellpadding="4">
<tr>
@@ -228,21 +262,26 @@
</td>
<td>SLF4J supports popular logging systems, namely log4j,
- JDK 1.4 logging, Simple logging and NOP.
+ JDK 1.4 logging, Simple logging and NOP whereas x4juli and
+ logback logging systems support the SLF4J API natively.
</td>
+
</tr>
<tr>
<td>Easy migration path</td>
- <td>The implementation of JCL over SLF4J will allow your
- project to migrate to SLF4J piecemeal, without breaking
- compatibility with existing software, while enhancing the
- reliability of your software at the same time.
-
- <p>In existing applications where JCL is a requirement,
- the JCL binding will allow parts of that application to
- switch to SLF4J without having any impact on the larger
- application.</p>
+
+ <td>
+ <p>The implementation of JCL over SLF4J, i.e
+ <em>jcl104-over-slf4j.jar</em>, will allow your project
+ to migrate to SLF4J piecemeal, without breaking
+ compatibility with existing software using
+ JCL. Similarly, the implementation of log4j's client
+ interface over SLF4J, i.e <em>log4j-over-slf4j.jar</em>,
+ will allow your project to migrate to SLF4J one class at
+ a time, without breaking compatibility with existing
+ legacy logging calls to the log4j API.
+ </p>
</td>
</tr>
Modified: slf4j/trunk/slf4j-site/src/site/xdocs/news.xml
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/xdocs/news.xml (original)
+++ slf4j/trunk/slf4j-site/src/site/xdocs/news.xml Wed Sep 6 23:37:33 2006
@@ -10,37 +10,30 @@
<h1>SLF4J News</h1>
- <p>You can receive SLF4J and NLOG4J related announcements by
- subscribing to the <a
- href="http://www.slf4j.org/mailman/listinfo/announce">SLF4J
+ <p>You can receive SLF4J related announcements by subscribing to the
+ <a href="http://www.slf4j.org/mailman/listinfo/announce">SLF4J
announce</a> mailing list.
</p>
<hr noshade="noshade" size="1"/>
- <h3>July 25th, 2006 - Release of SLF4J 1.1.0</h3>
-
- <p>Release 1.1.0 is a relatively important
- only.</p>
-
- <ul>
-
- <li>Fixed <a
- href="http://bugzilla.slf4j.org/show_bug.cgi?id=22">bug number
- 22</a> reported by Bjorn Danielsson. This version of the SLF4J API
- will no longer systematically throw an exception when the
- <code>o.a.c.l.impl.SLF4FLogFactory#release()</code> method is
- invoked. Instead, the <code>release()</code> method will issue a
- <a href="http://www.slf4j.org/codes.html">warning</a>.
-
- </li>
-
- </ul>
+ <h3>September 7th, 2006 - Release of SLF4J 1.1.0-RC1</h3>
+ <p>Release 1.1.0-RC1 is a relatively important release with a
+ refactoring of the way class files are organized in jar files. In
+ previous releases, each binding was self-contained in a single jar
+ file. In this release, each and every binding depends on
+ <em>slf4j-api.jar</em> which contains the bulk of the classes
+ required to use SLF4J, except for one or two adapter classes. Only
+ the adapter classes are now shipped with each specific binding jar
+ as appropriate for the underlying logging system..
+ </p>
+ <p>This release is built using Maven instead of Ant. As for the java
+ code, it has not been changed.</p>
+
<hr noshade="noshade" size="1"/>
-
<h3>June 8th, 2006 - Release of SLF4J 1.0.2</h3>
<p>Release 1.0.2 is a maintenance release containing bug fixes
More information about the slf4j-dev
mailing list