Class AUIDGenerator.AUID
java.lang.Object
org.datanucleus.store.valuegenerator.AUIDGenerator.AUID
- All Implemented Interfaces:
Comparable
- Enclosing class:
AUIDGenerator
An almost unique ID.
This class represents a best possible derivate of a DCE UUID as is possible
with the standard Java API, which provides no way to determine the IEEE 802
address of a system and only provides a time with a granularity of
milliseconds instead of the required 100nanoseconds.
It therefore uses random node values and also does not use non-volatile
storage for internal state fields.
The uuid is internally stored as two 64 bit long values. This allows a fast
implementation of the
equals
method, but provides possibly
poor performance for the compare
method due to the required
unpacking of the data.
To create "real" UUIDs the default implementations of loadState
and saveState
have to be overridden to provide hardware
derived node values and non-volatile generator state storage. The first is
not possible with Java's standard API and there is no standard way to do the
latter, therefore this class was called AUID = "almost unique id", as it
tries to circumvent these short comings by random initializations.
Note: Due to the construction of the time stamp included in an AUID as a
60-bit value of 100-nanosecond intervals since 00:00:00.00, 15 October 1582
(the date of Gregorian reform to the Christian Calendar), this implementation
will break due to field overflow on 23:21:00 CEST of March 31st in the year
5236, that is when we are long gone and became ashes.-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static class
This class represents the current state of the AUID generator. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static AUIDGenerator.AUID.State
The state of the AUID generator.private static final int
private static final int
private static final int
private static final int
private long
The first 64 bits of the uuid value.private static final char[]
An array of chars for Hex conversion.private static final long
private long
The last 64 bits of the uuid value.private static final long
Scale from System.currentTimeMillis() granularity to that of AUID.private static final long
The offset between UTC and the AUID timestamps in 100-nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian Calendar).private static final int
private static final int
private static final int
private static final int
private static final int
-
Constructor Summary
ConstructorsModifierConstructorDescriptionAUID()
Constructs an AUID with new values.AUID
(byte[] bytes) Constructs an AUID from the specified byte array representation, which is in the same format as returned bygetBytes(dst, dstBegin)
.AUID
(byte[] bytes, int offset) Constructs an AUID from the specified byte array representation, which is in the same format as returned bygetBytes(dst, dstBegin)
.protected
AUID
(int securityAttributes) Constructs an AUID with new values and the specified security attributes.protected
AUID
(long time, int version, int clockSeq, int variant, long node) Constructs an AUID from the specified values.protected
AUID
(long timeLow, long timeMid, long timeHiAndVersion, int clockSeqHiAndVariant, int clockSeqLow, long node) Constructs an AUID from the specified original DCE field values.AUID
(CharSequence auid) Constructs an AUID from the specified string representation in CharSequence.Constructs an AUID from the specified string representation.protected
AUID
(AUIDGenerator.AUID auid) Constructs an AUID with the same values as the specified AUID. -
Method Summary
Modifier and TypeMethodDescriptionint
private static long
entropicSeed
(int bits, long initialSeed) boolean
final byte[]
getBytes()
Conveniance method just returnsgetBytes(null, 0)
.byte[]
getBytes
(byte[] dst, int dstBegin) Returns the AUID value as byte array.protected byte[]
getBytes
(byte[] dst, int dstBegin, boolean bigendian) This is the implementation ofgetBytes(dst, dstBegin)
, however, the endianess can be specified through the boolean argument.final int
Returns clock sequence.final int
Returns clock sequence and variant octets 8-9 (unsigned) short in a signed int.final int
Returns clock sequence high and variant octet 8 (unsigned) small in a signed int.final int
Returns clock sequence low octet 9 (unsigned) small in a signed int.int
getClockSeqMaskForVariant
(int variant) This returns the bit mask to be applied to a clock sequence before it is ORed with the variant value.protected long
Returns the current time as 100-nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian Calendar).final Date
getDate()
Returns the time of the AUID as Date.final long
getNanos()
Returns the nanoseconds truncated from the time of the AUID bygetDate
.final long
getNode()
Returns node value octets 10-15 (unsigned) 48-bit in a signed long.protected static final long
getOctets
(int octets, byte[] bytes, int begin, boolean bigendian) Gets a value from the specified byte array starting at begin with the specified number of octets and endianess.final long
getTime()
Returns octets 0-7 time only.final long
Returns time high octets 6-7 (unsigned) int in a signed long.final long
Returns octets 6-7 (unsigned) int in a signed long.final long
Returns time low octets 0-3 (unsigned) int in a signed long.final long
Returns time mid octets 4-5 (unsigned) int in a signed long.final int
Returns the variant.final int
Returns octets 6-7 version only.int
hashCode()
protected int
identifyVariant
(int clockSeqAndVariant) Identifies the variant from the combined clock sequence and variant value, as it is returned bygetClockSeqAndVariant()
.protected AUIDGenerator.AUID.State
Loads the generator state from non-volatile storage into the provided State object or creates a new one ifnull
.private void
makeUnique
(int securityAttributes, boolean hasSecurityAttributes) Contains the algorithm to create an AUID.private void
packDCEFieldsFirstHalf
(long timeLow, long timeMid, long timeHiAndVersion) Packs the original DCE fields time low, mid and hiAndVersion into the first 64 bits (octets 0-7).private void
packDCEFieldsSecondHalf
(int clockSeqHiAndVariant, int clockSeqLow, long node) Packs the original DCE fields clockSeqHiAndVariant, clockSeqLow and node into the second 64 bits (octets 8-15).private void
packFirstHalf
(long time, int version) Packs time and version into the first 64 bits (octets 0-7).private void
packSecondHalf
(int clockSeq, int variant, long node) Packs clock sequence, variant and node into the second 64 bits (octets 8-15).static AUIDGenerator.AUID
parse
(CharSequence auid) Parse a String representation of an AUID.static AUIDGenerator.AUID
Parse a String representation of an AUID.private long
parseFirstHalf
(CharSequence charSequence) Parses the character sequencecs
from begin to end as the first 18 charcters of a string representation of an AUID.private long
parseHex
(CharSequence cs) Parses the character sequencecs
from begin to end as hex string.private void
parseHyphen
(char c) Tests wetherc
is a hyphen '-' character.private long
parseNibble
(char c) Converts a hex character into the corresponding nibble value.private long
parseSecondHalf
(CharSequence charSequence) Parses the character sequencecs
from begin to end as the second 18 charcters of a string representation of an AUID.protected static final void
putOctets
(long value, int octets, byte[] dst, int dstBegin, boolean bigendian) Puts the specified value into the byte array in the specified endianess.protected void
Can be overridden together withloadState
to provide persistent storage for the auid generator state.private void
toHex
(StringBuilder result, long value, int nibbles) Convertsnibbles
least significant nibbles ofvalue
into a hex representation and appends it toresult
.toString()
Appends the String representation of this AUID to the specified StringBuilder or if null to a new created StringBuilder and returns the StringBuilder.
-
Field Details
-
VERSION_RANDOM_NODE
private static final int VERSION_RANDOM_NODE- See Also:
-
VARIANT_NCS
private static final int VARIANT_NCS- See Also:
-
VARIANT_DCE
private static final int VARIANT_DCE- See Also:
-
VARIANT_MICROSOFT
private static final int VARIANT_MICROSOFT- See Also:
-
VARIANT_RESERVED
private static final int VARIANT_RESERVED- See Also:
-
CS_MASK_NCS
private static final int CS_MASK_NCS- See Also:
-
CS_MASK_DCE
private static final int CS_MASK_DCE- See Also:
-
CS_MASK_MICROSOFT
private static final int CS_MASK_MICROSOFT- See Also:
-
CS_MASK_RESERVED
private static final int CS_MASK_RESERVED- See Also:
-
MAXIMUM_ENTROPIC_TIME_MS
private static final long MAXIMUM_ENTROPIC_TIME_MS- See Also:
-
TIME_SCALE
private static final long TIME_SCALEScale from System.currentTimeMillis() granularity to that of AUID.- See Also:
-
UTC_OFFSET
private static final long UTC_OFFSETThe offset between UTC and the AUID timestamps in 100-nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian Calendar). -
HEX_CHARS
private static final char[] HEX_CHARSAn array of chars for Hex conversion. -
auidState
The state of the AUID generator. -
firstHalf
private long firstHalfThe first 64 bits of the uuid value. -
secondHalf
private long secondHalfThe last 64 bits of the uuid value.
-
-
Constructor Details
-
AUID
public AUID()Constructs an AUID with new values. -
AUID
protected AUID(int securityAttributes) Constructs an AUID with new values and the specified security attributes. The subclass which calls this constructor MUST set the state accordingly.- Parameters:
securityAttributes
- the security attributes to include in the new AUID.
-
AUID
protected AUID(long time, int version, int clockSeq, int variant, long node) Constructs an AUID from the specified values. This constructor is for subclasses only and should not be made available to API users.- Parameters:
time
- the time field of the new AUIDversion
- the version of the new AUIDclockSeq
- the clock sequence of the new AUIDvariant
- the variant of the new AUIDnode
- the node of the new AUID
-
AUID
protected AUID(long timeLow, long timeMid, long timeHiAndVersion, int clockSeqHiAndVariant, int clockSeqLow, long node) Constructs an AUID from the specified original DCE field values. This constructor is for subclasses only and should not be made available to API users.- Parameters:
timeLow
- the time low field of the new AUIDtimeMid
- the time mid field of the new AUIDtimeHiAndVersion
- the packed time high and version field of the new AUIDclockSeqHiAndVariant
- the packed clock sequence high and variant field of the new AUIDclockSeqLow
- the clock sequence low field of the new AUIDnode
- the node field of the new AUID
-
AUID
Constructs an AUID with the same values as the specified AUID.- Parameters:
auid
- the AUID to clone
-
AUID
Constructs an AUID from the specified string representation.- Parameters:
auid
- string in the format "LLLLLLLL-MMMM-HHHH-CCCC-NNNNNNNNNNNN"- Throws:
NumberFormatException
- ifauid
does not match the pattern "LLLLLLLL-MMMM-HHHH-CCCC-NNNNNNNNNNNN" where 'L', 'M', 'H', 'C' and 'N' are time low, mid, high, clock sequence and node fields respectively. a string representation of an AUID
-
AUID
Constructs an AUID from the specified string representation in CharSequence.- Parameters:
auid
- a string representation of an AUID- Throws:
NumberFormatException
- ifauid
does not match the pattern "LLLLLLLL-MMMM-HHHH-CCCC-NNNNNNNNNNNN" where 'L', 'M', 'H', 'C' and 'N' are time low, mid, high, clock sequence and node fields respectively.
-
AUID
public AUID(byte[] bytes) Constructs an AUID from the specified byte array representation, which is in the same format as returned bygetBytes(dst, dstBegin)
. This constructor is equal toAUID(bytes, 0)
.- Parameters:
bytes
- a byte array representation of an AUID
-
AUID
public AUID(byte[] bytes, int offset) Constructs an AUID from the specified byte array representation, which is in the same format as returned bygetBytes(dst, dstBegin)
.- Parameters:
bytes
- a byte array representation of an AUIDoffset
- the offset at which the byte array representation is located in the byte array.
-
-
Method Details
-
parse
Parse a String representation of an AUID. Equal tonew AUID(auid)
.- Parameters:
auid
- a string representation of an AUID- Returns:
- the AUID represented by
auid
. - Throws:
NumberFormatException
- ifauid
does not match the pattern "LLLLLLLL-MMMM-HHHH-CCCC-NNNNNNNNNNNN" where 'L', 'M', 'H', 'C' and 'N' are time low, mid, high, clock sequence and node fields respectively.
-
parse
Parse a String representation of an AUID. Equal tonew AUID(auid)
.- Parameters:
auid
- string in the format "LLLLLLLL-MMMM-HHHH-CCCC-NNNNNNNNNNNN"- Returns:
- the AUID represented by
auid
. - Throws:
NumberFormatException
- ifauid
does not match the pattern "LLLLLLLL-MMMM-HHHH-CCCC-NNNNNNNNNNNN" where 'L', 'M', 'H', 'C' and 'N' are time low, mid, high, clock sequence and node fields respectively. a string representation of an AUID
-
identifyVariant
protected int identifyVariant(int clockSeqAndVariant) Identifies the variant from the combined clock sequence and variant value, as it is returned bygetClockSeqAndVariant()
. May be overridden to support new variants.- Parameters:
clockSeqAndVariant
- the combined clock sequence and variant value, as it is returned bygetClockSeqAndVariant()
.- Returns:
- the variant identified in the specified combined value.
- Throws:
IllegalArgumentException
- if variant could not be identified.
-
getClockSeqMaskForVariant
public int getClockSeqMaskForVariant(int variant) This returns the bit mask to be applied to a clock sequence before it is ORed with the variant value. May be overridden to support new variants.- Parameters:
variant
- the variant for which the mask shall be returned.- Returns:
- the mask to apply to a sequence when combining values.
-
getCurrentTime
protected long getCurrentTime()Returns the current time as 100-nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian Calendar). This may be overridden to support high resolution time devices.- Returns:
- a time stamp for use in an AUID
-
loadState
Loads the generator state from non-volatile storage into the provided State object or creates a new one ifnull
. Overriding this method allows to actually add persistent storage facilities for the generator state and may also support non-random node that have been retrieved from the hardware.
To override this method follow this pattern:protected State loadState(State state) { State loadInto = state; if (loadInto == null) { if (staticStateField == null) { loadInto = staticStateField = new State(); } state = staticStateField; } if (loadInto != null) { if (loadInto.random == null) { // set loadInto.random to a customized Random generator if possible // YOUR CODE TO SET RANDOM GENERATOR GOES HERE (OPTIONAL) } // call super implementation to initialize with defaults. super(loadInto); // load state into loadInto (consider to use getClass() to distinguish // between multiple stored versions). // always load lastTime and adjustTime // load clock sequence only if node value is retrieved from hardware that // cannot be moved to another system and is guaranteed to be unique between // different systems // Do not modify the above values if loading failed (for example due to // I/O failure). // YOUR CODE TO LOAD CLOCK RELATED VALUES GOES HERE (REQUIRED) // Set node, version, variant and security attribute inclusion as required. // YOUR CODE TO SET NODE, VERSION, VARIANT VALUES GOES HERE (RECOMMENDED) } return state; }
- Parameters:
state
- the State object into which the state has to be loaded.- Returns:
- an initialized State object
-
saveState
Can be overridden together withloadState
to provide persistent storage for the auid generator state. The default implementation does nothing.- Parameters:
state
- the State object to persist.
-
getBytes
protected byte[] getBytes(byte[] dst, int dstBegin, boolean bigendian) This is the implementation ofgetBytes(dst, dstBegin)
, however, the endianess can be specified through the boolean argument. Subclasses can use this to provide little endian byte array representations. If this is done, there should also be a constructor using this byte array order. If this method is overridden to provide a different field order, the new field order will also be used by thegetBytes(dst, dstBegin)
method.- Parameters:
dst
- the destination byte array, ifnull
a new array will be createddstBegin
- the offset to use when writing into the destination byte array, ignored if dst is nullbigendian
- iftrue
big endian byte order is used- Returns:
- a byte array
-
getBytes
public byte[] getBytes(byte[] dst, int dstBegin) Returns the AUID value as byte array. The array will be filled with the original DCE fields in big endian order, that is each field starts with the most significant byte:+---------------------------+---------+---+---+-------+-------+ ! FIELD DESCRIPTION ! OCTETS ! LENGTH in bits ! +---------------------------+---------+---------------+-------+ ! time low ! 0 - 3 ! 32 ! +---------------------------+---------+-------+-------+ ! time mid ! 4 - 5 ! 16 ! +---------------------------+---------+-------+ ! time hi and version ! 6 - 7 ! 16 ! +---------------------------+---------+---+---+ ! clock seq hi and reserved ! 8 ! 8 ! +---------------------------+---------+---+ ! clock seq low ! 9 ! 8 ! +---------------------------+---------+---+-------------------+ ! node ! 10 - 15 ! 48 ! +---------------------------+---------+-----------------------+
This implementation just returnsgetBytes(dst, dstBegin, true)
.- Parameters:
dst
- the destination byte array, ifnull
a new array will be createddstBegin
- the offset to use when writing into the destination byte array, ignored if dst is null- Returns:
- a byte array
-
toStringBuilder
Appends the String representation of this AUID to the specified StringBuilder or if null to a new created StringBuilder and returns the StringBuilder. This method is called bytoString
, therefore it is sufficient to override this method together with providing new parse methods to create a new string representation of an AUID.- Parameters:
sb
- the StringBuilder to use- Returns:
- a StringBuilder to which this AUID has been appended
-
packFirstHalf
private void packFirstHalf(long time, int version) Packs time and version into the first 64 bits (octets 0-7). -
packDCEFieldsFirstHalf
private void packDCEFieldsFirstHalf(long timeLow, long timeMid, long timeHiAndVersion) Packs the original DCE fields time low, mid and hiAndVersion into the first 64 bits (octets 0-7). -
packSecondHalf
private void packSecondHalf(int clockSeq, int variant, long node) Packs clock sequence, variant and node into the second 64 bits (octets 8-15). -
packDCEFieldsSecondHalf
private void packDCEFieldsSecondHalf(int clockSeqHiAndVariant, int clockSeqLow, long node) Packs the original DCE fields clockSeqHiAndVariant, clockSeqLow and node into the second 64 bits (octets 8-15). -
makeUnique
private void makeUnique(int securityAttributes, boolean hasSecurityAttributes) Contains the algorithm to create an AUID. -
toHex
Convertsnibbles
least significant nibbles ofvalue
into a hex representation and appends it toresult
. -
parseNibble
private long parseNibble(char c) Converts a hex character into the corresponding nibble value.- Returns:
- the nibble value.
- Throws:
NumberFormatException
- ifc
is not a valid hex character.
-
parseHyphen
private void parseHyphen(char c) Tests wetherc
is a hyphen '-' character.- Throws:
NumberFormatException
- ifc
is not a hyphen '-' character.
-
parseHex
Parses the character sequencecs
from begin to end as hex string.- Throws:
NumberFormatException
- ifcs
contains non-hex characters.
-
parseFirstHalf
Parses the character sequencecs
from begin to end as the first 18 charcters of a string representation of an AUID.- Returns:
- the first 64 bits represented by
cs
. - Throws:
NumberFormatException
- ifcs
does no match the pattern "LLLLLLLL-MMMM-HHHH" where 'L', 'M', 'H' are time low, mid and high fields respectively.
-
parseSecondHalf
Parses the character sequencecs
from begin to end as the second 18 charcters of a string representation of an AUID.- Returns:
- the second 64 bits represented by
cs
. - Throws:
NumberFormatException
- ifcs
does no match the pattern "-CCCC-NNNNNNNNNNNN" where 'C', 'N' are clock sequence and node fields respectively.
-
getOctets
protected static final long getOctets(int octets, byte[] bytes, int begin, boolean bigendian) Gets a value from the specified byte array starting at begin with the specified number of octets and endianess.- Parameters:
octets
- the number of octetsbytes
- the array to get the value frombegin
- the offset to use when writing into the destination byte array, ignored if dst is nullbigendian
- iftrue
big endian byte order is used- Returns:
- the octet
-
putOctets
protected static final void putOctets(long value, int octets, byte[] dst, int dstBegin, boolean bigendian) Puts the specified value into the byte array in the specified endianess.- Parameters:
value
- the valueoctets
- the number of octetsdst
- the destination arraydstBegin
- the offset to use when writing into the destination byte array, ignored if dst is nullbigendian
- iftrue
big endian byte order is used
-
getTimeLow
public final long getTimeLow()Returns time low octets 0-3 (unsigned) int in a signed long.- Returns:
- the time low field (original DCE field).
-
getTimeMid
public final long getTimeMid()Returns time mid octets 4-5 (unsigned) int in a signed long.- Returns:
- the time mid field (original DCE field).
-
getTimeHigh
public final long getTimeHigh()Returns time high octets 6-7 (unsigned) int in a signed long.- Returns:
- the time high field with version masked out.
-
getTimeHighAndVersion
public final long getTimeHighAndVersion()Returns octets 6-7 (unsigned) int in a signed long.- Returns:
- the time high and version field (original DCE field).
-
getTime
public final long getTime()Returns octets 0-7 time only.- Returns:
- the complete time value.
-
getDate
Returns the time of the AUID as Date. This is a narrowing conversion because Date only supports a granularity of milliseconds, while the time value represents 100 nanosecond intervals. UsegetNanos
to retrieve the truncated nanoseconds.- Returns:
- the complete time value as Date truncated to the next millisecond.
-
getNanos
public final long getNanos()Returns the nanoseconds truncated from the time of the AUID bygetDate
.- Returns:
- the nanoseconds truncated from the time of the AUID by
getDate
.
-
getVersion
public final int getVersion()Returns octets 6-7 version only.- Returns:
- the version field.
-
getClockSeqHighAndVariant
public final int getClockSeqHighAndVariant()Returns clock sequence high and variant octet 8 (unsigned) small in a signed int.- Returns:
- the clock seq hi and reserved (variant) field (original DCE field).
-
getClockSeqLow
public final int getClockSeqLow()Returns clock sequence low octet 9 (unsigned) small in a signed int.- Returns:
- the clock seq low field (original DCE field).
-
getClockSeqAndVariant
public final int getClockSeqAndVariant()Returns clock sequence and variant octets 8-9 (unsigned) short in a signed int.- Returns:
- the clock sequence and variant field.
-
getClockSeq
public final int getClockSeq()Returns clock sequence.- Returns:
- the clock sequence field.
-
getVariant
public final int getVariant()Returns the variant.- Returns:
- the variant field.
-
getNode
public final long getNode()Returns node value octets 10-15 (unsigned) 48-bit in a signed long.- Returns:
- the node field (original DCE field).
-
getBytes
public final byte[] getBytes()Conveniance method just returnsgetBytes(null, 0)
.- Returns:
getBytes(null, 0)
.
-
equals
-
hashCode
public int hashCode() -
toString
-
compareTo
- Specified by:
compareTo
in interfaceComparable
-
entropicSeed
private static long entropicSeed(int bits, long initialSeed)
-