| java.lang.Object org.jpox.store.poid.AUID
AUID | class AUID implements Comparable(Code) | | 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.
version: $Revision: 1.4 $ |
Inner Class :protected static class State | |
Constructor Summary | |
public | AUID() Constructs an AUID with new values. | 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. | protected | AUID(AUID auid) Constructs an AUID with the same values as the specified AUID. | public | AUID(String auid) Constructs an AUID from the specified string representation. | public | AUID(CharSequence auid) Constructs an AUID from the specified string representation in
CharSequence. | public | AUID(byte[] bytes) Constructs an AUID from the specified byte array representation, which is
in the same format as returned by getBytes(dst, dstBegin) . | public | AUID(byte[] bytes, int offset) Constructs an AUID from the specified byte array representation, which is
in the same format as returned by getBytes(dst, dstBegin) . |
Method Summary | |
public int | compareTo(Object o) | public boolean | equals(Object obj) | protected byte[] | getBytes(byte[] dst, int dstBegin, boolean bigendian) This is the implementation of getBytes(dst, dstBegin) ,
however, the endianess can be specified through the boolean argument.
Subclasses can use this to provide little endian byte array
representations. | public byte[] | getBytes(byte[] dst, int dstBegin) Returns the AUID value as byte array. | final public byte[] | getBytes() Conveniance method just returns getBytes(null, 0) . | final public int | getClockSeq() Returns clock sequence. | final public int | getClockSeqAndVariant() Returns clock sequence and variant octets 8-9 (unsigned) short in a
signed int. | final public int | getClockSeqHighAndVariant() Returns clock sequence high and variant octet 8 (unsigned) small in a
signed int. | final public int | getClockSeqLow() Returns clock sequence low octet 9 (unsigned) small in a signed int. | 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. | 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). | final public Date | getDate() Returns the time of the AUID as Date. | final public long | getNanos() Returns the nanoseconds truncated from the time of the AUID by
getDate . | final public long | getNode() Returns node value octets 10-15 (unsigned) 48-bit in a signed long. | final protected static 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 public long | getTime() Returns octets 0-7 time only. | final public long | getTimeHigh() Returns time high octets 6-7 (unsigned) int in a signed long. | final public long | getTimeHighAndVersion() Returns octets 6-7 (unsigned) int in a signed long. | final public long | getTimeLow() Returns time low octets 0-3 (unsigned) int in a signed long. | final public long | getTimeMid() Returns time mid octets 4-5 (unsigned) int in a signed long. | final public int | getVariant() Returns the variant. | final public int | getVersion() Returns octets 6-7 version only. | public int | hashCode() | protected int | identifyVariant(int clockSeqAndVariant) Identifies the variant from the combined clock sequence and variant
value, as it is returned by getClockSeqAndVariant() .
May be overridden to support new variants.
Parameters: clockSeqAndVariant - the combined clock sequence and variant value, as it isreturned by getClockSeqAndVariant() . | protected State | loadState(State state) Loads the generator state from non-volatile storage into the provided
State object or creates a new one if null .
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. | public static AUID | parse(String auid) Parse a String representation of an AUID. | public static AUID | parse(CharSequence auid) Parse a String representation of an AUID. | final protected static 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 | saveState(State state) Can be overridden together with loadState to provide
persistent storage for the auid generator state. | public String | toString() | public StringBuffer | toStringBuffer(StringBuffer sb) Appends the String representation of this AUID to the specified
StringBuffer or if null to a new created StringBuffer and returns the
StringBuffer. |
AUID | public AUID()(Code) | | Constructs an AUID with new values.
|
AUID | protected AUID(int securityAttributes)(Code) | | 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)(Code) | | 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 AUID Parameters: version - the version of the new AUID Parameters: clockSeq - the clock sequence of the new AUID Parameters: variant - the variant of the new AUID Parameters: node - the node of the new AUID |
AUID | protected AUID(long timeLow, long timeMid, long timeHiAndVersion, int clockSeqHiAndVariant, int clockSeqLow, long node)(Code) | | 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 AUID Parameters: timeMid - the time mid field of the new AUID Parameters: timeHiAndVersion - the packed time high and version field of the new AUID Parameters: clockSeqHiAndVariant - the packed clock sequence high and variant field of the newAUID Parameters: clockSeqLow - the clock sequence low field of the new AUID Parameters: node - the node field of the new AUID |
AUID | protected AUID(AUID auid)(Code) | | Constructs an AUID with the same values as the specified AUID.
Parameters: auid - the AUID to clone |
AUID | public AUID(String auid)(Code) | | Constructs an AUID from the specified string representation.
Parameters: auid - string in the format "LLLLLLLL-MMMM-HHHH-CCCC-NNNNNNNNNNNN" throws: NumberFormatException - if auid 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 nodefields respectively.a string representation of an AUID |
AUID | public AUID(CharSequence auid)(Code) | | Constructs an AUID from the specified string representation in
CharSequence.
Parameters: auid - a string representation of an AUID throws: NumberFormatException - if auid 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 nodefields respectively. |
AUID | public AUID(byte[] bytes)(Code) | | Constructs an AUID from the specified byte array representation, which is
in the same format as returned by getBytes(dst, dstBegin) .
This constructor is equal to AUID(bytes, 0) .
Parameters: bytes - a byte array representation of an AUID |
AUID | public AUID(byte[] bytes, int offset)(Code) | | Constructs an AUID from the specified byte array representation, which is
in the same format as returned by getBytes(dst, dstBegin) .
Parameters: bytes - a byte array representation of an AUID Parameters: offset - the offset at which the byte array representation is locatedin the byte array. |
getBytes | protected byte[] getBytes(byte[] dst, int dstBegin, boolean bigendian)(Code) | | This is the implementation of getBytes(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 the
getBytes(dst, dstBegin) method.
Parameters: dst - the destination byte array, if null a new arraywill be created Parameters: dstBegin - the offset to use when writing into the destination bytearray, ignored if dst is null Parameters: bigendian - if true big endian byte order is used a byte array |
getBytes | public byte[] getBytes(byte[] dst, int dstBegin)(Code) | | 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 returns
getBytes(dst, dstBegin, true) .
Parameters: dst - the destination byte array, if null a new arraywill be created Parameters: dstBegin - the offset to use when writing into the destination bytearray, ignored if dst is null a byte array |
getBytes | final public byte[] getBytes()(Code) | | Conveniance method just returns getBytes(null, 0) .
getBytes(null, 0) . |
getClockSeq | final public int getClockSeq()(Code) | | Returns clock sequence.
the clock sequence field. |
getClockSeqAndVariant | final public int getClockSeqAndVariant()(Code) | | Returns clock sequence and variant octets 8-9 (unsigned) short in a
signed int.
the clock sequence and variant field. |
getClockSeqHighAndVariant | final public int getClockSeqHighAndVariant()(Code) | | Returns clock sequence high and variant octet 8 (unsigned) small in a
signed int.
the clock seq hi and reserved (variant) field (original DCEfield). |
getClockSeqLow | final public int getClockSeqLow()(Code) | | Returns clock sequence low octet 9 (unsigned) small in a signed int.
the clock seq low field (original DCE field). |
getClockSeqMaskForVariant | public int getClockSeqMaskForVariant(int variant)(Code) | | 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. the mask to apply to a sequence when combining values. |
getCurrentTime | protected long getCurrentTime()(Code) | | 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.
a time stamp for use in an AUID |
getDate | final public Date getDate()(Code) | | 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. Use getNanos to
retrieve the truncated nanoseconds.
the complete time value as Date truncated to the nextmillisecond. |
getNanos | final public long getNanos()(Code) | | Returns the nanoseconds truncated from the time of the AUID by
getDate .
the nanoseconds truncated from the time of the AUID bygetDate . |
getNode | final public long getNode()(Code) | | Returns node value octets 10-15 (unsigned) 48-bit in a signed long.
the node field (original DCE field). |
getOctets | final protected static long getOctets(int octets, byte[] bytes, int begin, boolean bigendian)(Code) | | Gets a value from the specified byte array starting at begin with the
specified number of octets and endianess.
Parameters: octets - the number of octets Parameters: bytes - the array to get the value from Parameters: begin - the offset to use when writing into the destination bytearray, ignored if dst is null Parameters: bigendian - if true big endian byte order is used the octet |
getTime | final public long getTime()(Code) | | Returns octets 0-7 time only.
the complete time value. |
getTimeHigh | final public long getTimeHigh()(Code) | | Returns time high octets 6-7 (unsigned) int in a signed long.
the time high field with version masked out. |
getTimeHighAndVersion | final public long getTimeHighAndVersion()(Code) | | Returns octets 6-7 (unsigned) int in a signed long.
the time high and version field (original DCE field). |
getTimeLow | final public long getTimeLow()(Code) | | Returns time low octets 0-3 (unsigned) int in a signed long.
the time low field (original DCE field). |
getTimeMid | final public long getTimeMid()(Code) | | Returns time mid octets 4-5 (unsigned) int in a signed long.
the time mid field (original DCE field). |
getVariant | final public int getVariant()(Code) | | Returns the variant.
the variant field. |
getVersion | final public int getVersion()(Code) | | Returns octets 6-7 version only.
the version field. |
hashCode | public int hashCode()(Code) | | |
identifyVariant | protected int identifyVariant(int clockSeqAndVariant)(Code) | | Identifies the variant from the combined clock sequence and variant
value, as it is returned by getClockSeqAndVariant() .
May be overridden to support new variants.
Parameters: clockSeqAndVariant - the combined clock sequence and variant value, as it isreturned by getClockSeqAndVariant() . the variant identified in the specified combined value. throws: IllegalArgumentException - if variant could not be identified. |
loadState | protected State loadState(State state)(Code) | | Loads the generator state from non-volatile storage into the provided
State object or creates a new one if null .
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. an initialized State object |
parse | public static AUID parse(String auid)(Code) | | Parse a String representation of an AUID. Equal to
new AUID(auid) .
Parameters: auid - a string representation of an AUID the AUID represented by auid . throws: NumberFormatException - if auid 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 nodefields respectively. |
parse | public static AUID parse(CharSequence auid)(Code) | | Parse a String representation of an AUID. Equal to
new AUID(auid) .
Parameters: auid - string in the format "LLLLLLLL-MMMM-HHHH-CCCC-NNNNNNNNNNNN" the AUID represented by auid . throws: NumberFormatException - if auid 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 nodefields respectively.a string representation of an AUID |
putOctets | final protected static void putOctets(long value, int octets, byte[] dst, int dstBegin, boolean bigendian)(Code) | | Puts the specified value into the byte array in the specified endianess.
Parameters: value - the value Parameters: octets - the number of octets Parameters: dst - the destination array Parameters: dstBegin - the offset to use when writing into the destination bytearray, ignored if dst is null Parameters: bigendian - if true big endian byte order is used |
saveState | protected void saveState(State state)(Code) | | Can be overridden together with loadState to provide
persistent storage for the auid generator state. The default
implementation does nothing.
Parameters: state - the State object to persist. |
toStringBuffer | public StringBuffer toStringBuffer(StringBuffer sb)(Code) | | Appends the String representation of this AUID to the specified
StringBuffer or if null to a new created StringBuffer and returns the
StringBuffer. This method is called by toString ,
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 StringBuffer to use a StringBuffer to which this AUID has been appended |
|
|