src/asciidoctor/usage.adoc

////
    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.
////
== Usage

Using the Scala API is as simple as mixing in the https://logging.apache.org/log4j/scala/log4j-api-scala_2.12/scaladocs/org/apache/logging/log4j/scala/[`Logging`] trait to your class. Example:

[source,scala]
----
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")
  }
  def doStuffWithUser(user: User): Unit = {
    logger.info(s"Doing stuff with ${user.getName}.")
  }
}
----

=== API Documentation

|===
|Scala Version |API Link

|Scala 2.10
|https://logging.apache.org/log4j/scala/log4j-api-scala_2.10/scaladocs/#org.apache.logging.log4j.scala.package[ScalaDocs]

|Scala 2.11
|https://logging.apache.org/log4j/scala/log4j-api-scala_2.11/scaladocs/#org.apache.logging.log4j.scala.package[ScalaDocs]

|Scala 2.12
|https://logging.apache.org/log4j/scala/log4j-api-scala_2.12/scaladocs/org/apache/logging/log4j/scala/[ScalaDocs]
|===

=== Configuration

Log4j Scala API uses https://logging.apache.org/log4j/2.x/manual/configuration.html[Log4j configuration] by default.
This supports XML, properties files, and Java-based builders, as well as JSON and YAML with additional dependencies.

=== Substituting Parameters

Unlike in Java, Scala provides native functionality for string interpolation https://docs.scala-lang.org/overviews/core/string-interpolation.html[beginning in Scala 2.10].
As all logger calls are implemented as macros, using string interpolation directly does not require additional if checks.
For example:

[source,scala]
----
logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}")
----

=== Logger Names

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 `Logger` property added by the `Logging` trait follows this convention: the trait ensures the `Logger` is automatically named according to the class it is being used in.