From 8a1702ba0f1ccd5dec8b4fca59829399313edeac Mon Sep 17 00:00:00 2001 From: Ceki Gulcu Date: Sun, 14 Dec 2014 17:51:48 +0100 Subject: [PATCH] polish the docs on slf4j.detectLoggerNameMismatch --- pom.xml | 8 ++-- .../main/java/org/slf4j/LoggerFactory.java | 9 ++++ slf4j-site/pom.xml | 2 +- slf4j-site/src/site/pages/codes.html | 45 +++++++++++-------- slf4j-site/src/site/pages/manual.html | 9 ++-- slf4j-site/src/site/pages/news.html | 7 ++- 6 files changed, 50 insertions(+), 30 deletions(-) diff --git a/pom.xml b/pom.xml index 8794f1af..6219ff4c 100755 --- a/pom.xml +++ b/pom.xml @@ -40,6 +40,7 @@ 1.2.17 1.0.13 4.10 + 3.3 @@ -142,8 +143,7 @@ maven-jar-plugin 2.3.1 - - + org.apache.maven.plugins maven-surefire-plugin @@ -206,7 +206,7 @@ org.apache.maven.plugins maven-site-plugin - 3.0 + ${maven-site-plugin.version} @@ -223,7 +223,7 @@ org.apache.maven.plugins maven-javadoc-plugin - 2.8 + 2.10.1 org.slf4j.migrator:org.slf4j.migrator.* diff --git a/slf4j-api/src/main/java/org/slf4j/LoggerFactory.java b/slf4j-api/src/main/java/org/slf4j/LoggerFactory.java index 146bf785..87efaa71 100755 --- a/slf4j-api/src/main/java/org/slf4j/LoggerFactory.java +++ b/slf4j-api/src/main/java/org/slf4j/LoggerFactory.java @@ -292,8 +292,17 @@ public final class LoggerFactory { * Return a logger named corresponding to the class passed as parameter, using * the statically bound {@link ILoggerFactory} instance. * + *

In case the the clazz parameter differs from the name of + * the caller as computed internally by SLF4J, a logger name mismatch warning will be + * printed but only if the slf4j.detectLoggerNameMismatch system property is + * set to true. By default, this property is not set and no warnings will be printed + * even in case of a logger name mismatch. + * * @param clazz the returned logger will be named after clazz * @return logger + * + * + * @see Detected logger name mismatch */ @Nonnull public static Logger getLogger(@Nonnull Class clazz) { diff --git a/slf4j-site/pom.xml b/slf4j-site/pom.xml index f016347c..cb7f9f19 100755 --- a/slf4j-site/pom.xml +++ b/slf4j-site/pom.xml @@ -31,7 +31,7 @@ org.apache.maven.plugins maven-site-plugin - 3.3 + ${maven-site-plugin.version} ${project.parent.basedir}/target/site diff --git a/slf4j-site/src/site/pages/codes.html b/slf4j-site/src/site/pages/codes.html index 4d7a8ef4..c1038aed 100755 --- a/slf4j-site/src/site/pages/codes.html +++ b/slf4j-site/src/site/pages/codes.html @@ -89,23 +89,25 @@

-

Detected logger name mismatch.

+

Detected logger + name mismatch.

-

inactive by default Logger name - mismatch warnings are printed only if the - slf4j.detectLoggerNameMismatch system propery is set - to true. +

Note Logger name mismatch + warnings are printed only if the + slf4j.detectLoggerNameMismatch system property is set + to true. By default, this property is not set and no warnings will + be printed even in case of a logger name mismatch.

-

The warning will be printed in case the - name of the logger specified via a class passed as an argument to - the LoggerFactory.getLogger(Class) method differs from the name of - the caller as computed internally by SLF4J. +

The warning will be printed in case the name of the logger + specified via a class passed as an argument to the + LoggerFactory.getLogger(Class) method differs from + the name of the caller as computed internally by SLF4J.

For example, the following code snippet

-
package com.acme;
+
package com.acme;
 import com.foo.Kangaroo;
 
 class Fruit {
@@ -114,26 +116,31 @@ class Fruit {
 
     
will result in the warning

 
-    
SLF4J: Detected logger name mismatch. Given name: "com.foo.Kangaroo"; computed name: "com.acme.Fruit".

+    
SLF4J: Detected logger name mismatch. Given name: "com.foo.Kangaroo"; computed name: "com.acme.Fruit".

     
     
but only if slf4j.detectLoggerNameMismatch system
-    propery is set to true.

+    property is set to true.

     
     
No warning will be issued for the special case where the class
     in which the logger is defined is a super-type of the class
     parameter passed as argument. For example,

     
-    
abstract class A { 
-    // no mismatch warning as class A is a super-type of class B
+    
class A { 
     Logger logger = LoggerFactory.getLogger(getClass()); 
 }
-class B extends A { }

+class B extends A { 
+    // no mismatch warning will be issued when B is instantiated 
+    // given that class A is a super-type of class B
+}

 
-    
In case you come across a mismatch warning which cannot be
-    explained, then you might have spotted a white elepahant, or a
+    
If you come across a mismatch warning which cannot be
+    explained, then you might have spotted a white elephant, that is a
     very rare occurrence where SLF4J cannot correctly compute the name
-    of the class where a logger is defined. Please do not hesitate to
-    file a bug report.
+    of the class where a logger is defined. We are very interested to
+    learn about cases where SLF4J fails to correclty compute the name
+    of the class where a logger is defined. If and when you spot such
+    a case, please do file a bug
+    report with us.
     

 
     
diff --git a/slf4j-site/src/site/pages/manual.html b/slf4j-site/src/site/pages/manual.html
index becf3577..042a4799 100755
--- a/slf4j-site/src/site/pages/manual.html
+++ b/slf4j-site/src/site/pages/manual.html
@@ -53,10 +53,11 @@
     users are highly encouraged to migrate to SLF4J 1.7.5 or later.
     

 
-    
since 1.7.8 Spot incorrectly named
-    loggers by setting the slf4j.detectLoggerNameMismatch
-    system property to true.
+    
since 1.7.8 By setting he
+    slf4j.detectLoggerNameMismatch system property to
+    true, SLF4J can automatically spot incorrectly named
+    loggers.
     

 
 
diff --git a/slf4j-site/src/site/pages/news.html b/slf4j-site/src/site/pages/news.html
index 5ff35b7a..cc1e4ed1 100755
--- a/slf4j-site/src/site/pages/news.html
+++ b/slf4j-site/src/site/pages/news.html
@@ -31,7 +31,6 @@
 
    
14th of December, 2014 - Release of SLF4J 1.7.8 

 
-
    
Spot
    incorrectly named loggers by setting the
    slf4j.detectLoggerNameMismatch system property to
@@ -40,7 +39,8 @@
    
Spot incorrectly named
    loggers by setting the
    slf4j.detectLoggerNameMismatch system property to
-   true.

+   true.  This significant feature was contributed by Alexander
+   Dorokhine.

 
    
Added MDC.putCloeable method so that it can be used
    as a Added JSR305 @Nonnull annotations in LoggerFactory
    class. Further annotations are likely to follow.
 
 
+   
Numerous small code improvements too minor to be listed
+   here.

+
    

 
    
4th of April, 2014 - Release of SLF4J 1.7.7