Summary

Add a static factory method UUID.ofEpochMillis(long) to create Version 7 UUIDs as defined in RFC 9562, embedding the supplied Unix time in milliseconds.

Problem

The JDK currently exposes static factories for version 3 (name-based) and version 4 (random) UUIDs via nameUUIDFromBytes() and randomUUID(), respectively. However, there is no built-in support for generating version 7 UUIDs, which incorporate millisecond-precision Unix timestamps and provide lexicographically sortable, time-ordered identifiers. UUIDv7 provides unique identifiers which can be sorted by creation time and has been of increasing popularity especially in distributed systems.

Solution

Introduce a new static factory method in java.util.UUID:

public static UUID ofEpochMillis(long timestamp) - Generates a Version 7 UUID using the provided Unix epoch timestamp in milliseconds (must fit within 48 bits). The method embeds the timestamp into the first 48 bits, sets the version (7) and IETF variant fields, and fills the remaining bits with cryptographically strong random data.

Specification

Update UUID.java spec with the following:

-  * <p> The version field holds a value that describes the type of this {@code
-  * UUID}.  There are four different basic types of UUIDs: time-based, DCE
-  * security, name-based, and randomly generated UUIDs.  These types have a
-  * version value of 1, 2, 3 and 4, respectively.
+ * <p> See <a href="https://www.rfc-editor.org/rfc/rfc9562.html">
+ * <i>RFC 9562: Universally Unique Identifiers (UUIDs)</i></a> for the complete specification,
+ * including the UUID format, layouts, and algorithms for creating {@code UUID}s.
-  * <p> For more information including algorithms used to create {@code UUID}s,
-  * see <a href="http://www.ietf.org/rfc/rfc4122.txt"> <i>RFC&nbsp;4122: A
-  * Universally Unique IDentifier (UUID) URN Namespace</i></a>, section 4.2
-  * &quot;Algorithms for Creating a Time-Based UUID&quot;.
+ * <p> There are eight defined types of UUIDs, each identified by a version number:
+ * time-based (version 1), DCE security (version 2), name-based with MD5 (version 3),
+ * randomly generated (version 4), name-based with SHA-1 (version 5), reordered time-based   (version 6),
+ * Unix epoch time-based (version 7), and custom-defined layout (version 8).    *
-  * @spec https://www.rfc-editor.org/info/rfc4122
-  *      RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace
+ * @spec https://www.rfc-editor.org/rfc/rfc9562.html
+ *      RFC 9562 Universally Unique IDentifiers (UUIDs)   * @since   1.5   */  public final class UUID implements java.io.Serializable, Comparable<UUID> {  

+    /**
+     * Creates a type 7 UUID (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, allocating the required version (4 bits) and variant (2-bits) and filling 
 +     * the remaining 74 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 (1L << 48) - 1}
+     *
+     * @since 26
+     */
+    public static UUID ofEpochMillis(long timestamp) {


      * <li>2    DCE security UUID
      * <li>3    Name-based UUID
      * <li>4    Randomly generated UUID
+    * <li>7    Unix Epoch time-based UUID
      * </ul>
      *
      * @return  The version number of this {@code UUID} @@ -336,16 +395,13 @@ public int version() {


      * The variant number has the following meaning:
      * <ul>
      * <li>0    Reserved for NCS backward compatibility
-     * <li>2    <a href="http://www.ietf.org/rfc/rfc4122.txt">IETF&nbsp;RFC&nbsp;4122</a>
+    * <li>2    <a href="https://www.ietf.org/rfc/rfc9562.txt">IETF&nbsp;RFC&nbsp;9562</a>
      * (Leach-Salz), used by this class
      * <li>6    Reserved, Microsoft Corporation backward compatibility
      * <li>7    Reserved for future definition
      * </ul>
      *
      * @return  The variant number of this {@code UUID}
-     *
-     * @spec https://www.rfc-editor.org/info/rfc4122
-     *      RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace
      */
     public int variant() {