com.groupon.uuid
Class UUID

java.lang.Object
  com.groupon.uuid.UUID

public class UUID
extends Object

See README.md for more information. This is a UUID implementation that uses vB (custom) UUIDs by default, but can parse and hold validly formatted UUIDs of any type. The content is stored as a byte array, and some effort has been put into making this look at least a little bit like the java.util.UUID implementation. Probably the most common uses of this class will be UUID id = new UUID(); to generate a new vB UUID UUID id = new UUID(uuidString); to parse a 36-character string representation of a UUID String s = id.toString(); to serialize the UUID to a String

Field Summary

protected byte[]	content
static byte[]	MAC
static int	PID

Constructor Summary

UUID()
Constructor that generates a new vB UUID using the current process id, MAC address, and timestamp.

UUID(byte[] bytes)
Constructor that takes a byte array as this UUID's content.

UUID(long mostSigBits, long leastSigBits)
Constructs a UUID using long values representing the first and second half of the UUID content.

UUID(String id)
Constructor that takes a UUID string representation and parses it.

UUID(UUID uuid)
Constructs a Locality UUID from a standard Java java.util.UUID object.

Method Summary

boolean	equals(Object o) Basic implementation of equals that checks if the given object is null or a different type, then compares the byte arrays which store the content of the UUID.
byte[]	getBytes() Get contents of this UUID as a byte array.
long	getLeastSignificantBits() Get the least significant bits (the second half) of the UUID content as a 64-bit long.
byte[]	getMacFragment() Extract MAC address fragment from raw UUID bytes, setting missing values to 0, thus the first 2 and a half bytes will be 0, followed by 3 and a half bytes of the active MAC address when the UUID was generated.
long	getMostSignificantBits() Get the most significant bits (the first half) of the UUID content as a 64-bit long.
int	getProcessId() Extract process id from raw UUID bytes and return as int.
Date	getTimestamp() Extract timestamp from raw UUID bytes and return as int.
char	getVersion() Extract version field as a hex char from raw UUID bytes.
int	hashCode() The hash code implementation just calls Arrays.hashCode() on the contents of this UUID (stored as a byte array).
static boolean	isValidUUID(char[] ch) This method validates a character array as the expected format for a printed representation of a UUID.
static boolean	isValidUUID(String id) This method validates a UUID String by making sure its non-null and calling isValidUUID(char[]).
UUID	toJavaUUID() Get the java.util.UUID representation of this UUID object.
String	toString() Get this UUID object as a String.
static void	useSequentialIds() Toggle UUID generator into sequential mode, so the random segment is in order and increases by one.
static void	useVariableIds() Toggle uuid generator into variable mode, so the random segment is in reverse order and increases by a large increment.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

PID

public static final int PID

MAC

public static final byte[] MAC

content

protected final byte[] content

Constructor Detail

UUID

public UUID()

Constructor that generates a new vB UUID using the current process id, MAC address, and timestamp.

UUID

public UUID(byte[] bytes)

Constructor that takes a byte array as this UUID's content. This is equivalent to the binary representation of the UUID. Note that the byte array is copied, so if the argument value changes then the constructed UUID will not. This throws an IllegalArgumentException if the byte array is null or not 16 bytes long.

Parameters:

bytes - UUID content as bytes.

UUID

public UUID(String id)

Constructor that takes a UUID string representation and parses it. This constructor expects the canonical UUID String format validated by the isValidUUID() method and thros an IllegalArgumentException otherwise.

Parameters:

id - UUID String representation, expected to be the valid UUID format.

UUID

public UUID(UUID uuid)

Constructs a Locality UUID from a standard Java java.util.UUID object. A java.util.UUID object won't return its content as a byte array, but will return the first and second halves of content as longs. We use these to construct a new Locality UUID object. This throws an IllegalArgumentException if the uuid argument is null.

Parameters:

uuid - A non-null java.util.UUID object, from which we will construct a locality UUID with identical content.

UUID

public UUID(long mostSigBits,
            long leastSigBits)

Constructs a UUID using long values representing the first and second half of the UUID content. This was added to be consistent with the java.util.UUID constructor.

Parameters:

mostSigBits - Long value representing the first half of the UUID.

leastSigBits - Long value representing the second half of the UUID.

Method Detail

isValidUUID

public static boolean isValidUUID(String id)

This method validates a UUID String by making sure its non-null and calling isValidUUID(char[]).

Parameters:

id - UUID String.

Returns:

True or false based on whether the String can be used to construct a UUID.

isValidUUID

public static boolean isValidUUID(char[] ch)

This method validates a character array as the expected format for a printed representation of a UUID. The expected format is 36 characters long, with '-' at the 8th, 13th, 18th, and 23rd characters. The remaining characters are expected to be valid hex, meaning in the range ('0' - '9', 'a' - 'f', 'A' - 'F') inclusive. If a character array is valid, then it can be used to construct a UUID. This method has been written unrolled and verbosely, with the theory that this is simpler and faster than using loops or a regex.

Parameters:

ch - A character array of a UUID's printed representation.

Returns:

True or false based on whether the UUID is valid, no exceptions are thrown.

useSequentialIds

public static void useSequentialIds()

Toggle UUID generator into sequential mode, so the random segment is in order and increases by one. In sequential mode, there is presumably a desire that UUIDs generated around the same time should begin with similar characters, but this is difficult in a distributed environment. The solution is to set the counter value based on a hash of the UTC date and time up to a 10 minute precision. This means that UUID classes initialized at similar times should start with similar counter values, but this is not guaranteed. If one of these classes is generating vastly more UUIDs than others, then these counters can become skewed. Calling this method more than once without toggling back to variable mode has no effect, so it probably makes more sense to call this from a static context, like your main method or in a class' static initialization.

useVariableIds

public static void useVariableIds()

Toggle uuid generator into variable mode, so the random segment is in reverse order and increases by a large increment. This is the default mode.

getBytes

public byte[] getBytes()

Get contents of this UUID as a byte array. The array is copied before returning so that it can't be changed.

Returns:

Raw byte array of UUID contents.

toString

public String toString()

Get this UUID object as a String. It will be returned as a canonical 36-character UUID string with lower-case hex characters.

Overrides:

toString in class Object

Returns:

UUID as String.

getMostSignificantBits

public long getMostSignificantBits()

Get the most significant bits (the first half) of the UUID content as a 64-bit long.

Returns:

The first half of the UUID as a long.

getLeastSignificantBits

public long getLeastSignificantBits()

Get the least significant bits (the second half) of the UUID content as a 64-bit long.

Returns:

The second half of the UUID as a long.

toJavaUUID

public UUID toJavaUUID()

Get the java.util.UUID representation of this UUID object. The java.util.UUID is constructed using the most and least significant bits of this UUID's content. No memory is shared with the new java.util.UUID.

Returns:

This com.groupon.uuid.UUID's representation as a java.util.UUID.

getVersion

public char getVersion()

Extract version field as a hex char from raw UUID bytes. By default, generated UUIDs will have 'b' as the version, but it is possible to parse UUIDs of different types, '4' for example.

Returns:

UUID version as a char.

getProcessId

public int getProcessId()

Extract process id from raw UUID bytes and return as int. This only applies for this type of UUID, for other UUID types, such as the randomly generated v4, its not possible to discover process id, so -1 is returned.

Returns:

Id of process that generated the UUID, or -1 for unrecognized format.

getTimestamp

public Date getTimestamp()

Extract timestamp from raw UUID bytes and return as int. If the UUID is not the default type, then we can't parse the timestamp out and null is returned.

Returns:

Millisecond UTC timestamp from generation of the UUID, or null for unrecognized format.

getMacFragment

public byte[] getMacFragment()

Extract MAC address fragment from raw UUID bytes, setting missing values to 0, thus the first 2 and a half bytes will be 0, followed by 3 and a half bytes of the active MAC address when the UUID was generated.

Returns:

Byte array of UUID fragment, or null for unrecognized format.

equals

public boolean equals(Object o)

Basic implementation of equals that checks if the given object is null or a different type, then compares the byte arrays which store the content of the UUID. I've considered making this compatible with the content of java.util.UUID, but not sure thats a good idea given that those are objects of a different type, and doing a deep comparison might be surprising functionality.

Overrides:

equals in class Object

Parameters:

o - Object against which we compare this UUID.

Returns:

True or false if this UUID's content is identical to the given UUID.

hashCode

public int hashCode()

The hash code implementation just calls Arrays.hashCode() on the contents of this UUID (stored as a byte array).

Overrides:

hashCode in class Object

Returns:

The hash value of this object.