org.safehaus.uuid
Class UUIDGenerator

java.lang.Object
  org.safehaus.uuid.UUIDGenerator

public final class UUIDGenerator
extends java.lang.Object

UUIDGenerator is the class that contains factory methods for generating UUIDs using one of the three specified 'standard' UUID generation methods: (see draft-leach-uuids-guids-01.txt for details)

• Time-based generation generates UUID using spatial and temporal uniqueness. Spatial uniqueness is derived from ethernet address (MAC, 802.1); temporal from system clock. See the details from the explanation of generateTimeBasedUUID() function.
• Name-based method uses MD5 hash (or, optionally any user-specified digest method) of the string formed from a name space and name.
• Random method uses Java2 API's SecureRandom to produce cryptographically secure UUIDs.
• Tag URI - method uses a variation of name-based method; instead of using a name space UUID and name, a hash (MD5 by default) is calculated from URI-tag-prefix, 2 obligatory strings (URL, path) and one optional string (current date). The resulting UUID is still considered to be 'name-based UUID' as the specification does not have additional UUID type ids available. Note that this is a non-standard method and not strictly UUID-'standard' compliant.

Some comments about performance:

• For non-performance critical generation, all methods with default arguments (default random number generator, default hash algorithm) should do just fine.
• When optimizing performance, it's better to use explicit random number generator and/or hash algorithm; this way global instance sharing need not be synchronized
• Which of the 3 methods is fastest? It depends, and the best way is to just measure performance, discarding the first UUID generated with the methods. With time-based method, main overhead comes from synchronization, with name-based (MD5-)hashing, and with random-based the speed of random-number generator. Additionally, all methods may incur some overhead when using the shared global random nunber generator or hash algorithm.
• When generating the first UUID with random-/time-based methods, there may be noticeable delay, as the random number generator is initialized. This can be avoided by either pre-initialising the random number generator passed (with random-based method), or by generating a dummy UUID on a separate thread, when starting a program needs to generate UUIDs at a later point.

Method Summary

UUID	generateNameBasedUUID(UUID nameSpaceUUID, java.lang.String name) Method similar to the previous one; the difference being that a shared MD5 digest instance will be used.
UUID	generateNameBasedUUID(UUID nameSpaceUUID, java.lang.String name, java.security.MessageDigest digest) Method for generating name-based UUIDs, using the standard name-based generation method described in the UUID specs, and the caller supplied hashing method.
UUID	generateRandomBasedUUID() Method for generating (pseudo-)random based UUIDs, using the default (shared) SecureRandom object.
UUID	generateRandomBasedUUID(java.util.Random randomGenerator) Method for generating (pseudo-)random based UUIDs, using the specified SecureRandom object.
UUID	generateTagURIBasedUUID(TagURI name) Method for generating UUIDs using tag URIs.
UUID	generateTagURIBasedUUID(TagURI name, java.security.MessageDigest hasher) Method for generating UUIDs using tag URIs.
UUID	generateTimeBasedUUID() Method for generating time based UUIDs.
UUID	generateTimeBasedUUID(EthernetAddress addr) Method for generating time based UUIDs.
EthernetAddress	getDummyAddress() Method that returns a randomly generated dummy ethernet address.
java.security.MessageDigest	getHashAlgorithm()
static UUIDGenerator	getInstance() Method used for accessing the singleton generator instance.
java.util.Random	getRandomNumberGenerator() Method for getting the shared random number generator used for generating the UUIDs.
static void	main(java.lang.String[] args) A simple test harness is added to make (automated) testing of the class easier.
void	setRandomNumberGenerator(java.util.Random r) Method that can be called to specify alternative random number generator to use.
void	synchronizeExternally(TimestampSynchronizer sync) Method that can (and should) be called once right after getting the instance, to ensure that system time stamp values used are valid (with respect to values used earlier by JUG instances), and to use file-lock based synchronization mechanism to prevent multiple JVMs from running conflicting instances of JUG (first one to be started wins on contention).

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static UUIDGenerator getInstance()

Method used for accessing the singleton generator instance.

synchronizeExternally

public void synchronizeExternally(TimestampSynchronizer sync)
                           throws java.io.IOException

Method that can (and should) be called once right after getting the instance, to ensure that system time stamp values used are valid (with respect to values used earlier by JUG instances), and to use file-lock based synchronization mechanism to prevent multiple JVMs from running conflicting instances of JUG (first one to be started wins on contention). It can also be called to stop synchronization by calling it with argument null, although such usage is strongly discouraged (ie. it's a good idea to either never use synchronization, or always; but not to mix modes).

Caller needs to instantiate an instance of TimestampSynchronizer; currently the only standard implementation is FileBasedTimestampSynchronizer (which is JDK 1.4+).

Note: since the generator instance is a singleton, calling this method will always cause all generation to be synchronized using the specified method.

Parameters:

sync - Synchronizer instance to use for synchronization.

Throws:

java.io.IOException

getDummyAddress

public EthernetAddress getDummyAddress()

Method that returns a randomly generated dummy ethernet address. To prevent collision with real addresses, the returned address has the broadcast bit set, ie. it doesn't represent address of any existing NIC. Note that this dummy address will be shared for the lifetime of this UUIDGenerator, ie. only one is ever generated independent of how many times this methods is called.

Returns:

Randomly generated dummy ethernet broadcast address.

getRandomNumberGenerator

public java.util.Random getRandomNumberGenerator()

Method for getting the shared random number generator used for generating the UUIDs. This way the initialization cost is only taken once; access need not be synchronized (or in cases where it has to, SecureRandom takes care of it); it might even be good for getting really 'random' stuff to get shared access...

setRandomNumberGenerator

public void setRandomNumberGenerator(java.util.Random r)

Method that can be called to specify alternative random number generator to use. This is usually done to use implementation that is faster than SecureRandom that is used by default.

Note that to avoid first-time initialization penalty of using SecureRandom, this method has to be called before generating the first random-number based UUID.

getHashAlgorithm

public java.security.MessageDigest getHashAlgorithm()

generateRandomBasedUUID

public UUID generateRandomBasedUUID()

Method for generating (pseudo-)random based UUIDs, using the default (shared) SecureRandom object. Note that the first time SecureRandom object is used, there is noticeable delay between calling the method and getting the reply. This is because SecureRandom has to initialize itself to reasonably random state. Thus, if you want to lessen delay, it may be be a good idea to either get the first random UUID asynchronously from a separate thread, or to use the other generateRandomBasedUUID passing a previously initialized SecureRandom instance.

Returns:

UUID generated using (pseudo-)random based method

generateRandomBasedUUID

public UUID generateRandomBasedUUID(java.util.Random randomGenerator)

Method for generating (pseudo-)random based UUIDs, using the specified SecureRandom object. To prevent/avoid delay JDK's default SecureRandom object causes when first random number is generated, it may be a good idea to initialize the SecureRandom instance (on a separate thread for example) when app starts.

Parameters:

randomGenerator - Random number generator to use for getting the random number from which UUID will be composed.

Returns:

UUID generated using (pseudo-)random based method

generateTimeBasedUUID

public UUID generateTimeBasedUUID()

Method for generating time based UUIDs. Note that this version doesn't use any existing Hardware address (because none is available for some reason); instead it uses randomly generated dummy broadcast address.

Note that since the dummy address is only to be created once and shared from there on, there is some synchronization overhead.

Returns:

UUID generated using time based method

generateTimeBasedUUID

public UUID generateTimeBasedUUID(EthernetAddress addr)

Method for generating time based UUIDs.

Parameters:

addr - Hardware address (802.1) to use for generating spatially unique part of UUID. If system has more than one NIC, any address is usable. If no NIC is available (or its address not accessible; often the case with java apps), a randomly generated broadcast address is acceptable. If so, use the alternative method that takes no arguments.

Returns:

UUID generated using time based method

generateNameBasedUUID

public UUID generateNameBasedUUID(UUID nameSpaceUUID,
                                  java.lang.String name,
                                  java.security.MessageDigest digest)

Method for generating name-based UUIDs, using the standard name-based generation method described in the UUID specs, and the caller supplied hashing method. Note that this method is not synchronized, so caller has to make sure the digest object will not be accessed from other threads. Note that if you call this method directly (instead of calling the version with one less argument), you have to make sure that access to 'hash' is synchronized; either by only generating UUIDs from one single thread, or by using explicit sync'ing.

Parameters:

nameSpaceUUID - UUID of the namespace, as defined by the spec. UUID has 4 pre-defined "standard" name space strings that can be passed to UUID constructor (see example below). Note that this argument is optional; if no namespace is needed (for example when name includes namespace prefix), null may be passed.

name - Name to base the UUID on; for example, IP-name ("www.w3c.org") of the system for UUID.NAMESPACE_DNS, URL ("http://www.w3c.org/index.html") for UUID.NAMESPACE_URL and so on.

digest - Instance of MessageDigest to use for hashing the name value. hash.reset() will be called before calculating the has value, to make sure digest state is not random and UUID will not be randomised.

Returns:

UUID generated using name-based method based on the arguments given. Example: UUID uuid = gen.generateNameBasedUUID( new UUID(UUID.NAMESPACE_DNS, "www.w3c.org"));

generateNameBasedUUID

public UUID generateNameBasedUUID(UUID nameSpaceUUID,
                                  java.lang.String name)

Method similar to the previous one; the difference being that a shared MD5 digest instance will be used. This also means that there is some synchronization overhead as MD5-instances are not thread-safe per se.

generateTagURIBasedUUID

public UUID generateTagURIBasedUUID(TagURI name)

Method for generating UUIDs using tag URIs. A hash is calculated from the given tag URI (default being MD5 hash). The resulting UUIDs are reproducible, ie. given the same tag URI, same UUID will always result, much like with the default name-based generation method. Note that this a non-standard way of generating UUIDs; it will create UUIDs that appear to be name-based (and which are, but not using the method specified in UUID specs).

Parameters:

name - tag URI to base UUID on.

generateTagURIBasedUUID

public UUID generateTagURIBasedUUID(TagURI name,
                                    java.security.MessageDigest hasher)

Method for generating UUIDs using tag URIs. A hash is calculated from the given tag URI using the specified hashing algorith,. The resulting UUIDs are reproducible, ie. given the same tag URI and hash algorithm, same UUID will always result, much like with the default name-based generation method. Note that this a non-standard way of generating UUIDs; it will create UUIDs that appear to be name-based (and which are, but not using the method specified in UUID specs).

Parameters:

name - tag URI to base UUID on.

hasher - Hashing algorithm to use. Note that the caller has to make sure that it's thread-safe to use 'hasher', either by never calling this method from multiple threads, or by explicitly sync'ing the calls.

main

public static void main(java.lang.String[] args)

A simple test harness is added to make (automated) testing of the class easier. For real testing, JUnit based unit tests should be run.