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 91191dae2bf1fd17a4138048685a8e8d62515ad5..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,18 @@ import java.util.function.Supplier;
  * @see https://datatracker.ietf.org/doc/html/rfc4122
  */
 public interface UuidFactory extends Supplier<UUID> {
+
+       /*
+        * DEFAULT
+        */
+       /**
+        * The default {@link UUID} to provide, either random (v4) or time based (v1).
+        * It SHOULD wrap either {@link #timeUUID()} (recommended) or
+        * {@link #randomUUID()}.
+        */
+       @Override
+       UUID get();
+
        /*
         * TIME-BASED (version 1)
         */
@@ -120,16 +132,6 @@ public interface UuidFactory extends Supplier<UUID> {
                return randomUUIDStrong();
        }
 
-       /**
-        * The default {@link UUID} to provide, either random (v4) or time based (v1).
-        * This default implementations returns {@link #timeUUID()} because it is
-        * supposed to be fast and use few resources.
-        */
-       @Override
-       default UUID get() {
-               return timeUUID();
-       }
-
        /*
         * STANDARD UUIDs
         */
@@ -157,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
         */
@@ -187,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();
+       }
 }