On Tue, 30 Sep 2025 05:59:13 GMT, Jaikiran Pai <[email protected]> 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
