[slf4j-dev] svn commit: r1230 - in slf4j/trunk/slf4j-site/src/site/pages: . css templates
ceki at slf4j.org
ceki at slf4j.org
Thu Nov 13 12:34:03 CET 2008
Author: ceki
Date: Thu Nov 13 12:34:03 2008
New Revision: 1230
Modified:
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/download.html
slf4j/trunk/slf4j-site/src/site/pages/extensions.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/legacy.html
slf4j/trunk/slf4j-site/src/site/pages/license.html
slf4j/trunk/slf4j-site/src/site/pages/mailing-lists.html
slf4j/trunk/slf4j-site/src/site/pages/manual.html
slf4j/trunk/slf4j-site/src/site/pages/migrator.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
Log:
- changes in indentation or cosmetic changes to make the documentation be XHTML compliant
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 Thu Nov 13 12:34:03 2008
@@ -1,23 +1,24 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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>SLF4J Bug reporting</title>
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
-</head>
-<body>
- <script>
-prefix='';
-</script>
-
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <title>SLF4J Bug reporting</title>
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';
+ </script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <div id="content">
- <h1>Before you report a bug</h1>
+ <h1>Before you report a bug</h1>
<p>The SLF4J community consists of those who use SLF4J and its
implementations, help answer questions on discussions lists,
@@ -88,7 +89,7 @@
- <script src="templates/footer.js"></script>
+ <script src="templates/footer.js" type="text/javascript"></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 Thu Nov 13 12:34:03 2008
@@ -83,6 +83,10 @@
font-size: normal;
}
+table.footer {
+ width: 100%;
+}
+
.footer {
text-align: right;
color: #564b47;
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 Thu Nov 13 12:34:03 2008
@@ -1,20 +1,20 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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>SLF4J Documentation</title>
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
-</head>
-<body>
- <script>
-prefix='';
-</script>
-
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <title>SLF4J Documentation</title>
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';</script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <div id="content">
<h1>Documentation</h1>
@@ -68,11 +68,10 @@
href="http://bsnyderblog.blogspot.com/2007/08/my-soapbox-for-slf4j.html">My
Soapbox for SLF4J</a>, by Bruce Snyder
</li>
-
-
-
</ul>
+ <script src="templates/footer.js" type="text/javascript"></script>
+
</div>
</body>
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 Thu Nov 13 12:34:03 2008
@@ -1,20 +1,20 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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>SLF4J Binary files</title>
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
-</head>
-<body>
- <script>
-prefix='';
-</script>
-
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <title>SLF4J Binary files</title>
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';</script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <div id="content">
@@ -32,12 +32,12 @@
<h2>Previous versions</h2>
- <p>Previous versions of SLF4J can be downloaded from the <A
- href="dist/">main repository</A>.
+ <p>Previous versions of SLF4J can be downloaded from the <a
+ href="dist/">main repository</a>.
</p>
-
+ <script src="templates/footer.js" type="text/javascript"></script>
</div>
</body>
</html>
Modified: slf4j/trunk/slf4j-site/src/site/pages/extensions.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/extensions.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/extensions.html Thu Nov 13 12:34:03 2008
@@ -1,21 +1,21 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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>SLF4J extensions</title>
-
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
-</head>
-<body>
- <script>
-prefix='';
-</script>
-
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <title>SLF4J extensions</title>
+
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';</script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <div id="content">
<h1>SLF4J extensions</h1>
@@ -23,11 +23,11 @@
which ships with SLF4J. </p>
- <dl>
- <dt><a href="#profiler">Profiler</a></dt>
- <dt><a href="#extended_logger">Extended logger</a></dt>
- <dt><a href="#javaagent">Logging added with Java agent</> (requires Java 5)</a></dt>
- </dl>
+ <ul>
+ <li><a href="#profiler">Profiler</a></li>
+ <li><a href="#extended_logger">Extended logger</a></li>
+ <li><a href="#javaagent">Logging added with Java agent (requires Java 5)</a></li>
+ </ul>
<h2><a name="profiler"></a>Profilers</h2>
@@ -373,97 +373,81 @@
not handled.
</p>
-<p class="source">
- package com.test;
+ <p class="source">package com.test;
+
+import org.slf4j.ext.XLogger;
+import org.slf4j.ext.XLoggerFactory;
+
+import java.util.Random;
+
+public class TestService {
+ private XLogger logger = XLoggerFactory.getXLogger(TestService.class
+ .getName());
- import org.slf4j.ext.XLogger;
- import org.slf4j.ext.XLoggerFactory;
+ private String[] messages = new String[] { "Hello, World",
+ "Goodbye Cruel World", "You had me at hello" };
- import java.util.Random;
+ private Random rand = new Random(1);
- public class TestService
- {
- private XLogger logger = XLoggerFactory.getXLogger(TestService.class.getName());
-
- private String[] messages = new String[]
- {
- "Hello, World",
- "Goodbye Cruel World",
- "You had me at hello"
- };
- private Random rand = new Random(1);
-
- public String retrieveMessage()
- {
- logger.entry();
-
- String testMsg = getMessage(getKey());
-
- logger.exit(testMsg);
- return testMsg;
- }
-
- public void exampleException()
- {
- logger.entry();
- try
- {
- String msg = messages[messages.length];
- logger.error("An exception should have been thrown");
- }
- catch (Exception ex)
- {
- logger.catching(ex);
- }
- logger.exit();
- }
-
- public String getMessage(int key)
- {
- logger.entry(key);
-
- String value = messages[key];
-
- logger.exit(value);
- return value;
- }
-
- private int getKey()
- {
- logger.entry();
- int key = rand.nextInt(messages.length);
- logger.exit(key);
- return key;
- }
+ public String retrieveMessage() {
+ logger.entry();
+
+ String testMsg = getMessage(getKey());
+
+ logger.exit(testMsg);
+ return testMsg;
+ }
+
+ public void exampleException() {
+ logger.entry();
+ try {
+ String msg = messages[messages.length];
+ logger.error("An exception should have been thrown");
+ } catch (Exception ex) {
+ logger.catching(ex);
}
-</p>
+ logger.exit();
+ }
- <p>
- This test application uses the preceding service to generate
+ public String getMessage(int key) {
+ logger.entry(key);
+
+ String value = messages[key];
+
+ logger.exit(value);
+ return value;
+ }
+
+ private int getKey() {
+ logger.entry();
+ int key = rand.nextInt(messages.length);
+ logger.exit(key);
+ return key;
+ }
+}</p>
+
+ <p>This test application uses the preceding service to generate
logging events.
</p>
-<p class="source">
-package com.test;
+ <p class="source">package com.test;
-public class App
-{
- public static void main( String[] args )
- {
- TestService service = new TestService();
- service.retrieveMessage();
- service.retrieveMessage();
- service.exampleException();
- }
-}
-</p>
- <p>
- The configuration below will cause all output to be routed to target/test.log. The pattern for
- the FileAppender includes the class name, line number and method name. Including these
- in the pattern are critical for the log to be of value.
+public class App {
+ public static void main( String[] args ) {
+ TestService service = new TestService();
+ service.retrieveMessage();
+ service.retrieveMessage();
+ service.exampleException();
+ }
+} </p>
+
+ <p>The configuration below will cause all output to be routed to
+ target/test.log. The pattern for the FileAppender includes the
+ class name, line number and method name. Including these in the
+ pattern are critical for the log to be of value.
</p>
-<p class="source">
-<?xml version='1.0' encoding='UTF-8'?>
+
+ <p class="source"><?xml version='1.0' encoding='UTF-8'?>
<configuration>
<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
<filter class="ch.qos.logback.classic.filter.LevelFilter">
@@ -492,216 +476,233 @@
<p>
Here is the output that results from the Java classes and configuration above.
</p>
-<p class="source">
- 00:07:57.725 TRACE com.test.TestService:22 retrieveMessage - entry
- 00:07:57.738 TRACE com.test.TestService:57 getKey - entry
- 00:07:57.739 TRACE com.test.TestService:59 getKey - exit with (0)
- 00:07:57.741 TRACE com.test.TestService:47 getMessage - entry with (0)
- 00:07:57.741 TRACE com.test.TestService:51 getMessage - exit with (Hello, World)
- 00:07:57.742 TRACE com.test.TestService:26 retrieveMessage - exit with (Hello, World)
- 00:07:57.742 TRACE com.test.TestService:22 retrieveMessage - entry
- 00:07:57.742 TRACE com.test.TestService:57 getKey - entry
- 00:07:57.743 TRACE com.test.TestService:59 getKey - exit with (1)
- 00:07:57.745 TRACE com.test.TestService:47 getMessage - entry with (1)
- 00:07:57.745 TRACE com.test.TestService:51 getMessage - exit with (Goodbye Cruel World)
- 00:07:57.746 TRACE com.test.TestService:26 retrieveMessage - exit with (Goodbye Cruel World)
- 00:07:57.746 TRACE com.test.TestService:32 exampleException - entry
- 00:07:57.750 ERROR com.test.TestService:40 exampleException - catching
- java.lang.ArrayIndexOutOfBoundsException: 3
- at com.test.TestService.exampleException(TestService.java:35)
- at com.test.AppTest.testApp(AppTest.java:39)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
- at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
- at java.lang.reflect.Method.invoke(Method.java:585)
- at junit.framework.TestCase.runTest(TestCase.java:154)
- at junit.framework.TestCase.runBare(TestCase.java:127)
- at junit.framework.TestResult$1.protect(TestResult.java:106)
- at junit.framework.TestResult.runProtected(TestResult.java:124)
- at junit.framework.TestResult.run(TestResult.java:109)
- at junit.framework.TestCase.run(TestCase.java:118)
- at junit.framework.TestSuite.runTest(TestSuite.java:208)
- at junit.framework.TestSuite.run(TestSuite.java:203)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
- at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
- at java.lang.reflect.Method.invoke(Method.java:585)
- at org.apache.maven.surefire.junit.JUnitTestSet.execute(JUnitTestSet.java:213)
- at org.apache.maven.surefire.suite.AbstractDirectoryTestSuite.executeTestSet(AbstractDirectoryTestSuite.java:140)
- at org.apache.maven.surefire.suite.AbstractDirectoryTestSuite.execute(AbstractDirectoryTestSuite.java:127)
- at org.apache.maven.surefire.Surefire.run(Surefire.java:177)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
- at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
- at java.lang.reflect.Method.invoke(Method.java:585)
- at org.apache.maven.surefire.booter.SurefireBooter.runSuitesInProcess(SurefireBooter.java:338)
- at org.apache.maven.surefire.booter.SurefireBooter.main(SurefireBooter.java:997)
- 00:07:57.750 TRACE com.test.TestService:42 exampleException - exit
-</p>
- <p>
- Simply changing the root logger level to DEBUG in the example above will reduce the output
- considerably.
- </p>
-<p class="source">
- 00:28:06.004 ERROR com.test.TestService:40 exampleException - catching
- java.lang.ArrayIndexOutOfBoundsException: 3
- at com.test.TestService.exampleException(TestService.java:35)
- at com.test.AppTest.testApp(AppTest.java:39)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
- at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
- at java.lang.reflect.Method.invoke(Method.java:585)
- at junit.framework.TestCase.runTest(TestCase.java:154)
- at junit.framework.TestCase.runBare(TestCase.java:127)
- at junit.framework.TestResult$1.protect(TestResult.java:106)
- at junit.framework.TestResult.runProtected(TestResult.java:124)
- at junit.framework.TestResult.run(TestResult.java:109)
- at junit.framework.TestCase.run(TestCase.java:118)
- at junit.framework.TestSuite.runTest(TestSuite.java:208)
- at junit.framework.TestSuite.run(TestSuite.java:203)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
- at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
- at java.lang.reflect.Method.invoke(Method.java:585)
- at org.apache.maven.surefire.junit.JUnitTestSet.execute(JUnitTestSet.java:213)
- at org.apache.maven.surefire.suite.AbstractDirectoryTestSuite.executeTestSet(AbstractDirectoryTestSuite.java:140)
- at org.apache.maven.surefire.suite.AbstractDirectoryTestSuite.execute(AbstractDirectoryTestSuite.java:127)
- at org.apache.maven.surefire.Surefire.run(Surefire.java:177)
- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
- at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
- at java.lang.reflect.Method.invoke(Method.java:585)
- at org.apache.maven.surefire.booter.SurefireBooter.runSuitesInProcess(SurefireBooter.java:338)
- at org.apache.maven.surefire.booter.SurefireBooter.main(SurefireBooter.java:997)
-</p>
-
-<h2><a name="javaagent"></a>Adding logging with Java agent</h2>
+<p class="source">00:07:57.725 TRACE com.test.TestService:22 retrieveMessage - entry
+00:07:57.738 TRACE com.test.TestService:57 getKey - entry
+00:07:57.739 TRACE com.test.TestService:59 getKey - exit with (0)
+00:07:57.741 TRACE com.test.TestService:47 getMessage - entry with (0)
+00:07:57.741 TRACE com.test.TestService:51 getMessage - exit with (Hello, World)
+00:07:57.742 TRACE com.test.TestService:26 retrieveMessage - exit with (Hello, World)
+00:07:57.742 TRACE com.test.TestService:22 retrieveMessage - entry
+00:07:57.742 TRACE com.test.TestService:57 getKey - entry
+00:07:57.743 TRACE com.test.TestService:59 getKey - exit with (1)
+00:07:57.745 TRACE com.test.TestService:47 getMessage - entry with (1)
+00:07:57.745 TRACE com.test.TestService:51 getMessage - exit with (Goodbye Cruel World)
+00:07:57.746 TRACE com.test.TestService:26 retrieveMessage - exit with (Goodbye Cruel World)
+00:07:57.746 TRACE com.test.TestService:32 exampleException - entry
+00:07:57.750 ERROR com.test.TestService:40 exampleException - catching
+java.lang.ArrayIndexOutOfBoundsException: 3
+ at com.test.TestService.exampleException(TestService.java:35)
+ at com.test.AppTest.testApp(AppTest.java:39)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+ at java.lang.reflect.Method.invoke(Method.java:585)
+ at junit.framework.TestCase.runTest(TestCase.java:154)
+ at junit.framework.TestCase.runBare(TestCase.java:127)
+ at junit.framework.TestResult$1.protect(TestResult.java:106)
+ at junit.framework.TestResult.runProtected(TestResult.java:124)
+ at junit.framework.TestResult.run(TestResult.java:109)
+ at junit.framework.TestCase.run(TestCase.java:118)
+ at junit.framework.TestSuite.runTest(TestSuite.java:208)
+ at junit.framework.TestSuite.run(TestSuite.java:203)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+ at java.lang.reflect.Method.invoke(Method.java:585)
+ at org.apache.maven.surefire.junit.JUnitTestSet.execute(JUnitTestSet.java:213)
+ at org.apache.maven.surefire.suite.AbstractDirectoryTestSuite.executeTestSet(AbstractDirectoryTestSuite.java:140)
+ at org.apache.maven.surefire.suite.AbstractDirectoryTestSuite.execute(AbstractDirectoryTestSuite.java:127)
+ at org.apache.maven.surefire.Surefire.run(Surefire.java:177)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+ at java.lang.reflect.Method.invoke(Method.java:585)
+ at org.apache.maven.surefire.booter.SurefireBooter.runSuitesInProcess(SurefireBooter.java:338)
+ at org.apache.maven.surefire.booter.SurefireBooter.main(SurefireBooter.java:997)
+00:07:57.750 TRACE com.test.TestService:42 exampleException - exit</p>
+
+ <p>Simply changing the root logger level to DEBUG in the example
+ above will reduce the output considerably.
+ </p>
+ <p class="source">00:28:06.004 ERROR com.test.TestService:40 exampleException - catching
+java.lang.ArrayIndexOutOfBoundsException: 3
+ at com.test.TestService.exampleException(TestService.java:35)
+ at com.test.AppTest.testApp(AppTest.java:39)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+ at java.lang.reflect.Method.invoke(Method.java:585)
+ at junit.framework.TestCase.runTest(TestCase.java:154)
+ at junit.framework.TestCase.runBare(TestCase.java:127)
+ at junit.framework.TestResult$1.protect(TestResult.java:106)
+ at junit.framework.TestResult.runProtected(TestResult.java:124)
+ at junit.framework.TestResult.run(TestResult.java:109)
+ at junit.framework.TestCase.run(TestCase.java:118)
+ at junit.framework.TestSuite.runTest(TestSuite.java:208)
+ at junit.framework.TestSuite.run(TestSuite.java:203)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+ at java.lang.reflect.Method.invoke(Method.java:585)
+ at org.apache.maven.surefire.junit.JUnitTestSet.execute(JUnitTestSet.java:213)
+ at org.apache.maven.surefire.suite.AbstractDirectoryTestSuite.executeTestSet(AbstractDirectoryTestSuite.java:140)
+ at org.apache.maven.surefire.suite.AbstractDirectoryTestSuite.execute(AbstractDirectoryTestSuite.java:127)
+ at org.apache.maven.surefire.Surefire.run(Surefire.java:177)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+ at java.lang.reflect.Method.invoke(Method.java:585)
+ at org.apache.maven.surefire.booter.SurefireBooter.runSuitesInProcess(SurefireBooter.java:338)
+ at org.apache.maven.surefire.booter.SurefireBooter.main(SurefireBooter.java:997) </p>
+
+ <h2><a name="javaagent"></a>Adding logging with Java agent</h2>
+
+ <p><b>NOTE: BETA RELEASE, NOT PRODUCTION QUALITY</b> </p>
+
+ <p>Quickstart for the impatient:</p>
+
+ <ol>
+ <li>Use Java 5 or later.</li>
+ <li>Download slf4j-ext-${project.version}.jar and javassist.jar, and put them
+ both in the same directory.</li>
+ <li>Ensure your application is properly configured with
+ slf4j-api-X.Y.Z.jar and a suitable backend.</li>
+ <li>Instead of "java ..." use "java --javaagent:PATH/slf4j-ext-${project.version}.jar=time,verbose,level=info ..."<br/>
+ (replace PATH with the path to the jar)
+ </li>
+ <li>That's it!</li>
+ </ol>
+
+ <p>In some applications logging is used to trace the actual
+ execution of the application as opposed to log an occasional event.
+ One approach is using the <a href="#extended_logger">extended
+ logger</a> to add statements as appropriately, but another is to use
+ a tool which modifies compiled bytecode to add these statements!
+ Many exist, and the one included in slf4j-ext is not intended to
+ compete with these, but merely provide a quick way to get very basic
+ trace information from a given application.
+ </p>
-<p><b>NOTE: BETA RELEASE, NOT PRODUCTION QUALITY</b>
-</p>
+ <p>Java 5 added the Java Instrumentation mechanism, which allows you
+ to provide "Java agents" that can inspect and modify the byte code
+ of the classes as they are loaded. This allows the original class
+ files to remain unchanged, and the transformations done on the byte
+ codes depend on the needs at launch time.
+ </p>
-<p>Quickstart for the impatient:
-<ol>
-<li>Use Java 5 or later.
-<li>Download slf4j-ext-X.Y.Z.jar and javassist.jar, and put them both in the same directory.</li>
-<li>Ensure your application is properly configured with slf4j-api-X.Y.Z.jar and a suitable backend.</li>
-<li>Instead of "java ..." use "java --javaagent:#PATH#/slf4j-ext-X.Y.Z.jar=time,verbose,level=info ..."<br/>
- (replace #PATH# with the path to the jar)
-<li>That's it!
-</ol>
-</p>
+ <p>Given the well-known "Hello World" example:</p>
-<p>
-In some applications logging is used to trace the actual execution of the
-application as opposed to log an occasional event. One approach is using the <a href="#extended_logger">extended
-logger</a> to add statements as appropriately, but another is to use a tool which modifies compiled bytecode
-to add these statements! Many exist, and the one included in slf4j-ext is not intended to compete with these, but
-merely provide a quick way to get very basic trace information from a given application.
-</p>
+ <p class="source">public class HelloWorld {
+ public static void main(String args[]) {
+ System.out.println("Hello World");
+ }
+}</p>
-<p>Java 5 added the Java Instrumentation mechanism, which
-allows you to provide "Java agents" that can inspect and modify the
-byte code of the classes as they are loaded. This allows the original class files to remain unchanged,
-and the transformations done on the byte codes depend on the needs at launch time.
-</p>
+ <p>a typical transformation would be similar to: (imports omitted)</p>
-<p>Given the well-known "Hello World" example:</p>
+ <p class="source">public class LoggingHelloWorld {
+ final static Logger _log = LoggerFactory.getLogger(LoggingHelloWorld.class.getName());
-<p class="source">public class HelloWorld {
- public static void main(String args[]) {
- System.out.println("Hello World");
+ public static void main(String args[]) {
+ if (_log.isInfoEnabled()) {
+ _log.info("> main(args=" + Arrays.asList(args) + ")");
+ }
+ System.out.println("Hello World");
+ if (_log.isInfoEnabled()) {
+ _log.info("< main()");
}
+ }
}</p>
-<p>a typical transformation would be similar to: (imports omitted)</p>
+ <p>which in turn produces the following result when run similar to
+ "java LoggingHelloWorld 1 2 3 4":
+ </p>
-<p class="source">public class LoggingHelloWorld {
- final static Logger _log = LoggerFactory.getLogger(LoggingHelloWorld.class.getName());
+ <p class="source">1 [main] INFO LoggingHelloWorld - > main(args=[1, 2, 3, 4])
+Hello World
+1 [main] INFO LoggingHelloWorld - < main()</p>
- public static void main(String args[]) {
- if (_log.isInfoEnabled()) {
- _log.info("> main(args=" + Arrays.asList(args) + ")");
- }
- System.out.println("Hello World");
- if (_log.isInfoEnabled()) {
- _log.info("< main()");
- }
- }
-}</p>
+ <p>The same effect could have been had by using this command (with
+ the relative path to javassist.jar and
+ slf4j-ext-${project.version}.jar being ../jars):</p>
-<p>which in turn produces the following result when run similar to
-"java LoggingHelloWorld 1 2 3 4":
-</p>
+ <p class="source">java -javaagent:../jars/slf4j-ext-${project.version}.jar HelloWorld 1 2 3 4</p>
-<p class="source">1 [main] INFO LoggingHelloWorld - > main(args=[1, 2, 3, 4])
-Hello World
-1 [main] INFO LoggingHelloWorld - < main()</p>
+ <p></p>
-<p>The same effect could have been had by using this command (with the
-relative path to javassist.jar and slf4j-ext-X.Y.Z.jar being ../jars):</p>
-<p class="source">java -javaagent:../jars/slf4j-ext-X.Y.Z.jar HelloWorld 1 2 3 4</p>
+ <h3>How to use</h3>
+ <p>The javaagent may take one or more options separated by comma. The following options
+ are currently supported:</p>
-<p></p>
+ <dl>
+ <dt><b>level</b>=X</dt>
+ <dd>The log level to use for the generated log statements. X is
+ one of "info", "debug" or "trace". Default is "info".</dd>
+
+ <dt><b>time</b></dt>
+ <dd>Print out the current date at program start, and again when
+ the program ends plus the execution time in milliseconds.</dd>
+
+ <dt><b>verbose</b></dt>
+ <dd>Print out when a class is processed as part of being loaded</dd>
+ <dt><b>ignore</b>=X:Y:...</dt>
+ <dd>(Advanced) Provide full list of colon separated prefixes of
+ class names NOT to add logging to. The default list is { "sun/",
+ "java/", "javax/", "org/slf4j/", "ch/qos/logback/",
+ "org/apache/log4j/", "apple/", "com/sun/" }.
+ </dd>
+ </dl>
+
+ <p>Note: These are not finalized yet, and may change.</p>
-<h3>How to use</h3>
-<p>The javaagent may take one or more options separated by comma. The following options
-are currently supported:</p>
-
-<p>
-<dl>
-<dt><b>level</b>=X</dt>
-<dd>The log level to use for the generated log statements. X is one of "info", "debug" or "trace".
-Default is "info".</dd>
-<dt><b>time</b></dt>
-<dd>Print out the current date at program start, and again when the program ends plus the execution time in milliseconds.</dd>
-<dt><b>verbose</b></dt>
-<dd>Print out when a class is processed as part of being loaded</dd>
-<dt><b>ignore</b>=X:Y:...</dt>
-<dd>(Advanced) Provide full list of colon separated prefixes of class names NOT to add logging to.
-The default list is { "sun/", "java/", "javax/", "org/slf4j/",
- "ch/qos/logback/", "org/apache/log4j/", "apple/", "com/sun/" }.
-</dd>
-</dl>
-
-<p>Note: These are not finalized yet, and may change.</p>
-
-<h3>Locations of jar files</h3>
-<p>
-The javassist library is used for the actual byte code manipulation and must
-be available to be able to add any logging statements. slf4j-ext-X.Y.Z has been
-configured to look for the following:
-
-<ul>
-<li>"javassist-3.4.GA.jar" relatively to slf4j-ext-X.Y.Z as would be if Maven had downloaded both from the repository and slf4j-ext-X.Y.Z.jar was referenced directly in the
-Maven repository in the "-javaagent"-argument.</li>
-<li>"javassist-3.4.GA.jar" in the same directory as slf4j-ext-X.Y.Z</li>
-<li>"javassist.jar" in the same directory as slf4j-ext-X.Y.Z</li>
-</ul>
+ <h3>Locations of jar files</h3>
-A warning message is printed if the javassist library was not found by the agent.
-</p>
+ <p>The javassist library is used for the actual byte code
+ manipulation and must be available to be able to add any logging
+ statements. slf4j-ext-${project.version} has been configured to
+ look for the following:
+ </p>
+ <ul>
+ <li>"javassist-3.4.GA.jar" relatively to
+ slf4j-ext-${project.version} as would be if Maven had downloaded
+ both from the repository and slf4j-ext-${project.version}.jar was
+ referenced directly in the Maven repository in the
+ "-javaagent"-argument.</li>
+ <li>"javassist-3.4.GA.jar" in the same directory as slf4j-ext</li>
+ <li>"javassist.jar" in the same directory as slf4j-ext</li>
+ </ul>
-<h3>Misc notes</h3>
+ <p>A warning message is printed if the javassist library was not
+ found by the agent.
+ </p>
-<p>
-<ul>
-<li>A java agent does not "see" any classes already loaded by the class loader.</li>
-<li>Any exceptions in the java agent that would normally have been printed, are silently swallowed by the JVM.</li>
-<li>The javaagent does not do any logging itself, and the slf4j backend does not need to be available to the agent.
-<li>You MUST remember to have slf4j-api-X.Y.Z.jar explicitly provided to the program to be instrumented. If not, the one
-embedded in the slf4j-ext-X.Y.Z.jar library is used, and these classes cannot see the jars loaded later. (Empirically determined, reference would be appreciated).
-</ul>
-</p>
+ <h3>Misc notes</h3>
-<p>
-(The agent is an adaption of the java.util.logging version described in
-<a href="http://today.java.net/pub/a/today/2008/04/24/add-logging-at-class-load-time-with-instrumentation.html"
->http://today.java.net/pub/a/today/2008/04/24/add-logging-at-class-load-time-with-instrumentation.html</a>)
-</p>
+ <ul>
+ <li>A java agent does not "see" any classes already loaded by the
+ class loader.</li>
+ <li>Any exceptions in the java agent that would normally have been
+ printed, are silently swallowed by the JVM.</li>
+ <li>The javaagent does not do any logging itself, and the slf4j
+ backend does not need to be available to the agent. </li>
+
+ <li>You MUST remember to have slf4j-api-${project.version}.jar explicitly
+ provided to the program to be instrumented. If not, the one
+ embedded in the slf4j-ext-X.Y.Z.jar library is used, and these
+ classes cannot see the jars loaded later. (Empirically
+ determined, reference would be appreciated).
+ </li>
+ </ul>
+
+ <p>(The agent is an adaption of the java.util.logging version
+ described in <a
+ href="http://today.java.net/pub/a/today/2008/04/24/add-logging-at-class-load-time-with-instrumentation.html"
+ >http://today.java.net/pub/a/today/2008/04/24/add-logging-at-class-load-time-with-instrumentation.html</a>)
+ </p>
</div>
</body>
</html>
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 Thu Nov 13 12:34:03 2008
@@ -1,1064 +1,1047 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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>SLF4J FAQ</title>
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
-</head>
-<body>
- <script>
-prefix='';
-</script>
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
-
- <div class="section">
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <title>SLF4J FAQ</title>
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';</script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
- <h2><a name="top">Frequently Asked Questions about SLF4J</a></h2>
+ <div id="content">
- <p><b>Generalities</b></p>
+ <h2><a name="top">Frequently Asked Questions about SLF4J</a></h2>
- <ol type="1">
- <li><a href="#what_is">What is SLF4J?</a></li>
+ <p><b>Generalities</b></p>
+
+ <ol type="1">
+ <li><a href="#what_is">What is SLF4J?</a></li>
+
+ <li><a href="#when">When should SLF4J be used?</a></li>
+
+ <li><a href="#yet_another_facade"> Is SLF4J yet another loggingfacade?</a></li>
+
+ <li><a href="#why_new_project"> If SLF4J fixes JCL, then why
+ wasn't the fix made in JCL instead of creating a new project?
+ </a>
+ </li>
+
+ <li><a href="#need_to_recompile"> When using SLF4J, do I have to
+ recompile my application to switch to a different logging
+ system?
+ </a>
+ </li>
+
+ <li><a href="#requirements">What are SLF4J's requirements?</a></li>
+
+
+ <li>
+ <a href="#license">Why is SLF4J licensed under X11 type
+ license instead of the Apache Software License?
+ </a>
+ </li>
+
+ <li>
+ <a href="#where_is_binding">Where can I get a particular
+ SLF4J binding?
+ </a>
+ </li>
+
+ <li>
+ <a href="#configure_logging">Should my library attempt to
+ configure logging?
+ </a>
+ </li>
+
+ <li>
+ <a href="#maven2">What about Maven 2 transitive
+ dependencies?
+ </a>
+ </li>
+
+ <li>
+ <a href="#excludingJCL">How do I exclude commons-logging as a
+ Maven dependency?
+ </a>
+ </li>
+ </ol>
+
+
+ <b>About the SLF4J API</b>
+
+ <ol type="1">
+
+ <li>
+ <a href="#string_or_object"> Why don't the printing methods
+ in the Logger interface accept message of type Object, but only
+ messages of type String?
+ </a>
+ </li>
+
+ <li>
+ <a href="#exception_message">
+ Can I log an exception without an accompanying message?
+ </a>
+ </li>
+
+
+ <li>
+ <a href="#logging_performance"> What is the fastest way of
+ (not) logging?
+ </a>
+ </li>
+
+ <li>
+ <a href="#string_contents"> How can I log the string contents
+ of a single (possibly complex) object?
+ </a>
+ </li>
+
+
+ <li><a href="#fatal"> Why doesn't the
+ <code>org.slf4j.Logger</code> interface have methods for the
+ FATAL level? </a></li>
+
+ <li><a href="#trace">Why was the TRACE level introduced only in
+ SLF4J version 1.4.0? </a></li>
+
+ <li><a href="#i18n">Does the SLF4J logging API support I18N
+ (internationalization)? </a></li>
+
+ </ol>
+
+
+
+ <b>Implementing the SLF4J API</b>
+
+ <ol type="1">
+
+ <li><a href="#slf4j_compatible"> How do I make my logging
+ framework SLF4J compatible? </a></li>
+
+ <li><a href="#marker_interface"> How can my logging system add
+ support for the <code>Marker</code> interface? </a></li>
+
+ <li><a href="#version_checks">How does SLF4J's version check
+ mechanism work? </a></li>
+
+
+ </ol>
+
+
+ <b>General questions about logging</b>
+
+
+ <ol type="1">
+
+ <li><a href="#declared_static"> Should Logger members of a class
+ be declared as static? </a></li>
+
+
+ <li><a href="#declaration_pattern">Is there a recommended idiom
+ for declaring a loggers in a class?</a></li>
+
+ </ol>
+
+ <h2>Generalities</h2>
+
+ <dl>
+ <dt><a name="what_is" href="#what_is">What is SLF4J?</a></dt>
+ <dd>
+ <p>SLF4J is a simple facade for logging systems allowing the
+ end-user to plug-in the desired logging system at deployment
+ time.
+ </p>
- <li><a href="#when">When should SLF4J be used?</a></li>
+ <hr />
+ </dd>
+
+ <dt><a name="when" href="#when"> When should SLF4J be used?
+ </a></dt>
+
+ <dd>
+ <p>In short, libraries and other embedded components should
+ consider SLF4J for their logging needs because libraries
+ cannot afford to impose their choice of logging system on the
+ end-user. On the other hand, it does not necessarily make
+ sense for stand-alone applications to use SLF4J. Stand-alone
+ applications can invoke the logging system of their choice
+ directly.
+ </p>
- <li><a href="#yet_another_facade"> Is SLF4J yet another loggingfacade?</a></li>
+ <p>SLF4J is only a facade, meaning that it does not provide a
+ complete logging solution. Operations such as configuring
+ appenders or setting logging levels cannot be performed with
+ SLF4J. Thus, at some point in time, any non-trivial
+ application will need to directly invoke the underlying
+ logging system. In other words, complete independence from the
+ API underlying logging system is not possible for a
+ stand-alone application. Nevertheless, SLF4J reduces the
+ impact of this dependence to near-painless levels.
+ </p>
- <li>
- <a href="#why_new_project"> If SLF4J fixes JCL, then why
- wasn't the fix made in JCL instead of creating a new project?
- </a>
- </li>
-
- <li>
- <a href="#need_to_recompile"> When using SLF4J, do I have to
- recompile my application to switch to a different logging
- system?
- </a>
- </li>
-
- <li><a href="#requirements">What are SLF4J's requirements?</a></li>
-
-
- <li>
- <a href="#license">Why is SLF4J licensed under X11 type
- license instead of the Apache Software License?
- </a>
- </li>
-
- <li>
- <a href="#where_is_binding">Where can I get a particular
- SLF4J binding?
- </a>
- </li>
-
- <li>
- <a href="#configure_logging">Should my library attempt to
- configure logging?
- </a>
- </li>
-
- <li>
- <a href="#maven2">What about Maven 2 transitive
- dependencies?
- </a>
- </li>
-
- <li>
- <a href="#excludingJCL">How do I exclude commons-logging as a
- Maven dependency?
- </a>
- </li>
- </ol>
-
-
- <b>About the SLF4J API</b>
+ <p>Suppose that your CRM application uses log4j for its
+ logging. However, one of your important clients request that
+ logging be performed through JDK 1.4 logging. If your
+ application is riddled with thousands of direct log4j calls,
+ migration to JDK 1.4 would be a long and error-prone
+ process. Had you been invoking SLF4J API instead of log4j, the
+ migration could be completed in a matter of minutes instead of
+ hours.
+ </p>
+
+ <p>SLF4J lets component developers to defer the choice of the
+ logging system to the end-user but eventually a choice needs
+ to be made.
+ </p>
+
+ <hr />
+
+ </dd>
+
+ <dt>
+ <a name="yet_another_facade" href="#yet_another_facade">
+ Is SLF4J yet another logging facade? </a>
+ </dt>
- <ol type="1">
+ <dd>
+ <p>SLF4J is conceptually very similar to JCL. As such, it can
+ be thought of as yet another logging facade. However, SLF4J is
+ much simpler in design and arguably more robust. In a
+ nutshell, SLF4J avoid the class loader issues that plague JCL.
+ </p>
- <li>
- <a href="#string_or_object"> Why don't the printing methods
- in the Logger interface accept message of type Object, but only
- messages of type String?
- </a>
- </li>
-
- <li>
- <a href="#exception_message">
- Can I log an exception without an accompanying message?
- </a>
- </li>
-
-
- <li>
- <a href="#logging_performance"> What is the fastest way of
- (not) logging?
- </a>
- </li>
-
- <li>
- <a href="#string_contents"> How can I log the string contents
- of a single (possibly complex) object?
- </a>
- </li>
-
-
- <li><a href="#fatal"> Why doesn't the
- <code>org.slf4j.Logger</code> interface have methods for the
- FATAL level? </a></li>
-
- <li><a href="#trace">Why was the TRACE level introduced only in
- SLF4J version 1.4.0? </a></li>
-
- <li><a href="#i18n">Does the SLF4J logging API support I18N
- (internationalization)? </a></li>
-
-
- </ol>
-
-
-
- <b>Implementing the SLF4J API</b>
-
- <ol type="1">
-
- <li><a href="#slf4j_compatible"> How do I make my logging
- framework SLF4J compatible? </a></li>
-
- <li><a href="#marker_interface"> How can my logging system add
- support for the <code>Marker</code> interface? </a></li>
-
- <li><a href="#version_checks">How does SLF4J's version check
- mechanism work? </a></li>
-
-
- </ol>
-
-
- <b>General questions about logging</b>
-
-
- <ol type="1">
-
- <li><a href="#declared_static"> Should Logger members of a class
- be declared as static? </a></li>
-
-
- <li><a href="#declaration_pattern">Is there a recommended idiom
- for declaring a loggers in a class?</a></li>
-
- </ol>
-
- </div>
-
-
- <div class="section">
-
- <h2>Generalities</h2>
+ <hr />
+
+ </dd>
+ <dt>
+ <a name="why_new_project" href="#why_new_project">
+ If SLF4J fixes JCL, then why wasn't the fix made in JCL
+ instead of creating a new project?
+ </a>
+ </dt>
- <dl>
- <dt><a name="what_is" href="#what_is">What is SLF4J?</a></dt>
- <dd>
- <p>SLF4J is a simple facade for logging systems allowing the
- end-user to plug-in the desired logging system at deployment
- time.
- </p>
-
- <hr />
- </dd>
-
- <dt><a name="when" href="#when"> When should SLF4J be used?
- </a></dt>
+ <dd>
+ <p>This is a very good question. First, SLF4J static binding
+ approach is very simple, perhaps even laughably so. It was
+ not easy to convince developers of the validity of that
+ approach. It is only after SLF4J was released and started to
+ become accepted did it gain respectability in the relevant
+ community.
+ </p>
- <dd>
- <p>In short, libraries and other embedded components should
- consider SLF4J for their logging needs because libraries
- cannot afford to impose their choice of logging system on the
- end-user. On the other hand, it does not necessarily make
- sense for stand-alone applications to use SLF4J. Stand-alone
- applications can invoke the logging system of their choice
- directly.
- </p>
-
- <p>SLF4J is only a facade, meaning that it does not provide a
- complete logging solution. Operations such as configuring
- appenders or setting logging levels cannot be performed with
- SLF4J. Thus, at some point in time, any non-trivial
- application will need to directly invoke the underlying
- logging system. In other words, complete independence from the
- API underlying logging system is not possible for a
- stand-alone application. Nevertheless, SLF4J reduces the
- impact of this dependence to near-painless levels.
- </p>
-
- <p>Suppose that your CRM application uses log4j for its
- logging. However, one of your important clients request that
- logging be performed through JDK 1.4 logging. If your
- application is riddled with thousands of direct log4j calls,
- migration to JDK 1.4 would be a long and error-prone
- process. Had you been invoking SLF4J API instead of log4j, the
- migration could be completed in a matter of minutes instead of
- hours.
- </p>
-
- <p>SLF4J lets component developers to defer the choice of the
- logging system to the end-user but eventually a choice needs
- to be made.
- </p>
-
- <hr />
+ <p>Second, SLF4J offers two enhancements which tend to be
+ underestimated. Parameterized log messages solve an important
+ problem associated with logging performance, in a pragmatic
+ way. Marker objects, which are supported by the
+ <code>org.slf4j.Logger</code> interface, pave the way for
+ adoption of advanced logging systems and still leave the door
+ open to switching back to more traditional logging systems if
+ need be.
+ </p>
- </dd>
-
- <dt>
- <a name="yet_another_facade" href="#yet_another_facade">
- Is SLF4J yet another logging facade? </a>
- </dt>
-
- <dd>
- <p>SLF4J is conceptually very similar to JCL. As such, it can
- be thought of as yet another logging facade. However, SLF4J is
- much simpler in design and arguably more robust. In a
- nutshell, SLF4J avoid the class loader issues that plague JCL.
- </p>
-
- <hr />
-
- </dd>
- <dt>
- <a name="why_new_project" href="#why_new_project">
- If SLF4J fixes JCL, then why wasn't the fix made in JCL
- instead of creating a new project?
- </a>
- </dt>
-
- <dd>
- <p>This is a very good question. First, SLF4J static binding
- approach is very simple, perhaps even laughably so. It was
- not easy to convince developers of the validity of that
- approach. It is only after SLF4J was released and started to
- become accepted did it gain respectability in the relevant
- community.
- </p>
-
- <p>Second, SLF4J offers two enhancements which tend to be
- underestimated. Parameterized log messages solve an important
- problem associated with logging performance, in a pragmatic
- way. Marker objects, which are supported by the
- <code>org.slf4j.Logger</code> interface, pave the way for
- adoption of advanced logging systems and still leave the door
- open to switching back to more traditional logging systems if
- need be.
- </p>
-
- <hr />
- </dd>
-
- <dt>
- <a name="need_to_recompile" href="#need_to_recompile"> When
- using SLF4J, do I have to recompile my application to switch
- to a different logging system? </a>
- </dt>
-
- <dd>
- <p>No, you do not need to recompile your application. You can
- switch to a different logging system by removing the previous
- SLF4J binding and replacing it with the binding of your choice.
- </p>
-
- <p>For example, if you were using the NOP implementation and
- would like to switch to log4j version 1.2, simply replace
- <em>slf4j-nop.jar</em> with <em>slf4j-log4j12.jar</em> on
- your class path but do not forget to add log4j-1.2.x.jar as
- well. Want to switch to JDK 1.4 logging? Just replace
- <em>slf4j-log4j12.jar</em> with <em>slf4j-jdk14.jar</em>.
- </p>
-
- <hr />
- </dd>
- <dt>
- <a name="requirements" href="#requirements">What are SLF4J's
- requirements?</a>
- </dt>
-
- <dd>
-
- <p>In principle, SLF4J requires JDK 1.3 or above, in
- particular slf4j-api is compatible with JDK 1.3. However,
- the underlying logging system might have a higher
- requirement. For instance, the <em>slf4j-jdk14</em> binding
- requires JDK 1.4. Logback requires JDK 1.5.
- </p>
-
- <p> </p>
-
- <table border="1">
- <tr align="left">
- <th>Binding</th>
- <th>Requirements</th>
- </tr>
-
- <tr>
- <td>slf4j-nop</td>
- <td>JDK 1.3</td>
- </tr>
- <tr>
- <td>slf4j-simple</td>
- <td>JDK 1.3</td>
- </tr>
-
- <tr>
- <td>slf4j-log4j12</td>
- <td align="left">JDK 1.3, plus any other library
- dependencies required by the log4j appenders in use</td>
- </tr>
- <tr>
- <td>slf4j-jdk14</td>
- <td>JDK 1.4 or above</td>
- </tr>
- <tr>
- <td>logback-classic</td>
- <td>JDK 1.5 or above, plus any other library dependencies
- required by the logback appenders in use</td>
- </tr>
-
- </table>
-
- <hr />
- </dd>
-
- <dt>
- <a name="license" href="#license">
- Why is SLF4J licensed under X11 type license instead of the
- Apache Software License?
- </a>
- </dt>
-
- <dd>
- <p>SLF4J is licensed under a permissive X11 type license
- instead of the <a
- href="http://www.apache.org/licenses/">ASL</a> or the <a
- href="http://www.gnu.org/copyleft/lesser.html">LGPL</a>
- because the X11 license is deemed by both the Apache Software
- Foundation as well as the Free Software Foundation as
- compatible with their respective licenses.
- </p>
-
- <hr />
- </dd>
- <dt>
- <a name="where_is_binding" href="#where_is_binding">
- Where can I get a particular SLF4J binding?
- </a>
- </dt>
-
- <dd>
+ <hr />
+ </dd>
+
+ <dt>
+ <a name="need_to_recompile" href="#need_to_recompile"> When
+ using SLF4J, do I have to recompile my application to switch
+ to a different logging system? </a>
+ </dt>
+
+ <dd>
+ <p>No, you do not need to recompile your application. You can
+ switch to a different logging system by removing the previous
+ SLF4J binding and replacing it with the binding of your choice.
+ </p>
+
+ <p>For example, if you were using the NOP implementation and
+ would like to switch to log4j version 1.2, simply replace
+ <em>slf4j-nop.jar</em> with <em>slf4j-log4j12.jar</em> on
+ your class path but do not forget to add log4j-1.2.x.jar as
+ well. Want to switch to JDK 1.4 logging? Just replace
+ <em>slf4j-log4j12.jar</em> with <em>slf4j-jdk14.jar</em>.
+ </p>
+
+ <hr />
+ </dd>
+ <dt>
+ <a name="requirements" href="#requirements">What are SLF4J's
+ requirements?</a>
+ </dt>
+
+ <dd>
+
+ <p>In principle, SLF4J requires JDK 1.3 or above, in
+ particular slf4j-api is compatible with JDK 1.3. However,
+ the underlying logging system might have a higher
+ requirement. For instance, the <em>slf4j-jdk14</em> binding
+ requires JDK 1.4. Logback requires JDK 1.5.
+ </p>
+
+ <p> </p>
+
+ <table border="1">
+ <tr align="left">
+ <th>Binding</th>
+ <th>Requirements</th>
+ </tr>
- <p>SLF4J bindings for <a
- href="api/org/slf4j/impl/SimpleLogger.html">SimpleLogger</a>,
- <a href="api/org/slf4j/impl/NOPLogger.html">NOPLogger</a>, <a
- href="api/org/slf4j/impl/Log4jLoggerAdapter.html">Log4jLoggerAdapter</a>
- and <a
- href="api/org/slf4j/impl/JDK14LoggerAdapter.html">JDK14LoggerAdapter</a>
- are contained within the files <em>slf4j-nop.jar</em>,
- <em>slf4j-simple.jar</em>, <em>slf4j-log4j12.jar</em>, and
- <em>slf4j-jdk14.jar</em>. These files ship with the <a
- href="download.html">official SLF4J distribution</a>. Please
- note that all bindings depend on <em>slf4j-api.jar</em>.
- </p>
+ <tr>
+ <td>slf4j-nop</td>
+ <td>JDK 1.3</td>
+ </tr>
+ <tr>
+ <td>slf4j-simple</td>
+ <td>JDK 1.3</td>
+ </tr>
- <p>The binding for logback-classic ships with the <a
- href="http://logback.qos.ch/download.html">logback
- distribution</a>. However, as with all other bindings, the
- logback-classic binding requires <em>slf4j-api.jar</em>.
- </p>
-
+ <tr>
+ <td>slf4j-log4j12</td>
+ <td align="left">JDK 1.3, plus any other library
+ dependencies required by the log4j appenders in use</td>
+ </tr>
+ <tr>
+ <td>slf4j-jdk14</td>
+ <td>JDK 1.4 or above</td>
+ </tr>
+ <tr>
+ <td>logback-classic</td>
+ <td>JDK 1.5 or above, plus any other library dependencies
+ required by the logback appenders in use</td>
+ </tr>
+
+ </table>
+
<hr />
- </dd>
-
- <dt><a name="configure_logging" href="#configure_logging">
- Should my library attempt to configure logging? </a>
- </dt>
-
- <dd>
- <p>Embedded components such as libraries do not need and
- should not configure the underlying logging system. They
- invoke SLF4J to log but should let the end-user configure the
- logging environment. When embedded components try to configure
- logging on their own, they often override the end-user's
- wishes. At the end of the day, it is the end-user who has to
- read the logs and process them. She should be the person to
- decide how she wants her logging configured.
- </p>
-
- <hr/>
- </dd>
-
- <dt><a name="maven2" href="#maven2">What about Maven2
- transitive dependencies? </a>
- </dt>
-
- <dd>
- <p>As an author of a library built with Maven2, you might
- want to test your application using a binding, say
- slf4j-log4j12 or logback-classic, without forcing log4j or
- logback-classic as a dependency upon your users. As of SLF4J
- version 1.3, this quite easy to accomplish. But first, since
- your library's code depends on the SLF4J API you will need to
- declare slf4j-api as a compile-time (default scope)
- dependency.
- </p>
- <p> </p>
- <p class="source"><dependency>
+ </dd>
+
+ <dt>
+ <a name="license" href="#license">
+ Why is SLF4J licensed under X11 type license instead of the
+ Apache Software License?
+ </a>
+ </dt>
+
+ <dd>
+ <p>SLF4J is licensed under a permissive X11 type license
+ instead of the <a
+ href="http://www.apache.org/licenses/">ASL</a> or the <a
+ href="http://www.gnu.org/copyleft/lesser.html">LGPL</a>
+ because the X11 license is deemed by both the Apache Software
+ Foundation as well as the Free Software Foundation as
+ compatible with their respective licenses.
+ </p>
+
+ <hr />
+ </dd>
+ <dt>
+ <a name="where_is_binding" href="#where_is_binding">
+ Where can I get a particular SLF4J binding?
+ </a>
+ </dt>
+
+ <dd>
+
+ <p>SLF4J bindings for <a
+ href="api/org/slf4j/impl/SimpleLogger.html">SimpleLogger</a>,
+ <a href="api/org/slf4j/impl/NOPLogger.html">NOPLogger</a>, <a
+ href="api/org/slf4j/impl/Log4jLoggerAdapter.html">Log4jLoggerAdapter</a>
+ and <a
+ href="api/org/slf4j/impl/JDK14LoggerAdapter.html">JDK14LoggerAdapter</a>
+ are contained within the files <em>slf4j-nop.jar</em>,
+ <em>slf4j-simple.jar</em>, <em>slf4j-log4j12.jar</em>, and
+ <em>slf4j-jdk14.jar</em>. These files ship with the <a
+ href="download.html">official SLF4J distribution</a>. Please
+ note that all bindings depend on <em>slf4j-api.jar</em>.
+ </p>
+
+ <p>The binding for logback-classic ships with the <a
+ href="http://logback.qos.ch/download.html">logback
+ distribution</a>. However, as with all other bindings, the
+ logback-classic binding requires <em>slf4j-api.jar</em>.
+ </p>
+
+ <hr />
+ </dd>
+
+ <dt><a name="configure_logging" href="#configure_logging">
+ Should my library attempt to configure logging? </a>
+ </dt>
+
+ <dd>
+ <p>Embedded components such as libraries do not need and
+ should not configure the underlying logging system. They
+ invoke SLF4J to log but should let the end-user configure the
+ logging environment. When embedded components try to configure
+ logging on their own, they often override the end-user's
+ wishes. At the end of the day, it is the end-user who has to
+ read the logs and process them. She should be the person to
+ decide how she wants her logging configured.
+ </p>
+
+ <hr/>
+ </dd>
+
+ <dt><a name="maven2" href="#maven2">What about Maven2
+ transitive dependencies? </a>
+ </dt>
+
+ <dd>
+ <p>As an author of a library built with Maven2, you might
+ want to test your application using a binding, say
+ slf4j-log4j12 or logback-classic, without forcing log4j or
+ logback-classic as a dependency upon your users. As of SLF4J
+ version 1.3, this quite easy to accomplish. But first, since
+ your library's code depends on the SLF4J API you will need to
+ declare slf4j-api as a compile-time (default scope)
+ dependency.
+ </p>
+ <p> </p>
+ <p class="source"><dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>${project.version}</version>
</dependency></p>
-
- <p> </p>
-
- <p>Limiting the transitivity of the SLF4J binding used in your
- tests can be accomplished by declaring the scope of the
- SLF4J-binding dependency as "test". Here is an example:</p>
-
- <p> </p>
-
- <p class="source"><dependency>
+
+ <p> </p>
+
+ <p>Limiting the transitivity of the SLF4J binding used in your
+ tests can be accomplished by declaring the scope of the
+ SLF4J-binding dependency as "test". Here is an example:</p>
+
+ <p> </p>
+
+ <p class="source"><dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<version>${project.version}</version>
<b><scope>test</scope></b>
</dependency></p>
-
- <p>Thus, as far as your users are concerned you are exporting
- slf4j-api as a transitive dependency of your library, but not
- any SLF4J-binding or an underlying logging system.
- </p>
-
- <hr/>
-
- </dd>
-
-
- <dt>
- <a name="excludingJCL">How do I exclude commons-logging as a
- Maven dependency?
- </a>
- </dt>
-
- <dd>
- <p>A large number of Maven projects declare commons-logging
- as a dependency. Thus, if you wish to migrate to SLF4J or use
- jcl-over-slf4j, you would need to declare a commons-logging
- exclusion in all of your dependencies which transitively
- depend on commons-logging. This can be an error prone
- process. To alleviate the pain, Erik van Oosten has developed
- a <a
- href="http://day-to-day-stuff.blogspot.com/2007/10/announcement-version-99-does-not-exist.html">clever
- hack around this problem.</a>
- </p>
- </dd>
-
-
- </dl>
- </div>
-
- <div class="section">
-
-
- <h2>About the SLF4J API</h2>
-
- <dl>
-
- <dt><a name="string_or_object" href="#string_or_object"> Why
- don't the printing methods in the Logger interface accept
- message of type Object, but only messages of type String? </a>
- </dt>
-
- <dd>
-
- <p>In SLF4J 1.0beta4, the printing methods such as debug(),
- info(), warn(), error() in the <a
- href="api/org/slf4j/Logger.html">Logger interface</a> were
- modified so as to accept only messages of type String
- instead of Object.
- </p>
-
- <p>Thus, the set of printing methods for the DEBUG level
- became:</p>
-
- <p class="source">debug(String msg);
+
+ <p>Thus, as far as your users are concerned you are exporting
+ slf4j-api as a transitive dependency of your library, but not
+ any SLF4J-binding or an underlying logging system.
+ </p>
+
+ <hr/>
+
+ </dd>
+
+
+ <dt>
+ <a name="excludingJCL">How do I exclude commons-logging as a
+ Maven dependency?
+ </a>
+ </dt>
+
+ <dd>
+ <p>A large number of Maven projects declare commons-logging
+ as a dependency. Thus, if you wish to migrate to SLF4J or use
+ jcl-over-slf4j, you would need to declare a commons-logging
+ exclusion in all of your dependencies which transitively
+ depend on commons-logging. This can be an error prone
+ process. To alleviate the pain, Erik van Oosten has developed
+ a <a
+ href="http://day-to-day-stuff.blogspot.com/2007/10/announcement-version-99-does-not-exist.html">clever
+ hack around this problem.</a>
+ </p>
+ </dd>
+
+
+ </dl>
+
+
+ <h2>About the SLF4J API</h2>
+
+ <dl>
+
+ <dt><a name="string_or_object" href="#string_or_object"> Why
+ don't the printing methods in the Logger interface accept
+ message of type Object, but only messages of type String? </a>
+ </dt>
+
+ <dd>
+
+ <p>In SLF4J 1.0beta4, the printing methods such as debug(),
+ info(), warn(), error() in the <a
+ href="api/org/slf4j/Logger.html">Logger interface</a> were
+ modified so as to accept only messages of type String
+ instead of Object.
+ </p>
+
+ <p>Thus, the set of printing methods for the DEBUG level
+ became:</p>
+
+ <p class="source">debug(String msg);
debug(String format, Object arg);
debug(String format, Object arg1, Object arg2);
debug(String msg, Throwable t);</p>
-
- <p>Previously, the first argument in the above methods was of
- type <code>Object</code>.</p>
-
- <p>This change enforces the notion that logging systems are
- about decorating and handling messages of type String, and not
- any arbitrary type (Object).
- </p>
-
- <p>Just as importantly, the new set of method signatures offer
- a clearer differentiation between the overloaded methods
- whereas previously the choice of the invoked method due to
- Java overloading rules were not always easy to follow.</p>
-
- <p>It was also easy to make mistakes. For example, previously
- it was legal to write:</p>
-
- <p class="source">logger.debug(new Exception("some error"));</p>
-
- <p>Unfortunately, the above call did not print the stack trace
- of the exception. Thus, a potentially crucial piece of
- information could be lost. When the first parameter is
- restricted to be of type String, then only the method
- </p>
-
- <p class="source">debug(String msg, Throwable t)</p>
-
- <p>can be used to log exceptions. Note that this method
- ensures that every logged exception is accompanied with a
- descriptive message.</p>
-
- <hr />
- </dd>
-
- <dt>
-
- <a name="exception_message" href="#exception_message">
- Can I log an exception without an accompanying message?
- </a>
- </dt>
- <dd>
- <p>In short, no.</p>
-
- <p>If <code>e</code> is an <code>Exception</code>, and you
- would like to log an exception at the ERROR level, you must
- add an accompanying message. For example,</p>
-
- <p class="source">logger.error("some accompanying message", e);</p>
-
- <p>You might correctly observe that not all exceptions have a
- meaningful message to accompany them. Moreover, a good
- exception should already contain a self explanatory
- description. The accompanying message may therefore be
- considered redundant.
- </p>
-
-
- <p>While these are valid arguments, there are three opposing
- arguments also worth considering. First, on many, albeit not
- all occasions, the accompanying message can convey useful
- information nicely complementing the description contained
- in the exception. Frequently, at the point where the
- exception is logged, the developer has access to more
- contextual information than at the point where the exception
- is thrown. Second, it is not difficult to imagine more or
- less generic messages, e.g. "Exception caught", "Exception
- follows", that can be used as the first argument for
- <code>error(String msg, Throwable t)</code> invocations.
- Third, most log output formats display the message on a
- line, followed by the exception on a separate line. Thus,
- the message line would look inconsistent without a message.
- </p>
-
- <p>In short, if the user were allowed to log an exception
- without an accompanying message, it would be the job of the
- logging system to invent a message. This is actually what
- the <a href="http://tinyurl.com/cr9kg">throwing(String
- sourceClass, String sourceMethod, Throwable thrown)</a>
- method in java.util.logging package does. (It decides on its
- own that accompanying message is the string "THROW".)
- </p>
-
- <p>It may initially appear strange to require an accompanying
- message to log an exception. Nevertheless, this is common
- practice in <em>all</em> log4j derived systems such as
- java.util.logging, logkit, etc. and of course log4j itself. It
- seems that the current consensus considers requiring an
- accompanying message as a good a thing (TM).
- </p>
-
- <hr/>
- </dd>
-
-
-
- <dt><a name="logging_performance" href="#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>
-
- <p>incurs the cost of constructing the message parameter, that
- is converting both integer <code>i</code> and
- <code>entry[i]</code> to a String, and concatenating
- intermediate strings. This, regardless of whether the message
- will be logged or not.
- </p>
-
- <p>One possible way to avoid the cost of parameter
- construction is by surrounding the log statement with a
- test. Here is an example.</p>
-
- <p class="source">if(logger.isDebugEnabled()) {
- logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
-}</p>
-
-
- <p>This way you will not incur the cost of parameter
- construction if debugging is disabled for
- <code>logger</code>. On the other hand, if the logger is
- enabled for the DEBUG level, you will incur the cost of
- evaluating whether the logger is enabled or not, twice: once in
- <code>debugEnabled</code> and once in <code>debug</code>. This
- is an insignificant overhead because evaluating a logger takes
- less than 1% of the time it takes to actually log a statement.
- </p>
-
- <p><b>Better yet, use 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>Previously, the first argument in the above methods was of
+ type <code>Object</code>.</p>
+
+ <p>This change enforces the notion that logging systems are
+ about decorating and handling messages of type String, and not
+ any arbitrary type (Object).
+ </p>
+
+ <p>Just as importantly, the new set of method signatures offer
+ a clearer differentiation between the overloaded methods
+ whereas previously the choice of the invoked method due to
+ Java overloading rules were not always easy to follow.</p>
+
+ <p>It was also easy to make mistakes. For example, previously
+ it was legal to write:</p>
+
+ <p class="source">logger.debug(new Exception("some error"));</p>
+
+ <p>Unfortunately, the above call did not print the stack trace
+ of the exception. Thus, a potentially crucial piece of
+ information could be lost. When the first parameter is
+ restricted to be of type String, then only the method
+ </p>
+
+ <p class="source">debug(String msg, Throwable t)</p>
+
+ <p>can be used to log exceptions. Note that this method
+ ensures that every logged exception is accompanied with a
+ descriptive message.</p>
+
+ <hr />
+ </dd>
+
+ <dt>
+ <a name="exception_message" href="#exception_message">
+ Can I log an exception without an accompanying message?
+ </a>
+ </dt>
+ <dd>
+ <p>In short, no.</p>
+
+ <p>If <code>e</code> is an <code>Exception</code>, and you
+ would like to log an exception at the ERROR level, you must
+ add an accompanying message. For example,</p>
+
+ <p class="source">logger.error("some accompanying message", e);</p>
+
+ <p>You might correctly observe that not all exceptions have a
+ meaningful message to accompany them. Moreover, a good
+ exception should already contain a self explanatory
+ description. The accompanying message may therefore be
+ considered redundant.
+ </p>
+
+
+ <p>While these are valid arguments, there are three opposing
+ arguments also worth considering. First, on many, albeit not
+ all occasions, the accompanying message can convey useful
+ information nicely complementing the description contained
+ in the exception. Frequently, at the point where the
+ exception is logged, the developer has access to more
+ contextual information than at the point where the exception
+ is thrown. Second, it is not difficult to imagine more or
+ less generic messages, e.g. "Exception caught", "Exception
+ follows", that can be used as the first argument for
+ <code>error(String msg, Throwable t)</code> invocations.
+ Third, most log output formats display the message on a
+ line, followed by the exception on a separate line. Thus,
+ the message line would look inconsistent without a message.
+ </p>
+
+ <p>In short, if the user were allowed to log an exception
+ without an accompanying message, it would be the job of the
+ logging system to invent a message. This is actually what
+ the <a href="http://tinyurl.com/cr9kg">throwing(String
+ sourceClass, String sourceMethod, Throwable thrown)</a>
+ method in java.util.logging package does. (It decides on its
+ own that accompanying message is the string "THROW".)
+ </p>
+
+ <p>It may initially appear strange to require an accompanying
+ message to log an exception. Nevertheless, this is common
+ practice in <em>all</em> log4j derived systems such as
+ java.util.logging, logkit, etc. and of course log4j itself. It
+ seems that the current consensus considers requiring an
+ accompanying message as a good a thing (TM).
+ </p>
+
+ <hr/>
+ </dd>
+
+
+
+ <dt>
+ <a name="logging_performance" href="#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>
+
+ <p>incurs the cost of constructing the message parameter, that
+ is converting both integer <code>i</code> and
+ <code>entry[i]</code> to a String, and concatenating
+ intermediate strings. This, regardless of whether the message
+ will be logged or not.
+ </p>
+
+ <p>One possible way to avoid the cost of parameter
+ construction is by surrounding the log statement with a
+ test. Here is an example.</p>
+
+ <p class="source">if(logger.isDebugEnabled()) {
+ logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
+}</p>
+
+
+ <p>This way you will not incur the cost of parameter
+ construction if debugging is disabled for
+ <code>logger</code>. On the other hand, if the logger is
+ enabled for the DEBUG level, you will incur the cost of
+ evaluating whether the logger is enabled or not, twice: once in
+ <code>debugEnabled</code> and once in <code>debug</code>. This
+ is an insignificant overhead because evaluating a logger takes
+ less than 1% of the time it takes to actually log a statement.
+ </p>
+
+ <p><b>Better yet, use 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();
logger.debug("The entry is {}.", entry);</p>
-
- <p>After evaluating 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 class="source">logger.debug("The new entry is "+entry+".");
+
+ <p>After evaluating 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 class="source">logger.debug("The new entry is "+entry+".");
logger.debug("The new entry is {}.", entry);</p>
-
-
- <p>A two argument variant is also available. For example, you
- can write:</p>
-
-
- <p class="source">logger.debug("The new entry is {}. It replaces {}.", entry, oldEntry);</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>Array type arguments, including multi-dimensional arrays,
- are also supported.</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 about 10 times
- faster but at the cost of being non-standard and less
- flexible.
- </p>
-
- <p><b>Escaping the "{}" pair</b></p>
-
- <p>The "{}" pair is called the <em>formatting anchor</em>. It
- serves to designate the location where arguments need to be
- substituted within the message pattern.
- </p>
-
- <p>SLF4J only cares about the <em>formatting anchor</em>, that
- is the '{' character immediately followed by '}'. Thus, in
- case your message contains the '{' or the '}' character, you
- do not have to do anything special unless the '}' character
- immediately follows '}'. For example,
- </p>
-
- <p class="source">logger.debug("Set {1,2} differs from {}", "3");</p>
-
- <p>which will print as "Set {1,2} differs from 3". </p>
-
- <p>You could have even written,</p>
- <p class="source">logger.debug("Set {1,2} differs from {{}}", "3");</p>
- <p>which would have printed as "Set {1,2} differs from {3}". </p>
-
- <p>In the extremely rare case where the the "{}" pair occurs
- naturally within your text and you wish to disable the special
- meaning of the formatting anchor, then you need to escape the
- '{' character with '\', that is the backslash character. Only
- the '{' character should be escaped. There is no need to
- escape the '}' character. For example,
- </p>
-
- <p class="source">logger.debug("Set \\{} differs from {}", "3");</p>
-
- <p>will print as "Set {} differs from 3". Note that within
- Java code, the backslash cracacter needs to be written as
- '\\'.</p>
-
- <p>In the rare case where the "\{}" occurs naturally in the
- message, you can double escape the formatting anchor so that
- it retains its original meaning. For example,</p>
-
-
- <p class="source">logger.debug("File name is C:\\\\{}.", "file.zip");</p>
- <p>will print as "File name is C:\file.zip".</p>
-
- <hr />
-
- </dd>
-
-
- <dt><a name="string_contents" href="#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 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>
-
- <hr />
-
- </dd>
-
-
-
-
- <dt><a name="fatal" href="#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>
-
-
- <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
- FATAL level is superfluous.
- </p>
-
-
- <hr />
- </dd>
-
- <dt>
- <a name="trace" href="#trace">Why was the TRACE level introduced only in
- SLF4J version 1.4.0?
- </a>
- </dt>
-
- <dd>
-
- <p>The addition of the TRACE level has been frequently and
- hotly debated request. By studying various projects, we
- observed that the TRACE level was used to disable logging
- output from certain classes <em>without</em> needing to
- configure logging for those classes. Indeed, the TRACE level
- is by default disabled in log4j and logback as well most other
- logging systems. The same result can be achieved by adding the
- appropriate directives in configuration files.
- </p>
-
- <p>Thus, in many of cases the TRACE level carried the same
- semantic meaning as DEBUG. In such cases, the TRACE level
- merely saves a few configuration directives. In other, more
- interesting occasions, where TRACE carries a different meaning
- than DEBUG, <a href="api/org/slf4j/Marker.html">Marker</a>
- objects can be put to use to convey the desired
- meaning. However, if you can't be bothered with markers and
- wish to use a logging level lower than DEBUG, the TRACE level
- can get the job done.
- </p>
-
- <p>Note that while the cost of evaluating a disabled log
- request is in the order of a few <code>nanoseconds</code>, the
- use of the TRACE level (or any other level for that matter) is
- discouraged in tight loops where the log request might be
- evaluated millions of times. If the log request is enabled,
- then it will overwhelm the target destination with massive
- output. If the request is disabled, it will waste resources.
- </p>
-
- <p>In short, although we still discourage the use of the TRACE
- level because alternatives exist or because in many cases log
- requests of level TRACE are wasteful, given that people kept
- asking for it, we decided to bow to popular demand.
- </p>
- <hr/>
-
- </dd>
-
- <dt>
- <a name="i18n" href="#i18n">Does the SLF4J logging API support
- I18N (internationalization)?
- </a>
- </dt>
+
+
+ <p>A two argument variant is also available. For example, you
+ can write:</p>
+
+
+ <p class="source">logger.debug("The new entry is {}. It replaces {}.", entry, oldEntry);</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>Array type arguments, including multi-dimensional arrays,
+ are also supported.</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 about 10 times
+ faster but at the cost of being non-standard and less
+ flexible.
+ </p>
+
+ <p><b>Escaping the "{}" pair</b></p>
+
+ <p>The "{}" pair is called the <em>formatting anchor</em>. It
+ serves to designate the location where arguments need to be
+ substituted within the message pattern.
+ </p>
+
+ <p>SLF4J only cares about the <em>formatting anchor</em>, that
+ is the '{' character immediately followed by '}'. Thus, in
+ case your message contains the '{' or the '}' character, you
+ do not have to do anything special unless the '}' character
+ immediately follows '}'. For example,
+ </p>
+
+ <p class="source">logger.debug("Set {1,2} differs from {}", "3");</p>
+
+ <p>which will print as "Set {1,2} differs from 3". </p>
+
+ <p>You could have even written,</p>
+ <p class="source">logger.debug("Set {1,2} differs from {{}}", "3");</p>
+ <p>which would have printed as "Set {1,2} differs from {3}". </p>
+
+ <p>In the extremely rare case where the the "{}" pair occurs
+ naturally within your text and you wish to disable the special
+ meaning of the formatting anchor, then you need to escape the
+ '{' character with '\', that is the backslash character. Only
+ the '{' character should be escaped. There is no need to
+ escape the '}' character. For example,
+ </p>
+
+ <p class="source">logger.debug("Set \\{} differs from {}", "3");</p>
+
+ <p>will print as "Set {} differs from 3". Note that within
+ Java code, the backslash cracacter needs to be written as
+ '\\'.</p>
+
+ <p>In the rare case where the "\{}" occurs naturally in the
+ message, you can double escape the formatting anchor so that
+ it retains its original meaning. For example,</p>
+
+
+ <p class="source">logger.debug("File name is C:\\\\{}.", "file.zip");</p>
+ <p>will print as "File name is C:\file.zip".</p>
+
+ <hr />
+
+ </dd>
+
+
+ <dt><a name="string_contents" href="#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 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>
+
+ <hr />
+
+ </dd>
+
+
+
+
+ <dt>
+ <a name="fatal" href="#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>
+
+
+ <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
+ FATAL level is superfluous.
+ </p>
+
+
+ <hr />
+ </dd>
+
+ <dt>
+ <a name="trace" href="#trace">Why was the TRACE level introduced only in
+ SLF4J version 1.4.0?
+ </a>
+ </dt>
+
+ <dd>
+
+ <p>The addition of the TRACE level has been frequently and
+ hotly debated request. By studying various projects, we
+ observed that the TRACE level was used to disable logging
+ output from certain classes <em>without</em> needing to
+ configure logging for those classes. Indeed, the TRACE level
+ is by default disabled in log4j and logback as well most other
+ logging systems. The same result can be achieved by adding the
+ appropriate directives in configuration files.
+ </p>
+
+ <p>Thus, in many of cases the TRACE level carried the same
+ semantic meaning as DEBUG. In such cases, the TRACE level
+ merely saves a few configuration directives. In other, more
+ interesting occasions, where TRACE carries a different meaning
+ than DEBUG, <a href="api/org/slf4j/Marker.html">Marker</a>
+ objects can be put to use to convey the desired
+ meaning. However, if you can't be bothered with markers and
+ wish to use a logging level lower than DEBUG, the TRACE level
+ can get the job done.
+ </p>
+
+ <p>Note that while the cost of evaluating a disabled log
+ request is in the order of a few <code>nanoseconds</code>, the
+ use of the TRACE level (or any other level for that matter) is
+ discouraged in tight loops where the log request might be
+ evaluated millions of times. If the log request is enabled,
+ then it will overwhelm the target destination with massive
+ output. If the request is disabled, it will waste resources.
+ </p>
+
+ <p>In short, although we still discourage the use of the TRACE
+ level because alternatives exist or because in many cases log
+ requests of level TRACE are wasteful, given that people kept
+ asking for it, we decided to bow to popular demand.
+ </p>
+ <hr/>
+
+ </dd>
+
+ <dt>
+ <a name="i18n" href="#i18n">Does the SLF4J logging API support
+ I18N (internationalization)?
+ </a>
+ </dt>
+
+ <dd>
+ <p>No. SLF4J does not offer any particular support for
+ I18N. However, nothing prevents you from implementing i18n
+ support around the SLF4J API.</p>
+
+ <p>As suggested by Sebastien Davids in <a
+ href="http://bugzilla.slf4j.org/show_bug.cgi?id=50">bug report
+ 50</a>, a possible pattern might be:</p>
+
+ <p class="source">class MyClass {
- <dd>
- <p>No. SLF4J does not offer any particular support for
- I18N. However, nothing prevents you from implementing i18n
- support around the SLF4J API.</p>
-
- <p>As suggested by Sebastien Davids in <a
- href="http://bugzilla.slf4j.org/show_bug.cgi?id=50">bug report
- 50</a>, a possible pattern might be:</p>
-
- <p class="source">
-class MyClass {
-
ResourceBundle bundle = ResourceBundle.getBundle("my.package.messages");
Logger logger = LoggerFactory.getLogger(MyClass.class);
-
+
void method() {
- if (logger.isWarnEnabled()) {
- MessageFormat format = new MessageFormat(bundle.getString("<b>my_message_key</b>"));
- logger.warn(format.format(new Object[] { new Date(), 1 }));
- }
+ if (logger.isWarnEnabled()) {
+ MessageFormat format = new MessageFormat(bundle.getString("<b>my_message_key</b>"));
+ logger.warn(format.format(new Object[] { new Date(), 1 }));
+ }
}
}</p>
-
+
<p>Where <code>my_message_key</code> is defined as</p>
<p class="source"><b>my_message_key</b>=my text to be i18n {1,date,short} {0,number,00}</p>
-
-
-
- </dd>
-
- </dl>
- </div>
-
-
- <div class="section">
-
- <h2>Implementing the SLF4J API</h2>
-
- <dl>
- <dt><a name="slf4j_compatible" href="#slf4j_compatible"> How do
- I make my logging framework SLF4J compatible?
+
+
+
+ </dd>
+
+ </dl>
+
+ <h2>Implementing the SLF4J API</h2>
+
+ <dl>
+ <dt><a name="slf4j_compatible" href="#slf4j_compatible"> How do
+ I make my logging framework SLF4J compatible?
+ </a>
+ </dt>
+
+
+ <dd>
+
+ <p>Adding supporting for the SLF4J is surprisingly
+ easy. Essentially, you coping an existing binding and tailoring
+ it a little (as explained below) does the trick.
+ </p>
+
+ <p>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
+ returns an new instance of <code>MyLoggerFactory</code>. You
+ will also need to modify the
+ <code>loggerFactoryClassStr</code> variable.
+ </p>
+
+ <p>For Marker or MDC support, you could use the one of the
+ existing NOP implementations.
+ </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,</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>
+
+ <hr/>
+ </dd>
+ <dt>
+ <a name="marker_interface" href="#marker_interface"> How
+ can my logging system add support for the <code>Marker</code>
+ interface?
</a>
- </dt>
+ </dt>
+ <dd>
-
- <dd>
-
- <p>Adding supporting for the SLF4J is surprisingly
- easy. Essentially, you coping an existing binding and tailoring
- it a little (as explained below) does the trick.
- </p>
-
- <p>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
- returns an new instance of <code>MyLoggerFactory</code>. You
- will also need to modify the
- <code>loggerFactoryClassStr</code> variable.
- </p>
-
- <p>For Marker or MDC support, you could use the one of the
- existing NOP implementations.
- </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,</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>
-
- <hr/>
- </dd>
- <dt><a name="marker_interface" href="#marker_interface"> How
- can my logging system add support for the <code>Marker</code>
- interface?
- </a>
- </dt>
- <dd>
-
- <p>Markers constitute a revolutionary concept which is
- supported by logback but not other existing logging
- systems. Consequently, SLF4J conforming logging systems are
- allowed to ignore marker data passed by the user.
- </p>
-
- <p>However, even though marker data may be ignored, the user
- must still be allowed to specify marker data. Otherwise, users
- would not be able to switch between logging systems that
- support markers and those that do not.
- </p>
-
- <p>The <code>MarkerIgnoringBase</code> class can serve as a
- base for adapters or native implementations of logging
- systems lacking marker support. In
- <code>MarkerIgnoringBase</code>, methods taking marker data
- simply invoke the corresponding method without the Marker
- argument, discarding any Marker data passed as
- argument. Your SLF4J adapters can extend
- <code>MarkerIgnoringBase</code> to quickly implement the
- methods in <code>org.slf4j.Logger</code> which take a
- <code>Marker</code> as the first argument.
- </p>
+ <p>Markers constitute a revolutionary concept which is
+ supported by logback but not other existing logging
+ systems. Consequently, SLF4J conforming logging systems are
+ allowed to ignore marker data passed by the user.
+ </p>
+
+ <p>However, even though marker data may be ignored, the user
+ must still be allowed to specify marker data. Otherwise, users
+ would not be able to switch between logging systems that
+ support markers and those that do not.
+ </p>
+
+ <p>The <code>MarkerIgnoringBase</code> class can serve as a
+ base for adapters or native implementations of logging
+ systems lacking marker support. In
+ <code>MarkerIgnoringBase</code>, methods taking marker data
+ simply invoke the corresponding method without the Marker
+ argument, discarding any Marker data passed as
+ argument. Your SLF4J adapters can extend
+ <code>MarkerIgnoringBase</code> to quickly implement the
+ methods in <code>org.slf4j.Logger</code> which take a
+ <code>Marker</code> as the first argument.
+ </p>
+
+ <hr/>
+ </dd>
- <hr/>
- </dd>
-
- <dt><a name="version_checks" href="#version_checks"> How does
- SLF4J's version check mechanism work?</a></dt>
+ <dt><a name="version_checks" href="#version_checks"> How does
+ SLF4J's version check mechanism work?</a>
+ </dt>
+
+ <dd>
+ <p>The version check performed by SLF4J API during its
+ initialization is an elective process. Conforming SLF4J
+ implementations may choose <em>not</em> to participate, in
+ which case, no version check will be performed.
+ </p>
- <dd>
- <p>The version check performed by SLF4J API during its
- initialization is an elective process. Conforming SLF4J
- implementations may choose <em>not</em> to participate, in
- which case, no version check will be performed.
- </p>
-
- <p>However, if an SLF4J implementation decides to participate,
- than it needs to declare a variable called
- REQUESTED_API_VERSION within its copy of the
- <code>StaticLoggerBinder</code> class. The value of this
- variable should be equal to the version of the slf4j-api.jar
- it is compiled with. If the implementation is upgraded to a
- newer version of slf4j-api, than you also need to update the
- value of REQUESTED_API_VERSION.
- </p>
-
- <p>For each version, SLF4J API maintains a list of compatible
- versions. SLF4J will emit a version mismatch warning only if
- the requested version is not found in the compatibility
- list. So even if your SLF4J binding has a different release
- schedule than SLF4J, assuming you update the SLF4J version you
- use every 6 to 12 months, you can still participate in the
- version check without incurring a mismatch warning. For
- example, logback has a different release schedule but still
- participates in version checks.</p>
-
- <p><b>As of SLF4J 1.5.5</b>, all bindings shipped within the
- SLF4J distribution, e.g. slf4j-logj12, slf4j-simple and
- slf4j-jdk14, declare the REQUESTED_API_VERSION field with a
- value equal to their SLF4J version. It follows that, for
- example if slf4j-simple-1.5.6.jar is mixed with
- slf4j-api-1.5.5.jar, then a version mismatch warning will be
- issued. Note that SLF4J versions prior to 1.5.5 did not have a
- version check mechanism. Only slf4j-api-1.5.5.jar and later
- can emit version mismatch warnings. (Actually, version 1.5.4
- offered a check policy which was much too restrictive and
- inconsistent with the size of our user base. Consequently,
- SLF4J version 1.5.5 was released just a day after 1.5.4.)
- </p>
-
- <p>Given its huge installed user base and several external
- implementations, it would have been unwise to expect all SLF4J
- implementations to closely follow SLF4J's release schedule,
- let alone align their release schedules with SLF4J. Hence, the
- elective version check policy.
- </p>
-
- </dd>
-
- </dl>
-
- </div>
-
- <div class="section">
- <h2>General questions about logging</h2>
-
-
- <dl>
- <dt><a name="declared_static" href="#declared_static"> Should Logger
- members of a class be declared as static? </a>
- </dt>
- <dd>
+ <p>However, if an SLF4J implementation decides to participate,
+ than it needs to declare a variable called
+ REQUESTED_API_VERSION within its copy of the
+ <code>StaticLoggerBinder</code> class. The value of this
+ variable should be equal to the version of the slf4j-api.jar
+ it is compiled with. If the implementation is upgraded to a
+ newer version of slf4j-api, than you also need to update the
+ value of REQUESTED_API_VERSION.
+ </p>
+
+ <p>For each version, SLF4J API maintains a list of compatible
+ versions. SLF4J will emit a version mismatch warning only if
+ the requested version is not found in the compatibility
+ list. So even if your SLF4J binding has a different release
+ schedule than SLF4J, assuming you update the SLF4J version you
+ use every 6 to 12 months, you can still participate in the
+ version check without incurring a mismatch warning. For
+ example, logback has a different release schedule but still
+ participates in version checks.</p>
+
+ <p><b>As of SLF4J 1.5.5</b>, all bindings shipped within the
+ SLF4J distribution, e.g. slf4j-logj12, slf4j-simple and
+ slf4j-jdk14, declare the REQUESTED_API_VERSION field with a
+ value equal to their SLF4J version. It follows that, for
+ example if slf4j-simple-1.5.6.jar is mixed with
+ slf4j-api-1.5.5.jar, then a version mismatch warning will be
+ issued. Note that SLF4J versions prior to 1.5.5 did not have a
+ version check mechanism. Only slf4j-api-1.5.5.jar and later
+ can emit version mismatch warnings. (Actually, version 1.5.4
+ offered a check policy which was much too restrictive and
+ inconsistent with the size of our user base. Consequently,
+ SLF4J version 1.5.5 was released just a day after 1.5.4.)
+ </p>
+
+ <p>Given its huge installed user base and several external
+ implementations, it would have been unwise to expect all SLF4J
+ implementations to closely follow SLF4J's release schedule,
+ let alone align their release schedules with SLF4J. Hence, the
+ elective version check policy.
+ </p>
+
+ </dd>
+
+ </dl>
+
+ <h2>General questions about logging</h2>
+
+
+ <dl>
+ <dt><a name="declared_static" href="#declared_static"> Should Logger
+ members of a class be declared as static? </a>
+ </dt>
+ <dd>
<p>We <code>used</code> to recommend that loggers members be
declared as instance variables instead of static. After further
analysis, <b>we no longer recommend one approach over the
other.</b>
</p>
-
+
<p>Here is a summary of the pros and cons of each approach.
</p>
@@ -1078,7 +1061,7 @@
consume one reference per class</li>
</ol>
</td>
-
+
<td> <!-- static con -->
<ol>
<li>For libraries shared between applications, not
@@ -1092,7 +1075,7 @@
</ol>
</td>
</tr>
-
+
<tr>
<th width="50%">Advantages for declaring loggers as instance variables</th>
<th width="50%">Disadvantages for declaring loggers as
@@ -1111,7 +1094,7 @@
<li>IOC-friendly</li>
</ol>
</td>
-
+
<td> <!-- instance cons -->
<ol>
<li>Less common idiom than declaring loggers as static
@@ -1119,7 +1102,7 @@
<li>higher CPU overhead: loggers are retrieved and
assigned for each instance of the hosting class</li>
-
+
<li>higher memory overhead: logger declaration will
consume one reference per instance of the hosting class</li>
</ol>
@@ -1127,9 +1110,9 @@
</tr>
</table>
-
+
<h3>Explanation</h3>
-
+
<p>Static logger members cost a single variable reference for
all instances of the class whereas an instance logger member
will cost a variable reference for every instance of the
@@ -1145,7 +1128,7 @@
between applications and offer a distinct logging environment
for each application.
</p>
-
+
<p>More specifically, each time a logger is retrieved by
invoking <code>LoggerFactory.getLogger()</code> method, the
underlying logging system will return an instance appropriate
@@ -1155,7 +1138,7 @@
different logger will be returned only for different
applications.
</p>
-
+
<p>If the logger is static, then it will only be retrieved once
when the hosting class is loaded into memory. If the hosting
class is used in only in one application, there is not much to
@@ -1165,7 +1148,7 @@
happened to first load the shared class into memory - hardly the
behavior expected by the user.
</p>
-
+
<p>Unfortunately, for non-native implementations of the SLF4J
API, namely with slf4j-log4j12, log4j's repository selector will
not be able to do its job properly because slf4j-log4j12, a
@@ -1174,13 +1157,13 @@
SLF4J implementations, such as logback-classic, repository
selectors will work as expected.
</p>
-
+
<p>The Apache Commons wiki contains an <a
href="http://wiki.apache.org/jakarta-commons/Logging/StaticLog">informative
article</a> covering the same question.</p>
-
+
<p><b>Logger serialization</b></p>
-
+
<p>Contrary to static variables, instance variables are
serialized by default. As of SLF4J version 1.5.3, logger
instances survive serialization. Thus, serialization of the host
@@ -1188,9 +1171,9 @@
are declared as instance variables. In previous versions, logger
instances needed to be declared as <code>transient</code> in the
host class. </p>
-
+
<p><b>Summary</b></p>
-
+
<p>In summary, declaring logger members as static variables
requires less CPU time and have a slightly smaller memory
footprint. On the other hand, declaring logger members as
@@ -1202,51 +1185,44 @@
considerations, instance variables are IOC-friendly whereas
static variables are not.
</p>
-
+
<p>See also <a
href="http://wiki.apache.org/jakarta-commons/Logging/StaticLog">related
discussion</a> in the commons-logging wiki.
</p>
-
+
</dd>
- </dl>
-
- <dl>
- <dt> <a name="declaration_pattern"
- href="#declaration_pattern">Is there a recommended idiom for
- declaring a logger in a class?</a>
- </dt>
-
- <dd>
- <p>The following is the recommended logger declaration
- idiom. It assumes that your logger is a static variable of the
- class.</p>
-
- <p class="source">package some.package;
+ </dl>
+
+ <dl>
+ <dt> <a name="declaration_pattern"
+ href="#declaration_pattern">Is there a recommended idiom for
+ declaring a logger in a class?</a>
+ </dt>
+
+ <dd>
+ <p>The following is the recommended logger declaration
+ idiom. It assumes that your logger is a static variable of the
+ class.</p>
+
+ <p class="source">package some.package;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
-
+
public class MyClass {
<b>final static Logger logger = LoggerFactory.getLogger(MyClass.class);</b>
... etc
}</p>
-
- <p>Unfortunately, give that the name of the hosting class is
- part of the logger declaration, the above logger declaration
- idiom is not is <em>not</em> resistant to cut-and-pasting
- between classes.
- </p>
- </dd>
- </dl>
-
-
+ <p>Unfortunately, give that the name of the hosting class is
+ part of the logger declaration, the above logger declaration
+ idiom is not is <em>not</em> resistant to cut-and-pasting
+ between classes.
+ </p>
+ </dd>
+ </dl>
-
-
-
-
- </div>
+ <script src="templates/footer.js" type="text/javascript"></script>
</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 Thu Nov 13 12:34:03 2008
@@ -1,26 +1,26 @@
-<!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>SLF4J</title>
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.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">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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>SLF4J</title>
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';</script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <!--
+ <div id="right">
+ <script src="templates/right.js" type="text/javascript"></script>
+ </div>
+ -->
+ <div id="content">
+
<h1>Simple Logging Facade for Java (SLF4J)</h1>
@@ -138,18 +138,19 @@
<li><a href="http://www.artofsolving.com/opensource/jodconverter">JODConverter</a></li>
<li><a href="http://jtrac.info/dependencies.html">JTrac</a></li>
<li><a href="http://jwebunit.sourceforge.net/2.x/">JWebUnit 2.x</a></li>
+ <li><a href="http://www.jquantlib.org/index.php/Main_Page">JQuantLib</a></li>
<li><a href="http://www.liferay.com/web/guest/home">LIFERAY</a></li>
<li><a href="http://log4jdbc.sourceforge.net">log4jdbc</a></li>
<li><a href="http://www.magnolia.info/en/magnolia.html">Magnolia</a></li>
<li><a href="http://mrcp4j.sourceforge.net/">MRCP4J</a></li>
<li><a href="http://www.mindquarry.com/">Mindquarry</a></li>
- <li><a href="http://mugshot.org/">Mugshot</a></li>
</ul>
</td>
<td valign="top">
<ul>
+ <li><a href="http://mugshot.org/">Mugshot</a></li>
<li><a href="http://mule.codehaus.org/display/MULE/Home">Mule</a></li>
<li><a href="http://nexus.sonatype.org/repository.html">Nexus</a></li>
<li><a href="http://www.novocode.com/naf/">Novocode</a></li>
@@ -159,13 +160,12 @@
<li><a href="http://pzfilereader.sourceforge.net/">PZFileReader</a></li>
<li><a href="http://www.quickfixj.org/">QuickFIX/J</a></li>
<li><a href="http://smsj.sourceforge.net/dependencies.html">SMSJ</a></li>
- <li><a href="http://www.springframework.org/osgi">Spring-OSGi</a></li>
-
</ul>
</td>
<td valign="top">
<ul>
+ <li><a href="http://www.springframework.org/osgi">Spring-OSGi</a></li>
<li><a href="http://streambase.com/">StreamBase</a></li>
<li><a href="http://www.timefinder.de/">TimeFinder</a></li>
<li><a href="http://www.wtfigo.org/index.html">WTFIGO</a></li>
@@ -176,7 +176,7 @@
</tr>
</table>
- <script src="templates/footer.js"></script>
+ <script src="templates/footer.js" type="text/javascript"></script>
</div>
</body>
</html>
Modified: slf4j/trunk/slf4j-site/src/site/pages/legacy.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/legacy.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/legacy.html Thu Nov 13 12:34:03 2008
@@ -1,228 +1,229 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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" />
-
+ <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 type="text/javascript">prefix='';</script>
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <div id="content">
- <h1>Bridging legacy APIs</h1>
-
- <p>Often, some of the components you depend on rely on a logging API
- other than SLF4J. These components presumably will not switch to
- SLF4J in the near future. SLF4J ships with several bridging modules
- which redirect calls to log4j, JCL and j.u.l APIs to behave as if
- they were made to the SLF4J API. The figure below illustrates the
- idea.
- </p>
-
- <p></p>
- <p></p>
-
-
- <p><a href="images/bridging.png">
+ <h1>Bridging legacy APIs</h1>
+
+ <p>Often, some of the components you depend on rely on a logging API
+ other than SLF4J. These components presumably will not switch to
+ SLF4J in the near future. SLF4J ships with several bridging modules
+ which redirect calls to log4j, JCL and j.u.l APIs to behave as if
+ they were made to the SLF4J API. The figure below illustrates the
+ idea.
+ </p>
+
+ <p></p>
+ <p></p>
+
+
+ <p><a href="images/bridging.png">
<img src="images/bridging.png" alt="click to enlarge" width="800"/>
- </a></p>
-
- <p>
- </p>
-
- <h2><a name="jcl-over-slf4j" href="#jcl-over-slf4j">Gradual migration to
- SLF4J from Jakarta Commons Logging (JCL)</a></h2>
-
- <h2><em>jcl-over-slf4j.jar</em></h2>
-
- <p>To ease migration to SLF4J from JCL, recent SLF4J distributions
- include the jar file <em>jcl-over-slf4j.jar</em>. This jar file is
- intended as a drop-in replacement for JCL version 1.1.1. It
- implements the public API of JCL but using SLF4J underneath, hence
- the name "JCL over SLF4J."
- </p>
-
- <p>Our JCL over SLF4J implementation will allow you to migrate to
- SLF4J gradually, especially if some of the libraries your software
- depends on continue to use JCL for the foreseeable future. You can
- immediately enjoy the benefits of SLF4J's reliability and preserve
- backward compatibility at the same time. Just replace
- <em>commons-logging.jar</em> with
- <em>jcl-over-slf4j.jar</em>. Subsequently, the selection of the
- underlying logging system will be done by SLF4J instead of JCL but
- without the class loader headaches. The underlying logging system
- can be any of NOP, simple, jdk14 logging, log4j or logback. Any
- existing dependency on commons-logging therefore becomes less of an
- issue.
- </p>
-
- <h2><em>slf4j-jcl.jar</em></h2>
-
- <p>Some of our users after having switched to SLF4J API realize that
- in some contexts the use of JCL is mandatory and their use of SLF4J
- can be a problem. For this uncommon but important case, SLF4J offers
- a JCL binding, found in the file <em>slf4j-jcl.jar</em>. The JCL
- binding will delegate all logging calls made through SLF4J API to
- JCL. Thus, if for some reason an existing application <em>must</em>
- use JCL, your part of that application can still code against the
- SLF4J API in a manner transparent to the larger application
- environment. Your choice of SLF4J API will be invisible to the rest
- of the application which can continue to use JCL.
- </p>
-
- <h2><em>jcl-over-slf4j.jar</em> should not be confused with
- <em>slf4j-jcl.jar</em></h2>
-
-
- <p>JCL-over-SLF4J, i.e. <em>jcl-over-slf4j.jar</em>, comes in handy
- in situations where JCL needs to be supported for backward
- compatibility reasons. It can be used to fix problems associated
- with JCL, without necessarily adopting the SLF4J API, a decision
- which can be deferred to a later time.
- </p>
-
- <p>On the other hand, <em>slf4j-jcl.jar</em> is useful
- <strong>after</strong> you have already adopted the SLF4J API for
- your component which needs to be embedded in a larger application
- environment where JCL is a formal requirement. Your software
- component can still use SLF4J API without disrupting the larger
- application. Indeed, <em>slf4j-jcl.jar</em> will delegate all
- logging decisions to JCL so that the dependency on SLF4J API by your
- component will be transparent to the larger whole.
- </p>
-
- <p>Please note that <em>jcl-over-slf4j.jar</em> and
- <em>slf4j-jcl.jar</em> cannot be deployed at the same time. The
- former jar file will cause JCL to delegate the choice of the logging
- system to SLF4J and the latter jar file will cause SLF4J to delegate
- the choice of the logging system to JCL, resulting in an infinite
- loop.
- </p>
-
-
- <h2><a name="log4j-over-slf4j" href="#log4j-over-slf4j">Log4j over
- SLF4J</a></h2>
+ </a></p>
- <p>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> but simply 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="http://logback.qos.ch/manual/index.html">its 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>
+ </p>
+
+ <h2><a name="jcl-over-slf4j" href="#jcl-over-slf4j">Gradual migration to
+ SLF4J from Jakarta Commons Logging (JCL)</a></h2>
+
+ <h2><em>jcl-over-slf4j.jar</em></h2>
+
+ <p>To ease migration to SLF4J from JCL, recent SLF4J distributions
+ include the jar file <em>jcl-over-slf4j.jar</em>. This jar file is
+ intended as a drop-in replacement for JCL version 1.1.1. It
+ implements the public API of JCL but using SLF4J underneath, hence
+ the name "JCL over SLF4J."
+ </p>
+
+ <p>Our JCL over SLF4J implementation will allow you to migrate to
+ SLF4J gradually, especially if some of the libraries your software
+ depends on continue to use JCL for the foreseeable future. You can
+ immediately enjoy the benefits of SLF4J's reliability and preserve
+ backward compatibility at the same time. Just replace
+ <em>commons-logging.jar</em> with
+ <em>jcl-over-slf4j.jar</em>. Subsequently, the selection of the
+ underlying logging system will be done by SLF4J instead of JCL but
+ without the class loader headaches. The underlying logging system
+ can be any of NOP, simple, jdk14 logging, log4j or logback. Any
+ existing dependency on commons-logging therefore becomes less of an
+ issue.
+ </p>
+
+ <h2><em>slf4j-jcl.jar</em></h2>
+
+ <p>Some of our users after having switched to SLF4J API realize that
+ in some contexts the use of JCL is mandatory and their use of SLF4J
+ can be a problem. For this uncommon but important case, SLF4J offers
+ a JCL binding, found in the file <em>slf4j-jcl.jar</em>. The JCL
+ binding will delegate all logging calls made through SLF4J API to
+ JCL. Thus, if for some reason an existing application <em>must</em>
+ use JCL, your part of that application can still code against the
+ SLF4J API in a manner transparent to the larger application
+ environment. Your choice of SLF4J API will be invisible to the rest
+ of the application which can continue to use JCL.
+ </p>
+
+ <h2><em>jcl-over-slf4j.jar</em> should not be confused with
+ <em>slf4j-jcl.jar</em></h2>
+
+
+ <p>JCL-over-SLF4J, i.e. <em>jcl-over-slf4j.jar</em>, comes in handy
+ in situations where JCL needs to be supported for backward
+ compatibility reasons. It can be used to fix problems associated
+ with JCL, without necessarily adopting the SLF4J API, a decision
+ which can be deferred to a later time.
+ </p>
+
+ <p>On the other hand, <em>slf4j-jcl.jar</em> is useful
+ <strong>after</strong> you have already adopted the SLF4J API for
+ your component which needs to be embedded in a larger application
+ environment where JCL is a formal requirement. Your software
+ component can still use SLF4J API without disrupting the larger
+ application. Indeed, <em>slf4j-jcl.jar</em> will delegate all
+ logging decisions to JCL so that the dependency on SLF4J API by your
+ component will be transparent to the larger whole.
+ </p>
+
+ <p>Please note that <em>jcl-over-slf4j.jar</em> and
+ <em>slf4j-jcl.jar</em> cannot be deployed at the same time. The
+ former jar file will cause JCL to delegate the choice of the logging
+ system to SLF4J and the latter jar file will cause SLF4J to delegate
+ the choice of the logging system to JCL, resulting in an infinite
+ loop.
+ </p>
+
+
+ <h2><a name="log4j-over-slf4j" href="#log4j-over-slf4j">Log4j over
+ SLF4J</a></h2>
+
+ <p>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> but simply 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="http://logback.qos.ch/manual/index.html">its 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, if you choose
+ logback as your underlying logging system, and given that logback is
+ both much faster and more memory-efficient than log4j, the gains
+ made by using logback should compensate for the overhead of using
+ log4j-over-slf4j instead of log4j directly.
+ </p>
+
+ <h3>log4j-over-slf4j.jar and slf4j-logj12.jar cannot be present
+ simultaneously
+ </h3>
+
+ <p>The presence of <em>slf4j-logj12.jar</em>, that is the log4j
+ binding for SLF4J, will force all SLF4J calls to be delegated to
+ log4j. The presence of <em>log4j-over-slf4j.jar</em> will in turn
+ delegate all log4j API calls to their SLF4J equivalents. If both are
+ present simulatenously, slf4j calls will be delegated to log4j, and
+ log4j calls redirected to SLF4j, resulting in an endless recursion.
+ </p>
+
+ <h2><a name="jul-to-slf4j" href="jul-to-slf4j">JUL to SLF4J</a></h2>
+
+ <p>The jul-to-slf4j module includes a jul handler, namely
+ SLF4JBridgeHandler, that routes all incoming jul records to the
+ SLF4j API. See also <a
+ href="api/org/slf4j/bridge/SLF4JBridgeHandler.html">SLF4JBridgeHandler
+ javadocs</a>. Contrary to other bridging modules such as
+ jcl-over-slfj and log4j-over-slf4h, which re-implement JCL and
+ respectively log4j, the jul-to-slf4j modules does not re-implement
+ the java.util.logging package because packages under the java.*
+ namespace cannot be replaced.
+ </p>
+
+ <h3>jul-to-slf4j.jar and slf4j-jdk14.jar cannot be present
+ simultaneously
+ </h3>
+
+ <p>The presence of slf4j-jdk14.jar, that is the jul binding for
+ SLF4J, will force SLF4J calls to be delegated to jul. On the other
+ hand, the presence of jul-to-slf4j.jar, plus the installation of
+ SLF4JBridgeHandler, by invoking "SLF4JBridgeHandler.install()" will
+ route jul records to SLF4J. Thus, if both jar are present
+ simultanesouly (and SLF4JBridgeHandler is installed), slf4j calls
+ will be delegated to jul and jul records will be routed to SLF4J,
+ resulting in an endless recursion.
+ </p>
- <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, if you choose
- logback as your underlying logging system, and given that logback is
- both much faster and more memory-efficient than log4j, the gains
- made by using logback should compensate for the overhead of using
- log4j-over-slf4j instead of log4j directly.
- </p>
-
- <h3>log4j-over-slf4j.jar and slf4j-logj12.jar cannot be present
- simultaneously
- </h3>
-
- <p>The presence of <em>slf4j-logj12.jar</em>, that is the log4j
- binding for SLF4J, will force all SLF4J calls to be delegated to
- log4j. The presence of <em>log4j-over-slf4j.jar</em> will in turn
- delegate all log4j API calls to their SLF4J equivalents. If both are
- present simulatenously, slf4j calls will be delegated to log4j, and
- log4j calls redirected to SLF4j, resulting in an endless recursion.
- </p>
-
- <h2><a name="jul-to-slf4j" href="jul-to-slf4j">JUL to SLF4J</a></h2>
-
- <p>The jul-to-slf4j module includes a jul handler, namely
- SLF4JBridgeHandler, that routes all incoming jul records to the
- SLF4j API. See also <a
- href="api/org/slf4j/bridge/SLF4JBridgeHandler.html">SLF4JBridgeHandler
- javadocs</a>. Contrary to other bridging modules such as
- jcl-over-slfj and log4j-over-slf4h, which re-implement JCL and
- respectively log4j, the jul-to-slf4j modules does not re-implement
- the java.util.logging package because packages under the java.*
- namespace cannot be replaced.
- </p>
-
- <h3>jul-to-slf4j.jar and slf4j-jdk14.jar cannot be present
- simultaneously
- </h3>
-
- <p>The presence of slf4j-jdk14.jar, that is the jul binding for
- SLF4J, will force SLF4J calls to be delegated to jul. On the other
- hand, the presence of jul-to-slf4j.jar, plus the installation of
- SLF4JBridgeHandler, by invoking "SLF4JBridgeHandler.install()" will
- route jul records to SLF4J. Thus, if both jar are present
- simultanesouly (and SLF4JBridgeHandler is installed), slf4j calls
- will be delegated to jul and jul records will be routed to SLF4J,
- resulting in an endless recursion.
- </p>
-
-<script
- src="templates/footer.js"></script> </div> </body> </html>
+ <script src="templates/footer.js" type="text/javascript"></script>
+ </div>
+</body>
+</html>
Modified: slf4j/trunk/slf4j-site/src/site/pages/license.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/license.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/license.html Thu Nov 13 12:34:03 2008
@@ -1,23 +1,23 @@
-<!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>SLF4J License</title>
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
-</head>
-<body>
- <script>
-prefix='';
-</script>
-
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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>SLF4J License</title>
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';</script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <div id="content">
- <h1>SLF4J License</h1>
+ <h1>SLF4J License</h1>
<p>SLF4J source code and binaries are distributed under the
following license.
@@ -61,6 +61,7 @@
</p>
+ <script src="templates/footer.js" type="text/javascript"></script>
</div>
</body>
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 Thu Nov 13 12:34:03 2008
@@ -1,21 +1,21 @@
-<!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>SLF4J</title>
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
-</head>
-<body>
- <script>
-prefix='';
-</script>
-
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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>SLF4J</title>
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';</script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <div id="content">
+
<h1>SLF4J Mailing Lists</h1>
<p>A mailing list is an electronic discussion forum that anyone can
@@ -121,7 +121,7 @@
</p>
<p> </p>
- <script src="templates/footer.js"></script>
+ <script src="templates/footer.js" type="text/javascript"></script>
</div>
</body>
</html>
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 Thu Nov 13 12:34:03 2008
@@ -1,4 +1,6 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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" />
Modified: slf4j/trunk/slf4j-site/src/site/pages/migrator.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/pages/migrator.html (original)
+++ slf4j/trunk/slf4j-site/src/site/pages/migrator.html Thu Nov 13 12:34:03 2008
@@ -1,72 +1,71 @@
-<!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>SLF4J Migrator</title>
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
-</head>
-<body>
- <script>
-prefix='';
-</script>
-
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
-
-
- <h1>SLF4J Migrator</h1>
-
- <p>The SLF4J migrator is a small Java tool for migrating Java source
- files from the Jakarta Commons Logging (JCL) API to SLF4J. It can
- also migrate from the log4j API to SLF4J, or from
- <code>java.util.logging</code> API to SLF4J.
- </p>
-
- <p>The SLF4J migrator consists of a single jar file that can be
- launched as a stand-alone java application. Here is the command:
- </p>
-
- <p class="source">java -jar slf4j-migrator-${version}.jar </p>
-
- <br/>
-
- <p>Once the application is launched, a window similar to the
- following should appear.
- </p>
-
- <p><img src="images/slf4j-migrator.gif"/></p>
-
- <p>Use the application should be self-explanatory. Please note that
- this migration tool does in-place replacement of Java files, meaning
- that there will be no back-up copies of modified files. <b>It is
- your responsibility to backup your files before using SLF4J
- migrator.</b>
- </p>
-
-
- <h2>Limitations</h2>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
- <p>SLF4J migrator is intended as a simple tool to help you to
- migrate your project source using JCL, log4j or JUL to SLF4J. It can
- only perform elementary conversion steps. Essentially, it will
- replace appropriate import lines and logger declarations.
- </p>
-
- <p>MyClass is a sample class using JCL. Here it is before:</p>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <title>SLF4J Migrator</title>
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';</script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <div id="content">
- <p class="source">package some.package;
+ <h1>SLF4J Migrator</h1>
+
+ <p>The SLF4J migrator is a small Java tool for migrating Java source
+ files from the Jakarta Commons Logging (JCL) API to SLF4J. It can
+ also migrate from the log4j API to SLF4J, or from
+ <code>java.util.logging</code> API to SLF4J.
+ </p>
+
+ <p>The SLF4J migrator consists of a single jar file that can be
+ launched as a stand-alone java application. Here is the command:
+ </p>
+
+ <p class="source">java -jar slf4j-migrator-${version}.jar </p>
+
+ <br/>
+
+ <p>Once the application is launched, a window similar to the
+ following should appear.
+ </p>
+
+ <p><img src="images/slf4j-migrator.gif" alt="slf4j-migrator.gif"/></p>
+
+ <p>Use the application should be self-explanatory. Please note that
+ this migration tool does in-place replacement of Java files, meaning
+ that there will be no back-up copies of modified files. <b>It is
+ your responsibility to backup your files before using SLF4J
+ migrator.</b>
+ </p>
+
+
+ <h2>Limitations</h2>
+
+ <p>SLF4J migrator is intended as a simple tool to help you to
+ migrate your project source using JCL, log4j or JUL to SLF4J. It can
+ only perform elementary conversion steps. Essentially, it will
+ replace appropriate import lines and logger declarations.
+ </p>
+
+ <p>MyClass is a sample class using JCL. Here it is before:</p>
+
+ <p class="source">package some.package;
+
<b>import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;</b>
-
+
public MyClass {
-
-
+
<b>Log logger = LogFactory.getLog(MyClass.class);</b>
-
+
public void someMethod() {
logger.info("Hello world");
}
@@ -139,17 +138,15 @@
<li>if a method declares multipe loggers on the same line, the
conversion will not be complete. Example:
- <p class="source">
- public void someMethod(Log l1, Log l2) {
+ <p class="source"> public void someMethod(Log l1, Log l2) {
...
}
- will be converted as
+will be converted as
public void someMethod(Log l1, Logger l2) {
...
- }
- </p>
+ } </p>
</li>
</ul>
@@ -223,6 +220,7 @@
</li>
</ul>
+ <script src="templates/footer.js" type="text/javascript"></script>
</div>
</body>
- </html>
\ No newline at end of file
+</html>
\ No newline at end of file
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 Thu Nov 13 12:34:03 2008
@@ -1,21 +1,21 @@
-<!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>SLF4J News</title>
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
-</head>
-<body>
- <script>
-prefix='';
-</script>
-
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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>SLF4J News</title>
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';</script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <div id="content">
+
<h1>SLF4J News</h1>
@@ -978,7 +978,7 @@
</p>
-
+ <script src="templates/footer.js" type="text/javascript"></script>
</div>
</body>
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 Thu Nov 13 12:34:03 2008
@@ -1,22 +1,22 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/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>SLF4J</title>
-<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
-</head>
-<body>
- <script>
-prefix='';
-</script>
-
-<script src="templates/header.js"></script>
-<div id="left">
- <script src="templates/left.js"></script>
-</div>
-<div id="content">
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <title>SLF4J</title>
+ <link rel="stylesheet" type="text/css" media="screen" href="css/site.css" />
+ </head>
+ <body>
+ <script type="text/javascript">prefix='';</script>
+
+ <script src="templates/header.js" type="text/javascript"></script>
+ <div id="left">
+ <script src="templates/left.js" type="text/javascript"></script>
+ </div>
+ <div id="content">
- <h1>Source code repositories</h1>
+ <h1>Source code repositories</h1>
<p>SLF4j developers live in different countries throughout the
world. To enable them to work together, we keep the source code in
@@ -66,8 +66,7 @@
</p>
- <script src="templates/footer.js"></script>
-
+ <script src="templates/footer.js" type="text/javascript"></script>
</div>
</body>
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 Thu Nov 13 12:34:03 2008
@@ -1,5 +1,17 @@
+document.write('<table class="footer">')
+
+document.write('<tr>')
+
+document.write(' <td>')
+document.write(' <a href="http://validator.w3.org/check?uri=referer">')
+document.write(' <img align="left" src="http://www.w3.org/Icons/valid-xhtml10"')
+document.write(' alt="Valid XHTML 1.0 Transitional" height="31" width="88" /></a>')
+document.write(' </td>')
+
+document.write('<td valign="top">Copyright © 2004-2008 <a href="http://www.qos.ch/">QOS.ch</a></td>')
+
+document.write('</tr>')
+document.write('</table>')
+
-document.write('<p class="footer">')
-document.write('Copyright © 2004-2008 <a href="http://www.qos.ch/">QOS.ch</a>')
-document.write('</p>')
More information about the slf4j-dev
mailing list