Merge remote-tracking branch 'apache/2.x' into fix/2.x/use-random-logging-path

Author: ppkarwasz

BUILDING.adoc

@@ -172,3 +172,59 @@ CI=true ./mvnw ...
 === Compilation in IntelliJ IDEA fails with `java: plug-in not found: ErrorProne`
 
 Try removing all _"Override compiler parameters per-module"_ entries in _"Settings > Build, Execution, Deployment > Compiler > Java Compiler"_.
+
+[#development-api-compatibility]
+=== Fixing API compatibility check failures
+
+Log4j uses the
+https://github.com/bndtools/bnd/tree/master/maven-plugins/bnd-baseline-maven-plugin[BND Baseline Maven Plugin]
+to enforce its
+https://semver.org/[semantic versioning policy].
+Following the
+https://bnd.bndtools.org/chapters/170-versioning.html#best-practices[OSGi versioning best practices], both Log4j artifacts and packages are versioned.
+If you modify Log4j's public API, a BND Baseline error like the following will occur:
+
+[source]
+----
+  Name                        Type     Delta      New    Old    Suggest  If Prov.
+  org.apache.logging.foo      PACKAGE  UNCHANGED  2.1.0  2.1.0  ok       -
+* org.apache.logging.foo.bar  PACKAGE  MINOR      2.3.4  2.3.4  2.4.0    -
+  MINOR        PACKAGE    org.apache.logging.foo.bar
+  ...
+----
+
+The solution of the error depends on the change kind (`Delta`):
+
+[#development-api-compatibility-micro]
+`MICRO`::
++
+For patch level changes modify the `package-info.java` file of the `org.apache.logging.foo.bar` package and update the `@Version` annotation to the number suggested by BND: increment just the patch number.
++
+[source,java]
+----
+@Version("2.3.5")
+package org.apache.logging.foo.bar;
+----
+
+[#development-api-compatibility-minor]
+`MINOR`::
++
+Changes of type `MINOR` require more work:
++
+--
+* Make sure that the current Log4j version is a minor upgrade over the last released version.
+If that is not the case (e.g., it is `2.34.5-SNAPSHOT`) modify the `<revision>` property in the main POM file (e.g., change it to `2.35.0-SNAPSHOT`).
+* Make sure to add a
+https://logging.apache.org/log4j/tools/log4j-changelog.html#changelog-entry-file[changelog entry]
+of type `added`, `changed` or `deprecated` to your PR.
+* As in the
+<<development-api-compatibility-micro,`MICRO` case>>
+modify the `package-info.java` file of the package and update the `@Version` annotation to the **next Log4j version** (`2.35.0` in the example) and **not** the minimal version number suggested by BND.
+The purpose of this policy is to have an alignment between package versions and the last Log4j version, where an API change occurred.
+--
+
+[#development-api-compatibility-major]
+`MAJOR`::
++
+Changes of type `MAJOR` (i.e. breaking changes) are not accepted in the `2.x` branch.
+If you believe it is not a breaking change (e.g., you removed a class **documented** as private), the development team will guide you on how to solve it.

log4j-1.2-api/pom.xml

@@ -43,93 +43,100 @@
       com.sun.jdmk.comm;resolution:=optional,
       <!-- JMS is optional -->
       javax.jms;version="[1.1,3)";resolution:=optional,
-      <!-- Log4j Core is optional -->
-      org.apache.logging.log4j.core.*;resolution:=optional
     </bnd-extra-package-options>
+    <bnd-extra-module-options>
+      <!-- Log4j Core is optional -->
+      org.apache.logging.log4j.core;static=true
+    </bnd-extra-module-options>
     <Fragment-Host>org.apache.logging.log4j.core</Fragment-Host>
-    <!-- we have an `bnd.bnd` file to override the parent's defaults -->
   </properties>
 
   <dependencies>
+
     <!-- Used for JMS appenders (needs an implementation of course) -->
     <dependency>
       <groupId>javax.jms</groupId>
       <artifactId>javax.jms-api</artifactId>
       <scope>provided</scope>
-      <optional>true</optional>
     </dependency>
-    <!-- Log4j Runtime -->
+
+    <dependency>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+      <scope>test</scope>
+    </dependency>
+
     <dependency>
       <groupId>org.apache.logging.log4j</groupId>
       <artifactId>log4j-api</artifactId>
     </dependency>
+
     <dependency>
       <groupId>org.apache.logging.log4j</groupId>
       <artifactId>log4j-core</artifactId>
       <optional>true</optional>
     </dependency>
+
     <dependency>
       <groupId>org.apache.logging.log4j</groupId>
       <artifactId>log4j-api-test</artifactId>
       <scope>test</scope>
     </dependency>
+
     <dependency>
       <groupId>org.apache.logging.log4j</groupId>
       <artifactId>log4j-core-test</artifactId>
       <scope>test</scope>
     </dependency>
+
     <dependency>
       <groupId>org.awaitility</groupId>
       <artifactId>awaitility</artifactId>
       <scope>test</scope>
     </dependency>
+
     <dependency>
       <groupId>commons-io</groupId>
       <artifactId>commons-io</artifactId>
       <scope>test</scope>
     </dependency>
+
     <dependency>
       <groupId>org.apache.commons</groupId>
       <artifactId>commons-lang3</artifactId>
       <scope>test</scope>
     </dependency>
+
     <dependency>
       <groupId>com.fasterxml.jackson.dataformat</groupId>
       <artifactId>jackson-dataformat-xml</artifactId>
       <scope>test</scope>
     </dependency>
+
+    <!-- JUnit -->
     <dependency>
       <groupId>org.junit.jupiter</groupId>
       <artifactId>junit-jupiter-engine</artifactId>
       <scope>test</scope>
     </dependency>
+
     <dependency>
       <groupId>org.junit.jupiter</groupId>
       <artifactId>junit-jupiter-params</artifactId>
       <scope>test</scope>
     </dependency>
-    <!-- JUnit -->
     <dependency>
-      <groupId>org.junit.vintage</groupId>
-      <artifactId>junit-vintage-engine</artifactId>
+      <groupId>org.hamcrest</groupId>
+      <artifactId>hamcrest</artifactId>
       <scope>test</scope>
     </dependency>
+
     <dependency>
       <groupId>org.mockito</groupId>
       <artifactId>mockito-core</artifactId>
       <scope>test</scope>
     </dependency>
-    <!-- 1.2 tests -->
-    <dependency>
-      <groupId>oro</groupId>
-      <artifactId>oro</artifactId>
-      <scope>test</scope>
-    </dependency>
-    <dependency>
-      <groupId>org.apache.velocity</groupId>
-      <artifactId>velocity</artifactId>
-      <scope>test</scope>
-    </dependency>
+
   </dependencies>
 
   <profiles>

log4j-1.2-api/src/main/java/org/apache/log4j/Level.java

@@ -115,8 +115,7 @@ protected Level(
             final String levelStr,
             final int syslogEquivalent,
             final org.apache.logging.log4j.Level version2Equivalent) {
-        super(level, levelStr, syslogEquivalent);
-        this.version2Level = version2Equivalent != null ? version2Equivalent : OptionConverter.createLevel(this);
+        super(level, levelStr, syslogEquivalent, version2Equivalent);
     }
 
     /**
@@ -222,6 +221,7 @@ private void readObject(final ObjectInputStream s) throws IOException, ClassNotF
         if (levelStr == null) {
             levelStr = Strings.EMPTY;
         }
+        version2Level = OptionConverter.createLevel(this);
     }
 
     /**

log4j-1.2-api/src/main/java/org/apache/log4j/Priority.java

@@ -16,6 +16,8 @@
  */
 package org.apache.log4j;
 
+import org.apache.log4j.helpers.OptionConverter;
+
 /**
  * <em style="color:#A44">Refrain from using this class directly, use
  * the {@link Level} class instead.</em>
@@ -64,31 +66,31 @@ public class Priority {
      * @deprecated Use {@link Level#FATAL} instead.
      */
     @Deprecated
-    public static final Priority FATAL = new Level(FATAL_INT, "FATAL", 0);
+    public static final Priority FATAL = new Priority(FATAL_INT, "FATAL", 0, org.apache.logging.log4j.Level.FATAL);
 
     /**
      * @deprecated Use {@link Level#ERROR} instead.
      */
     @Deprecated
-    public static final Priority ERROR = new Level(ERROR_INT, "ERROR", 3);
+    public static final Priority ERROR = new Priority(ERROR_INT, "ERROR", 3, org.apache.logging.log4j.Level.ERROR);
 
     /**
      * @deprecated Use {@link Level#WARN} instead.
      */
     @Deprecated
-    public static final Priority WARN = new Level(WARN_INT, "WARN", 4);
+    public static final Priority WARN = new Priority(WARN_INT, "WARN", 4, org.apache.logging.log4j.Level.WARN);
 
     /**
      * @deprecated Use {@link Level#INFO} instead.
      */
     @Deprecated
-    public static final Priority INFO = new Level(INFO_INT, "INFO", 6);
+    public static final Priority INFO = new Priority(INFO_INT, "INFO", 6, org.apache.logging.log4j.Level.INFO);
 
     /**
      * @deprecated Use {@link Level#DEBUG} instead.
      */
     @Deprecated
-    public static final Priority DEBUG = new Level(DEBUG_INT, "DEBUG", 7);
+    public static final Priority DEBUG = new Priority(DEBUG_INT, "DEBUG", 7, org.apache.logging.log4j.Level.DEBUG);
 
     /*
      * These variables should be private but were not in Log4j 1.2 so are left the same way here.
@@ -102,9 +104,7 @@ public class Priority {
      * Default constructor for deserialization.
      */
     protected Priority() {
-        level = DEBUG_INT;
-        levelStr = "DEBUG";
-        syslogEquivalent = 7;
+        this(DEBUG_INT, "DEBUG", 7, org.apache.logging.log4j.Level.DEBUG);
     }
 
     /**
@@ -114,9 +114,18 @@ protected Priority() {
      * @param syslogEquivalent The equivalent syslog value.
      */
     protected Priority(final int level, final String levelStr, final int syslogEquivalent) {
+        this(level, levelStr, syslogEquivalent, null);
+    }
+
+    Priority(
+            final int level,
+            final String levelStr,
+            final int syslogEquivalent,
+            final org.apache.logging.log4j.Level version2Equivalent) {
         this.level = level;
         this.levelStr = levelStr;
         this.syslogEquivalent = syslogEquivalent;
+        this.version2Level = version2Equivalent != null ? version2Equivalent : OptionConverter.createLevel(this);
     }
 
     /**
@@ -229,7 +238,8 @@ public static Priority toPriority(final int val) {
      */
     @Deprecated
     public static Priority toPriority(final int val, final Priority defaultPriority) {
-        return Level.toLevel(val, (Level) defaultPriority);
+        Level result = Level.toLevel(val, null);
+        return result == null ? defaultPriority : result;
     }
 
     /**
@@ -240,6 +250,7 @@ public static Priority toPriority(final int val, final Priority defaultPriority)
      */
     @Deprecated
     public static Priority toPriority(final String sArg, final Priority defaultPriority) {
-        return Level.toLevel(sArg, (Level) defaultPriority);
+        Level result = Level.toLevel(sArg, null);
+        return result == null ? defaultPriority : result;
     }
 }

log4j-1.2-api/src/main/java/org/apache/log4j/bridge/FilterAdapter.java

@@ -69,7 +69,7 @@ public static Filter addFilter(final Filter first, final Filter second) {
         if (first instanceof FilterWrapper && ((FilterWrapper) first).getFilter() instanceof CompositeFilter) {
             composite = (CompositeFilter) ((FilterWrapper) first).getFilter();
         } else {
-            composite = CompositeFilter.createFilters(new org.apache.logging.log4j.core.Filter[] {adapt(first)});
+            composite = CompositeFilter.createFilters(adapt(first));
         }
         return FilterWrapper.adapt(composite.addFilter(adapt(second)));
     }

log4j-1.2-api/src/main/java/org/apache/log4j/builders/filter/StringMatchFilterBuilder.java

@@ -86,7 +86,7 @@ private Filter createFilter(final String text, final boolean acceptOnMatch) {
                 ? org.apache.logging.log4j.core.Filter.Result.ACCEPT
                 : org.apache.logging.log4j.core.Filter.Result.DENY;
         return FilterWrapper.adapt(StringMatchFilter.newBuilder()
-                .setMatchString(text)
+                .setText(text)
                 .setOnMatch(onMatch)
                 .setOnMismatch(org.apache.logging.log4j.core.Filter.Result.NEUTRAL)
                 .build());

log4j-1.2-api/src/main/java/org/apache/log4j/xml/XmlConfiguration.java

@@ -90,7 +90,6 @@ public class XmlConfiguration extends Log4j1Configuration {
     private static final String INTERNAL_DEBUG_ATTR = "debug";
     private static final String THRESHOLD_ATTR = "threshold";
     private static final String EMPTY_STR = "";
-    private static final Class<?>[] ONE_STRING_PARAM = new Class[] {String.class};
     private static final String dbfKey = "javax.xml.parsers.DocumentBuilderFactory";
     private static final String THROWABLE_RENDERER_TAG = "throwableRenderer";
 
@@ -504,7 +503,6 @@ private void parseErrorHandler(Element element, Appender appender) {
     /**
      * Used internally to parse a filter element.
      * @param filterElement The Filter Element.
-     * @return The Filter.
      */
     public void addFilter(final AtomicReference<Filter> ref, final Element filterElement) {
         final Filter value = parseFilters(filterElement);

log4j-1.2-api/src/test/java/org/apache/log4j/CallerInformationTest.java

@@ -16,49 +16,46 @@
  */
 package org.apache.log4j;
 
-import static org.junit.Assert.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
 
 import java.util.List;
 import org.apache.logging.log4j.core.test.appender.ListAppender;
-import org.apache.logging.log4j.core.test.junit.LoggerContextRule;
-import org.junit.ClassRule;
-import org.junit.Test;
+import org.apache.logging.log4j.core.test.junit.LoggerContextSource;
+import org.apache.logging.log4j.core.test.junit.Named;
+import org.junit.jupiter.api.Test;
 
+// config from log4j-core test-jar
+@LoggerContextSource(value = "log4j2-calling-class.xml")
 public class CallerInformationTest {
 
-    // config from log4j-core test-jar
-    private static final String CONFIG = "log4j2-calling-class.xml";
-
-    @ClassRule
-    public static final LoggerContextRule ctx = new LoggerContextRule(CONFIG);
-
     @Test
-    public void testClassLogger() {
-        final ListAppender app = ctx.getListAppender("Class").clear();
+    public void testClassLogger(@Named("Class") final ListAppender app) {
+        app.clear();
         final Logger logger = Logger.getLogger("ClassLogger");
         logger.info("Ignored message contents.");
         logger.warn("Verifying the caller class is still correct.");
         logger.error("Hopefully nobody breaks me!");
         final List<String> messages = app.getMessages();
-        assertEquals("Incorrect number of messages.", 3, messages.size());
+
+        assertEquals(3, messages.size(), "Incorrect number of messages.");
         for (final String message : messages) {
-            assertEquals("Incorrect caller class name.", this.getClass().getName(), message);
+            assertEquals(this.getClass().getName(), message, "Incorrect caller class name.");
         }
     }
 
     @Test
-    public void testMethodLogger() {
-        final ListAppender app = ctx.getListAppender("Method").clear();
+    public void testMethodLogger(@Named("Method") final ListAppender app) {
+        app.clear();
         final Logger logger = Logger.getLogger("MethodLogger");
         logger.info("More messages.");
         logger.warn("CATASTROPHE INCOMING!");
         logger.error("ZOMBIES!!!");
         logger.warn("brains~~~");
         logger.info("Itchy. Tasty.");
         final List<String> messages = app.getMessages();
-        assertEquals("Incorrect number of messages.", 5, messages.size());
+        assertEquals(5, messages.size(), "Incorrect number of messages.");
         for (final String message : messages) {
-            assertEquals("Incorrect caller method name.", "testMethodLogger", message);
+            assertEquals("testMethodLogger", message, "Incorrect caller method name.");
         }
     }
 }