Replace timeThenRandom with UUIDv7 backport from Java 26

Implemented proper UUIDv7 (RFC 9562) as specified in JDK-8334015.
The ofEpochMillis() method creates type 7 UUIDs with:
- 48-bit Unix timestamp in milliseconds
- Version 7 identifier (4 bits)
- IETF variant (2 bits)
- 74 random bits from SecureRandom

Benefits:
- Time-based sortability for database applications
- Standards-compliant RFC 9562 implementation
- Monotonicity when timestamps are monotonic

Added 7 new tests for UUIDv7 conformance:
- Version and variant verification
- Timestamp embedding and extraction
- Monotonicity validation
- Invalid timestamp rejection
- Uniqueness with same timestamp

Co-authored-by: simbo1905 <322608+simbo1905@users.noreply.github.com>

Author: Copilot

json-java21/src/main/java/jdk/sandbox/demo/UUIDGenerator.java

@@ -11,17 +11,22 @@
 
 /// UUID Generator providing time-ordered globally unique IDs.
 /// 
+/// This is a backport of UUIDv7 from Java 26 (JDK-8334015: https://bugs.openjdk.org/browse/JDK-8334015)
+/// 
+/// UUIDv7's time-based sortability makes it an attractive option for globally unique identifiers,
+/// especially in database applications. (https://www.rfc-editor.org/rfc/rfc9562#name-uuid-version-7)
+/// 
+/// As DBMS vendors add support for UUIDv7 (https://commitfest.postgresql.org/47/4388/) Java users
+/// will not easily take advantage of its benefits until it is included in the Java core libraries.
+/// 
 /// Generation:
-/// - timeThenRandom: Time-ordered globally unique 128-bit identifier
+/// - ofEpochMillis: Creates a UUIDv7 from Unix Epoch timestamp (backport from Java 26)
 /// - uniqueThenTime: User-ID-then-time-ordered 128-bit identifier
 /// 
 /// Formatting:
 /// - formatAsUUID: RFC 4122 format with dashes, 36 characters, uppercase or lowercase
 /// - formatAsDenseKey: Base62 encoded, 22 characters, zero-padded fixed-width
 /// 
-/// Note: Intended usage is one instance per JVM process. Multiple instances
-/// in the same process do not guarantee uniqueness due to shared sequence counter.
-/// 
 /// Note: 22-character keys are larger than Firebase push IDs (20 characters)
 /// but provide full 128-bit time-ordered randomized identifiers.
 public class UUIDGenerator {
@@ -52,14 +57,70 @@ static long timeCounterBits() {
 
     // Generation - Public API
 
-    /// ┌──────────────────────────────────────────────────────────────────────────────┐
-    /// │  time+counter  (64 bits)  │  random  (64 bits)                              │
-    /// └──────────────────────────────────────────────────────────────────────────────┘
-    public static UUID timeThenRandom() {
-        long msb = timeCounterBits();
-        long lsb = getRandom().nextLong();
+    /// 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 Backport from Java 26 (JDK-8334015)
+    public static UUID ofEpochMillis(long timestamp) {
+        if ((timestamp >> 48) != 0) {
+            throw new IllegalArgumentException("Supplied timestamp: " + timestamp + " does not fit within 48 bits");
+        }
+
+        SecureRandom ng = getRandom();
+        byte[] randomBytes = new byte[16];
+        ng.nextBytes(randomBytes);
+
+        // Embed the timestamp into the first 6 bytes
+        randomBytes[0] = (byte)(timestamp >> 40);
+        randomBytes[1] = (byte)(timestamp >> 32);
+        randomBytes[2] = (byte)(timestamp >> 24);
+        randomBytes[3] = (byte)(timestamp >> 16);
+        randomBytes[4] = (byte)(timestamp >> 8);
+        randomBytes[5] = (byte)(timestamp);
+
+        // Set version to 7
+        randomBytes[6] &= 0x0f;
+        randomBytes[6] |= 0x70;
+
+        // Set variant to IETF
+        randomBytes[8] &= 0x3f;
+        randomBytes[8] |= (byte) 0x80;
+
+        // Convert byte array to UUID using ByteBuffer
+        ByteBuffer buffer = ByteBuffer.wrap(randomBytes);
+        long msb = buffer.getLong();
+        long lsb = buffer.getLong();
         return new UUID(msb, lsb);
     }
+    
+    /// Convenience method to create a UUIDv7 from the current system time.
+    /// Equivalent to {@code ofEpochMillis(System.currentTimeMillis())}.
+    ///
+    /// @return a {@code UUID} constructed using the current system time
+    public static UUID timeThenRandom() {
+        return ofEpochMillis(System.currentTimeMillis());
+    }
 
     /// ┌──────────────────────────────────────────────────────────────────────────────┐
     /// │  unique  (64 bits)  │  time+counter  (44 bits)  │  random  (20 bits)        │
@@ -134,12 +195,18 @@ public static String formatAsDenseKey(UUID uuid) {
     }
 
     public static void main(String[] args) {
+        // Test UUIDv7 with current time
         UUID uuid1 = UUIDGenerator.timeThenRandom();
-        System.out.println("UUID: " + UUIDGenerator.formatAsUUID(uuid1));
+        System.out.println("UUIDv7: " + UUIDGenerator.formatAsUUID(uuid1));
         System.out.println("Dense: " + UUIDGenerator.formatAsDenseKey(uuid1));
 
-        UUID uuid2 = UUIDGenerator.uniqueThenTime(0x123456789ABCDEF0L);
-        System.out.println("Unique UUID: " + UUIDGenerator.formatAsUUID(uuid2, true));
-        System.out.println("Unique Dense: " + UUIDGenerator.formatAsDenseKey(uuid2));
+        // Test UUIDv7 with specific timestamp
+        UUID uuid2 = UUIDGenerator.ofEpochMillis(System.currentTimeMillis());
+        System.out.println("UUIDv7 (explicit): " + UUIDGenerator.formatAsUUID(uuid2));
+        
+        // Test uniqueThenTime
+        UUID uuid3 = UUIDGenerator.uniqueThenTime(0x123456789ABCDEF0L);
+        System.out.println("Unique UUID: " + UUIDGenerator.formatAsUUID(uuid3, true));
+        System.out.println("Unique Dense: " + UUIDGenerator.formatAsDenseKey(uuid3));
     }
 }

json-java21/src/test/java/jdk/sandbox/demo/UUIDGeneratorTest.java

@@ -34,13 +34,27 @@ void testTimeThenRandomGeneratesUniqueUUIDs() {
 
     @Test
     void testTimeThenRandomIncreasingOrder() {
+        // UUIDv7 uses millisecond timestamps in the first 48 bits.
+        // Within the same millisecond, ordering is not guaranteed due to random bits.
+        // This test verifies that UUIDs generated with different timestamps are ordered.
         UUID prev = UUIDGenerator.timeThenRandom();
-        for (int i = 0; i < 100; i++) {
+        try {
+            Thread.sleep(2); // Ensure at least 1ms passes
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+        
+        for (int i = 0; i < 10; i++) {
             UUID current = UUIDGenerator.timeThenRandom();
-            // MSB should be increasing (time+counter)
+            // MSB should be increasing when timestamps differ
             assertTrue(current.getMostSignificantBits() >= prev.getMostSignificantBits(),
-                "UUIDs should be time-ordered");
+                "UUIDs with different timestamps should be time-ordered");
             prev = current;
+            try {
+                Thread.sleep(1); // Small delay to ensure different timestamps
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
         }
     }
 
@@ -235,4 +249,86 @@ void testFormatAsDenseKeyDeterministic() {
 
         assertEquals(key1, key2, "Same UUID should produce same dense key");
     }
+
+    @Test
+    void testOfEpochMillisVersion7() {
+        // Test that generated UUID has version 7
+        long timestamp = System.currentTimeMillis();
+        UUID uuid = UUIDGenerator.ofEpochMillis(timestamp);
+        
+        // Extract version bits (bits 48-51 of the UUID)
+        long msb = uuid.getMostSignificantBits();
+        int version = (int)((msb >> 12) & 0x0F);
+        
+        assertEquals(7, version, "UUID should have version 7");
+    }
+
+    @Test
+    void testOfEpochMillisVariantIETF() {
+        // Test that generated UUID has IETF variant
+        long timestamp = System.currentTimeMillis();
+        UUID uuid = UUIDGenerator.ofEpochMillis(timestamp);
+        
+        // Extract variant bits (bits 64-65 of the UUID)
+        long lsb = uuid.getLeastSignificantBits();
+        int variant = (int)((lsb >> 62) & 0x03);
+        
+        assertEquals(2, variant, "UUID should have IETF variant (2)");
+    }
+
+    @Test
+    void testOfEpochMillisTimestampExtraction() {
+        // Test that timestamp can be extracted from UUID
+        long timestamp = 1000000000000L;
+        UUID uuid = UUIDGenerator.ofEpochMillis(timestamp);
+        
+        // Extract timestamp from first 48 bits
+        long msb = uuid.getMostSignificantBits();
+        long extractedTimestamp = msb >>> 16; // Shift right 16 bits to get top 48 bits
+        
+        assertEquals(timestamp, extractedTimestamp, "Timestamp should be embedded in UUID");
+    }
+
+    @Test
+    void testOfEpochMillisMonotonicity() {
+        // Test that UUIDs with increasing timestamps are monotonic
+        UUID uuid1 = UUIDGenerator.ofEpochMillis(1000000000000L);
+        UUID uuid2 = UUIDGenerator.ofEpochMillis(1000000000001L);
+        UUID uuid3 = UUIDGenerator.ofEpochMillis(1000000000002L);
+        
+        assertTrue(uuid2.compareTo(uuid1) > 0, "UUID2 should be greater than UUID1");
+        assertTrue(uuid3.compareTo(uuid2) > 0, "UUID3 should be greater than UUID2");
+    }
+
+    @Test
+    void testOfEpochMillisInvalidTimestamp() {
+        // Test that timestamps that don't fit in 48 bits are rejected
+        long invalidTimestamp = (1L << 48); // 2^48, doesn't fit in 48 bits
+        
+        assertThrows(IllegalArgumentException.class, () -> {
+            UUIDGenerator.ofEpochMillis(invalidTimestamp);
+        }, "Should throw IllegalArgumentException for timestamp that doesn't fit in 48 bits");
+    }
+
+    @Test
+    void testOfEpochMillisNegativeTimestamp() {
+        // Test that negative timestamps are rejected
+        long negativeTimestamp = -1L;
+        
+        assertThrows(IllegalArgumentException.class, () -> {
+            UUIDGenerator.ofEpochMillis(negativeTimestamp);
+        }, "Should throw IllegalArgumentException for negative timestamp");
+    }
+
+    @Test
+    void testOfEpochMillisUniqueness() {
+        // Test that multiple UUIDs with same timestamp are still unique (due to random bits)
+        long timestamp = System.currentTimeMillis();
+        Set<UUID> uuids = new HashSet<>();
+        
+        for (int i = 0; i < 100; i++) {
+            UUID uuid = UUIDGenerator.ofEpochMillis(timestamp);
+            assertTrue(uuids.add(uuid), "Each UUID should be unique even with same timestamp");
+        }
+    }
 }