Package org.altbeacon.beacon

Class Identifier

  • All Implemented Interfaces:
    Serializable, Comparable<Identifier>
    public class Identifier
extends Object
implements Comparable<Identifier>, Serializable
    Encapsulates a beacon identifier of arbitrary byte length. It can encapsulate an identifier that is a 16-byte UUID, or an integer.

    Instances of this class are immutable, so those can be shared without problem between threads.

    The value is internally this is stored as a byte array.

    See Also:
    Serialized Form

    • Constructor Detail

      • Identifier

        @Deprecated
public Identifier​(Identifier identifier)
        Deprecated.
        objects of this class are immutable and therefore don't have to be cloned when used from multiple threads
        Creates a new copy of the specified Identifier.
        Parameters:
        identifier - identifier to copy

      • Identifier

        protected Identifier​(byte[] value)
        Creates a new instance of Identifier
        Parameters:
        value - value to use. This value isn't copied, so don't change the value after using it to create an instance!

    • Method Detail

      • parse

        public static Identifier parse​(String stringValue)
        Takes the passed string and tries to figure out what format it is in. Then turns the string into plain bytes and constructs an Identifier. Known bug: This method happily parses UUIDs without dashes (normally invalid). Although the bug is left unfixed for backward compatibility, please check your UUIDs or even better, use fromUuid(java.util.UUID) directly, which is safe. Allowed formats:
        • UUID: 2F234454-CF6D-4A0F-ADF2-F4911BA9FFA6 (16 bytes)
        • Hexadecimal: 0x000000000003 (variable length)
        • Decimal: 1337 (2 bytes)
        Parameters:
        stringValue - string to parse
        Returns:
        Identifier representing the specified value
        Throws:
        IllegalArgumentException - if the passed string cannot be parsed
        NullPointerException - if the passed string is null
        See Also:
        RFC 4122 on UUIDs

      • parse

        public static Identifier parse​(String stringValue,
                               int desiredByteLength)
        Variant of the parse method that allows specifying the byte length of the identifier.
        Parameters:
        stringValue -
        desiredByteLength -
        Returns:
        See Also:
        parse(String)

      • fromLong

        public static Identifier fromLong​(long longValue,
                                  int desiredByteLength)
        Creates an Identifer backed by an array of length desiredByteLength
        Parameters:
        longValue - a long to put into the identifier
        desiredByteLength - how many bytes to make the identifier
        Returns:

      • fromInt

        public static Identifier fromInt​(int intValue)
        Creates an Identifier backed by a two byte Array (big endian).
        Parameters:
        intValue - an integer between 0 and 65535 (inclusive)
        Returns:
        an Identifier with the specified value

      • fromBytes

        public static Identifier fromBytes​(byte[] bytes,
                                   int start,
                                   int end,
                                   boolean littleEndian)
        Creates an Identifier from the specified byte array.
        Parameters:
        bytes - array to copy from
        start - the start index, inclusive
        end - the end index, exclusive
        littleEndian - whether the bytes are ordered in little endian
        Returns:
        a new Identifier
        Throws:
        NullPointerException - bytes must not be null
        ArrayIndexOutOfBoundsException - start or end are outside the bounds of the array
        IllegalArgumentException - start is larger than end

      • fromUuid

        public static Identifier fromUuid​(UUID uuid)
        Transforms a UUID into an Identifier. No mangling with strings, only the underlying bytes of the UUID are used so this is fast and stable.

      • toString

        public String toString()
        Represents the value as a String. The output varies based on the length of the value.
        • When the value is 2 bytes long: decimal, for example 6536
        • When the value is 16 bytes long: uuid, for example 2f234454-cf6d-4a0f-adf2-f4911ba9ffa6
        • Else: hexadecimal prefixed with 0x, for example 0x0012ab
        Overrides:
        toString in class Object
        Returns:
        string representation of the current value

      • toInt

        public int toInt()
        Represents the value as an int.
        Returns:
        value represented as int
        Throws:
        UnsupportedOperationException - when value length is longer than 2

      • toByteArrayOfSpecifiedEndianness

        public byte[] toByteArrayOfSpecifiedEndianness​(boolean bigEndian)
        Converts identifier to a byte array
        Parameters:
        bigEndian - true if bytes are MSB first
        Returns:
        a new byte array with a copy of the value

      • getByteCount

        public int getByteCount()
        Returns the byte length of this identifier.
        Returns:
        length of identifier

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • equals

        public boolean equals​(Object that)
        Returns whether both Identifiers contain equal value. This is the case when the value is the same and has the same length
        Overrides:
        equals in class Object
        Parameters:
        that - object to compare to
        Returns:
        whether that equals this

      • toHexString

        public String toHexString()
        Represents the value as a hexadecimal String. The String is prefixed with 0x. For example 0x0034ab
        Returns:
        value as hexadecimal String

      • toUuidString

        @Deprecated
public String toUuidString()
        Deprecated.
        Replaced by stronger typed variant. This mathod returns a string, therefore does not offer type safety on the UUID per se. It was replaced by toUuid().
        Returns the value of this Identifier in UUID format. For example 2f234454-cf6d-4a0f-adf2-f4911ba9ffa6
        Returns:
        value in UUID format
        Throws:
        UnsupportedOperationException - when value length is not 16 bytes

      • toUuid

        public UUID toUuid()
        Gives you the Identifier as a UUID if possible.
        Throws:
        UnsupportedOperationException - if the byte array backing this Identifier is not exactly 16 bytes long.

      • toByteArray

        public byte[] toByteArray()
        Gives you the byte array backing this Identifier. Note that Identifiers are immutable, so changing the the returned array will not result in a changed Identifier.
        Returns:
        a deep copy of the data backing this Identifier.

      • compareTo

        public int compareTo​(Identifier that)
        Compares two identifiers. When the Identifiers don't have the same length, the Identifier having the shortest array is considered smaller than the other.
        Specified by:
        compareTo in interface Comparable<Identifier>
        Parameters:
        that - the other identifier
        Returns:
        0 if both identifiers are equal. Otherwise returns -1 or 1 depending on which is bigger than the other.
        See Also:
        Comparable.compareTo(T)