<?xml version="1.0"?>
<!--
    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.
-->

<document>
    <properties>
        <title>Log4j 2 API</title>
        <author email="rgoers@apache.org">Ralph Goers</author>
        <author email="ggregory@apache.org">Gary Gregory</author>
    </properties>

    <body>
        <section name="Log4j 2 API">
          <a name="Overview"/>
          <subsection name="Overview">
            <p>
              The Log4j 2 API provides the interface that applications should code to and provides the
              adapter components required for implementers to create a logging implementation. Although Log4j 2
              is broken up between an API and an implementation, the primary purpose of doing so was not to
              allow multiple implementations, although that is certainly possible, but to clearly define
              what classes and methods are safe to use in "normal" application code.
            </p>
            <h4>Hello World!</h4>
            <p>
              No introduction would be complete without the customary Hello, World example. Here is ours. First,
              a Logger with the name "HelloWorld" is obtained from the
              <a href="../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html">LogManager</a>.
              Next, the logger is used to write the "Hello, World!" message, however the message will be written
              only if the Logger is configured to allow informational messages.
            </p>
            <pre class="prettyprint linenums">import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

public class HelloWorld {
    private static Logger logger = LogManager.getLogger("HelloWorld");
    public static void main(String[] args) {
        logger.info("Hello, World!");
    }
}</pre>
            <p>
              The output from the call to logger.info() will vary significantly depending on the configuration
              used. See the <a href="./configuration.html">Configuration</a> section for more details.
            </p>
            <h4>Substituting Parameters</h4>
            <p>
              Frequently the purpose of logging is to provide information about what is happening in the system,
              which requires including information about the objects being manipulated. In Log4j 1.x this could
              be accomplished by doing:
            </p>
            <pre class="prettyprint linenums">if (logger.isDebugEnabled()) {
    logger.debug("Logging in user " + user.getName() + " with birthday " + user.getBirthdayCalendar());
}</pre>
            <p>
              Doing this repeatedly has the effect of making the code feel like it is more about logging than the
              actual task at hand. In addition, it results in the logging level being checked twice; once on the
              call to isDebugEnabled and once on the debug method. A better alternative would be:
            </p>
            <pre class="prettyprint">logger.debug("Logging in user {} with birthday {}", user.getName(), user.getBirthdayCalendar());</pre>
            <p>
              With the code above the logging level will only be checked once and the String construction will
              only occur when debug logging is enabled.
            </p>
            <h4>Formatting Parameters</h4>
            <p>
              Substituting parameters leaves formatting up to you if <code>toString()</code> is not what you want.
              To facilitate formatting, you can use the same format strings as Java's
              <a href="http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax">Formatter</a>.
              For example:
            </p>
            <pre class="prettyprint linenums">public static Logger logger = LogManager.getFormatterLogger("Foo");

logger.debug("Logging in user %s with birthday %s", user.getName(), user.getBirthdayCalendar());
logger.debug("Logging in user %1$s with birthday %2$tm %2$te,%2$tY", user.getName(), user.getBirthdayCalendar());
logger.debug("Integer.MAX_VALUE = %,d", Integer.MAX_VALUE);
logger.debug("Long.MAX_VALUE = %,d", Long.MAX_VALUE);
</pre>
            <p>
              To use a formatter Logger, you must call one of the LogManager
              <a href="../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html#getFormatterLogger(java.lang.Class)">getFormatterLogger</a>
              method. The output for this example shows that Calendar toString() is verbose compared to custom formatting:
            </p>
            <pre class="prettyprint linenums">2012-12-12 11:56:19,633 [main] DEBUG: User John Smith with birthday java.util.GregorianCalendar[time=?,areFieldsSet=false,areAllFieldsSet=false,lenient=true,zone=sun.util.calendar.ZoneInfo[id="America/New_York",offset=-18000000,dstSavings=3600000,useDaylight=true,transitions=235,lastRule=java.util.SimpleTimeZone[id=America/New_York,offset=-18000000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=3,startMonth=2,startDay=8,startDayOfWeek=1,startTime=7200000,startTimeMode=0,endMode=3,endMonth=10,endDay=1,endDayOfWeek=1,endTime=7200000,endTimeMode=0]],firstDayOfWeek=1,minimalDaysInFirstWeek=1,ERA=?,YEAR=1995,MONTH=4,WEEK_OF_YEAR=?,WEEK_OF_MONTH=?,DAY_OF_MONTH=23,DAY_OF_YEAR=?,DAY_OF_WEEK=?,DAY_OF_WEEK_IN_MONTH=?,AM_PM=0,HOUR=0,HOUR_OF_DAY=0,MINUTE=0,SECOND=0,MILLISECOND=?,ZONE_OFFSET=?,DST_OFFSET=?]
2012-12-12 11:56:19,643 [main] DEBUG: User John Smith with birthday 05 23, 1995
2012-12-12 11:56:19,643 [main] DEBUG: Integer.MAX_VALUE = 2,147,483,647
2012-12-12 11:56:19,643 [main] DEBUG: Long.MAX_VALUE = 9,223,372,036,854,775,807
</pre>
          <h4>Logger names</h4>
            <p>
              Most logging implementations use a hierarchical scheme for matching logger names with logging
              configuration. In this scheme the logger name hierarchy is represented by '.' characters in the
              logger name, in a fashion very similar to the hierarchy used for Java package names. For example,
              org.apache.logging.appender and org.apache.logging.filter both have org.apache.logging as their parent.
              In most cases, applications name their loggers by passing the current class's name to
              LogManager.getLogger.  Because this usage is so common, Log4j 2 provides that as the default when
              the logger name parameter is either omitted or is null. For example, in both examples below the Logger will
              have a name of "org.apache.test.MyTest".
            </p>
            <pre class="prettyprint linenums">package org.apache.test;

public class MyTest {
    private static Logger logger = LogManager.getLogger(MyTest.class.getName());
}
            </pre>
            <pre class="prettyprint linenums">package org.apache.test;

              public class MyTest {
              private static Logger logger = LogManager.getLogger();
              }
            </pre>
          </subsection>
        </section>
    </body>
</document>
