(logging-log4j2) branch doc-installation updated: Add information about JCL and JBoss Logging

[pk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

pkarwasz pushed a commit to branch doc-installation
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git


The following commit(s) were added to refs/heads/doc-installation by this push:
     new 462139c6ad Add information about JCL and JBoss Logging
462139c6ad is described below

commit 462139c6add293485f79bb1169675251b1eecf6d
Author: Piotr P. Karwasz <pi...@karwasz.org>
AuthorDate: Wed Apr 17 13:07:47 2024 +0200

    Add information about JCL and JBoss Logging
---
 src/site/antora/antora.tmpl.yml                    |  1 +
 src/site/antora/antora.yml                         |  1 +
 .../modules/ROOT/pages/manual/installation.adoc    | 51 ++++++++++++++++++++--
 3 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/src/site/antora/antora.tmpl.yml b/src/site/antora/antora.tmpl.yml
index 44a0c8b725..6eb73db6fc 100644
--- a/src/site/antora/antora.tmpl.yml
+++ b/src/site/antora/antora.tmpl.yml
@@ -46,6 +46,7 @@ asciidoc:
     java-compiler-version: "${minimalJavaBuildVersion}"
     logging-services-url: "https://logging.apache.org"
     # Dependency versions
+    commons-logging-version: "${commons-logging.version}"
     log4j-api-version: "${log4j-api.version}"
     log4j-core-version: "${site-log4j-core.version}"
     log4j-layout-template-json-version: "${site-log4j-layout-template-json.version}"
diff --git a/src/site/antora/antora.yml b/src/site/antora/antora.yml
index 9c25c458be..68647cec44 100644
--- a/src/site/antora/antora.yml
+++ b/src/site/antora/antora.yml
@@ -46,6 +46,7 @@ asciidoc:
     java-compiler-version: "[17,18)"
     logging-services-url: "https://logging.apache.org"
     # Dependency versions
+    commons-logging-version: "1.4.0"
     log4j-api-version: "1.2.3-api"
     log4j-core-version: "1.2.3-core"
     log4j-layout-template-json-version: "1.2.3-layout-template-json"
diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
index 9b186f77e3..e1f2907b58 100644
--- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
@@ -20,6 +20,7 @@
 :jul-link: https://docs.oracle.com/en/java/javase/{java-target-version}/core/java-logging-overview.html[JUL (Java Logging)]
 :logback-link: https://logback.qos.ch/[Logback]
 :slf4j-link: https://www.slf4j.org/[SLF4J]
+:jboss-logging-link: https://github.com/jboss-logging/jboss-logging[JBoss Logging]
 
 = Installation
 
@@ -55,7 +56,7 @@ It is crucial to understand certain concepts in logging to be able to talk about
 Logging API::
 A logging API is an interface your code or your dependencies directly logs against.
 It is implementation agnostic.
-Log4j API, {slf4j-link}, {jul-link}, {jcl-link}, and {jpl-link} are major logging APIs.
+Log4j API, {slf4j-link}, {jul-link}, {jcl-link}, {jpl-link} and {jboss-logging-link} are major logging APIs.
 
 [#logging-impl]
 Logging implementation::
@@ -71,7 +72,8 @@ In the case of Log4j, the API is called _Log4j API_, and its reference implement
 [#logging-bridge]
 Logging API bridges::
 Logging implementations are generally developed to directly accept input from a primary API of their preference; Log4j Core from Log4j API, Logback from SLF4J, etc.
-Logging API bridges allow a logging implementation to accept input from other logging APIs that are not their primary logging API. For instance, `log4j-slf4j2-impl` _bridges_ SLF4J calls to Log4 API and effectively enables Log4j Core to accept input from SLF4J.
+Logging API bridges allow a logging implementation to accept input from other logging APIs that are not their primary logging API.
+For instance, `log4j-slf4j2-impl` _bridges_ SLF4J calls to Log4 API and effectively enables Log4j Core to accept input from SLF4J.
 
 With this in mind, the type of software you are writing determines whether you should be installing a logging API, implementation, or bridge:
 
@@ -353,7 +355,7 @@ In order to activate the bridge from JUL to Log4j API, you also need to add:
 
 to the JVM parameters in your application launcher.
 
-[#impl-core-bridge-jcl]
+[#impl-core-bridge-jpl]
 ===== Installing JPL-to-Log4j bridge
 
 You can translate {jpl-link} calls to Log4j API using the `log4j-jpl` artifact:
@@ -380,6 +382,38 @@ runtimeOnly 'org.apache.logging.log4j:log4j-jpl' // JPL-to-Log4j bridge
 ----
 ====
 
+[#impl-core-bridge-jcl]
+===== Installing JCL-to-Log4j bridge
+
+Since version `1.3.0` https://commons.apache.org/proper/commons-logging/[Apache Commons Logging] natively supports Log4j API.
+
+You can enforce the version of a transitive dependency using the dependency management mechanism appropriate to your
+build tool:
+
+Maven::
+Maven users should add an entry to the `<dependencyManagement>` section of their POM file:
++
+[source,xml,subs="+attributes"]
+----
+<dependencyManagement>
+    <dependency>
+        <groupId>commons-logging</groupId>
+        <artifactId>commons-logging</artifactId>
+        <version>{commons-logging-version}</version>
+    </dependency>
+</dependencyManagement>
+----
+
+Gradle::
++
+Gradle users should refer to the https://docs.gradle.org/current/userguide/platforms.html#sub:using-platform-to-control-transitive-deps[Using a platform to control transitive versions] of the Gradle documentation.
+
+[#impl-core-bridge-jboss-logging]
+===== Installing JBoss Logging-to-Log4j bridge
+
+The JBoss Logging API is shipped with an integrated bridge to Log4j API and requires no steps from your part. See
+https://github.com/jboss-logging/jboss-logging?tab=readme-ov-file#supported-log-managers[Supported Log Managers] for more information.
+
 [#impl-core-spring-boot]
 ==== Installing Log4j Core for Spring Boot applications
 
@@ -387,6 +421,7 @@ Spring Boot users should replace the `spring-boot-starter-logging` dependency wi
 
 [tabs]
 ====
+
 Maven::
 +
 [source,xml]
@@ -439,6 +474,7 @@ A basic configuration can be obtained by adding one of these files to your appli
 
 [tabs]
 ====
+
 log4j2.xml::
 +
 [source,xml]
@@ -505,12 +541,14 @@ Configuration.Appenders.Console.name = CONSOLE
 Configuration.Loggers.Root.level = INFO
 Configuration.Loggers.Root.AppenderRef.ref = CONSOLE
 ----
+
 ====
 
 In order to use these formats, the following additional dependencies are required:
 
 [tabs]
 ====
+
 Maven::
 +
 [tabs]
@@ -597,11 +635,15 @@ runtimeOnly 'org.apache.logging.log4j:log4j-config-properties'
 [#impl-jul]
 === Installing JUL
 
+TIP::
+Are you using https://github.com/jboss-logging/jboss-logmanager[JBoss Log Manager] as JUL implementation? You can skip this section and use the https://github.com/jboss-logging/log4j2-jboss-logmanager[log4j2-jboss-logmanager] and https://github.com/jboss-logging/slf4j-jboss-logmanager[slf4j-jboss-logmanager] bridges from the JBoss Logging project instead.
+
 Java Platform contains a very simple logging API and its implementation called {jul-link}.
 Since it is embedded in the platform, it only requires the addition of bridges from Log4j API and SLF4J:
 
 [tabs]
 ====
+
 Maven::
 +
 [source,xml,subs="+attributes"]
@@ -631,6 +673,7 @@ Gradle::
 runtimeOnly 'org.apache.logging.log4j:log4j-to-jul' // Log4j-to-JUL bridge
 runtimeOnly 'org.slf4j:slf4j-jdk14:{slf4j-version}' // SLF4J-to-JUL bridge
 ----
+
 ====
 
 To configure JUL, see https://docs.oracle.com/en/java/javase/{java-target-version}/docs/api/java.logging/java/util/logging/LogManager.html[`java.util.logging.LogManager`].
@@ -642,6 +685,7 @@ To install https://logback.qos.ch/[Logback] as the logging implementation, you o
 
 [tabs]
 ====
+
 Maven::
 +
 [source,xml]
@@ -669,6 +713,7 @@ Gradle::
 runtimeOnly 'ch.qos.logback:logback-classic:{logback-version}'
 runtimeOnly 'org.apache.logging.log4j:log4j-to-slf4j' // Log4j-to-SLF4J bridge
 ----
+
 ====
 
 To configure Logback, see https://logback.qos.ch/manual/configuration.html[Logback's configuration documentation].