src/site/index.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.
////

include::_constants.adoc[]
:log4j-url: https://logging.apache.org/log4j/2.x
:log4j-api-url: {log4j-url}/manual/api-separation.html

= Log4j Scala API

{project-name} provides a Scala-friendly interface to log against {log4j-api-url}[the Log4j API].
It supports Scala `2.10`, `2.11`, `2.12`, `2.13`, and `3`.

[IMPORTANT]
====
This is just a logging API.
Your application still needs to have a logging backend (e.g., {log4j-url}[Log4j]) configured.
====

[#dependencies]
== Dependencies

You need to have the `org.apache.logging.log4j:log4j-api-scala` dependency in your classpath:

[source,sbt,subs="+attributes"]
----
libraryDependencies ++= Seq(
  "org.apache.logging.log4j" %% "log4j-api-scala" % "{project-version}"
)
----

Java module name and OSGi `Bundle-SymbolicName` are set to `{bnd-module-name}`.

[#usage]
== Usage

Using the Scala API is as simple as mixing in the `Logging` trait to your class:

[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}.")
  }

}
----

[#params]
== Parameter substitution

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:

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

[#logger-names]
== 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.

[#development]
== Development

{project-name} uses {project-github-url}[GitHub] for source code management.

The project requires two Java compilers to build:

. `8` (required for Scala `2.10` and `2.11`)
. one matching the `{java-compiler-version}` range.

You can build and verify sources using:

[source,bash]
----
./mvnw verify
----

You can build and view the website as follows:

[source,bash]
----
./mvnw -N site
python -m http.server -d target/site
----

[#distribution]
== Distribution

In accordance with the Apache Software Foundation's release https://infra.apache.org/release-distribution.html[distribution policy] and https://infra.apache.org/release-publishing.html[creation process], project artifacts are _officially_ accessible from the following locations:

* ASF https://repository.apache.org/content/repositories/releases[Release] and https://repository.apache.org/content/repositories/snapshots[snapshot] repositories (mirrored to https://central.sonatype.dev/[the Maven Central Repository])
* ASF https://downloads.apache.org/logging/{project-id}[Distribution directory]

See xref:#release-instructions[the release instructions] for details.

[#support]
== Support

Please keep in mind that this project is intended for internal usage only.
You can use GitHub Issues for feature requests and bug reports – not questions!
See https://logging.apache.org/log4j/2.x/support.html[the Log4j support policy] for details.

[#security]
== Security

If you have encountered an unlisted security vulnerability or other unexpected behaviour that has security impact, please report them privately to mailto:security@logging.apache.org[the Log4j security mailing list].
See https://logging.apache.org/log4j/2.x/security.html[the Log4j Security page] for further details.

include::_release-notes.adoc[]

[#release-instructions]
== Release instructions

{project-name} employs the CI/CD foundation provided by the https://logging.apache.org/logging-parent[`logging-parent`].
You can simply use its release instructions.

[#license]
== License

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.
See `NOTICE.txt` 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 https://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.