<?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>Log4j 2 Scala API</title>
        <author email="mikes@apache.org">Mikael Ståldal</author>
    </properties>

    <body>
        <section name="Log4j 2 API">
            <a name="ScalaAPI"/>
            <subsection name="Scala API">
                <p>
                    Log4j 2 has a companion Log4j Scala project that contains a convenient Scala wrapper for the
                    <a class="javadoc" href="../log4j-api/apidocs/org/apache/logging/log4j/Logger.html">Logger</a>
                    API.
                </p>

                <h4>Requirements</h4>
                <p>
                    Log4j 2 Scala API is dependent on the Log4j 2 API, Scala runtime library and reflection.
                    It currently supports Scala 2.10, 2.11 and 2.12. See <a href="../maven-artifacts.html#Scala_API">instructions</a>
                    on including this in an SBT, Maven, Ivy, or Gradle project.
                </p>

                <h4>Example</h4>
                <pre class="prettyprint linenums">
import org.apache.logging.log4j.scala.Logging
import org.apache.logging.log4j.Level

class MyClass extends BaseClass with Logging {
  def doStuff(): Unit = {
    logger.info("Doing stuff")
  }
  def doStuffWithLevel(level: Level): Unit = {
    logger(level, "Doing stuff with arbitrary level")
  }
}
                </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 Scala, you can use
                    <a href="http://docs.scala-lang.org/overviews/core/string-interpolation.html">string interpolation
                    </a>
                    to achieve this:
                </p>
                <pre class="prettyprint">
logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}")
                </pre>
                <p>
                    Since the Scala Logger is implemented with macros, the String construction and method invocations
                    will only occur when debug logging is enabled.
                </p>

                <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/Scala package names.
                    The Logging trait will automatically name the Logger accordingly to the class it is being used in.
                </p>

              <p>Please see the <a href="http://logging.apache.org/log4j/scala/index.html">Log4j Scala</a> project for more details.</p>

            </subsection>
        </section>
    </body>
</document>