Document and clean up UUID factory API and implementation.

[lgpl/argeo-commons.git] / org.argeo.api.uuid / src / org / argeo / api / uuid / UuidFactory.java

diff --git a/org.argeo.api.uuid/src/org/argeo/api/uuid/UuidFactory.java b/org.argeo.api.uuid/src/org/argeo/api/uuid/UuidFactory.java
index dc83f48ec10ea62fbb5ea4c08578a27ae6276d43..4ab6c2e4b754d7818be29a24fece361373b5f6e9 100644 (file)
--- a/org.argeo.api.uuid/src/org/argeo/api/uuid/UuidFactory.java
+++ b/org.argeo.api.uuid/src/org/argeo/api/uuid/UuidFactory.java
@@ -17,6 +17,7 @@ import java.util.function.Supplier;
  * @see https://datatracker.ietf.org/doc/html/rfc4122
  */
 public interface UuidFactory extends Supplier<UUID> {
+
        /*
         * DEFAULT
         */
@@ -158,6 +159,14 @@ public interface UuidFactory extends Supplier<UUID> {
         */
        final static UUID NAMESPACE_UUID_X500 = UUID.fromString("6ba7b814-9dad-11d1-80b4-00c04fd430c8");
 
+       /*
+        * BIT LEVEL CONSTANTS
+        */
+       /** Base for the most significant bit of version 1 (time based) UUIDs. */
+       long MOST_SIG_VERSION1 = (1l << 12);
+       /** Base for the least significant part of RFC4122 (variant 2) UUIDs. */
+       long LEAST_SIG_RFC4122_VARIANT = (1l << 63);
+
        /*
         * UTILITIES
         */
@@ -188,4 +197,30 @@ public interface UuidFactory extends Supplier<UUID> {
        static boolean isNameBased(UUID uuid) {
                return uuid.version() == 3 || uuid.version() == 5;
        }
+
+       /**
+        * The state of a time based UUID generator, as described and discussed in
+        * section 4.2.1 of RFC4122.
+        * 
+        * @see https://datatracker.ietf.org/doc/html/rfc4122#section-4.2.1
+        */
+       interface TimeUuidState {
+               /** Current node id and clock sequence for this thread. */
+               long getLeastSignificantBits();
+
+               /** A new current timestamp for this thread. */
+               long getMostSignificantBits();
+
+               /**
+                * The last timestamp which was produced by this thread, as returned by
+                * {@link UUID#timestamp()}.
+                */
+               long getLastTimestamp();
+
+               /**
+                * The current clock sequence for this thread, as returned by
+                * {@link UUID#clockSequence()}.
+                */
+               long getClockSequence();
+       }
 }