org.apache.axiom.util

Class UIDGenerator

java.lang.Object

org.apache.axiom.util.UIDGenerator

public final class UIDGenerator
extends java.lang.Object

Contains utility methods to generate unique IDs of various kinds.

Depending on the requested type of ID, this class will either use UUID.randomUUID() or its own unique ID generator. This implementation generates unique IDs based on the assumption that the following triplet is unique:

1. The thread ID.
2. The timestamp in milliseconds when the first UID is requested by the thread.
3. A per thread sequence number that is incremented each time a UID is requested by the thread.

Considering that these three numbers are represented as long values, these assumptions are correct because:

• The probability that two different threads with the same ID exist in the same millisecond interval is negligibly small.
• One can expect that no thread will ever request more than 2^64 UIDs during its lifetime.

Before building an ID from this triplet, the implementation will XOR the three values with random values calculated once when the class is loaded. This transformation preserves the uniqueness of the calculated triplet and serves several purposes:

• It reduces the probability that the same ID is produces by two different systems, i.e. it increases global uniqueness.
• It adds entropy, i.e. it makes an individual ID appear as random. Indeed, without the XOR transformation, a hexadecimal representation of the triplet would in general contain several sequences of '0'.
• It prevents the implementation from leaking information about the system state.

Field Summary

Fields

Modifier and Type	Field and Description
private static long	seqXorOperand
private static long	startTimeXorOperand
private static long	threadIdXorOperand
private static java.lang.ThreadLocal	triplet Thread local that holds the triplet described in the Javadoc of this class.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	UIDGenerator()

Method Summary

Modifier and Type	Method and Description
static java.lang.String	generateContentId() Generates a unique ID suitable for usage as a MIME content ID.
private static void	generateHex(java.lang.StringBuilder buffer) Generate a unique ID as hex value and add it to the given buffer.
static java.lang.String	generateMimeBoundary() Generates a MIME boundary.
static java.lang.String	generateUID() Generate a general purpose unique ID.
static java.net.URI	generateURN() Generate a URN with uuid NID (namespace identifier).
static java.lang.String	generateURNString() Generate a URN with uuid NID (namespace identifier).
private static void	writeReverseLongHex(long value, java.lang.StringBuilder buffer)

Methods inherited from class java.lang.Object

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

Field Detail

startTimeXorOperand

private static final long startTimeXorOperand

threadIdXorOperand

private static final long threadIdXorOperand

seqXorOperand

private static final long seqXorOperand

triplet

private static final java.lang.ThreadLocal triplet

Thread local that holds the triplet described in the Javadoc of this class. Note that we use a simple array here (instead of our own class) to avoid class loader leaks (see AXIOM-354).

Constructor Detail

UIDGenerator

private UIDGenerator()

Method Detail

writeReverseLongHex

private static void writeReverseLongHex(long value,
                                        java.lang.StringBuilder buffer)

generateHex

private static void generateHex(java.lang.StringBuilder buffer)

Generate a unique ID as hex value and add it to the given buffer. Note that with respect to the triplet, the order of nibbles is reversed, i.e. the least significant nibble of the sequence is written first. This makes comparing two IDs for equality more efficient.

Parameters:

buffer -

generateContentId

public static java.lang.String generateContentId()

Generates a unique ID suitable for usage as a MIME content ID.

RFC2045 (MIME) specifies that the value of the Content-ID header must match the msg-id production, which is defined by RFC2822 as follows:

 msg-id        = [CFWS] "<" id-left "@" id-right ">" [CFWS]
 id-left       = dot-atom-text / no-fold-quote / obs-id-left
 id-right      = dot-atom-text / no-fold-literal / obs-id-right
 dot-atom-text = 1*atext *("." 1*atext)
 atext         = ALPHA / DIGIT / "!" / "#" / "$" / "%" / "&"
                   / "'" / "*" / "+" / "-" / "/" / "=" / "?"
                   / "^" / "_" / "`" / "{" / "|" / "}" / "~"

In addition, RFC2392 specifies that when used in an URL with scheme "cid:", the content ID must be URL encoded. Since not all implementations handle this correctly, any characters considered "unsafe" in an URL (and requiring encoding) should be avoided in a content ID.

This method generates content IDs that satisfy these requirements. It guarantees a high level of uniqueness, but makes no provisions to guarantee randomness. The implementation is thread safe, but doesn't use synchronization.

Returns:

The generated content ID. Note that this value does not include the angle brackets of the msg-id production, but only represents the bare content ID.

generateMimeBoundary

public static java.lang.String generateMimeBoundary()

Generates a MIME boundary.

Valid MIME boundaries are defined by the following production in RFC2046:

 boundary      := 0*69<bchars> bcharsnospace
 bchars        := bcharsnospace / " "
 bcharsnospace := DIGIT / ALPHA / "'" / "(" / ")" /
                  "+" / "_" / "," / "-" / "." /
                  "/" / ":" / "=" / "?"

It should be noted that the boundary in general will also appear as a parameter in the content type of the MIME package. According to RFC2045 (which defines the Content-Type header), it will require quoting if it contains characters from the following production:

 tspecials := "(" / ")" / "<" / ">" / "@" /
              "," / ";" / ":" / "\" / <"> /
              "/" / "[" / "]" / "?" / "="

This method produces a boundary that doesn't contain any of these characters and therefore doesn't need to be quoted. To avoid accidental collisions, the returned value is unique and doesn't overlap with any other type of unique ID returned by methods in this class. The implementation is thread safe, but doesn't use synchronization.

Returns:

the generated MIME boundary

generateUID

public static java.lang.String generateUID()

Generate a general purpose unique ID. The returned value is the hexadecimal representation of a 192 bit value, i.e. it is 48 characters long. The implementation guarantees a high level of uniqueness, but makes no provisions to guarantee randomness. It is thread safe, but doesn't use synchronization.

The fact that this method doesn't guarantee randomness implies that the generated IDs are predictable and must not be used in contexts where this would cause a security vulnerability. In particular, this method should not be used to generate the following kind of IDs:

• Session IDs.
• Message IDs used in WS-Addressing.

Returns:

the generated unique ID

generateURNString

public static java.lang.String generateURNString()

Generate a URN with uuid NID (namespace identifier). These URNs have the following form: urn:uuid:dae6fae1-93df-4824-bc70-884c9edb5973. The UUID is generated using a cryptographically strong pseudo random number generator.

Returns:

the generated URN

generateURN

public static java.net.URI generateURN()

Generate a URN with uuid NID (namespace identifier). This method does the same as generateURNString(), but returns a URI object.

Returns:

the generated URN