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

[Jaikiran Pai]

On Tue, 30 Sep 2025 05:59:13 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> Kieran Farrell has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   missing semicolon
>
> src/java.base/share/classes/java/util/UUID.java line 185:
> 
>> 183: 
>> 184:     /**
>> 185:      * Static factory to create a version 7 (time-based) {@code UUID} with a user-supplied
> 
> Would it be better to reword this method javadoc to something like:
> 
> 
> /**
>  * Creates a {@code UUIDv7} {@code UUID} from the given Unix Epoch timestamp.
>  *
>  * The returned {@code UUID} will have the given {@code timestamp} in
>  * the first 6 bytes, followed by the version and variant bits representing {@code UUIDv7},
>  * and the remaining bytes will contain random data from a cryptographically strong
>  * pseudo-random number generator.
>  *
>  * @apiNote {@code UUIDv7} values are created by allocating a Unix timestamp in milliseconds
>  * in the most significant 48 bits and filling the remaining 74 bits, excluding the required
>  * version and variant bits, with random bits. As such, this method rejects {@code timestamp}
>  * values that do not fit into 48 bits.
>  * <p>
>  * Monotonicity (each subsequent value being greater than the last) is a primary characteristic
>  * of {@code UUIDv7} values. This is due to the {@code timestamp} value being part of the {@code UUID}.
>  * Callers of this method that wish to generate monotonic {@code UUIDv7} values are expected to
>  * ensure that the given {@code timestamp} value is monotonic.
>  *
>  *
>  * @param timestamp the number of milliseconds since midnight 1 Jan 1970 UTC,
>  *                 leap seconds excluded.
>  *
>  * @return a {@code UUID} constructed using the given {@code timestamp}
>  *
>  * @throws IllegalArgumentException if the timestamp is negative or greater than {@code 281474976710655L}
>  *
>  * @spec https://www.rfc-editor.org/rfc/rfc9562.html
>  *       RFC 9562 Universally Unique IDentifiers (UUIDs)
>  *
>  * @since 26
>  *
>  */
> 
> (the text used for the apiNote is borrowed from the RFC)

I had forgotten to include a note about monotonicity of the UUIDs generated by this new method. I've now updated my previous javadoc comment inline to propose an additional paragraph about this in the `@apiNote`.

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

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