org.argeo.api.acr/src/org/argeo/api/acr/uuid/UuidFactory.java

   1 package org.argeo.api.acr.uuid;
   2
   3 import static java.nio.charset.StandardCharsets.UTF_8;
   4
   5 import java.util.Objects;
   6 import java.util.UUID;
   7 import java.util.concurrent.ThreadLocalRandom;
   8 import java.util.function.Supplier;
   9
  10 /**
  11  * A provider of RFC 4122 {@link UUID}s. Only the RFC 4122 variant (also known
  12  * as Leach–Salz variant) is supported. The default, returned by the
  13  * {@link Supplier#get()} method MUST be a v4 UUID (random).
  14  *
  15  * @see UUID
  16  * @see https://datatracker.ietf.org/doc/html/rfc4122
  17  */
  18 public interface UuidFactory extends Supplier<UUID> {
  19         /*
  20          * TIME-BASED (version 1)
  21          */
  22
  23         UUID timeUUID();
  24
  25         UUID timeUUIDwithMacAddress();
  26
  27         /*
  28          * NAME BASED (version 3 and 5)
  29          */
  30
  31         UUID nameUUIDv5(UUID namespace, byte[] data);
  32
  33         UUID nameUUIDv3(UUID namespace, byte[] data);
  34
  35         default UUID nameUUIDv5(UUID namespace, String name) {
  36                 Objects.requireNonNull(name, "Name cannot be null");
  37                 return nameUUIDv5(namespace, name.getBytes(UTF_8));
  38         }
  39
  40         default UUID nameUUIDv3(UUID namespace, String name) {
  41                 Objects.requireNonNull(name, "Name cannot be null");
  42                 return nameUUIDv3(namespace, name.getBytes(UTF_8));
  43         }
  44
  45         /*
  46          * RANDOM (version 4)
  47          */
  48         /** A random UUID at least as good as {@link UUID#randomUUID()}. */
  49         UUID randomUUIDStrong();
  50
  51         /**
  52          * An {@link UUID} generated based on {@link ThreadLocalRandom}. Implementations
  53          * should always provide it synchronously.
  54          */
  55         UUID randomUUIDWeak();
  56
  57         /**
  58          * The default random {@link UUID} (v4) generator to use. This default
  59          * implementation returns {@link #randomUUIDStrong()}.
  60          */
  61         default UUID randomUUID() {
  62                 return randomUUIDStrong();
  63         }
  64
  65         /**
  66          * The default {@link UUID} to provide, either random (v4) or time based (v1).
  67          * This default implementations returns {@link #randomUUID()}.
  68          */
  69         @Override
  70         default UUID get() {
  71                 return randomUUID();
  72         }
  73
  74         /*
  75          * STANDARD UUIDs
  76          */
  77
  78         /** Nil UUID (00000000-0000-0000-0000-000000000000). */
  79         final static UUID NIL_UUID = UUID.fromString("00000000-0000-0000-0000-000000000000");
  80         /**
  81          * Standard DNS namespace ID for type 3 or 5 UUID (as defined in Appendix C of
  82          * RFC4122).
  83          */
  84         final static UUID NS_DNS = UUID.fromString("6ba7b810-9dad-11d1-80b4-00c04fd430c8");
  85         /**
  86          * Standard URL namespace ID for type 3 or 5 UUID (as defined in Appendix C of
  87          * RFC4122).
  88          */
  89         final static UUID NS_URL = UUID.fromString("6ba7b811-9dad-11d1-80b4-00c04fd430c8");
  90         /**
  91          * Standard OID namespace ID (typically an LDAP type) for type 3 or 5 UUID (as
  92          * defined in Appendix C of RFC4122).
  93          */
  94         final static UUID NS_OID = UUID.fromString("6ba7b812-9dad-11d1-80b4-00c04fd430c8");
  95         /**
  96          * Standard X500 namespace ID (typically an LDAP DN) for type 3 or 5 UUID (as
  97          * defined in Appendix C of RFC4122).
  98          */
  99         final static UUID NS_X500 = UUID.fromString("6ba7b814-9dad-11d1-80b4-00c04fd430c8");
 100
 101         /*
 102          * UTILITIES
 103          */
 104
 105         static boolean isRandom(UUID uuid) {
 106                 return uuid.version() == 4;
 107         }
 108
 109         static boolean isTimeBased(UUID uuid) {
 110                 return uuid.version() == 1;
 111         }
 112
 113         /**
 114          * Whether this UUID is time based but was not generated from an IEEE 802
 115          * address, as per Section 4.5 of RFC4122.
 116          *
 117          * @see https://datatracker.ietf.org/doc/html/rfc4122#section-4.5
 118          */
 119         static boolean isTimeBasedWithMacAddress(UUID uuid) {
 120                 if (uuid.version() == 1) {
 121                         return (uuid.node() & 1L) == 0;
 122                 } else
 123                         return false;
 124         }
 125
 126         static boolean isNameBased(UUID uuid) {
 127                 return uuid.version() == 3 || uuid.version() == 5;
 128         }
 129 }