vy commented on code in PR #3768:
URL: https://github.com/apache/logging-log4j2/pull/3768#discussion_r2158847545
##########
log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java:
##########
@@ -39,9 +39,18 @@ private UuidPatternConverter(final boolean isRandom) {
}
/**
- * Obtains an instance of SequencePatternConverter.
+ * Obtains an instance of UuidPatternConverter.
+ * <p>
+ * The {@code "RANDOM"} option generates a type 4 (pseudo randomly
generated) UUID. The UUID is generated using
+ * a cryptographically strong pseudo random number generator.
+ * <p>
+ * 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"}
Review Comment:
```suggestion
* @param options An array containing either {@code RANDOM} or {@code
TIME}.
If empty, {@code TIME} will be used.
```
##########
log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java:
##########
@@ -39,9 +39,18 @@ private UuidPatternConverter(final boolean isRandom) {
}
/**
- * Obtains an instance of SequencePatternConverter.
+ * Obtains an instance of UuidPatternConverter.
+ * <p>
+ * The {@code "RANDOM"} option generates a type 4 (pseudo randomly
generated) UUID. The UUID is generated using
+ * a cryptographically strong pseudo random number generator.
+ * <p>
+ * 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.
Review Comment:
```suggestion
* @return a new {@link UuidPatternConverter} instance
```
##########
log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java:
##########
@@ -39,9 +39,18 @@ private UuidPatternConverter(final boolean isRandom) {
}
/**
- * Obtains an instance of SequencePatternConverter.
+ * Obtains an instance of UuidPatternConverter.
Review Comment:
```suggestion
* Creates an instance of {@link UuidPatternConverter}.
```
##########
log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java:
##########
@@ -39,9 +39,18 @@ private UuidPatternConverter(final boolean isRandom) {
}
/**
- * Obtains an instance of SequencePatternConverter.
+ * Obtains an instance of UuidPatternConverter.
+ * <p>
+ * The {@code "RANDOM"} option generates a type 4 (pseudo randomly
generated) UUID. The UUID is generated using
+ * a cryptographically strong pseudo random number generator.
+ * <p>
+ * 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.
Review Comment:
```suggestion
* The {@code RANDOM} option generates a Type 4 (pseudo-randomly
generated) UUID.
* The UUID is generated using a cryptographically strong pseudo-random
number generator.
* <p>
* 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.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
