Guide to UUID in Java

1. Overview

In this article, we will learn about UUID (Universally Unique Identifier) codes, occasionally referred to as GUID (Globally Unique Identifier). In short, it is a 128-bit long number in hex characters separated by “-“:

e58ed763-928c-4155-bee9-fdbaaadc15f3

A standard UUID code contains 32 hex digits along with 4 “-” symbols, which makes its length equal to 36 characters. There is also a Nil UUID code where all bits are set to zero.

Here, we’ll look at the UUID class in Java. First, we’ll see how to use the class itself. Then we’ll look at the different types of UUIDs and how we can generate them in Java.

2. The UUID Class

The UUID class has a single constructor that requires two long parameters describing the most significant at the least significant 64 bits:

UUID uuid = new UUID(mostSignificant64Bits, leastSignificant64Bits);

The downside of using the constructor directly is that we must construct the bit pattern of the UUID, which might be a good solution when we want to recreate a UUID object. But most of the time, we use UUID to identify something and can assign a random value. Therefore, the UUID class provides three static methods we can use.

First, we can create a version 3 UUIF using the .nameUUIDFromBytes() method, which requires a byte array as a parameter:

UUID uuid = UUID.nameUUIDFromBytes(bytes);

Second, we can parse a UUID string value from a previously generated code:

UUID uuid = UUID.fromString(uuidHexDigitString);

Again, this method uses some input to create the UUID code. But, there is a more convenient way to create a UUID without giving any parameter as input. Finally, using the .randomUUID() method, we can create a version 4 UUID:

UUID uuid = UUID.randomUUID();

Next, we’ll try to understand the structure of a UUID.

3. Structure

In particular, let’s consider the following UUID with a corresponding mask underneath:

123e4567-e89b-42d3-a456-556642440000
xxxxxxxx-xxxx-Bxxx-Axxx-xxxxxxxxxxxx

3.1. UUID Variant

In the example above, A denotes the variant that defines the layout of the UUID. All the other bits in the UUID depend on the layout of the variant field. Therefore, the variant represents the three most significant bits of A:

  MSB1    MSB2    MSB3
   0       X       X     reserved (0)
   1       0       X     current variant (2)
   1       1       0     reserved for Microsoft (6)
   1       1       1     reserved for future (7)

Above, the A value in the example UUID is “a”, which is 10xx in binary. So, the layout variant is 2.

3.2. UUID Version

Similarly, B represents the version. In the example UUID, the value of B is 4, which means it is using version 4.

For any UUID object inside Java, we can check the variant and the version using the .variant() and the .version() methods:

UUID uuid = UUID.randomUUID();
int variant = uuid.variant();
int version = uuid.version();

Moreover, there are five different versions for variant 2 UUIDs:

• Time-Based (UUIDv1)
• DCE Security (UUIDv2)
• Name Based (UUIDv3 and UUIDv5)
• Random (UUIDv4)

However, Java provides an implementation only for v3 and v4. Alternatively, we can use the constructor to generate the other types.

4. The UUID Versions

4.1. Version 1

UUID version 1 uses the current timestamp and the MAC address of the device generating the UUID. In particular, the timestamp is measured in units of 100 nanoseconds from October 15, 1582. Still, if privacy is a concern, we can use a random 48-bit number instead of the MAC address.

With this in mind, let’s generate the least significant and most significant 64 bits as long values:

private static long get64LeastSignificantBitsForVersion1() {
    Random random = new Random();
    long random63BitLong = random.nextLong() & 0x3FFFFFFFFFFFFFFFL;
    long variant3BitFlag = 0x8000000000000000L;
    return random63BitLong | variant3BitFlag;
}

Above, we combine two long values representing the last 63 bits of a random long value and the 3-bit variant flag. Next, we create the 64 most significant bits using a timestamp:

private static long get64MostSignificantBitsForVersion1() {
    final long currentTimeMillis = System.currentTimeMillis();
    final long time_low = (currentTimeMillis & 0x0000_0000_FFFF_FFFFL) << 32; 
    final long time_mid = ((currentTimeMillis >> 32) & 0xFFFF) << 16;
    final long version = 1 << 12; 
    final long time_hi = ((currentTimeMillis >> 48) & 0x0FFF);
    return time_low | time_mid | version | time_hi;
}

We can then pass these two values to the constructor of the UUID:

public static UUID generateType1UUID() {
    long most64SigBits = get64MostSignificantBitsForVersion1();
    long least64SigBits = get64LeastSignificantBitsForVersion1();
    return new UUID(most64SigBits, least64SigBits);
}

4.2. Version 2

Next, version 2 uses a timestamp and the MAC address as well. However, RFC 4122 does not specify the exact generation details, so that we won’t look at an implementation in this article.

4.3. Versions 3 and 5

Versions 3 and 5 UUIDs use hashed names drawn from a unique namespace. Moreover, the concept of names is not limited to textual form. For example, Domain Name System (DNS), Object Identifiers (OIDs), URLs, etc., are considered valid namespaces.

UUID = hash(NAMESPACE_IDENTIFIER + NAME)

In detail, the difference between UUIDv3 and UUIDv5 is the Hashing Algorithm — v3 uses MD5 (128 bits), while v5 uses SHA-1 (160 bits) truncated to 128 bits. For both versions, we replace the bits to correct the version and the variant accordingly.

Alternatively, we can generate type 3 UUID from a previous namespace and given name and use the method .nameUUIDFromBytes():

byte[] nameSpaceBytes = bytesFromUUID(namespace);
byte[] nameBytes = name.getBytes("UTF-8");
byte[] result = joinBytes(nameSpaceBytes, nameBytes);

UUID uuid = UUID.nameUUIDFromBytes(result);

Here, we convert the hex string for the namespace to a byte array and then combine it with the name to create the UUID.

To keep things simple, we won’t describe the implementation for version 5 as it is similar. However, keep in mind that Java doesn’t implement type 5.

4.4. Version 4

Finally, we already described how to generate version 4 UUID. Again, we call the randomUUID() method the UUID class provides to get the UUIDv4.

5. Conclusion

In this tutorial, we saw a UUID’s structure and the various existing versions. First, we looked the how to create UUID in Java. Then, we described some UUID versions in more detail. Finally, we provided some code examples to generate UUID codes for custom needs manually.

And as always, the implementation’s source code is available over on GitHub.