[slf4j-dev] svn commit: r837 - in slf4j/trunk: slf4j-api/src/main/java/org/slf4j slf4j-site/src/site/pages slf4j-site/src/site/pages/css slf4j-site/src/site/pages/templates
ceki at slf4j.org
ceki at slf4j.org
Sun Jul 8 22:52:25 CEST 2007
Author: ceki
Date: Sun Jul 8 22:52:24 2007
New Revision: 837
Added:
slf4j/trunk/slf4j-site/src/site/pages/log4j-over-slf4j.html
Modified:
slf4j/trunk/slf4j-api/src/main/java/org/slf4j/MDC.java
slf4j/trunk/slf4j-site/src/site/pages/bug-reporting.html
slf4j/trunk/slf4j-site/src/site/pages/css/site.css
slf4j/trunk/slf4j-site/src/site/pages/docs.html
slf4j/trunk/slf4j-site/src/site/pages/faq.html
slf4j/trunk/slf4j-site/src/site/pages/index.html
slf4j/trunk/slf4j-site/src/site/pages/mailing-lists.html
slf4j/trunk/slf4j-site/src/site/pages/news.html
slf4j/trunk/slf4j-site/src/site/pages/svn.html
slf4j/trunk/slf4j-site/src/site/pages/templates/footer.js
slf4j/trunk/slf4j-site/src/site/pages/templates/left.js
Log:
- started work on 1.4.2
- preparing the move of log4j-bridge from logback into slf4j as log4j-over-slf4j
- minor addition to the MDC class
Modified: slf4j/trunk/slf4j-api/src/main/java/org/slf4j/MDC.java
==============================================================================
--- slf4j/trunk/slf4j-api/src/main/java/org/slf4j/MDC.java (original)
+++ slf4j/trunk/slf4j-api/src/main/java/org/slf4j/MDC.java Sun Jul 8 22:52:24 2007
@@ -54,6 +54,7 @@
* Please note that all methods in this class are static.
*
* @author Ceki Gülcü
+ * @since 1.4.1
*/
public class MDC {
Modified: slf4j/trunk/slf4j-site/src/site/pages/bug-reporting.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/bug-reporting.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/bug-reporting.html Sun Jul 8 22:52:24 2007
@@ -91,6 +91,7 @@
+ <script src="templates/footer.js"></script>
</div>
Modified: slf4j/trunk/slf4j-site/src/site/pages/css/site.css
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/css/site.css (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/css/site.css Sun Jul 8 22:52:24 2007
@@ -86,11 +86,14 @@
.footer {
text-align: right;
color: #564b47;
- background-color: #90897a;
+ background-color: #fff;
padding:0px;
- margin:0px
+ border-top: 1px solid #CCCCCC;
+ margin-top: 3ex;
+ font-size: smaller;
}
+
strong {
/*font-size: 13px;*/
font-weight: bold;
Modified: slf4j/trunk/slf4j-site/src/site/pages/docs.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/docs.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/docs.html Sun Jul 8 22:52:24 2007
@@ -26,9 +26,10 @@
<ul>
<li><a href="manual.html">User manual</a></li>
+ <li><a href="faq.html">FAQ</a></li>
+ <li><a href="log4j-over-slf4j.html">log4j-over-slf4j</a></li>
<li><a href="api/index.html">javadocs</a></li>
<li><a href="xref/index.html">sources</a></li>
- <li><a href="faq.html">FAQ</a></li>
</ul>
<h2>Articles</h2>
Modified: slf4j/trunk/slf4j-site/src/site/pages/faq.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/faq.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/faq.html Sun Jul 8 22:52:24 2007
@@ -553,16 +553,26 @@
accompanying message as a good a thing (TM).
</p>
- <table border="0">
-
- <tr>
- <td align="right">
- <a href="#top">[top]</a></td></tr></table><hr />
</dd>
+
+ <table border="0">
+ <tr>
+ <td align="right">
+ <a href="#top">[top]</a>
+ </td>
+ </tr>
+ </table>
+
+ <hr />
+
<dt><a name="logging_performance"> What is the fastest way of
(not) logging?</a></dt><dd>
+ <p>SLF4J supports an advanced feature called parameterized
+ logging which can significantly boost logging performance for
+ <em>disabled</em> logging statement.</p>
+
<p> For some Logger <code>logger</code>, writing,</p>
<p class="source">logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));</p>
@@ -592,95 +602,139 @@
less than 1% of the time it takes to actually log a statement.
</p>
-
-
- <p><b>Better alternative based on format messages</b></p>
+ <p><b>Better alternative based on parameterized
+ messages</b></p>
<p>There exists a very convenient alternative based on message
formats. Assuming <code>entry</code> is an object, you can write:
</p>
- <p class="source">Object entry = new SomeObject();
+ <p class="source">Object entry = new SomeObject();
logger.debug("The entry is {}.", entry);</p>
- <p>After evaluting whether to log or not, and only if the
- decision is affirmative, will the logger implementation format
- the message and replace the '{}' pair with the string value of
- <code>entry</code>. In other words, this form does not incur
- the cost of parameter construction in case the log statement
- is disabled.
+ <p>After evaluting whether to log or not, and only if the
+ decision is affirmative, will the logger implementation format
+ the message and replace the '{}' pair with the string value of
+ <code>entry</code>. In other words, this form does not incur
+ the cost of parameter construction in case the log statement is
+ disabled.
+ </p>
+
+
+ <p>The following two lines will yield the exact same
+ output. However, the second form will outperform the first
+ form by a factor of at least 30, in case of a
+ <em>disabled</em> logging statement.
</p>
-
- <p>The following two lines will yield the exact same
- output. However, the second form will outperform the first
- form by a factor of at least 30, in case of a
- <em>disabled</em> logging statement.
- </p>
-
+
<p class="source">logger.debug("The new entry is "+entry+".");
logger.debug("The new entry is {}.", entry);</p>
- <p>A two argument variant is also availalble. For example, you can
- write:</p>
+ <p>A two argument variant is also availalble. For example, you
+ can write:</p>
+
<p class="source">logger.debug("The new entry is {}. It replaces {}.", entry, oldEntry);</p>
- <p>If three or more arguments need to be passed, an
- <code>Object[]</code> variant is also availalble. For example,
- you can write:</p>
-
+ <p></p>
+ <p>If three or more arguments need to be passed, you can make
+ use of the <code>Object[]</code> variant. For example, you can
+ write:</p>
+
+ <p> </p>
<p class="source">logger.debug("Value {} was inserted between {} and {}.",
new Object[] {newVal, below, above});</p>
+ <p></p>
+ <p>SLF4J uses its own message formatting implementation which
+ differs from that of the Java platform. This is justified by
+ the fact that SLF4J's implementation performs several orders
+ of magnitude faster but at the cost of being non-standard and
+ less flexible.
+ </p>
-
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="string_contents">
- How can I log the string contents of a single (possibly
- complex) object?
- </a></dt><dd>
<p>
- In relatively rare cases where the message to be logged is the
- string form of an object, then the parameterized printing
- method of the appropriate level can be used. Assuming
- <code>complexObject</code> is an object of certain complexity,
- for a log statement of level DEBUG, you can write:
- </p>
+ </p>
- <p class="source">logger.debug("{}", complexObject);</p>
+ </dd>
+
+ <table border="0">
+ <tr>
+ <td align="right">
+ <a href="#top">[top]</a>
+ </td>
+ </tr>
+ </table>
+ <hr />
+
+ <dt><a name="string_contents">
+ How can I log the string contents of a single (possibly
+ complex) object?
+ </a>
+
+ <dd>
+ <p> In relatively rare cases where the message to be logged
+ is the string form of an object, then the parameterized
+ printing method of the appropriate level can be
+ used. Assuming <code>complexObject</code> is an object of
+ certain complexity, for a log statement of level DEBUG, you
+ can write:
+ </p>
+
+ <p class="source">logger.debug("{}", complexObject);</p>
+
+
+ <p>The logging system will invoke
+ <code>complexObject.toString()</code> method only after it
+ has ascertained that the log statement was
+ enabled. Otherwise, the cost of
+ <code>complexObject.toString()</code> conversion will be
+ advantageously avoided.
+ </p>
+ </dd>
- <p>The logging system will invoke
- <code>complexObject.toString()</code> method only after it has
- ascertained that the log statement was enabled. Otherwise, the
- cost of <code>complexObject.toString()</code> conversion will
- be advantageously avoided.
- </p>
+ <table border="0">
+ <tr>
+ <td align="right">
+ <a href="#top">[top]</a>
+ </td>
+ </tr>
+ </table>
+
+ <hr />
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="fatal">
- Why doesn't the <code>org.slf4j.Logger</code> interface
- have methods for the FATAL level?
- </a></dt><dd>
- <p>From the stand point of a logging system, the distinction
- between a fatal error and an error is usually not very
- useful. Most programmers exit the application when a fatal
- error is encountered. However, a logging library cannot (and
- should not) decide on its own to terminate an application. The
- initiative to exit the application must be left to the
- developer.
- </p>
+ <dt><a name="fatal"> Why doesn't the
+ <code>org.slf4j.Logger</code> interface have methods for the
+ FATAL level?
+ </a>
+ </dt>
- <p>Thus, the most the FATAL level can do is to
- <em>highlight</em> a given error as the cause for application
- to crash. However, errors are by definition exceptional events
- that merit attention. If a given situation causes errors to be
- logged, the causes should be attended to as soon as
- possible. However, if the "error" is actually a normal
- situation which cannot be prevented but merits being aware of,
- then it should be marked as WARN, not ERROR.
- </p>
+ <dd>
+
+ <p>From the stand point of a logging system, the distinction
+ between a fatal error and an error is usually not very
+ useful. Most programmers exit the application when a fatal
+ error is encountered. However, a logging library cannot (and
+ should not) decide on its own to terminate an
+ application. The initiative to exit the application must be
+ left to the developer.
+ </p>
+
+
+ <p>Thus, the most the FATAL level can do is to
+ <em>highlight</em> a given error as the cause for
+ application to crash. However, errors are by definition
+ exceptional events that merit attention. If a given
+ situation causes errors to be logged, the causes should be
+ attended to as soon as possible. However, if the "error" is
+ actually a normal situation which cannot be prevented but
+ merits being aware of, then it should be marked as WARN, not
+ ERROR.
+ </p>
<p>Assuming the ERROR level designates exceptional situations
meriting close attention, we are inclined to believe that the
@@ -823,7 +877,7 @@
the <code>Marker</code> interface?
</a></dt><dd>
<p>Markers consitute a revolutionary concept which is
- supported by LOGBack but not other existing logging
+ supported by logback but not other existing logging
systems. Consequently, SLF4J confromant logging systems are
allowed to ignore marker data passed by the user.
</p>
@@ -900,13 +954,24 @@
hardly the behavior expected by the user.
</p>
- <p>In summary, except for classes with few members
- <em>and</em> instantiated very frequently, logger members
- should be instance variables.
+ <p>In summary, logger members should be instance variables,
+ except for classes with few members <em>and</em> instantiated
+ very (very!) frequently.
</p>
+ </dd>
+
+
+ <table border="0">
+ <tr>
+ <td align="right">
+ <a href="#top">[top]</a>
+ </td>
+ </tr>
+ </table>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table></dd></dl></div>
+ </dl>
+ </div>
</div>
</body>
</html>
Modified: slf4j/trunk/slf4j-site/src/site/pages/index.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/index.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/index.html Sun Jul 8 22:52:24 2007
@@ -30,8 +30,15 @@
Jakarta Commons Logging (JCL).
</p>
- <p>Logging API implementations can either choose to implement the
- the SLF4J interfaces directly, à la <a
+ <p>SLF4J API offers an advanced abstraction of various logging
+ systems, including JDK 1.4 logging, log4j and logback. Advacned
+ features include <a
+ href="faq.html#logging_performance">parameterized logging</a> and <a
+ href="manual.html#mdc">MDC support</a>.
+ </p>
+
+ <p>Logging systems can either choose to implement the the SLF4J
+ interfaces directly, à la <a
href="http://logback.qos.ch">logback</a> or <a
href="api/org/slf4j/impl/SimpleLogger.html">SimpleLogger</a>. Alternatively,
it is possible (and rather easy) to write SLF4J adapters for a given
@@ -124,6 +131,8 @@
</tr>
</table>
+
+ <script src="templates/footer.js"></script>
</div>
</body>
</html>
Added: slf4j/trunk/slf4j-site/src/site/pages/log4j-over-slf4j.html
==============================================================================
--- (empty file)
+++ slf4j/trunk/slf4j-site/src/site/pages/log4j-over-slf4j.html Sun Jul 8 22:52:24 2007
@@ -0,0 +1,103 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/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>Log4j Bridge</title>
+<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+<link rel="stylesheet" type="text/css" media="print" href="css/print.css" />
+
+</head>
+<body>
+ <script>
+prefix='';
+</script>
+
+<script src="templates/header.js"></script>
+<div id="left">
+ <script src="templates/left.js"></script>
+</div>
+<div id="right">
+ <script src="templates/right.js"></script>
+</div>
+<div id="content">
+
+ <h2>Log4j over SLF4J</h2>
+
+ <p>Recent versions of SLF4J ship with a module called
+ <em>log4j-over-slf4j</em>. It allows log4j users to migrate
+ existing applications to SLF4J without changing <em>a single line
+ of code</em> by replacing the <em>log4j.jar</em> file with
+ <em>log4j-over-slf4j.jar</em>, as described below.
+ </p>
+
+ <h3>How does it work?</h3>
+
+ <p>The log4j-over-slf4j module contains replacements of most
+ widely used log4j classes, namely
+ <code>org.apache.log4j.Category</code>,
+ <code>org.apache.log4j.Logger</code>,
+ <code>org.apache.log4j.Priority</code>,
+ <code>org.apache.log4j.Level</code>,
+ <code>org.apache.log4j.MDC</code>, and
+ <code>org.apache.log4j.BasicConfigurator</code>. These replacement
+ classes redirect all work to their corresponding SLF4J classes.
+ </p>
+
+ <p>To use log4j-over-slf4j in your own application, the first step
+ is to locate and then to replace <em>log4j.jar</em> with
+ <em>log4j-over-slf4j.jar</em>. Note that you still need an SLF4J
+ binding and its dependencies for log4j-over-slf4j to work
+ properly.
+ </p>
+
+ <p>
+ In most situtations, replacing a jar file is all it takes in
+ order to migrate from log4j to SLF4J.
+ </p>
+
+ <p>Note that as a result of this migration, log4j configuration
+ files will no longer be picked up. If you need to migrate your
+ log4j.properties file to logback, the <a
+ href="http://logback.qos.ch/translator/">log4j translator</a>
+ might be of help. For configuring logback, please refer to <a
+ href="manual/index.html">the manual</a>.
+ </p>
+
+ <p>We are happy to report that several applications are
+ successfully using log4j-over-slf4j in production.
+ </p>
+
+
+ <h3>When does it not work?</h3>
+
+ <p>The <em>log4j-over-slf4j</em> module will not work when the
+ application calls log4j components that are not present in the
+ bridge. For example, direct references to log4j appenders,
+ filters or PropertyConfigurator are not supported by
+ log4j-over-slf4j. While the number of cases where
+ log4j-over-slf4j is insufficient is not completely negligible, in
+ the vast majority of cases where log4j is configured through a
+ configuration file, be it <em>log4j.properties</em> or
+ <em>log4j.xml</em>, log4j-over-slf4j is enough in order to migrate
+ your application to SLF4J.
+ </p>
+
+ <h3>What about the overhead?</h3>
+
+ <p>There overhead of using log4j-over-slf4j instead of log4j
+ directly is relatively small. Given that log4j-over-slf4j
+ immediately delegates all work to SLF4J, the CPU overhead should
+ be negligible, in the order of a few <em>nanoseconds</em>. There
+ is a memory overhead corresponding to an entry in a hashmap per
+ logger, which should be usually acceptable even for very large
+ applications consisting of several thousand loggers. Moreover,
+ given that logback is both much faster and more memory-efficient,
+ the gains made by using logback should compensate for the overhead
+ of using log4j-over-slf4j instead of log4j directly.
+ </p>
+
+
+<script src="templates/footer.js"></script>
+</div>
+</body>
+</html>
Modified: slf4j/trunk/slf4j-site/src/site/pages/mailing-lists.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/mailing-lists.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/mailing-lists.html Sun Jul 8 22:52:24 2007
@@ -131,6 +131,7 @@
<p> </p>
+ <script src="templates/footer.js"></script>
</div>
</body>
</html>
Modified: slf4j/trunk/slf4j-site/src/site/pages/news.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/news.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/news.html Sun Jul 8 22:52:24 2007
@@ -30,6 +30,17 @@
<hr noshade="noshade" size="1"/>
+ <h3>July 9th, 2007 - Release of SLF4J 1.4.2</h3>
+
+ <p>The log4j-over-slf4j project has been moved
+
+ <p>Addition of the <code>getMDCAdapter</code> method to
+ org.slf4j.MDC class. This allows access to the actual MDC
+ implementation which can occasionally come in handly.
+ </p>
+
+ <hr noshade="noshade" size="1"/>
+
<h3>July 4th, 2007 - Release of SLF4J 1.4.1</h3>
Modified: slf4j/trunk/slf4j-site/src/site/pages/svn.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/svn.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/svn.html Sun Jul 8 22:52:24 2007
@@ -69,6 +69,7 @@
</p>
+ <script src="templates/footer.js"></script>
</div>
Modified: slf4j/trunk/slf4j-site/src/site/pages/templates/footer.js
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/templates/footer.js (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/templates/footer.js Sun Jul 8 22:52:24 2007
@@ -1,4 +1,5 @@
+
document.write('<p class="footer">')
-document.write('<a href="http://www.qos.ch/">QOS.ch</a>')
-document.write('</p>')
\ No newline at end of file
+document.write('Copyright © 2004-2007 <a href="http://www.qos.ch/">QOS.ch</a>')
+document.write('</p>')
Modified: slf4j/trunk/slf4j-site/src/site/pages/templates/left.js
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/templates/left.js (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/templates/left.js Sun Jul 8 22:52:24 2007
@@ -3,10 +3,13 @@
document.write('<p><a href="index.html">Introduction</a>');
document.write('<a href="news.html">News</a>');
document.write('<a href="docs.html">Documentation</a>');
+document.write('<a href="license.html">License</a>');
document.write('<a href="download.html">Download</a>');
+
document.write('<a href="svn.html">Source Repository</a>');
document.write('<a href="mailing-lists.html">Mailing Lists</a>');
document.write('<a href="bug-reporting.html">Bug Reporting</a>');
+
document.write('<p class="menu_header">Native implementations</p>');
document.write('<a href="http://logback.qos.ch/">Logback</a>');
document.write('<a href="http://www.x4juli.org">x4juli</a>');
More information about the slf4j-dev
mailing list