public final class Uuids extends Object
The algorithm to generate time-based UUIDs roughly follows the description in RFC-4122, but with the following adaptations:
"com.datastax.oss.driver.PID"
is set then the
value to use as a PID will be read from that property;
POSIX.getpid()
is possible, then the PID will
be read from that call;
RuntimeMXBean
, since most JVMs tend to use the
JVM's PID as part of that MXBean name (however that behavior is not officially part
of the specification, so it may not work for all JVMs);
Modifier and Type | Field and Description |
---|---|
static UUID |
NAMESPACE_DNS
The namespace UUID for fully-qualified domain names, as defined in Appendix C of RFC-4122.
|
static UUID |
NAMESPACE_OID
The namespace UUID for OIDs, as defined in Appendix C of RFC-4122.
|
static UUID |
NAMESPACE_URL
The namespace UUID for URLs, as defined in Appendix C of RFC-4122.
|
static UUID |
NAMESPACE_X500
The namespace UUID for X.500 domain names, as defined in Appendix C of RFC-4122.
|
static String |
PID_SYSTEM_PROPERTY
The system property to use to force the value of the process ID ("com.datastax.oss.driver.PID").
|
Modifier and Type | Method and Description |
---|---|
static UUID |
endOf(long timestamp)
Creates a "fake" time-based UUID that sorts as the biggest possible version 1 UUID generated at
the provided timestamp.
|
static UUID |
nameBased(byte[] namespaceAndName)
Creates a new name-based (version 3)
UUID from the given byte array containing the
namespace UUID and the name parts concatenated together. |
static UUID |
nameBased(byte[] namespaceAndName,
int version)
Creates a new name-based (version 3 or version 5)
UUID from the given byte array
containing the namespace UUID and the name parts concatenated together. |
static UUID |
nameBased(UUID namespace,
byte[] name)
Creates a new name-based (version 3)
UUID from the given namespace UUID and the given
byte array representing the name part. |
static UUID |
nameBased(UUID namespace,
byte[] name,
int version)
Creates a new name-based (version 3 or version 5)
UUID from the given namespace UUID
and the given byte array representing the name part. |
static UUID |
nameBased(UUID namespace,
String name)
Creates a new name-based (version 3)
UUID from the given namespace UUID and the given
string representing the name part. |
static UUID |
nameBased(UUID namespace,
String name,
int version)
Creates a new name-based (version 3 or version 5)
UUID from the given namespace UUID
and the given string representing the name part. |
static UUID |
random()
Creates a new random (version 4) UUID.
|
static UUID |
startOf(long timestamp)
Creates a "fake" time-based UUID that sorts as the smallest possible version 1 UUID generated
at the provided timestamp.
|
static UUID |
timeBased()
Creates a new time-based (version 1) UUID.
|
static long |
unixTimestamp(UUID uuid)
Returns the Unix timestamp contained by the provided time-based UUID.
|
public static final String PID_SYSTEM_PROPERTY
public static final UUID NAMESPACE_URL
URL
.public static final UUID NAMESPACE_DNS
public static final UUID NAMESPACE_OID
public static final UUID NAMESPACE_X500
@NonNull public static UUID random()
This method is just a convenience for UUID.randomUUID()
.
@NonNull public static UUID nameBased(@NonNull UUID namespace, @NonNull String name)
UUID
from the given namespace UUID and the given
string representing the name part.
Note that the given string will be converted to bytes using StandardCharsets.UTF_8
.
namespace
- The namespace UUID to use; cannot be null.name
- The name part; cannot be null.NullPointerException
- if namespace
or name
is null.IllegalStateException
- if the MessageDigest
algorithm for version 3 (MD5) is not
available on this platform.@NonNull public static UUID nameBased(@NonNull UUID namespace, @NonNull byte[] name)
UUID
from the given namespace UUID and the given
byte array representing the name part.namespace
- The namespace UUID to use; cannot be null.name
- The name part; cannot be null.NullPointerException
- if namespace
or name
is null.IllegalStateException
- if the MessageDigest
algorithm for version 3 (MD5) is not
available on this platform.@NonNull public static UUID nameBased(@NonNull UUID namespace, @NonNull String name, int version)
UUID
from the given namespace UUID
and the given string representing the name part.
Note that the given string will be converted to bytes using StandardCharsets.UTF_8
.
namespace
- The namespace UUID to use; cannot be null.name
- The name part; cannot be null.version
- The version to use, must be either 3 or 5; version 3 uses MD5 as its MessageDigest
algorithm, while version 5 uses SHA-1.NullPointerException
- if namespace
or name
is null.IllegalArgumentException
- if version
is not 3 nor 5.IllegalStateException
- if the MessageDigest
algorithm for the desired version is
not available on this platform.@NonNull public static UUID nameBased(@NonNull UUID namespace, @NonNull byte[] name, int version)
UUID
from the given namespace UUID
and the given byte array representing the name part.namespace
- The namespace UUID to use; cannot be null.name
- The name to use; cannot be null.version
- The version to use, must be either 3 or 5; version 3 uses MD5 as its MessageDigest
algorithm, while version 5 uses SHA-1.NullPointerException
- if namespace
or name
is null.IllegalArgumentException
- if version
is not 3 nor 5.IllegalStateException
- if the MessageDigest
algorithm for the desired version is
not available on this platform.@NonNull public static UUID nameBased(@NonNull byte[] namespaceAndName)
UUID
from the given byte array containing the
namespace UUID and the name parts concatenated together.
The byte array is expected to be at least 16 bytes long.
namespaceAndName
- A byte array containing the concatenated namespace UUID and name;
cannot be null.NullPointerException
- if namespaceAndName
is null.IllegalArgumentException
- if namespaceAndName
is not at least 16 bytes
long.IllegalStateException
- if the MessageDigest
algorithm for version 3 (MD5) is not
available on this platform.@NonNull public static UUID nameBased(@NonNull byte[] namespaceAndName, int version)
UUID
from the given byte array
containing the namespace UUID and the name parts concatenated together.
The byte array is expected to be at least 16 bytes long.
namespaceAndName
- A byte array containing the concatenated namespace UUID and name;
cannot be null.version
- The version to use, must be either 3 or 5.NullPointerException
- if namespaceAndName
is null.IllegalArgumentException
- if namespaceAndName
is not at least 16 bytes
long.IllegalArgumentException
- if version
is not 3 nor 5.IllegalStateException
- if the MessageDigest
algorithm for the desired version is
not available on this platform.@NonNull public static UUID timeBased()
UUIDs generated by this method are suitable for use with the timeuuid
Cassandra
type. In particular the generated UUID includes the timestamp of its generation.
Note that there is no way to provide your own timestamp. This is deliberate, as we feel that this does not conform to the UUID specification, and therefore don't want to encourage it through the API. If you want to do it anyway, use the following workaround:
Random random = new Random(); UUID uuid = new UUID(UUIDs.startOf(userProvidedTimestamp).getMostSignificantBits(), random.nextLong());If you simply need to perform a range query on a
timeuuid
column, use the "fake" UUID
generated by startOf(long)
and endOf(long)
.@NonNull public static UUID startOf(long timestamp)
Such created UUIDs are useful in queries to select a time range of a timeuuid
column.
The UUIDs created by this method are not unique and as such are not suitable
for anything else than querying a specific time range. In particular, you should not insert
such UUIDs. "True" UUIDs from user-provided timestamps are not supported (see timeBased()
for more explanations).
Also, the timestamp to provide as a parameter must be a Unix timestamp (as returned by
System.currentTimeMillis()
or Date.getTime()
), and not a count of
100-nanosecond intervals since 00:00:00.00, 15 October 1582 (as required by RFC-4122).
In other words, given a UUID uuid
, you should never call startOf(uuid.timestamp())
but rather startOf(unixTimestamp(uuid))
.
Lastly, please note that Cassandra's timeuuid
sorting is not compatible with UUID.compareTo(java.util.UUID)
and hence the UUIDs created by this method are not necessarily lower bound for
that latter method.
timestamp
- the Unix timestamp for which the created UUID must be a lower bound.timeuuid
sorting) UUID of timestamp
.@NonNull public static UUID endOf(long timestamp)
See startOf(long)
for explanations about the intended usage of such UUID.
timestamp
- the Unix timestamp for which the created UUID must be an upper bound.timeuuid
sorting) UUID of timestamp
.public static long unixTimestamp(@NonNull UUID uuid)
This method is not equivalent to UUID.timestamp()
. More precisely, a version 1 UUID
stores a timestamp that represents the number of 100-nanoseconds intervals since midnight, 15
October 1582 and that is what UUID.timestamp()
returns. This method however converts
that timestamp to the equivalent Unix timestamp in milliseconds, i.e. a timestamp representing
a number of milliseconds since midnight, January 1, 1970 UTC. In particular, the timestamps
returned by this method are comparable to the timestamps returned by System.currentTimeMillis()
, Date.getTime()
, etc.
IllegalArgumentException
- if uuid
is not a version 1 UUID.Copyright © 2017–2020. All rights reserved.