From 3297bdd2a0d587f035a2789b05e3446a88f19843 Mon Sep 17 00:00:00 2001 From: Julian Ladisch Date: Fri, 20 Jun 2025 11:40:28 +0200 Subject: [PATCH 1/7] Fix UuidPatternConverter javadoc Remove javadoc incorrectly copied from SequencePatternConverter. Add javadoc for UuidPatternConverter based on the pattern-layout.adoc manual page. --- .../log4j/core/pattern/UuidPatternConverter.java | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java index bd93dcfbfad..e998abf77cd 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java @@ -22,7 +22,7 @@ import org.apache.logging.log4j.core.util.UuidUtil; /** - * Formats the event sequence number. + * Formats a UUID. */ @Plugin(name = "UuidPatternConverter", category = PatternConverter.CATEGORY) @ConverterKeys({"u", "uuid"}) @@ -39,9 +39,18 @@ private UuidPatternConverter(final boolean isRandom) { } /** - * Obtains an instance of SequencePatternConverter. + * Obtains an instance of UuidPatternConverter. + *

+ * The {@code "RANDOM"} option generates a type 4 (pseudo randomly generated) UUID. The UUID is generated using + * a cryptographically strong pseudo random number generator. + *

+ * The {@code "TIME"} option generates a type 1 (date and time based) UUID using the MAC address of each host. + * To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between + * 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based + * UUID generated. See {@link UuidUtil#UUID_SEQUENCE} how to seed the UUID generation with an integer value. + * Because time-based UUIDs contain the MAC address and timestamp, they should be used with care. * - * @param options options, currently ignored, may be null. + * @param options a single option with the value {@code "RANDOM"} or {@code "TIME"}, or an empty array for {@code "TIME"} * @return instance of SequencePatternConverter. */ public static UuidPatternConverter newInstance(final String[] options) { From 6cecd3853928e948002df38d7c408473668ff052 Mon Sep 17 00:00:00 2001 From: julianladisch Date: Fri, 20 Jun 2025 15:56:04 +0200 Subject: [PATCH 2/7] Update log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Volkan Yazıcı --- .../apache/logging/log4j/core/pattern/UuidPatternConverter.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java index e998abf77cd..170fe6a903b 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java @@ -39,7 +39,7 @@ private UuidPatternConverter(final boolean isRandom) { } /** - * Obtains an instance of UuidPatternConverter. + * Creates an instance of {@link UuidPatternConverter}. *

* The {@code "RANDOM"} option generates a type 4 (pseudo randomly generated) UUID. The UUID is generated using * a cryptographically strong pseudo random number generator. From 45e0d44dbb65835a633cd24de25b3efa2c744ff3 Mon Sep 17 00:00:00 2001 From: julianladisch Date: Fri, 20 Jun 2025 15:56:20 +0200 Subject: [PATCH 3/7] Update log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Volkan Yazıcı --- .../log4j/core/pattern/UuidPatternConverter.java | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java index 170fe6a903b..6a92c14ebdb 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java @@ -41,13 +41,12 @@ private UuidPatternConverter(final boolean isRandom) { /** * Creates an instance of {@link UuidPatternConverter}. *

- * The {@code "RANDOM"} option generates a type 4 (pseudo randomly generated) UUID. The UUID is generated using - * a cryptographically strong pseudo random number generator. + * The {@code RANDOM} option generates a Type 4 (pseudo-randomly generated) UUID. + * The UUID is generated using a cryptographically strong pseudo-random number generator. *

- * The {@code "TIME"} option generates a type 1 (date and time based) UUID using the MAC address of each host. - * To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between - * 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based - * UUID generated. See {@link UuidUtil#UUID_SEQUENCE} how to seed the UUID generation with an integer value. + * The {@code TIME} option generates a Type 1 (date and time based) UUID using the local network interface's MAC address. + * To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated. + * See {@link UuidUtil#UUID_SEQUENCE} how to seed the UUID generation with an integer value. * Because time-based UUIDs contain the MAC address and timestamp, they should be used with care. * * @param options a single option with the value {@code "RANDOM"} or {@code "TIME"}, or an empty array for {@code "TIME"} From e830e1b14bec4caab778438f52adc20cef0bc4bb Mon Sep 17 00:00:00 2001 From: julianladisch Date: Fri, 20 Jun 2025 15:56:28 +0200 Subject: [PATCH 4/7] Update log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Volkan Yazıcı --- .../logging/log4j/core/pattern/UuidPatternConverter.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java index 6a92c14ebdb..84cf227d614 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java @@ -49,7 +49,8 @@ private UuidPatternConverter(final boolean isRandom) { * See {@link UuidUtil#UUID_SEQUENCE} how to seed the UUID generation with an integer value. * Because time-based UUIDs contain the MAC address and timestamp, they should be used with care. * - * @param options a single option with the value {@code "RANDOM"} or {@code "TIME"}, or an empty array for {@code "TIME"} + * @param options An array containing either {@code RANDOM} or {@code TIME}. + If empty, {@code TIME} will be used. * @return instance of SequencePatternConverter. */ public static UuidPatternConverter newInstance(final String[] options) { From 72dd782be10a4a45a9b234768a685b4b954f06bc Mon Sep 17 00:00:00 2001 From: julianladisch Date: Fri, 20 Jun 2025 15:56:34 +0200 Subject: [PATCH 5/7] Update log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Volkan Yazıcı --- .../apache/logging/log4j/core/pattern/UuidPatternConverter.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java index 84cf227d614..a9c0167c9c0 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java @@ -51,7 +51,7 @@ private UuidPatternConverter(final boolean isRandom) { * * @param options An array containing either {@code RANDOM} or {@code TIME}. If empty, {@code TIME} will be used. - * @return instance of SequencePatternConverter. + * @return a new {@link UuidPatternConverter} instance */ public static UuidPatternConverter newInstance(final String[] options) { if (options.length == 0) { From 2e27ecfe48361ba6a5e22415142d7e529baa1ea4 Mon Sep 17 00:00:00 2001 From: Julian Ladisch Date: Fri, 20 Jun 2025 16:22:44 +0200 Subject: [PATCH 6/7] Expand UuidPatternConverter section of pattern-layout.adoc --- .../modules/ROOT/pages/manual/pattern-layout.adoc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc index d3f713e7942..b6b4aa788f1 100644 --- a/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc @@ -1339,15 +1339,19 @@ Includes either a random or a time-based UUID .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/UuidPatternConverter.html[`UuidPatternConverter`] specifier grammar [source,text] ---- -u{RANDOM|TIME} -uuid{RANDOM|TIME} +u[{RANDOM|TIME}] +uuid[{RANDOM|TIME}] ---- -The time-based UUID is a Type 1 UUID generated using the MAC address of each host +The random UUID is a type 4 UUID. The UUID is generated using a cryptographically strong pseudo-random number generator. + +The time-based UUID is a Type 1 (date and time based) UUID generated using the MAC address of each host. To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated. See also xref:manual/systemproperties.adoc#log4j2.uuidSequence[`log4j2.uuidSequence`]. Because time-based UUIDs contain the MAC address and timestamp, they should be used with care. +TIME is the default. + [#format-modifiers] === Format modifiers From bd5b545b36191f2a88948544c158daf72e3d5e7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Volkan=20Yaz=C4=B1c=C4=B1?= Date: Fri, 27 Jun 2025 09:22:33 +0200 Subject: [PATCH 7/7] Try fixing Spotless failures --- .../apache/logging/log4j/core/pattern/UuidPatternConverter.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java index a9c0167c9c0..c1a4aebd422 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java @@ -50,7 +50,7 @@ private UuidPatternConverter(final boolean isRandom) { * Because time-based UUIDs contain the MAC address and timestamp, they should be used with care. * * @param options An array containing either {@code RANDOM} or {@code TIME}. - If empty, {@code TIME} will be used. + * If empty, {@code TIME} will be used. * @return a new {@link UuidPatternConverter} instance */ public static UuidPatternConverter newInstance(final String[] options) {