1 package org
.argeo
.api
.uuid
;
3 import static java
.nio
.charset
.StandardCharsets
.UTF_8
;
5 import java
.nio
.charset
.Charset
;
6 import java
.util
.Objects
;
8 import java
.util
.concurrent
.ThreadLocalRandom
;
9 import java
.util
.function
.Supplier
;
12 * A provider of RFC 4122 {@link UUID}s. Only the RFC 4122 variant (also known
13 * as Leach–Salz variant) is supported. The default, returned by the
14 * {@link Supplier#get()} method MUST be a v4 UUID (random).
17 * @see "https://datatracker.ietf.org/doc/html/rfc4122"
19 public interface UuidFactory
extends Supplier
<UUID
> {
25 * The default {@link UUID} to provide, either random (v4) or time based (v1).
26 * It SHOULD wrap either {@link #timeUUID()} (recommended) or
27 * {@link #randomUUID()}.
33 * TIME-BASED (version 1)
36 * A new time based {@link UUID} (v1) with efforts to make it unique on this
42 * NAME BASED (version 3 and 5)
45 * A new {@link UUID} v5, which an SHA1 digest of namespace and the provided
46 * bytes. This use to build names and implementation MAY restrict the maximal
47 * size of the byte array.
49 * @see UuidFactory#NAMESPACE_UUID_DNS
50 * @see UuidFactory#NAMESPACE_UUID_URL
51 * @see UuidFactory#NAMESPACE_UUID_OID
52 * @see UuidFactory#NAMESPACE_UUID_X500
54 UUID
nameUUIDv5(UUID namespace
, byte[] data
);
57 * A new {@link UUID} v3, which a MD5 digest of namespace and the provided
58 * bytes. This use to build names and implementation MAY restrict the maximal
59 * size of the byte array.
61 * @see UuidFactory#NAMESPACE_UUID_DNS
62 * @see UuidFactory#NAMESPACE_UUID_URL
63 * @see UuidFactory#NAMESPACE_UUID_OID
64 * @see UuidFactory#NAMESPACE_UUID_X500
66 UUID
nameUUIDv3(UUID namespace
, byte[] data
);
69 * A convenience method to generate a name based UUID v5 based on a string,
70 * using the UTF-8 charset.
72 * @see UuidFactory#nameUUIDv5(UUID, byte[])
74 default UUID
nameUUIDv5(UUID namespace
, String name
) {
75 return nameUUIDv5(namespace
, name
, UTF_8
);
79 * A convenience method to generate a name based UUID v5 based on a string.
81 * @see UuidFactory#nameUUIDv5(UUID, byte[])
83 default UUID
nameUUIDv5(UUID namespace
, String name
, Charset charset
) {
84 Objects
.requireNonNull(name
, "Name cannot be null");
85 return nameUUIDv5(namespace
, name
.getBytes(charset
));
89 * A convenience method to generate a name based UUID v3 based on a string,
90 * using the UTF-8 charset.
92 * @see UuidFactory#nameUUIDv3(UUID, byte[])
94 default UUID
nameUUIDv3(UUID namespace
, String name
) {
95 return nameUUIDv3(namespace
, name
, UTF_8
);
99 * A convenience method to generate a name based UUID v3 based on a string.
101 * @see UuidFactory#nameUUIDv3(UUID, byte[])
103 default UUID
nameUUIDv3(UUID namespace
, String name
, Charset charset
) {
104 Objects
.requireNonNull(name
, "Name cannot be null");
105 return nameUUIDv3(namespace
, name
.getBytes(charset
));
112 * A random UUID at least as good as {@link UUID#randomUUID()}, but with efforts
113 * to make it even more random, using more secure algorithms and resseeding.
115 UUID
randomUUIDStrong();
118 * An {@link UUID} generated based on {@link ThreadLocalRandom}. Implementations
119 * should always provide it synchronously.
121 UUID
randomUUIDWeak();
124 * The default random {@link UUID} (v4) generator to use. This default
125 * implementation returns {@link #randomUUIDStrong()}. In general, one should
126 * use {@link UUID#randomUUID()} to generate random UUID, as it is certainly the
127 * best balanced and to avoid unnecessary dependencies with an API. The
128 * implementations provided here are either when is looking for something
129 * "stronger" ({@link #randomUUIDStrong()} or faster {@link #randomUUIDWeak()}.
131 default UUID
randomUUID() {
132 return randomUUIDStrong();
139 /** Nil UUID (00000000-0000-0000-0000-000000000000). */
140 final static UUID NIL_UUID
= UUID
.fromString("00000000-0000-0000-0000-000000000000");
142 * Standard DNS namespace ID for type 3 or 5 UUID (as defined in Appendix C of
145 final static UUID NAMESPACE_UUID_DNS
= UUID
.fromString("6ba7b810-9dad-11d1-80b4-00c04fd430c8");
147 * Standard URL namespace ID for type 3 or 5 UUID (as defined in Appendix C of
150 final static UUID NAMESPACE_UUID_URL
= UUID
.fromString("6ba7b811-9dad-11d1-80b4-00c04fd430c8");
152 * Standard OID namespace ID (typically an LDAP type) for type 3 or 5 UUID (as
153 * defined in Appendix C of RFC4122).
155 final static UUID NAMESPACE_UUID_OID
= UUID
.fromString("6ba7b812-9dad-11d1-80b4-00c04fd430c8");
157 * Standard X500 namespace ID (typically an LDAP DN) for type 3 or 5 UUID (as
158 * defined in Appendix C of RFC4122).
160 final static UUID NAMESPACE_UUID_X500
= UUID
.fromString("6ba7b814-9dad-11d1-80b4-00c04fd430c8");
163 * BIT LEVEL CONSTANTS
165 /** Base for the most significant bit of version 1 (time based) UUIDs. */
166 long MOST_SIG_VERSION1
= (1l << 12);
167 /** Base for the least significant part of RFC4122 (variant 2) UUIDs. */
168 long LEAST_SIG_RFC4122_VARIANT
= (1l << 63);
173 /** Whether this {@link UUID} is random (v4). */
174 static boolean isRandom(UUID uuid
) {
175 return uuid
.version() == 4;
178 /** Whether this {@link UUID} is time based (v1). */
179 static boolean isTimeBased(UUID uuid
) {
180 return uuid
.version() == 1;
184 * Whether this UUID is time based but was not generated from an IEEE 802
185 * address, as per Section 4.5 of RFC4122.
187 * @see "https://datatracker.ietf.org/doc/html/rfc4122#section-4.5"
189 static boolean isTimeBasedWithMacAddress(UUID uuid
) {
190 if (uuid
.version() == 1) {
191 return (uuid
.node() & 1L) == 0;
196 /** Whether this {@link UUID} is name based (v3 or v5). */
197 static boolean isNameBased(UUID uuid
) {
198 return uuid
.version() == 3 || uuid
.version() == 5;
202 * The state of a time based UUID generator, as described and discussed in
203 * section 4.2.1 of RFC4122.
205 * @see "https://datatracker.ietf.org/doc/html/rfc4122#section-4.2.1"
207 interface TimeUuidState
{
208 /** Current node id and clock sequence for this thread. */
209 long getLeastSignificantBits();
211 /** A new current timestamp for this thread. */
212 long getMostSignificantBits();
215 * The last timestamp which was produced by this thread, as returned by
216 * {@link UUID#timestamp()}.
218 long getLastTimestamp();
221 * The current clock sequence for this thread, as returned by
222 * {@link UUID#clockSequence()}.
224 long getClockSequence();