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

[Roger Riggs]

On Tue, 27 May 2025 21:44:32 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> spec updated in class javadoc to RFC 9562 which obsolete RFC 4122, @spec tag also added above the method.
>
> I'd say "create" instead of "retrieve" in the first line comment. (Though that word is used in the other static factories).
> 
> The "sub-millisecond precision" can't be relied upon. Its the precision that gives the impression that it can be added to the millisecond value and get an exact time. But the nano-second value is read from a different clock and the bits being used from it may wrap-around in the time between the reads of the clocks.
> The second description ("derived from") is makes fewer promises than the first-line comment.
> An application should not use them for any purpose other than random.  And for that the buffer already contains random bytes.
> 
> An alternative is to capture the MS time and the nano-time on first use to compute an offset and then use only the nano-time plus/minus the offset to create the version 7 UUIDs.

The `timestamp` method may mislead an app developer thinking its the time from the version 7 timestamp.
The first-line comment might make it more obvious if it says:
`The timestamp value associated with a version 1 UUID.`

The Unix Epoch time would be easier to use if a method was added to return it.
`long UnixEpochTimeNanos()`   (name subject to bike-shedding).
And throwing if it was not version 7.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25303#discussion_r2110368888