From a71baa4579bb35930aa4a64c6b4fb8a997518d39 Mon Sep 17 00:00:00 2001
From: Herve Boutemy <hboutemy@apache.org>
Date: Fri, 23 Nov 2012 07:45:43 +0000
Subject: [PATCH] added notes about logger name, with Plexus Logger API that
 cannot follow logger name as class name convention :(

git-svn-id: https://svn.apache.org/repos/asf/maven/maven-3/trunk@1412766 13f79535-47bb-0310-9956-ffa450edef68
---
 .../apache/maven/cli/logging/Slf4jLogger.java | 12 +++++++-
 .../maven/cli/logging/Slf4jLoggerManager.java | 29 +++++++++++++++++--
 maven-embedder/src/site/apt/logging.apt       | 13 +++++++++
 3 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/maven-embedder/src/main/java/org/apache/maven/cli/logging/Slf4jLogger.java b/maven-embedder/src/main/java/org/apache/maven/cli/logging/Slf4jLogger.java
index e231b53255..a2b9bca5be 100644
--- a/maven-embedder/src/main/java/org/apache/maven/cli/logging/Slf4jLogger.java
+++ b/maven-embedder/src/main/java/org/apache/maven/cli/logging/Slf4jLogger.java
@@ -22,7 +22,8 @@ package org.apache.maven.cli.logging;
 import org.codehaus.plexus.logging.Logger;
 
 /**
- * Adapt an SLF4J logger to a Plexus logger.
+ * Adapt an SLF4J logger to a Plexus logger, ignoring Plexus logger API parts that are not classical and
+ * probably not really used.
  * 
  * @author Jason van Zyl
  */
@@ -112,15 +113,24 @@ public class Slf4jLogger
         return logger.isErrorEnabled();
     }
 
+    /**
+     * <b>Warning</b>: ignored (always return <code>0</code>).
+     */
     public int getThreshold()
     {
         return 0;
     }
 
+    /**
+     * <b>Warning</b>: ignored.
+     */
     public void setThreshold( int threshold )
     {
     }
 
+    /**
+     * <b>Warning</b>: ignored (always return <code>0</code>).
+     */
     public Logger getChildLogger( String name )
     {
         return null;
diff --git a/maven-embedder/src/main/java/org/apache/maven/cli/logging/Slf4jLoggerManager.java b/maven-embedder/src/main/java/org/apache/maven/cli/logging/Slf4jLoggerManager.java
index 0197f5c730..f30ea8f68e 100644
--- a/maven-embedder/src/main/java/org/apache/maven/cli/logging/Slf4jLoggerManager.java
+++ b/maven-embedder/src/main/java/org/apache/maven/cli/logging/Slf4jLoggerManager.java
@@ -25,7 +25,8 @@ import org.slf4j.ILoggerFactory;
 import org.slf4j.LoggerFactory;
 
 /**
- * Use an SLF4J {@link org.slf4j.ILoggerFactory} as a backing for a Plexus {@link org.codehaus.plexus.logging.LoggerManager}.
+ * Use an SLF4J {@link org.slf4j.ILoggerFactory} as a backing for a Plexus {@link org.codehaus.plexus.logging.LoggerManager},
+ * ignoring Plexus logger API parts that are not classical and probably not really used.
  *
  * @author Jason van Zyl
  * @since 3.1
@@ -46,37 +47,61 @@ public class Slf4jLoggerManager
         return new Slf4jLogger( loggerFactory.getLogger( role ) );
     }
 
+    /**
+     * The logger name for a component with a non-null hint is <code>role.hint</code>.
+     * <b>Warning</b>: this does not conform to logger name as class name convention.
+     * (and what about <code>null</code> and <code>default</code> hint equivalence?)
+     */
     public Logger getLoggerForComponent( String role, String hint )
     {
         return ( null == hint
             ? getLoggerForComponent( role )
-            : new Slf4jLogger( loggerFactory.getLogger( role + "." + hint ) ) );
+            : new Slf4jLogger( loggerFactory.getLogger( role + '.' + hint ) ) );
     }
 
     //
     // Trying to give loggers back is a bad idea. Ceki said so :-)
+    // notice to self: what was this method supposed to do?
     //
+    /**
+     * <b>Warning</b>: ignored.
+     */
     public void returnComponentLogger( String role )
     {
     }
 
+    /**
+     * <b>Warning</b>: ignored.
+     */
     public void returnComponentLogger( String role, String hint )
     {
     }
 
+    /**
+     * <b>Warning</b>: ignored (always return <code>0</code>).
+     */
     public int getThreshold()
     {
         return 0;
     }
 
+    /**
+     * <b>Warning</b>: ignored.
+     */
     public void setThreshold( int threshold )
     {
     }
 
+    /**
+     * <b>Warning</b>: ignored.
+     */
     public void setThresholds( int threshold )
     {
     }
 
+    /**
+     * <b>Warning</b>: ignored (always return <code>0</code>).
+     */
     public int getActiveLoggerCount()
     {
         return 0;
diff --git a/maven-embedder/src/site/apt/logging.apt b/maven-embedder/src/site/apt/logging.apt
index 2caf177579..cca01bf974 100644
--- a/maven-embedder/src/site/apt/logging.apt
+++ b/maven-embedder/src/site/apt/logging.apt
@@ -50,3 +50,16 @@ public class Wombat
    final Logger logger = LoggerFactory.getLogger(Wombat.class);
 }
 +-----
+
+* Logger Name
+
+ Before Maven 3.1.0, with logging implementation done in Maven, logger name wasn't used: they are as-is, without clear definition.
+
+ Starting with Maven 3.1.0, logging implementation can be of greatest use if logger names are well defined. This definition still
+ needs to be defined and implemented:
+
+ * classical "class name" pattern?
+
+ * Maven-specific name hierarchy?
+
+ * a mix (some with class name, some with Maven-specific hierarchy)?