fix: expose legacy FixedFormat patterns via NamedInstantPattern

To decouple `DatePatternConverter` from `FixedFormat`, legacy pattern values are now provided through the `NamedInstantPattern.getLegacyPattern` method.

These patterns are specific to `FixedDateFormat` and not intended for general use, so the method is kept package-private.

Author: ppkarwasz

log4j-core-test/src/test/java/org/apache/logging/log4j/core/pattern/NamedInstantPatternTest.java

@@ -0,0 +1,45 @@
+/*
+ * 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.
+ */
+package org.apache.logging.log4j.core.pattern;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.time.Instant;
+import org.apache.logging.log4j.core.time.MutableInstant;
+import org.apache.logging.log4j.core.util.internal.instant.InstantPatternFormatter;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
+
+class NamedInstantPatternTest {
+
+    @ParameterizedTest
+    @EnumSource(NamedInstantPattern.class)
+    void compatibilityOfLegacyPattern(NamedInstantPattern namedPattern) {
+        InstantPatternFormatter legacyFormatter = InstantPatternFormatter.newBuilder()
+                .setPattern(namedPattern.getLegacyPattern())
+                .setLegacyFormattersEnabled(true)
+                .build();
+        InstantPatternFormatter formatter = InstantPatternFormatter.newBuilder()
+                .setPattern(namedPattern.getPattern())
+                .setLegacyFormattersEnabled(false)
+                .build();
+        Instant javaTimeInstant = Instant.now();
+        MutableInstant instant = new MutableInstant();
+        instant.initFromEpochSecond(javaTimeInstant.getEpochSecond(), javaTimeInstant.getNano());
+        assertThat(legacyFormatter.format(instant)).isEqualTo(formatter.format(instant));
+    }
+}

log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/DatePatternConverter.java

@@ -109,40 +109,19 @@ private static String readPattern(@Nullable final String[] options) {
      * @since 2.25.0
      */
     static String decodeNamedPattern(final String pattern) {
-        // If legacy formatters are enabled, we need to produce output aimed for `FixedDateFormat` and `FastDateFormat`.
-        // Otherwise, we need to produce output aimed for `DateTimeFormatter`.
-        // In conclusion, we need to check if legacy formatters enabled and apply following transformations.
+        // `FixedDateFormat` accepted two types of patterns:
+        //   - the names of `FixedFormat` enum constants (identical to `NamedInstantPattern` enum names),
+        //   - or custom pattern strings.
         //
-        //                               | Microseconds | Nanoseconds | Time-zone
-        // ------------------------------+--------------+-------------+-----------
-        // Legacy formatter directive    | nnnnnn       | nnnnnnnnn   | X, XX, XXX
-        // `DateTimeFormatter` directive | SSSSSS       | SSSSSSSSS   | x, xx, xxx
-        //
-        // Enabling legacy formatters mean that user requests the pattern to be formatted using deprecated
-        // `FixedDateFormat` and `FastDateFormat`.
-        // These two have, let's not say _bogus_, but an _interesting_ way of handling certain pattern directives:
-        //
-        // - They say they adhere to `SimpleDateFormat` specification, but use `n` directive.
-        //   `n` is neither defined by `SimpleDateFormat`, nor `SimpleDateFormat` supports sub-millisecond precisions.
-        //   `n` is probably manually introduced by Log4j to support sub-millisecond precisions.
-        //
-        // - `n` denotes nano-of-second for `DateTimeFormatter`.
-        //   In Java 17, `n` and `N` (nano-of-day) always output nanosecond precision.
-        //   This is independent of how many times they occur consequently.
-        //   Yet legacy formatters use repeated `n` to denote sub-milliseconds precision of certain length.
-        //   This doesn't work for `DateTimeFormatter`, which needs
-        //
-        //   - `SSSSSS` for 6-digit microsecond precision
-        //   - `SSSSSSSSS` for 9-digit nanosecond precision
-        //
-        // - Legacy formatters use `X`, `XX,` and `XXX` to choose between `+00`, `+0000`, or `+00:00`.
-        //   This is the correct behaviour for `SimpleDateFormat`.
-        //   Though `X` in `DateTimeFormatter` produces `Z` for zero-offset.
-        //   To avoid the `Z` output, one needs to use `x` with `DateTimeFormatter`.
+        // To determine the format's precision, we cannot return the legacy name directly;
+        // instead, we must return the equivalent `FixedDateFormat` pattern string.
+        // These patterns are only recognized by `FixedDateFormat` so we make them available only
+        // via the package-private `getLegacyPattern()` method.
         try {
+            NamedInstantPattern namedInstantPattern = NamedInstantPattern.valueOf(pattern);
             return InstantPatternFormatter.LEGACY_FORMATTERS_ENABLED
-                    ? FixedDateFormat.FixedFormat.valueOf(pattern).getPattern()
-                    : NamedInstantPattern.valueOf(pattern).getPattern();
+                    ? namedInstantPattern.getLegacyPattern()
+                    : namedInstantPattern.getPattern();
         } catch (IllegalArgumentException ignored) {
             return pattern;
         }

log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/NamedInstantPattern.java

@@ -16,18 +16,21 @@
  */
 package org.apache.logging.log4j.core.pattern;
 
+import org.jspecify.annotations.NullMarked;
+
 /**
  * Represents named date & time patterns for formatting log timestamps.
  *
  * @see DatePatternConverter
  * @since 2.26.0
  */
+@NullMarked
 public enum NamedInstantPattern {
     ABSOLUTE("HH:mm:ss,SSS"),
 
-    ABSOLUTE_MICROS("HH:mm:ss,SSSSSS"),
+    ABSOLUTE_MICROS("HH:mm:ss,SSSSSS", "HH:mm:ss,nnnnnn"),
 
-    ABSOLUTE_NANOS("HH:mm:ss,SSSSSSSSS"),
+    ABSOLUTE_NANOS("HH:mm:ss,SSSSSSSSS", "HH:mm:ss,nnnnnnnnn"),
 
     ABSOLUTE_PERIOD("HH:mm:ss.SSS"),
 
@@ -39,9 +42,9 @@ public enum NamedInstantPattern {
 
     DEFAULT("yyyy-MM-dd HH:mm:ss,SSS"),
 
-    DEFAULT_MICROS("yyyy-MM-dd HH:mm:ss,SSSSSS"),
+    DEFAULT_MICROS("yyyy-MM-dd HH:mm:ss,SSSSSS", "yyyy-MM-dd HH:mm:ss,nnnnnn"),
 
-    DEFAULT_NANOS("yyyy-MM-dd HH:mm:ss,SSSSSSSSS"),
+    DEFAULT_NANOS("yyyy-MM-dd HH:mm:ss,SSSSSSSSS", "yyyy-MM-dd HH:mm:ss,nnnnnnnnn"),
 
     DEFAULT_PERIOD("yyyy-MM-dd HH:mm:ss.SSS"),
 
@@ -51,30 +54,50 @@ public enum NamedInstantPattern {
 
     ISO8601("yyyy-MM-dd'T'HH:mm:ss,SSS"),
 
-    ISO8601_OFFSET_DATE_TIME_HH("yyyy-MM-dd'T'HH:mm:ss,SSSx"),
+    ISO8601_OFFSET_DATE_TIME_HH("yyyy-MM-dd'T'HH:mm:ss,SSSx", "yyyy-MM-dd'T'HH:mm:ss,SSSX"),
 
-    ISO8601_OFFSET_DATE_TIME_HHMM("yyyy-MM-dd'T'HH:mm:ss,SSSxx"),
+    ISO8601_OFFSET_DATE_TIME_HHMM("yyyy-MM-dd'T'HH:mm:ss,SSSxx", "yyyy-MM-dd'T'HH:mm:ss,SSSXX"),
 
-    ISO8601_OFFSET_DATE_TIME_HHCMM("yyyy-MM-dd'T'HH:mm:ss,SSSxxx"),
+    ISO8601_OFFSET_DATE_TIME_HHCMM("yyyy-MM-dd'T'HH:mm:ss,SSSxxx", "yyyy-MM-dd'T'HH:mm:ss,SSSXXX"),
 
     ISO8601_PERIOD("yyyy-MM-dd'T'HH:mm:ss.SSS"),
 
-    ISO8601_PERIOD_MICROS("yyyy-MM-dd'T'HH:mm:ss.SSSSSS"),
+    ISO8601_PERIOD_MICROS("yyyy-MM-dd'T'HH:mm:ss.SSSSSS", "yyyy-MM-dd'T'HH:mm:ss.nnnnnn"),
 
     US_MONTH_DAY_YEAR2_TIME("dd/MM/yy HH:mm:ss.SSS"),
 
     US_MONTH_DAY_YEAR4_TIME("dd/MM/yyyy HH:mm:ss.SSS");
 
     private final String pattern;
+    private final String legacyPattern;
 
     NamedInstantPattern(String pattern) {
+        this(pattern, pattern);
+    }
+
+    NamedInstantPattern(String pattern, String legacyPattern) {
         this.pattern = pattern;
+        this.legacyPattern = legacyPattern;
     }
 
     /**
-     * @return pattern that is compatible with {@link java.time.format.DateTimeFormatter}
+     * Returns the date-time pattern string compatible with {@link java.time.format.DateTimeFormatter}
+     * that is associated with this named pattern.
+     *
+     * @return the date-time pattern string for use with {@code DateTimeFormatter}
      */
     public String getPattern() {
         return pattern;
     }
+
+    /**
+     * Returns the legacy {@link org.apache.logging.log4j.core.util.datetime.FixedDateFormat} pattern
+     * associated with this named pattern.
+     *
+     * @return the legacy pattern string as used in
+     * {@link org.apache.logging.log4j.core.util.datetime.FixedDateFormat.FixedFormat}
+     */
+    String getLegacyPattern() {
+        return legacyPattern;
+    }
 }