org.doomdark.uuid
Class UUIDGenerator

java.lang.Object
  extended by org.doomdark.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)

Some comments about performance:


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.security.SecureRandom 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.security.SecureRandom 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.
 
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.


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.security.SecureRandom 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...


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.security.SecureRandom 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 - SecureRandom 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.

Parameters:
hwAddress - 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

generateTimeBasedUUID

public UUID generateTimeBasedUUID(EthernetAddress addr)
Method for generating time based UUIDs.

Parameters:
hwAddress - 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.
hash - 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.



Copyright © 2003 MBARI.

The Monterey Bay Aquarium Research Institute (MBARI) provides this documentation and code "as is", with no warranty, express or implied, of its quality or consistency. It is provided without support and without obligation on the part of MBARI to assist in its use, correction, modification, or enhancement.