Skip to content

Commit 0ef914b

Browse files
vyvy
authored
Improve style and cross references in docs
1 parent 9758413 commit 0ef914b

File tree

3 files changed

+72
-49
lines changed

3 files changed

+72
-49
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ private static String readPattern(@Nullable final String[] options) {
111111
static String decodeNamedPattern(final String pattern) {
112112
try {
113113
return NamedDatePattern.valueOf(pattern).getPattern();
114-
} catch (IllegalArgumentException ignored) { // for Java 22+ it can be changed to `IllegalArgumentException _`
114+
} catch (IllegalArgumentException ignored) {
115115
return pattern;
116116
}
117117
}

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

Lines changed: 68 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -16,70 +16,92 @@
1616
*/
1717
package org.apache.logging.log4j.core.pattern;
1818

19+
import static org.apache.logging.log4j.core.util.internal.instant.InstantPatternFormatter.LEGACY_FORMATTERS_ENABLED;
20+
1921
import org.apache.logging.log4j.core.util.internal.instant.InstantPatternFormatter;
2022

21-
// If legacy formatters are enabled, we need to produce output aimed for `FixedDateFormat` and `FastDateFormat`.
22-
// Otherwise, we need to produce output aimed for `DateTimeFormatter`.
23-
// In conclusion, we need to check if legacy formatters enabled and apply following transformations.
24-
//
25-
// | Microseconds | Nanoseconds | Time-zone
26-
// ------------------------------+--------------+-------------+-----------
27-
// Legacy formatter directive | nnnnnn | nnnnnnnnn | X, XX, XXX
28-
// `DateTimeFormatter` directive | SSSSSS | SSSSSSSSS | x, xx, xxx
29-
//
30-
// Enabling legacy formatters mean that user requests the pattern to be formatted using deprecated
31-
// `FixedDateFormat` and `FastDateFormat`.
32-
// These two have, let's not say _bogus_, but an _interesting_ way of handling certain pattern directives:
33-
//
34-
// - They say they adhere to `SimpleDateFormat` specification, but use `n` directive.
35-
// `n` is neither defined by `SimpleDateFormat`, nor `SimpleDateFormat` supports sub-millisecond precisions.
36-
// `n` is probably manually introduced by Log4j to support sub-millisecond precisions.
37-
//
38-
// - `n` denotes nano-of-second for `DateTimeFormatter`.
39-
// In Java 17, `n` and `N` (nano-of-day) always output nanosecond precision.
40-
// This is independent of how many times they occur consequently.
41-
// Yet legacy formatters use repeated `n` to denote sub-milliseconds precision of certain length.
42-
// This doesn't work for `DateTimeFormatter`, which needs
43-
//
44-
// - `SSSSSS` for 6-digit microsecond precision
45-
// - `SSSSSSSSS` for 9-digit nanosecond precision
46-
//
47-
// - Legacy formatters use `X`, `XX,` and `XXX` to choose between `+00`, `+0000`, or `+00:00`.
48-
// This is the correct behaviour for `SimpleDateFormat`.
49-
// Though `X` in `DateTimeFormatter` produces `Z` for zero-offset.
50-
// To avoid the `Z` output, one needs to use `x` with `DateTimeFormatter`.
5123
/**
52-
* Represents named date/time patterns for formatting log timestamps.
53-
* Provides patterns for legacy and modern formatters based on configuration.
24+
* Represents named date & time patterns for formatting log timestamps.
25+
*
26+
* @see InstantPatternFormatter#LEGACY_FORMATTERS_ENABLED
27+
* @see DatePatternConverter
28+
* @since 2.26.0
5429
*/
55-
@SuppressWarnings("SpellCheckingInspection")
5630
public enum NamedDatePattern {
31+
32+
// If legacy formatters are enabled, we need to produce output aimed for `FixedDateFormat` and `FastDateFormat`.
33+
// Otherwise, we need to produce output aimed for `DateTimeFormatter`.
34+
// In conclusion, we need to check if legacy formatters enabled and apply following transformations.
35+
//
36+
// | Microseconds | Nanoseconds | Time-zone
37+
// ------------------------------+--------------+-------------+-----------
38+
// Legacy formatter directive | nnnnnn | nnnnnnnnn | X, XX, XXX
39+
// `DateTimeFormatter` directive | SSSSSS | SSSSSSSSS | x, xx, xxx
40+
//
41+
// Enabling legacy formatters mean that user requests the pattern to be formatted using deprecated
42+
// `FixedDateFormat` and `FastDateFormat`.
43+
// These two have, let's not say _bogus_, but an _interesting_ way of handling certain pattern directives:
44+
//
45+
// - They say they adhere to `SimpleDateFormat` specification, but use `n` directive.
46+
// `n` is neither defined by `SimpleDateFormat`, nor `SimpleDateFormat` supports sub-millisecond precisions.
47+
// `n` is probably manually introduced by Log4j to support sub-millisecond precisions.
48+
//
49+
// - `n` denotes nano-of-second for `DateTimeFormatter`.
50+
// In Java 17, `n` and `N` (nano-of-day) always output nanosecond precision.
51+
// This is independent of how many times they occur consequently.
52+
// Yet legacy formatters use repeated `n` to denote sub-milliseconds precision of certain length.
53+
// This doesn't work for `DateTimeFormatter`, which needs
54+
//
55+
// - `SSSSSS` for 6-digit microsecond precision
56+
// - `SSSSSSSSS` for 9-digit nanosecond precision
57+
//
58+
// - Legacy formatters use `X`, `XX,` and `XXX` to choose between `+00`, `+0000`, or `+00:00`.
59+
// This is the correct behaviour for `SimpleDateFormat`.
60+
// Though `X` in `DateTimeFormatter` produces `Z` for zero-offset.
61+
// To avoid the `Z` output, one needs to use `x` with `DateTimeFormatter`.
62+
5763
ABSOLUTE("HH:mm:ss,SSS"),
58-
ABSOLUTE_MICROS("HH:mm:ss," + (InstantPatternFormatter.LEGACY_FORMATTERS_ENABLED ? "nnnnnn" : "SSSSSS")),
59-
ABSOLUTE_NANOS("HH:mm:ss," + (InstantPatternFormatter.LEGACY_FORMATTERS_ENABLED ? "nnnnnnnnn" : "SSSSSSSSS")),
64+
65+
ABSOLUTE_MICROS("HH:mm:ss," + (LEGACY_FORMATTERS_ENABLED ? "nnnnnn" : "SSSSSS")),
66+
67+
ABSOLUTE_NANOS("HH:mm:ss," + (LEGACY_FORMATTERS_ENABLED ? "nnnnnnnnn" : "SSSSSSSSS")),
68+
6069
ABSOLUTE_PERIOD("HH:mm:ss.SSS"),
70+
6171
COMPACT("yyyyMMddHHmmssSSS"),
72+
6273
DATE("dd MMM yyyy HH:mm:ss,SSS"),
74+
6375
DATE_PERIOD("dd MMM yyyy HH:mm:ss.SSS"),
76+
6477
DEFAULT("yyyy-MM-dd HH:mm:ss,SSS"),
65-
DEFAULT_MICROS("yyyy-MM-dd HH:mm:ss," + (InstantPatternFormatter.LEGACY_FORMATTERS_ENABLED ? "nnnnnn" : "SSSSSS")),
66-
DEFAULT_NANOS(
67-
"yyyy-MM-dd HH:mm:ss," + (InstantPatternFormatter.LEGACY_FORMATTERS_ENABLED ? "nnnnnnnnn" : "SSSSSSSSS")),
78+
79+
DEFAULT_MICROS("yyyy-MM-dd HH:mm:ss," + (LEGACY_FORMATTERS_ENABLED ? "nnnnnn" : "SSSSSS")),
80+
81+
DEFAULT_NANOS("yyyy-MM-dd HH:mm:ss," + (LEGACY_FORMATTERS_ENABLED ? "nnnnnnnnn" : "SSSSSSSSS")),
82+
6883
DEFAULT_PERIOD("yyyy-MM-dd HH:mm:ss.SSS"),
84+
6985
ISO8601_BASIC("yyyyMMdd'T'HHmmss,SSS"),
86+
7087
ISO8601_BASIC_PERIOD("yyyyMMdd'T'HHmmss.SSS"),
88+
7189
ISO8601("yyyy-MM-dd'T'HH:mm:ss,SSS"),
72-
ISO8601_OFFSET_DATE_TIME_HH(
73-
"yyyy-MM-dd'T'HH:mm:ss,SSS" + (InstantPatternFormatter.LEGACY_FORMATTERS_ENABLED ? "X" : "x")),
74-
ISO8601_OFFSET_DATE_TIME_HHMM(
75-
"yyyy-MM-dd'T'HH:mm:ss,SSS" + (InstantPatternFormatter.LEGACY_FORMATTERS_ENABLED ? "XX" : "xx")),
76-
ISO8601_OFFSET_DATE_TIME_HHCMM(
77-
"yyyy-MM-dd'T'HH:mm:ss,SSS" + (InstantPatternFormatter.LEGACY_FORMATTERS_ENABLED ? "XXX" : "xxx")),
90+
91+
ISO8601_OFFSET_DATE_TIME_HH("yyyy-MM-dd'T'HH:mm:ss,SSS" + (LEGACY_FORMATTERS_ENABLED ? "X" : "x")),
92+
93+
ISO8601_OFFSET_DATE_TIME_HHMM("yyyy-MM-dd'T'HH:mm:ss,SSS" + (LEGACY_FORMATTERS_ENABLED ? "XX" : "xx")),
94+
95+
ISO8601_OFFSET_DATE_TIME_HHCMM("yyyy-MM-dd'T'HH:mm:ss,SSS" + (LEGACY_FORMATTERS_ENABLED ? "XXX" : "xxx")),
96+
7897
ISO8601_PERIOD("yyyy-MM-dd'T'HH:mm:ss.SSS"),
79-
ISO8601_PERIOD_MICROS(
80-
"yyyy-MM-dd'T'HH:mm:ss." + (InstantPatternFormatter.LEGACY_FORMATTERS_ENABLED ? "nnnnnn" : "SSSSSS")),
98+
99+
ISO8601_PERIOD_MICROS("yyyy-MM-dd'T'HH:mm:ss." + (LEGACY_FORMATTERS_ENABLED ? "nnnnnn" : "SSSSSS")),
100+
81101
US_MONTH_DAY_YEAR2_TIME("dd/MM/yy HH:mm:ss.SSS"),
102+
82103
US_MONTH_DAY_YEAR4_TIME("dd/MM/yyyy HH:mm:ss.SSS");
104+
83105
private final String pattern;
84106

85107
NamedDatePattern(String pattern) {

‎src/changelog/.2.x.x/exported_named_patterns_into_public_enum.xml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
<entry xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
33
xmlns="https://logging.apache.org/xml/ns"
44
xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-changelog-0.xsd"
5-
type="changed">
6-
<description format="asciidoc">Exported named-patterns into its own public enum</description>
5+
type="added">
6+
<issue id="3789" link="https://github.com/apache/logging-log4j2/pull/3789"/>
7+
<description format="asciidoc">Add and export `org.apache.logging.log4j.core.pattern.NamedDatePattern` class where users can programmatically access named date & time patterns supported by Pattern Layout</description>
78
</entry>

0 commit comments

Comments
 (0)