<?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 xmlns="http://maven.apache.org/XDOC/2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
    <properties>
        <title>Migrating from Log4j 1.x</title>
        <author email="rgoers@apache.org">Ralph Goers</author>
    </properties>

    <body>
        <section name="Migrating from Log4j 1.x">
          <a name="Log4j1.2Bridge"/>
          <subsection name="Using the Log4j 1.x bridge">
            <p>
              Perhaps the simplest way to convert to using Log4j 2 is to replace the log4j 1.x jar file with
              Log4j 2's <code>log4j-1.2-api.jar</code>. However, to use this successfully applications must meet the
              following requirements:
            </p>
              <ol>
                <li>They must not access methods and classes internal to the Log4j 1.x implementation such
                  as <code>Appender</code>s, <code>LoggerRepository</code> or <code>Category</code>'s
                  <code>callAppenders</code> method.</li>
                <li>They must not programmatically configure Log4j.</li>
                <li>They must not configure by calling the classes <code>DOMConfigurator</code> or
                  <code>PropertyConfigurator</code>.</li>
              </ol>
          </subsection>
          <subsection name="Converting to the Log4j 2 API">
            <p>For the most part, converting from the Log4j 1.x API to Log4j 2 should be fairly simple. Many
              of the log statements will require no modification. However, where necessary the following changes must be
              made.</p>
              <ol>
                <li>
                  The main package in version 1 is <code>org.apache.log4j</code>, in version 2 it is
                  <code>org.apache.logging.log4j</code>
                </li>
                <li>
                  Calls to <code>org.apache.log4j.Logger.getLogger()</code> must be modified to
                  <code>org.apache.logging.log4j.LogManager.getLogger()</code>.
                </li>
                <li>
                  Calls to <code>org.apache.log4j.Logger.getRootLogger()</code> or
                  <code>org.apache.log4j.LogManager.getRootLogger()</code> must be replaced with
                  <code>org.apache.logging.log4j.LogManager.getRootLogger()</code>.</li>
                <li>
                  Calls to <code>org.apache.log4j.Logger.getLogger</code> that accept a <code>LoggerFactory</code> must
                  remove the <code>org.apache.log4j.spi.LoggerFactory</code> and use one of Log4j 2's other extension
                  mechanisms.
                </li>
                <li>
                  Replace calls to <code>org.apache.log4j.Logger.getEffectiveLevel()</code> with
                  <code>org.apache.logging.log4j.Logger.getLevel()</code>.
                </li>
                <li>
                  Remove calls to <code>org.apache.log4j.LogManager.shutdown()</code>, they are not needed in version 2
                  because the Log4j Core now automatically adds a JVM shutdown hook on start up to perform any Core
                  clean ups.
                  <ol>
                    <li>
                      Starting in Log4j 2.1, you can specify a custom
                      <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry.html">ShutdownCallbackRegistry</a>
                      to override the default JVM shutdown hook strategy.
                    </li>
                    <li>
                      Starting in Log4j 2.6, you can now use <code>org.apache.logging.log4j.LogManager.shutdown()</code>
                      to initiate shutdown manually.
                    </li>
                  </ol>
                </li>
                <li>
                  Calls to <code>org.apache.log4j.Logger.setLevel()</code> or similar methods are not supported in the API.
                  Applications should remove these. Equivalent functionality is provided in the Log4j 2 implementation
                  classes, see <code>org.apache.logging.log4j.core.config.Configurator.setLevel()</code>, but may leave 
                  the application susceptible to changes in Log4j 2 internals.                   
                </li>
                <li>
                  Where appropriate, applications should convert to use parameterized messages instead of String
                  concatenation.
                </li>
                <li>
                  <a href="http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html"><code>org.apache.log4j.MDC</code></a> and
                  <a href="http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/NDC.html"><code>org.apache.log4j.NDC</code></a>
                  have been replaced by the <a href="thread-context.html">Thread Context</a>.
                </li>
              </ol>
          </subsection>
          <subsection name="Configuring Log4j 2">
            <p>
              Although the Log4j 2 configuration syntax is different than that of Log4j 1.x, most, if not all, of
              the same functionality is available.
            </p>
            <p>
              Note that system property interpolation via the <code>${foo}</code> syntax has been extended to allow
              property lookups from many different sources. See the <a href="lookups.html">Lookups</a> documentation
              for more details. For example, using a lookup for the system property named <code>catalina.base</code>,
              in Log4j 1.x, the syntax would be <code>${catalina.base}</code>. In Log4j 2, the syntax would be
              <code>${sys:catalina.base}</code>.
            </p>
            <p>
              Log4j 1.x has a XMLLayout which is different from the XmlLayout in Log4j 2, the log4j-1.2-api module
              contains a <code>Log4j1XmlLayout</code> which produce output in the format as in Log4j 1.x.
              The Log4j 1.x <code>SimpleLayout</code> can be emulated with PatternLayout "%level - %m%n".
              The Log4j 1.x <code>TTCCLayout</code> can be emulated with PatternLayout "%r [%t] %p %c %notEmpty{%ndc }- %m%n".
            </p>
            <p>
              Both <code>PatternLayout</code> and <code>EnhancedPatternLayout</code> in Log4j 1.x can be replaced with
              <code>PatternLayout</code> in Log4j 2. The log4j-1.2-api module contains two pattern conversions "%ndc" and "%properties" which
              can be used to emulate "%x" and "%X" in Log4j 1.x PatternLayout ("%x" and %X" in Log4j 2 have a slightly different format).
            </p>
            <p>
              Below are the example configurations for Log4j 1.x and their counterparts in Log4j 2.
            </p>

            <h4>Sample 1 - Simple configuration using a Console Appender</h4>
            <p>Log4j 1.x XML configuration</p>
            <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
<log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'>
  <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </layout>
  </appender>
  <category name="org.apache.log4j.xml">
    <priority value="info" />
  </category>
  <Root>
    <priority value ="debug" />
    <appender-ref ref="STDOUT" />
  </Root>
</log4j:configuration>]]></pre>
            <p>Log4j 2 XML configuration</p>
            <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
  <Appenders>
    <Console name="STDOUT" target="SYSTEM_OUT">
      <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="org.apache.log4j.xml" level="info"/>
    <Root level="debug">
      <AppenderRef ref="STDOUT"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>

            <h4>Sample 2 - Simple configuration using a File Appender, XMLLayout and SimpleLayout</h4>
            <p>Log4j 1.x XML configuration</p>
            <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
  <appender name="A1" class="org.apache.log4j.FileAppender">
    <param name="File"   value="A1.log" />
    <param name="Append" value="false" />
    <layout class="org.apache.log4j.xml.XMLLayout" />
  </appender>
  <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.SimpleLayout" />
  </appender>
  <category name="org.apache.log4j.xml">
    <priority value="debug" />
    <appender-ref ref="A1" />
  </category>
  <root>
    <priority value ="debug" />
    <appender-ref ref="STDOUT" />
  </Root>
</log4j:configuration>]]></pre>

           <p>Log4j 2 XML configuration</p>
            <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
  <Appenders>
    <File name="A1" fileName="A1.log" append="false">
      <Log4j1XmlLayout />
    </File>
    <Console name="STDOUT" target="SYSTEM_OUT">
      <PatternLayout pattern="%level - %m%n"/>
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="org.apache.log4j.xml" level="debug">
      <AppenderRef ref="A1"/>
    </Logger>
    <Root level="debug">
      <AppenderRef ref="STDOUT"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>

            <h4>Sample 3 - SocketAppender</h4>
            <p>Log4j 1.x XML configuration. This example from Log4j 1.x is misleading. The SocketAppender does not
              actually use a Layout. Configuring one will have no effect.</p>
            <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
  <appender name="A1" class="org.apache.log4j.net.SocketAppender">
    <param name="RemoteHost" value="localhost"/>
    <param name="Port" value="5000"/>
    <param name="LocationInfo" value="true"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%t %-5p %c{2} - %m%n"/>
    </layout>
  </appender>
  <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </layout>
  </appender>
  <category name="org.apache.log4j.xml">
    <priority value="debug"/>
    <appender-ref ref="A1"/>
  </category>
  <root>
    <priority value="debug"/>
    <appender-ref ref="STDOUT"/>
  </Root>
</log4j:configuration>]]></pre>

           <p>Log4j 2 XML configuration</p>
            <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
  <Appenders>
    <Socket name="A1" host="localHost" port="5000">
      <PatternLayout pattern="%t %-5p %c{2} - %m%n"/>
    </Socket>
    <Console name="STDOUT" target="SYSTEM_OUT">
      <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="org.apache.log4j.xml" level="debug">
      <AppenderRef ref="A1"/>
    </Logger>
    <Root level="debug">
      <AppenderRef ref="STDOUT"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>

            <h4>Sample 4 - AsyncAppender and TTCCLayout</h4>
            <p>Log4j 1.x XML configuration using the AsyncAppender.</p>
            <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" configDebug="true">
  <appender name="ASYNC" class="org.apache.log4j.AsyncAppender">
    <appender-ref ref="TEMP"/>
  </appender>
  <appender name="TEMP" class="org.apache.log4j.FileAppender">
    <param name="File" value="temp"/>
    <layout class="org.apache.log4j.TTCCLayout">
      <param name="ThreadPrinting" value="true"/>
      <param name="CategoryPrefixing" value="true"/>
      <param name="ContextPrinting" value="true"/>
    </layout>
  </appender>
  <root>
    <priority value="debug"/>
    <appender-ref ref="ASYNC"/>
  </Root>
</log4j:configuration>]]></pre>

           <p>Log4j 2 XML configuration. </p>
            <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="debug">
  <Appenders>
    <File name="TEMP" fileName="temp">
      <PatternLayout pattern="%r [%t] %p %c %notEmpty{%ndc }- %m%n"/>
    </File>
    <Async name="ASYNC">
      <AppenderRef ref="TEMP"/>
    </Async>
  </Appenders>
  <Loggers>
    <Root level="debug">
      <AppenderRef ref="ASYNC"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>


            <h4>Sample 5 - AsyncAppender with Console and File</h4>
            <p>Log4j 1.x XML configuration using the AsyncAppender.</p>
            <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN" "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" configDebug="true">
  <appender name="ASYNC" class="org.apache.log4j.AsyncAppender">
    <appender-ref ref="TEMP"/>
    <appender-ref ref="CONSOLE"/>
  </appender>
  <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </layout>
  </appender>
  <appender name="TEMP" class="org.apache.log4j.FileAppender">
    <param name="File" value="temp"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </layout>
  </appender>
  <root>
    <priority value="debug"/>
    <appender-ref ref="ASYNC"/>
  </Root>
</log4j:configuration>]]></pre>

            <p>Log4j 2 XML configuration. Note that the Async Appender should be configured after the appenders it
              references. This will allow it to shutdown properly.</p>
            <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="debug">
  <Appenders>
    <Console name="CONSOLE" target="SYSTEM_OUT">
      <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </Console>
    <File name="TEMP" fileName="temp">
      <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
    </File>
    <Async name="ASYNC">
      <AppenderRef ref="TEMP"/>
      <AppenderRef ref="CONSOLE"/>
    </Async>
  </Appenders>
  <Loggers>
    <Root level="debug">
      <AppenderRef ref="ASYNC"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
          </subsection>
        </section>
    </body>
</document>
