org.safehaus.uuid
Class UUIDGenerator
java.lang.Object
org.safehaus.uuid.UUIDGenerator
public final class UUIDGenerator
- extends 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,
String name)
Method similar to the previous one; the difference being that a
shared MD5 digest instance will be used. |
UUID |
generateNameBasedUUID(UUID nameSpaceUUID,
String name,
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(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,
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. |
MessageDigest |
getHashAlgorithm()
|
static UUIDGenerator |
getInstance()
Method used for accessing the singleton generator instance. |
Random |
getRandomNumberGenerator()
Method for getting the shared random number generator used for
generating the UUIDs. |
static void |
main(String[] args)
A simple test harness is added to make (automated) testing of the
class easier. |
void |
setRandomNumberGenerator(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 |
getInstance
public static UUIDGenerator getInstance()
- Method used for accessing the singleton generator instance.
synchronizeExternally
public void synchronizeExternally(TimestampSynchronizer sync)
throws 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:
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 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(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 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(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,
String name,
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,
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,
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(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.