~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~ http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

 -----
 Maven Logging
 -----
 Hervé Boutemy
 -----
 2013-08-02
 -----

Maven Logging

 End-user logging documentation is available {{{/maven-logging.html}in Maven site}}.
 This documentation is focused on internal implementation details.

* Logging API

 Maven uses
 {{{http://plexus.codehaus.org/plexus-containers/plexus-container-default/apidocs/org/codehaus/plexus/logging/package-summary.html}Plexus
 Container logging API}}, like any other Plexus components, ie
 {{{http://plexus.codehaus.org/plexus-containers/plexus-container-default/apidocs/org/codehaus/plexus/logging/LoggerManager.html}LoggerManager}}
 / {{{http://plexus.codehaus.org/plexus-containers/plexus-container-default/apidocs/org/codehaus/plexus/logging/Logger.html}Logger}}.

 Starting with Maven 3.1.0:

  *  Maven supports SLF4J API logging API too, ie {{{http://slf4j.org/apidocs/org/slf4j/LoggerFactory.html}LoggerFactory}} /
     {{{http://slf4j.org/apidocs/org/slf4j/Logger.html}Logger}},

  *  instead of implementing Plexus logging API itself with basic output to console, Maven implements it using SLF4J API in
     {{{./apidocs/org/apache/maven/cli/logging/Slf4jLoggerManager.html}Slf4jLoggerManager}}
     / {{{./apidocs/org/apache/maven/cli/logging/Slf4jLogger.html}Slf4jLogger}}.


* Logging Implementation

 Maven 3.1.0 ships bundled with {{{http://www.slf4j.org/apidocs/org/slf4j/impl/SimpleLogger.html}SLF4J simple logger}},
 but is ready to use other logging implementations: SLF4J is responsible for loading the implementation, referred to as
 {{{http://www.slf4j.org/manual.html#swapping}"SLF4J bindings"}}.

 Logging configuration loading is actually done by logging implementation, without any Maven extensions to support merging
 Maven installation configuration with per-user configuration for example:
 `${maven.home}/conf/logging` directory was added to core's classpath (see `${maven.home}/bin/m2.conf`). See your implementation
 documentation for details on file names, formats, and so on.

 During Maven initialization, Maven tweaks default root logging level to match CLI verbosity choice. Since such feature isn't available
 in SLF4J API, logging implementation specific extensions need to be added into Maven to support these CLI options: see
 {{{./apidocs/org/apache/maven/cli/logging/Slf4jConfigurationFactory.html}Slf4jConfigurationFactory}} /
 {{{./apidocs/org/apache/maven/cli/logging/Slf4jConfiguration.html}Slf4jConfiguration}}.

* Getting Logger Instance

 Plexus Logger and LoggerManager can be injected in Plexus component using Plexus annotations

+------+
import org.codehaus.plexus.logging.Logger;
import org.codehaus.plexus.component.annotations.Component;
import org.codehaus.plexus.component.annotations.Requirement;

@Component( role = MyComponent.class )
public class DefaultMyComponent
    implements MyComponent
{
    @Requirement
    private Logger logger;

    @Requirement
    private LoggerManager loggerManager;
}
+------+

 Starting with Maven 3.1.0, SLF4J Logger can be used directly too, without Plexus. Of course, this will only work when run under
 Maven 3.1.0, then this technique can be used safely only in Maven core components or in plugins/component not requiring
 compatibility with previous Maven versions.

+-----+
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class MyClass
{
   final Logger logger = LoggerFactory.getLogger( MyClass.class );
}
+-----+

* Logger Name

 Before Maven 3.1.0, with logging implementation done in Maven, logger name wasn't used by basic console logging implementation:
 they are as-is, without clear convention on when to pass logger from class to class or when to create a new logger.

 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)?
