com.datastax.oss.driver.api.core.uuid

Class Uuids

java.lang.Object

com.datastax.oss.driver.api.core.uuid.Uuids

public final class Uuids
extends Object

Utility methods to help working with UUIDs, and more specifically, with time-based UUIDs (also known as Version 1 UUIDs).

The algorithm to generate time-based UUIDs roughly follows the description in RFC-4122, but with the following adaptations:

1. Since Java does not provide direct access to the host's MAC address, that information is replaced with a digest of all IP addresses available on the host;
2. The process ID (PID) isn't easily available to Java either, so it is determined by one of the following methods, in the order they are listed below:
   1. If the System property "com.datastax.oss.driver.PID" is set then the value to use as a PID will be read from that property;
   2. Otherwise, if a native call to POSIX.getpid() is possible, then the PID will be read from that call;
   3. Otherwise, an attempt will be made to read the PID from JMX's 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);
   4. If all of the above fail, a random integer will be generated and used as a surrogate PID.

See Also:

JAVA-444, A Universally Unique IDentifier (UUID) URN Namespace (RFC 4122)

Field Summary

Fields

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").

Method Summary

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	random(Random random) Creates a new random (version 4) UUID using the provided Random instance.
static UUID	random(SplittableRandom random) Creates a new random (version 4) UUID using the provided SplittableRandom instance.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PID_SYSTEM_PROPERTY

public static final String PID_SYSTEM_PROPERTY

The system property to use to force the value of the process ID ("com.datastax.oss.driver.PID").

See Also:

Constant Field Values

NAMESPACE_URL

public static final UUID NAMESPACE_URL

The namespace UUID for URLs, as defined in Appendix C of RFC-4122. When using this namespace to create a name-based UUID, it is expected that the name part be a valid URL.

NAMESPACE_DNS

public static final UUID NAMESPACE_DNS

The namespace UUID for fully-qualified domain names, as defined in Appendix C of RFC-4122. When using this namespace to create a name-based UUID, it is expected that the name part be a valid domain name.

NAMESPACE_OID

public static final UUID NAMESPACE_OID

The namespace UUID for OIDs, as defined in Appendix C of RFC-4122. When using this namespace to create a name-based UUID, it is expected that the name part be an ISO OID.

NAMESPACE_X500

public static final UUID NAMESPACE_X500

The namespace UUID for X.500 domain names, as defined in Appendix C of RFC-4122. When using this namespace to create a name-based UUID, it is expected that the name part be a valid X.500 domain name, in DER or a text output format.

Method Detail

random

@NonNull
public static UUID random()

Creates a new random (version 4) UUID.

This method has received a new implementation as of driver 4.10. Unlike the JDK's UUID.randomUUID() method, it does not use anymore the cryptographic SecureRandom number generator. Instead, it uses the non-cryptographic Random class, with a different seed at every invocation.

Using a non-cryptographic generator has two advantages:

1. UUID generation is much faster than with UUID.randomUUID();
2. Contrary to UUID.randomUUID(), UUID generation with this method does not require I/O and is not a blocking call, which makes this method better suited for non-blocking applications.

Of course, this method is intended for usage where cryptographic strength is not required, such as when generating row identifiers for insertion in the database. If you still need cryptographic strength, consider using random(Random) instead, and pass an instance of SecureRandom.

random

@NonNull
public static UUID random(@NonNull
                                   Random random)

Creates a new random (version 4) UUID using the provided Random instance.

This method offers more flexibility than random() as it allows to customize the Random instance to use, and also offers the possibility to reuse instances across successive calls. Reusing Random instances is the norm when using ThreadLocalRandom, for instance; however other Random implementations may perform poorly under heavy thread contention.

Note: some Random implementations, such as SecureRandom, may trigger I/O activity during random number generation; these instances should not be used in non-blocking contexts.

random

@NonNull
public static UUID random(@NonNull
                                   SplittableRandom random)

Creates a new random (version 4) UUID using the provided SplittableRandom instance.

This method should be preferred to random() when UUID generation happens in massive parallel computations, such as when using the ForkJoin framework. Note that SplittableRandom instances are not thread-safe.

nameBased

@NonNull
public static UUID nameBased(@NonNull
                                      UUID namespace,
                                      @NonNull
                                      String name)

Creates a new name-based (version 3) 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.

Parameters:

namespace - The namespace UUID to use; cannot be null.

name - The name part; cannot be null.

Throws:

NullPointerException - if namespace or name is null.

IllegalStateException - if the MessageDigest algorithm for version 3 (MD5) is not available on this platform.

nameBased

@NonNull
public static UUID nameBased(@NonNull
                                      UUID namespace,
                                      @NonNull
                                      byte[] name)

Creates a new name-based (version 3) UUID from the given namespace UUID and the given byte array representing the name part.

Parameters:

namespace - The namespace UUID to use; cannot be null.

name - The name part; cannot be null.

Throws:

NullPointerException - if namespace or name is null.

IllegalStateException - if the MessageDigest algorithm for version 3 (MD5) is not available on this platform.

nameBased

@NonNull
public static UUID nameBased(@NonNull
                                      UUID namespace,
                                      @NonNull
                                      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.

Note that the given string will be converted to bytes using StandardCharsets.UTF_8.

Parameters:

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.

Throws:

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.

nameBased

@NonNull
public static UUID nameBased(@NonNull
                                      UUID namespace,
                                      @NonNull
                                      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.

Parameters:

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.

Throws:

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.

nameBased

@NonNull
public static UUID nameBased(@NonNull
                                      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.

The byte array is expected to be at least 16 bytes long.

Parameters:

namespaceAndName - A byte array containing the concatenated namespace UUID and name; cannot be null.

Throws:

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.

nameBased

@NonNull
public static UUID nameBased(@NonNull
                                      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.

The byte array is expected to be at least 16 bytes long.

Parameters:

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.

Throws:

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.

timeBased

@NonNull
public static UUID timeBased()

Creates a new time-based (version 1) UUID.

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).

Usage with non-blocking threads: beware that this method may block the calling thread on its very first invocation, because the node part of time-based UUIDs needs to be computed at that moment, and the computation may require the loading of native libraries. If that is a problem, consider invoking this method once from a thread that is allowed to block. Subsequent invocations are guaranteed not to block.

startOf

@NonNull
public 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.

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.

Parameters:

timestamp - the Unix timestamp for which the created UUID must be a lower bound.

Returns:

the smallest (for Cassandra timeuuid sorting) UUID of timestamp.

endOf

@NonNull
public 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.

See startOf(long) for explanations about the intended usage of such UUID.

Parameters:

timestamp - the Unix timestamp for which the created UUID must be an upper bound.

Returns:

the biggest (for Cassandra timeuuid sorting) UUID of timestamp.

unixTimestamp

public static long unixTimestamp(@NonNull
                                 UUID uuid)

Returns the Unix timestamp contained by the provided time-based 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.

Throws:

IllegalArgumentException - if uuid is not a version 1 UUID.