public final class AUIDImpl extends Object implements AUID, UL, Serializable, XMLSerializable, Cloneable, Comparable<AUID>
Implementation of a 16 byte unique identifier whose value is a SMPTE 298M Universal Label or a UUID or GUID. This implementation provides methods for generating AUIDs that are UUIDs and can be embedded within an entity to become its primary key.
This class supports transformation of AUIDs to and from string representations as
Unique Resource Names (URNs), as defined in
RFC 4122/a>. Use the
toString() method and static parseFactory(String) methods to do this.
This class makes a best effort to generate unique identifiers from the information provided to it and the features provided by the Java APIs. However, there is no 100% guarantee that it will generate a UUID that is totally unique. This class is provided with out any warranty whatsoever and its use is entirely at the users own risk.
The internal representation of an AUID used by the MAJ API is an array of 16 bytes.
This array can be manipulated by an application using the getAUIDValue(), setAUIDValue(byte[])
and #AUID(byte[]) methods. The database schema for an AUID value is a column defined as
follows:
`Identification` binary(16)
| Modifier and Type | Field and Description |
|---|---|
static String |
MYSQL_COLUMN_DEFINITION |
| Constructor and Description |
|---|
AUIDImpl()
Create a new UUID as an AUID using the random generation method.
|
AUIDImpl(byte[] auidValue)
Create a new AUID value from a 16-byte array representing its internal value.
|
AUIDImpl(int data1,
short data2,
short data3,
byte[] data4)
Create a new AUID from its component parts.
|
| Modifier and Type | Method and Description |
|---|---|
void |
appendXMLChildren(Node parent)
Append extra child elements to the given parent node to serialize the value of an object
to an XML fragment.
|
static AUIDImpl |
auidFactory(AUIDGeneration type,
byte[] extraData)
Generates a new UUID as an AUID using the given
generation method. |
static boolean |
auidsEqual(AUID auid1,
AUID auid2)
Compares two AUIDs to see if they represent equal values.
|
UL |
clone()
Create a cloned copy of this AUID value.
|
int |
compareTo(AUID o) |
static AUID |
createFromBuffer(ByteBuffer buffer) |
boolean |
equals(Object o)
Checks to see if two AUID values are equal.
|
static AUID |
fromPersistentForm(String persistentForm) |
static void |
generateEmbeddableORM(Node parent,
String namespace,
String prefix) |
static void |
generateEmbeddedORM(Node parent,
String ownerName,
String namespace,
String prefix) |
byte[] |
getAUIDValue()
Returns a copy of the array of bytes used to represent this AUID internally.
|
String |
getComment()
Include a comment when serializing a value to XML.
|
int |
getData1()
Returns the time-low part of the AUID.
|
short |
getData2()
Returns the time-mid part of the AUID.
|
short |
getData3()
Returns the time-hi and version parts of the AUID.
|
byte[] |
getData4()
Returns the variant, clock sequence and node parts of the AUID as an 8-byte
array.
|
byte[] |
getUniversalLabel() |
int |
hashCode() |
boolean |
isNil()
Check to see if all the component values of this AUID are set to 0, the only non-unique
value for an AUID.
|
boolean |
isUniversalLabel()
Returns
true if this AUID value is a SMPTE Universal Label, as defined
in SMPTE 298M-1997. |
static long |
lengthAsBuffer(AUID value) |
static AUIDImpl |
namebasedAUID(byte[] nameData)
Creates a new UUID as an AUID generated with the name-based method, type 3.
|
static AUIDImpl |
parseFactory(String auidValue)
Create a new AUID from a URN representation, as specified in section 3 of
rfc 4122 or
the commonly used URN representation of Universal Labels (starting with
"
urn:x-ul:" or "urn:smpte:ul:"). |
static AUIDImpl |
randomAUID()
Create a new AUID using pseudo-random number generation, type 4.
|
void |
setAUIDValue(byte[] auidValue)
Sets the array of bytes used to represent this AUID internally.
|
void |
setData1(int data1)
Sets the time-low part of the AUID.
|
void |
setData2(short data2)
Sets the time-mid part of the AUID.
|
void |
setData3(short data3)
Sets the time-hi and version parts of the AUID.
|
void |
setData4(byte[] data4)
Sets the variant, clock sequence and node parts of the AUID using an 8-byte
array.
|
static void |
setLocalNodeID(byte[] localNodeIDBytes)
Set the local node ID to use in the generation of timebased UUIDs as AUIDs.
|
static AUIDImpl |
timebasedAUID()
Create and return a new UUID as AUID generated according to the time and location
based method, type 1.
|
static AUIDImpl |
timebasedAUID(byte[] nodeId)
Generates a new UUID as an AUID from the current time and a location provided
by the given node id.
|
static String |
toPersistentForm(AUID auid) |
String |
toString()
Create a string representation of this AUID as either an URN for a Universal Label
(starting with "
urn:x-ul:") or an URN for an UUID (starting with
"urn:uuid:"). |
static void |
writeToBuffer(AUID value,
ByteBuffer buffer) |
static void |
writeToStructuredStorageBuffer(AUID value,
ByteBuffer buffer) |
public static final String MYSQL_COLUMN_DEFINITION
public AUIDImpl(@UInt32 int data1, @UInt16 short data2, @UInt16 short data3, @UInt8 byte[] data4) throws NullPointerException
Create a new AUID from its component parts.
data1 - Integer value ... the first 4 bytes, also known as the "time_low"
part.data2 - Short value ... the next 2 bytes, also known as the "time_mid"
part.data3 - Short value ... the next 2 bytes, also known as the
"time_mid_and_version" part.data4 - Array of 8 bytes ... the final 8 bytes, containing the variant, clock sequence
and node parts. The value will be truncated or padded if more or less than 8 bytes are
provided respectively.NullPointerExceptionpublic AUIDImpl(byte[] auidValue)
throws NullPointerException
Create a new AUID value from a 16-byte array representing its internal value. The given array is copied to make the internal representation used here safe from subsequent changes to the passed array. If the array length is less than or greater than 16, the array is padded with 0's or truncated to contain exactly 16 bytes.
If a SMPTE Universal Label is detected, starting with bytes 0x06,
0x0e, 0x2b and 0x34, then the first eight and
last eight bytes are swapped over to make a valid AUID.
auidValue - Byte array to use to set the value of the new AUID.NullPointerException - Argument is null.public AUIDImpl()
Create a new UUID as an AUID using the random generation method. Creating an AUID
with this constructor has the same result as calling the static factory method
randomAUID().
randomAUID()public static final void setLocalNodeID(byte[] localNodeIDBytes)
Set the local node ID to use in the generation of timebased UUIDs as AUIDs. This method is provided to allow the default host id generated in the instantiation of this class to be overridden. As the actual host id (ethernet address) of a system is not available through the Java 1.5 APIs, the default value is generated from the IP address and domain name of this system. Using this method, the actual host id of the system can be set, or any other 6-byte unique identifier for the host.
localNodeIDBytes - A guaranteed to be unique identifier for the node on which this
class is loaded. The value will be padded or truncated to 6-bytes.timebasedAUID()public static final AUIDImpl timebasedAUID()
Create and return a new UUID as AUID generated according to the time and location
based method, type 1. The node id used for this method can be set by calling
setLocalNodeID(byte[]).
Java's time resolution is to the nearest millisecond. Therefore, an extra counter is implemented in this method to provide an additional sequence of values to simulate the generation of time values measured in 100-nano second chunks as required by the UUID specification. The clock sequence part of the value is generated using a secure random number generator.
setLocalNodeID(byte[]),
auidFactory(AUIDGeneration, byte[])public static final AUIDImpl randomAUID()
Create a new AUID using pseudo-random number generation, type 4. This method uses
the java.security.SecureRandom number generator, seeded from values
in the local environment obscured with a mixing function.
auidFactory(AUIDGeneration, byte[]),
#AUID(),
Utilities.seedRandomMaker()public static final AUIDImpl namebasedAUID(byte[] nameData)
Creates a new UUID as an AUID generated with the name-based method, type 3. This
method is based on UUID.nameUUIDFromBytes(byte[]) that uses an
MD5 algorithm.
nameData - Name data to use to create a namebased UUID.NullPointerException - The name data argument is null.auidFactory(AUIDGeneration, byte[]),
UUID.nameUUIDFromBytes(byte[])public static final AUIDImpl timebasedAUID(byte[] nodeId) throws NullPointerException, IllegalArgumentException
Generates a new UUID as an AUID from the current time and a location provided by the given node id. The node id must be a byte array containing at least 6 values.
Java's time resolution is to the nearest millisecond. Therefore, an extra counter is implemented in this method to provide an additional sequence of values to simulate the generation of time values measured in 100-nano second chunks as required by the UUID specification. The clock sequence part of the value is generated using a secure random number generator.
nodeId - Unique identifier for this computational node, which must contain at least
6 bytes.NullPointerException - The node id byte array argument is null.IllegalArgumentException - The node id must contain at least 6 bytes.timebasedAUID(),
auidFactory(AUIDGeneration, byte[])public static final AUIDImpl auidFactory(AUIDGeneration type, byte[] extraData) throws NullPointerException
Generates a new UUID as an AUID using the given
generation method. Three different types are supported
by this factory:
AUIDGeneration.IETF_Type1 or AUIDGeneration.Timebased:
Generate a time and location based UUID as an AUID. If the extra data is null
then this method is equivalent to calling timebasedAUID() and if extra data
is provided, this method is equivalent to calling timebasedAUID(byte[]).AUIDGeneration.IETF_Type3 or AUIDGeneration.Namebased:
Generate a name based UUID as an AUID. Extra data must be provided and this method
is equivalent to calling namebasedAUID(byte[]).AUIDGeneration.IETF_Type4 or AUIDGeneration.Random:
Generate a random UUID as an AUID. The value of the extra data argument is ignored
and this method is equivalent to calling randomAUID().type - Generator type for a new UUID as an AUID.extraData - Additional data that may be required by the given generation method.NullPointerException - The type and/or extra data arguments is/are null.randomAUID(),
timebasedAUID(),
namebasedAUID(byte[]),
umidFactory()public final int getData1()
AUIDReturns the time-low part of the AUID.
public final void setData1(int data1)
AUIDSets the time-low part of the AUID.
public final short getData2()
AUIDReturns the time-mid part of the AUID.
public final void setData2(short data2)
AUIDSets the time-mid part of the AUID.
public final short getData3()
AUIDReturns the time-hi and version parts of the AUID. This is the high part of the timestamp value of a UUID multiplexed with the version number, where the version number refers to what specified kind of UUID this is.
public final void setData3(short data3)
AUIDSets the time-hi and version parts of the AUID. This is the high part of the timestamp value of a UUID multiplexed with the version number, where the version number refers to the kind of UUID this is.
public final byte[] getData4()
AUIDReturns the variant, clock sequence and node parts of the AUID as an 8-byte array.
public final void setData4(byte[] data4)
AUIDSets the variant, clock sequence and node parts of the AUID using an 8-byte array.
setData4 in interface AUIDdata4 - Variant, clock sequence and node parts of the AUID.AUID.setData4(byte[])public final byte[] getAUIDValue()
Returns a copy of the array of bytes used to represent this AUID internally.
getAUIDValue in interface AUIDpublic final void setAUIDValue(byte[] auidValue)
throws NullPointerException
Sets the array of bytes used to represent this AUID internally. The given array is copied to make the internal representation used here safe from subsequent changes to the passed array. If the array length is less than or greater than 16, the array is padded with 0's or truncated to contain exactly 16 bytes.
If a SMPTE Universal Label is detected, starting with bytes 0x06,
0x0e, 0x2b and 0x34, then the first eight and
last eight bytes are swapped over to make a valid AUID.
auidValue - Array of bytes to use to set the value of this AUID.NullPointerException - The given value is null.public final boolean isNil()
Check to see if all the component values of this AUID are set to 0, the only non-unique value for an AUID.
isNil in interface AUIDPackageID.isZero()public final boolean equals(Object o)
Checks to see if two AUID values are equal.
equals in class Objecto - Object to test for equality with this one.Object.equals(java.lang.Object),
#auidsEqual(AUIDImpl, AUIDImpl)public static final boolean auidsEqual(AUID auid1, AUID auid2) throws NullPointerException
Compares two AUIDs to see if they represent equal values. Two AUIDs are equal if and only if each of their component values are equal. This is always the case if the two objects that are provided are the same.
auid1 - First AUID to test for equality with.auid2 - Second AUID to test for equality with the first.NullPointerExceptionpublic final boolean isUniversalLabel()
Returns true if this AUID value is a SMPTE Universal Label, as defined
in SMPTE 298M-1997. An AUID can be either an Universal Label or an UUID, so if this methods
returns false then this is an UUID. All UUIDs have the MSB of their 9th byte
set, with the exception of the nil UUID.
isUniversalLabel in interface AUIDULpublic final String toString()
Create a string representation of this AUID as either an URN for a Universal Label
(starting with "urn:x-ul:") or an URN for an UUID (starting with
"urn:uuid:"). The kind of URN to be expected can be found by calling
isUniversalLabel(). Values created by this method can be parsed using the
parseFactory(String) method and will create an AUID of an equivalent value
to this one.
The canonical representation of hexadecimal characters used in this implementation
is lower case, eg. 'ae0c' rather than 'AE0C' or
'Ae0C'.
The following is the string representation of the Universal Label for timecode type data:
urn:smpte:ul:060e2b34.0401.0101.01030201.01000000The following is the string representation of the UUID for the edgecode type data:
urn:uuid:d2bb2af0-d234-11d2-89ee-006097116212toString in interface AUIDtoString in class ObjectparseFactory(String)public static final AUIDImpl parseFactory(String auidValue) throws NullPointerException, NumberFormatException
Create a new AUID from a URN representation, as specified in section 3 of
rfc 4122 or
the commonly used URN representation of Universal Labels (starting with
"urn:x-ul:" or "urn:smpte:ul:"). The method accepts
hexadecimal digits in upper or lower case.
auidValue - String value to use to create a new AUID.NullPointerException - AUID string value argument is null.NumberFormatException - The given string is not recognised as an AUID value,
either because it is of the wrong length, has its separators in the wrong place,
uses the wrong separators or contains non-hexadecimal values.toString()public final UL clone()
AUIDCreate a cloned copy of this AUID value.
public final void appendXMLChildren(Node parent)
XMLSerializableAppend extra child elements to the given parent node to serialize the value of an object
to an XML fragment. Methods of the XMLBuilder class are provided to help with this
process.
appendXMLChildren in interface XMLSerializableparent - XML parent element to append child nodes to.public byte[] getUniversalLabel()
getUniversalLabel in interface ULpublic String getComment()
XMLSerializableInclude a comment when serializing a value to XML. The comment will be inserted as the first child node of the element representing the class.
getComment in interface XMLSerializablepublic int compareTo(AUID o)
compareTo in interface Comparable<AUID>public static final AUID createFromBuffer(ByteBuffer buffer) throws NullPointerException, EndOfDataException
public static final long lengthAsBuffer(AUID value)
public static final void writeToBuffer(AUID value, ByteBuffer buffer) throws NullPointerException, InsufficientSpaceException
public static final void writeToStructuredStorageBuffer(AUID value, ByteBuffer buffer) throws NullPointerException, InsufficientSpaceException
public static final void generateEmbeddableORM(Node parent, String namespace, String prefix)
public static final void generateEmbeddedORM(Node parent, String ownerName, String namespace, String prefix)
(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.