Overridable Commons Logging bridge in separate spring-jcl jar

Issue: SPR-14512

Author: jhoeller

build.gradle

@@ -301,6 +301,15 @@ project("spring-build-src") {
 	configurations.archives.artifacts.clear()
 }
 
+project("spring-jcl") {
+	description = "Spring Commons Logging Bridge"
+
+	dependencies {
+		optional("org.apache.logging.log4j:log4j-api:${log4jVersion}")
+		optional("org.slf4j:slf4j-api:${slf4jVersion}")
+	}
+}
+
 project("spring-core") {
 	description = "Spring Core"
 
@@ -366,8 +375,7 @@ project("spring-core") {
 
 		compile(files(cglibRepackJar))
 		compile(files(objenesisRepackJar))
-		optional("org.apache.logging.log4j:log4j-api:${log4jVersion}")
-		optional("org.slf4j:slf4j-api:${slf4jVersion}")
+		compile(project(":spring-jcl"))
 		optional("net.sf.jopt-simple:jopt-simple:5.0.3")
 		optional("org.aspectj:aspectjweaver:${aspectjVersion}")
 		optional("org.jetbrains.kotlin:kotlin-reflect:${kotlinVersion}")

settings.gradle

@@ -10,6 +10,7 @@ include "spring-context-indexer"
 include "spring-core"
 include "spring-expression"
 include "spring-instrument"
+include "spring-jcl"
 include "spring-jdbc"
 include "spring-jms"
 include "spring-messaging"

spring-core/src/main/java/org/apache/commons/logging/package-info.java

@@ -0,0 +1,25 @@
+/**
+ * Spring's variant of the
+ * <a href="http://commons.apache.org/logging">Commons Logging API</a>:
+ * with special support for Log4J 2, SLF4J and {@code java.util.logging}.
+ *
+ * <p>This is a custom bridge along the lines of {@code jcl-over-slf4j}.
+ * You may exclude {@code spring-jcl} and switch to {@code jcl-over-slf4j}
+ * instead if you prefer the hard-bound SLF4J bridge. However, Spring's own
+ * bridge provides a better out-of-the-box experience when using Log4J 2
+ * or {@code java.util.logging}, with no extra bridge jars necessary, and
+ * also easier setup of SLF4J with Logback (no JCL exclude, no JCL bridge).
+ *
+ * <p>{@link org.apache.commons.logging.Log} is an unmodified repackaging.
+ * However, {@link org.apache.commons.logging.LogFactory} is a very different
+ * implementation which is minimized and optimized for Spring's purposes,
+ * detecting Log4J 2.x and SLF4J 1.7 in the framework classpath and falling
+ * back to {@code java.util.logging}. If you run into any issues with this
+ * implementation, consider excluding {@code spring-jcl} and switching to the
+ * standard {@code commons-logging} artifact or to {@code jcl-over-slf4j}.
+ *
+ * <p>Note that this Commons Logging bridge is only meant to be used for
+ * framework logging purposes, both in the core framework and in extensions.
+ * For applications, prefer direct use of Log4J/SLF4J or {@code java.util.logging}.
+ */
+package org.apache.commons.logging;

spring-core/src/main/java/org/apache/commons/logging/Log.java renamed to spring-jcl/src/main/java/org/apache/commons/logging/Log.java

@@ -395,8 +395,8 @@ Although Spring provides integration and support for a huge range of enterprise
 other external tools, it intentionally keeps its mandatory dependencies to an absolute
 minimum: you shouldn't have to locate and download (even automatically) a large number
 of jar libraries in order to use Spring for simple use cases. For basic dependency
-injection there is only one mandatory external dependency, and that is for logging (see
-below for a more detailed description of logging options).
+injection there is only one mandatory external dependency, and that is for logging
+(see below for a more detailed description of logging options).
 
 Next we outline the basic steps needed to configure an application that depends on
 Spring, first with Maven and then with Gradle and finally using Ivy. In all cases, if
@@ -597,11 +597,12 @@ http://repo.spring.io/snapshot/org/springframework/spring[snapshots].
 ==== Logging
 Spring's logging setup has been revised for Spring 5: It is still based on the Apache
 Commons Logging API, also known as Jakarta Commons Logging (JCL). However, `spring-core`
-includes an embedded variant of Commons Logging now, with a Spring-specific `LogFactory`
-which automatically bridges to https://logging.apache.org/log4j/2.x/[Log4j 2],
-http://www.slf4j.org[SLF4J], or the JDK's own `java.util.logging` (JUL). This
-implementation acts like the JCL-over-SLF4J bridge but with a range of dynamically
-detected providers, analogous to JBoss Logging's common targets (as used by Hibernate).
+refers to a custom Commons Logging bridge in the `spring-jcl` module now, with a
+Spring-specific `LogFactory` implementation which automatically bridges to
+https://logging.apache.org/log4j/2.x/[Log4j 2], http://www.slf4j.org[SLF4J], or the
+JDK's own `java.util.logging` (JUL). This implementation acts like the JCL-over-SLF4J
+bridge but with a range of dynamically detected providers, analogous to JBoss Logging's
+common targets (as supported by e.g. Hibernate and Undertow).
 
 As a benefit, there is no need for external bridges like JCL-over-SLF4J anymore,
 and correspondingly no need for a manual exclude of the standard Commons Logging jar
@@ -630,6 +631,10 @@ up since Spring's bridge does not support custom `commons-logging.properties' se
 For any other log provider, please set up a corresponding SLF4J or JUL bridge (which
 you are very likely going to need for other libraries such as Hibernate anyway).
 Note that Log4j 1.x has reached its end-of-life; please migrate to Log4j 2.x.
+
+If you run into any remaining issues with Spring's Commons Logging implementation,
+consider excluding `spring-jcl` and switching to the standard `commons-logging`
+artifact (supporting `commons-logging.properties' setup) or to `jcl-over-slf4j`.
 ====
 
 [[overview-logging-log4j]]