Package org.apache.logging.log4j.core.pattern

Enum NamedInstantPattern

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<NamedInstantPattern>
    @NullMarked
public enum NamedInstantPattern
extends java.lang.Enum<NamedInstantPattern>
    Represents named date & time patterns for formatting log timestamps.
    Since:
    2.26.0
    See Also:
    DatePatternConverter

    • Field Detail

      • pattern

        private final java.lang.String pattern

      • legacyPattern

        private final java.lang.String legacyPattern

    • Constructor Detail

      • NamedInstantPattern

        private NamedInstantPattern​(java.lang.String pattern)

      • NamedInstantPattern

        private NamedInstantPattern​(java.lang.String pattern,
                            java.lang.String legacyPattern)

    • Method Detail

      • values

        public static NamedInstantPattern[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows: 
        for (NamedInstantPattern c : NamedInstantPattern.values())
    System.out.println(c);
        Returns:
        an array containing the constants of this enum type, in the order they are declared

      • valueOf

        public static NamedInstantPattern valueOf​(java.lang.String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
        java.lang.NullPointerException - if the argument is null

      • getPattern

        public java.lang.String getPattern()
        Returns the date-time pattern string compatible with DateTimeFormatter that is associated with this named pattern.
        Returns:
        the date-time pattern string for use with DateTimeFormatter

      • getLegacyPattern

        java.lang.String getLegacyPattern()
        Returns the legacy FixedDateFormat pattern associated with this named pattern.

        If legacy formatters are enabled, output is produced for FixedDateFormat and FastDateFormat. To convert the DateTimeFormatter to its legacy counterpart, the following transformations need to be applied:

        Pattern Differences
        Microseconds Nanoseconds Time-zone
        Legacy formatter directive nnnnnn nnnnnnnnn X, XX, XXX
        DateTimeFormatter directive SSSSSS SSSSSSSSS x, xx, xxx

        Rationale

        • Legacy formatters are largely compatible with the SimpleDateFormat specification, but introduce a custom n pattern letter, unique to Log4j, to represent sub-millisecond precision. This n is not part of the standard SimpleDateFormat.

          In legacy formatters, repeating n increases the precision, similar to how repeated S is used for fractional seconds in DateTimeFormatter.

          In contrast, DateTimeFormatter interprets n as nano-of-second. In Java 17, both n and N always output nanosecond precision, regardless of the number of pattern letters.

        • Legacy formatters use X, XX, and XXX to format time zones as +00, +0000, or +00:00, following SimpleDateFormat conventions. In contrast, DateTimeFormatter outputs Z for zero-offset when using X. To ensure numeric output for zero-offset (e.g., +00), we use x, xx, or xxx instead.

        Returns:
        the legacy pattern string as used in FixedDateFormat.FixedFormat