Class AUIDGenerator.AUID

  • All Implemented Interfaces:
    java.lang.Comparable
    Enclosing class:
    AUIDGenerator

    static class AUIDGenerator.AUID
    extends java.lang.Object
    implements java.lang.Comparable
    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 Classes 
      Modifier and Type Class Description
      protected static class  AUIDGenerator.AUID.State
      This class represents the current state of the AUID generator.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        AUID()
      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 by getBytes(dst, dstBegin).
        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).
      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​(java.lang.CharSequence auid)
      Constructs an AUID from the specified string representation in CharSequence.
        AUID​(java.lang.String auid)
      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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(java.lang.Object o)  
      private static long entropicSeed​(int bits, long initialSeed)  
      boolean equals​(java.lang.Object obj)  
      byte[] getBytes()
      Conveniance method just returns getBytes(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 of getBytes(dst, dstBegin), however, the endianess can be specified through the boolean argument.
      int getClockSeq()
      Returns clock sequence.
      int getClockSeqAndVariant()
      Returns clock sequence and variant octets 8-9 (unsigned) short in a signed int.
      int getClockSeqHighAndVariant()
      Returns clock sequence high and variant octet 8 (unsigned) small in a signed int.
      int getClockSeqLow()
      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 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).
      java.util.Date getDate()
      Returns the time of the AUID as Date.
      long getNanos()
      Returns the nanoseconds truncated from the time of the AUID by getDate.
      long getNode()
      Returns node value octets 10-15 (unsigned) 48-bit in a signed long.
      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.
      long getTime()
      Returns octets 0-7 time only.
      long getTimeHigh()
      Returns time high octets 6-7 (unsigned) int in a signed long.
      long getTimeHighAndVersion()
      Returns octets 6-7 (unsigned) int in a signed long.
      long getTimeLow()
      Returns time low octets 0-3 (unsigned) int in a signed long.
      long getTimeMid()
      Returns time mid octets 4-5 (unsigned) int in a signed long.
      int getVariant()
      Returns the variant.
      int getVersion()
      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 by getClockSeqAndVariant().
      protected AUIDGenerator.AUID.State loadState​(AUIDGenerator.AUID.State state)
      Loads the generator state from non-volatile storage into the provided State object or creates a new one if null.
      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​(java.lang.CharSequence auid)
      Parse a String representation of an AUID.
      static AUIDGenerator.AUID parse​(java.lang.String auid)
      Parse a String representation of an AUID.
      private long parseFirstHalf​(java.lang.CharSequence charSequence)
      Parses the character sequence cs from begin to end as the first 18 charcters of a string representation of an AUID.
      private long parseHex​(java.lang.CharSequence cs)
      Parses the character sequence cs from begin to end as hex string.
      private void parseHyphen​(char c)
      Tests wether c is a hyphen '-' character.
      private long parseNibble​(char c)
      Converts a hex character into the corresponding nibble value.
      private long parseSecondHalf​(java.lang.CharSequence charSequence)
      Parses the character sequence cs from begin to end as the second 18 charcters of a string representation of an AUID.
      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​(AUIDGenerator.AUID.State state)
      Can be overridden together with loadState to provide persistent storage for the auid generator state.
      private void toHex​(java.lang.StringBuilder result, long value, int nibbles)
      Converts nibbles least significant nibbles of value into a hex representation and appends it to result.
      java.lang.String toString()  
      java.lang.StringBuilder toStringBuilder​(java.lang.StringBuilder sb)
      Appends the String representation of this AUID to the specified StringBuilder or if null to a new created StringBuilder and returns the StringBuilder.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • MAXIMUM_ENTROPIC_TIME_MS

        private static final long MAXIMUM_ENTROPIC_TIME_MS
        See Also:
        Constant Field Values
      • TIME_SCALE

        private static final long TIME_SCALE
        Scale from System.currentTimeMillis() granularity to that of AUID.
        See Also:
        Constant Field Values
      • UTC_OFFSET

        private static final long UTC_OFFSET
        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).
      • HEX_CHARS

        private static final char[] HEX_CHARS
        An array of chars for Hex conversion.
      • firstHalf

        private long firstHalf
        The first 64 bits of the uuid value.
      • secondHalf

        private long secondHalf
        The last 64 bits of the uuid value.
    • Constructor Detail

      • 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 AUID
        version - the version of the new AUID
        clockSeq - the clock sequence of the new AUID
        variant - the variant of the new AUID
        node - 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 AUID
        timeMid - the time mid field of the new AUID
        timeHiAndVersion - the packed time high and version field of the new AUID
        clockSeqHiAndVariant - the packed clock sequence high and variant field of the new AUID
        clockSeqLow - the clock sequence low field of the new AUID
        node - the node field of the new AUID
      • AUID

        protected AUID​(AUIDGenerator.AUID auid)
        Constructs an AUID with the same values as the specified AUID.
        Parameters:
        auid - the AUID to clone
      • AUID

        public AUID​(java.lang.String auid)
        Constructs an AUID from the specified string representation.
        Parameters:
        auid - string in the format "LLLLLLLL-MMMM-HHHH-CCCC-NNNNNNNNNNNN"
        Throws:
        java.lang.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 node fields respectively. a string representation of an AUID
      • AUID

        public AUID​(java.lang.CharSequence auid)
        Constructs an AUID from the specified string representation in CharSequence.
        Parameters:
        auid - a string representation of an AUID
        Throws:
        java.lang.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 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 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)
        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
        offset - the offset at which the byte array representation is located in the byte array.
    • Method Detail

      • parse

        public static AUIDGenerator.AUID parse​(java.lang.String auid)
        Parse a String representation of an AUID. Equal to new AUID(auid).
        Parameters:
        auid - a string representation of an AUID
        Returns:
        the AUID represented by auid.
        Throws:
        java.lang.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 node fields respectively.
      • parse

        public static AUIDGenerator.AUID parse​(java.lang.CharSequence auid)
        Parse a String representation of an AUID. Equal to new AUID(auid).
        Parameters:
        auid - string in the format "LLLLLLLL-MMMM-HHHH-CCCC-NNNNNNNNNNNN"
        Returns:
        the AUID represented by auid.
        Throws:
        java.lang.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 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 by getClockSeqAndVariant(). May be overridden to support new variants.
        Parameters:
        clockSeqAndVariant - the combined clock sequence and variant value, as it is returned by getClockSeqAndVariant().
        Returns:
        the variant identified in the specified combined value.
        Throws:
        java.lang.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

        protected AUIDGenerator.AUID.State loadState​(AUIDGenerator.AUID.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.
        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

        protected void saveState​(AUIDGenerator.AUID.State state)
        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.
      • getBytes

        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. 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 array will be created
        dstBegin - the offset to use when writing into the destination byte array, ignored if dst is null
        bigendian - if true 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 returns getBytes(dst, dstBegin, true).
        Parameters:
        dst - the destination byte array, if null a new array will be created
        dstBegin - the offset to use when writing into the destination byte array, ignored if dst is null
        Returns:
        a byte array
      • toStringBuilder

        public java.lang.StringBuilder toStringBuilder​(java.lang.StringBuilder sb)
        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 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 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

        private void toHex​(java.lang.StringBuilder result,
                           long value,
                           int nibbles)
        Converts nibbles least significant nibbles of value into a hex representation and appends it to result.
      • parseNibble

        private long parseNibble​(char c)
        Converts a hex character into the corresponding nibble value.
        Returns:
        the nibble value.
        Throws:
        java.lang.NumberFormatException - if c is not a valid hex character.
      • parseHyphen

        private void parseHyphen​(char c)
        Tests wether c is a hyphen '-' character.
        Throws:
        java.lang.NumberFormatException - if c is not a hyphen '-' character.
      • parseHex

        private long parseHex​(java.lang.CharSequence cs)
        Parses the character sequence cs from begin to end as hex string.
        Throws:
        java.lang.NumberFormatException - if cs contains non-hex characters.
      • parseFirstHalf

        private long parseFirstHalf​(java.lang.CharSequence charSequence)
        Parses the character sequence cs 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:
        java.lang.NumberFormatException - if cs does no match the pattern "LLLLLLLL-MMMM-HHHH" where 'L', 'M', 'H' are time low, mid and high fields respectively.
      • parseSecondHalf

        private long parseSecondHalf​(java.lang.CharSequence charSequence)
        Parses the character sequence cs 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:
        java.lang.NumberFormatException - if cs 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 octets
        bytes - the array to get the value from
        begin - the offset to use when writing into the destination byte array, ignored if dst is null
        bigendian - if true 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 value
        octets - the number of octets
        dst - the destination array
        dstBegin - the offset to use when writing into the destination byte array, ignored if dst is null
        bigendian - if true 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

        public final java.util.Date 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. Use getNanos 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 by getDate.
        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 returns getBytes(null, 0).
        Returns:
        getBytes(null, 0).
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • compareTo

        public int compareTo​(java.lang.Object o)
        Specified by:
        compareTo in interface java.lang.Comparable
      • entropicSeed

        private static long entropicSeed​(int bits,
                                         long initialSeed)