This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "SLF4J: Simple Logging Facade for Java". The branch, master has been updated via cfb117d9e4c0fc44313328e8a8f9b74ad9bbf622 (commit) from 96aa1878e03f1c1600aeb67d62c2d090433f60b5 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://git.qos.ch/gitweb/?p=slf4j.git;a=commit;h=cfb117d9e4c0fc44313328e8a8f... http://github.com/ceki/slf4j/commit/cfb117d9e4c0fc44313328e8a8f9b74ad9bbf622 commit cfb117d9e4c0fc44313328e8a8f9b74ad9bbf622 Author: Ceki Gulcu <ceki@qos.ch> Date: Sun Dec 27 00:54:37 2009 +0100 - added "In the presence of an exception/throwable, is it possible to parametizere a logging statement?" - mentioning provided scope as a convenient method for excluding commons-logging diff --git a/slf4j-site/src/site/pages/faq.html b/slf4j-site/src/site/pages/faq.html index 7e1223c..7da0d9d 100644 --- a/slf4j-site/src/site/pages/faq.html +++ b/slf4j-site/src/site/pages/faq.html @@ -130,6 +130,9 @@ without going through the static methods in <code>LoggerFactory</code>? </a></li> + <li><a href="#paramException">In the presence of an + exception/throwable, is it possible to parametizere a logging + statement?</a></li> </ol> @@ -543,16 +546,37 @@ org.slf4j.impl.StaticLoggerBinder.SINGLETON from class org.slf4j.LoggerFactory </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 + <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 + 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> + + <p>Alternatively, commons-logging can be rather simply and + conveniently excluded as a dependency by declaring it in the + <em>provided</em> scope within the pom.xml file of your + project. The actual commons-logging classes would be provided by + jcl-over-slf4j. This translates into the following pom file + snippet:</p> + + <pre class="prettyprint source"><dependency> + <groupId>commons-logging</groupId> + <artifactId>commons-logging</artifactId> + <version>1.1.1</version> + <scope>provided</scope> +</dependency> + +<dependency> + <groupId>org.slf4j</groupId> + <artifactId>jcl-over-slf4j</artifactId> + <version>${project.version}</version> +</dependency></pre> + + </dd> @@ -980,11 +1004,62 @@ logger.debug("The new entry is {}.", entry);</pre> <code>ILoggerFactory</code> interface as an alternative to inventing your own logging API.</p> </dd> + + <dt><a name="paramException" href="#paramException">In the presence of an + exception/throwable, is it possible to parametizere a logging + statement?</a></dt> + + + <dd> + <p>No. The SLF4J API does not support parametization in the + presence of an exception. Thus, + </p> + <pre class="prettyprint">String s = "Hello world"; +try { + throw new NumberFormatException("..."); +} catch (NumberFormatException e) { + logger.error("Failed to format {}", s, e); +}</pre> + <p>will <b>NOT</b> print the <code>NumberFormatException</code> nor its + stack trace. The java compiler will invoke the <a + href="http://www.slf4j.org/apidocs/org/slf4j/Logger.html#error%28java.lang.String,%20java.lang.Object,%20java.lang.Object%29">error + method taking a String and two Object arguments</a>, which, + contrary to the programmer's most probable intention, will cause + the <code>NumberFormatException</code> to be ignored. This is one + of the unfortunate warts present in the SLF4J API. + </p> + <p>The only way to have the exception treated properly, is to + invoke the <a + href="http://www.slf4j.org/apidocs/org/slf4j/Logger.html#error%28java.lang.String,%20java.lang.Throwable%29">error + method taking a String and a Throwable</a>. The correct code is + then,</p> + + <pre class="prettyprint">String s = "Hello world"; +try { + throw new NumberFormatException("..."); +} catch (NumberFormatException e) { + // concatenation instead of parametrization! + <b>logger.error("Failed to format "+ s, e);</b> +}</pre> - </dl> + <p>The second form MUST be employed in the presence of + exceptions. Given that exceptions are rare by definition, the cost + of concatenating "Failed format " and <em>s</em> should be + negligible in pracice. + </p> + <p>If you are user of the SLF4J API, and do not understand the + explanations in this question, you are advised to dwell on the + matter until it becomes clear. You have been warned. + </p> + + </dd> + + + + </dl> ----------------------------------------------------------------------- Summary of changes: slf4j-site/src/site/pages/faq.html | 89 +++++++++++++++++++++++++++++++++--- 1 files changed, 82 insertions(+), 7 deletions(-) hooks/post-receive -- SLF4J: Simple Logging Facade for Java