RFR: 8334015: Add Support for UUID Version 7 (UUIDv7) defined in RFC 9562 [v21]

[Alan Bateman]

On Thu, 23 Oct 2025 10:29:50 GMT, Kieran Farrell <kfarrell at openjdk.org> wrote:

>> With the recent approval of UUIDv7 (https://datatracker.ietf.org/doc/rfc9562/), this PR aims to add a new static method UUID.timestampUUID() which constructs and returns a UUID in support of the new time generated UUID version. 
>> 
>> The specification requires embedding the current timestamp in milliseconds into the first bits 0–47. The version number in bits 48–51, bits 52–63 are available for sub-millisecond precision or for pseudorandom data. The variant is set in bits 64–65. The remaining bits 66–127 are free to use for more pseudorandom data or to employ a counter based approach for increased time percision (https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7).
>> 
>> The choice of implementation comes down to balancing the sensitivity level of being able to distingush UUIDs created below <1ms apart with performance. A test simulating a high-concurrency environment with 4 threads generating 10000 UUIDv7 values in parallel to measure the collision rate of each implementation (the amount of times the time based portion of the UUID was not unique and entries could not distinguished by time) yeilded the following results for each implemtation:
>> 
>> 
>> - random-byte-only - 99.8%
>> - higher-precision - 3.5%
>> - counter-based - 0%
>> 
>> 
>> Performance tests show a decrease in performance as expected with the counter based implementation due to the introduction of synchronization:
>> 
>> - random-byte-only   143.487 ± 10.932  ns/op
>> - higher-precision      149.651 ±  8.438 ns/op
>> - counter-based         245.036 ±  2.943  ns/op
>> 
>> The best balance here might be to employ a higher-precision implementation as the large increase in time sensitivity comes at a very slight performance cost.
>
> Kieran Farrell has updated the pull request incrementally with one additional commit since the last revision:
> 
>   update name

src/java.base/share/classes/java/util/UUID.java line 40:

> 38:  * A UUID represents a 128-bit value.
> 39:  *
> 40:  * <p> There exist different variants of these global identifiers.  The methods

As follow-up (not this PR), we might consider re-visiting the switch from UUID in the first sentence/paragraph to "global identifiers" in the second paragraph. We seem to missing an "also known" to allow this switch.

src/java.base/share/classes/java/util/UUID.java line 66:

> 64:  * <p> See <a href="https://www.rfc-editor.org/rfc/rfc9562.html">
> 65:  * <i>RFC 9562: Universally Unique Identifiers (UUIDs)</i></a> for the complete specification,
> 66:  * including algorithms used to create {@code UUID}s.

Moving the dependency from RFC 4122 to RFC 95262 is good.

With the new reference then it would be good to expand a bit of what the reader will find. Instead of "including algorithms ..." then it would be clear to say "including the UUID format, layouts, and algorithms for creating UUIDs.".

src/java.base/share/classes/java/util/UUID.java line 184:

> 182: 
> 183:     /**
> 184:      * Creates a {@code UUIDv7} {@code UUID} from the given Unix Epoch timestamp.

The existing UUID docs, including the existing static factory methods, use "type $N UUID" rather than "UUIDv$N". It would be okay to say "Creates a type 7 UUID (UUIDv7) ..." so that it fits better with the existing docs, and allows you to use UUIDv7 in this description and API note.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/25303#discussion_r2463859986
PR Review Comment: https://git.openjdk.org/jdk/pull/25303#discussion_r2463868161
PR Review Comment: https://git.openjdk.org/jdk/pull/25303#discussion_r2463861726