Package com.aim2be.platform.outbox

Class UuidV7

java.lang.Object
com.aim2be.platform.outbox.UuidV7
public final class UuidV7 extends Object
UUIDv7 generator per draft-ietf-uuidrev-rfc4122bis (RFC9562 §5.7).

Java 17 stdlib lacks a UUIDv7 factory (UUID.randomUUID() returns v4 with no time component); ADR-0014 §D-5 mandates UUIDv7 for outbox event_id so that natural insert order matches creation time — giving the poller scan ORDER BY created_at ASC clustered locality.

Layout (128 bits): 

  0                   1                   2                   3
  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                          unix_ts_ms (48)                      |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |  ver  |       rand_a (12)     |var|     rand_b (62)           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

This implementation is thread-safe via the SecureRandom backing (Java's stdlib SecureRandom is documented thread-safe). No monotonicity guarantee within a millisecond — two calls inside the same ms may emit UUIDs that sort opposite their creation order. That's fine for outbox sort-by-created_at (the entity has a separate @CreationTimestamp column); collision probability across 8 services × 1000 inserts/ms is astronomically low (62 random bits).

  • Method Details

    • generate

      public static UUID generate()
      Generate a fresh UUIDv7 anchored at System.currentTimeMillis().
      Returns:
      a new UUIDv7 whose first 48 bits encode the current wall-clock time in milliseconds since the Unix epoch

    • generate

      public static UUID generate(long unixTsMs)
      Generate a UUIDv7 anchored at a specific Unix-epoch millisecond.

      Exposed for deterministic test fixtures; production code should call generate() with the system clock.

      Parameters:
      unixTsMs - Unix-epoch timestamp in milliseconds; must be non-negative and fit in 48 bits (i.e. < 2^48)
      Returns:
      a new UUIDv7 with the given timestamp prefix
      Throws:
      IllegalArgumentException - when unixTsMs is negative or exceeds 48-bit range

    • timestampMs

      public static long timestampMs(UUID uuid)
      Extract the embedded Unix-epoch millisecond timestamp from a UUIDv7.

      Caller is responsible for confirming the input is actually a v7 UUID (uuid.version() == 7); this method shifts unconditionally and returns nonsense for other versions.

      Parameters:
      uuid - the UUIDv7 to inspect
      Returns:
      the embedded Unix-epoch timestamp in milliseconds