AUIDImpl (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.record.impl

## Class AUIDImpl

- java.lang.Object
- - tv.amwa.maj.record.impl.AUIDImpl

- All Implemented Interfaces:
    Serializable, Cloneable, Comparable<AUID>, UL, XMLSerializable, AUID

      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)

  See Also:
    `AUIDGeneration`, `PackageIDImpl`, `DefinitionObject.getAUID()`, `UUID`, `TypeDefinitions.AUID`, `AUIDArray`, `TypeDefinitions.AUIDArray`, `TypeDefinitions.AUIDSet`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `MYSQL_COLUMN_DEFINITION`

  - ### Constructor Summary

    Constructors
    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.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    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)`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### MYSQL_COLUMN_DEFINITION

          public static final String MYSQL_COLUMN_DEFINITION

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### AUIDImpl

          public AUIDImpl(@UInt32
                          int data1,
                          @UInt16
                          short data2,
                          @UInt16
                          short data3,
                          @UInt8
                          byte[] data4)
                   throws NullPointerException

      Create a new AUID from its component parts.

      Parameters:
        `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.
      Throws:
        `NullPointerException`

    - #### AUIDImpl

          public 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.

      Parameters:
        `auidValue` - Byte array to use to set the value of the new AUID.
      Throws:
        `NullPointerException` - Argument is null.

    - #### AUIDImpl

          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()`.

      See Also:
        `randomAUID()`

  - ### Method Detail

    - #### setLocalNodeID

          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.

      Parameters:
        `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.
      See Also:
        `timebasedAUID()`

    - #### 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.

      Returns:
        Time and location based UUID as an AUID.
      See Also:
        `setLocalNodeID(byte[])`, `auidFactory(AUIDGeneration, byte[])`

    - #### randomAUID

          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.

      Returns:
        Random generation of a new UUID as an AUID.
      See Also:
        `auidFactory(AUIDGeneration, byte[])`, `#AUID()`, `Utilities.seedRandomMaker()`

    - #### namebasedAUID

          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.

      Parameters:
        `nameData` - Name data to use to create a namebased UUID.
      Returns:
        Namebased UUID as an AUID.
      Throws:
        `NullPointerException` - The name data argument is `null`.
      See Also:
        `auidFactory(AUIDGeneration, byte[])`, `UUID.nameUUIDFromBytes(byte[])`

    - #### timebasedAUID

          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.

      Parameters:
        `nodeId` - Unique identifier for this computational node, which must contain at least 6 bytes.
      Returns:
        Time and location based UUID as an AUID.
      Throws:
        `NullPointerException` - The node id byte array argument is `null`.
        `IllegalArgumentException` - The node id must contain at least 6 bytes.
      See Also:
        `timebasedAUID()`, `auidFactory(AUIDGeneration, byte[])`

    - #### auidFactory

          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()`.
      Parameters:
        `type` - Generator type for a new UUID as an AUID.
        `extraData` - Additional data that may be required by the given generation method.
      Returns:
        Newly generated UUID as an AUID.
      Throws:
        `NullPointerException` - The type and/or extra data arguments is/are `null`.
      See Also:
        `randomAUID()`, `timebasedAUID()`, `namebasedAUID(byte[])`, `umidFactory()`

    - #### getData1

          public final int getData1()

      Description copied from interface: `AUID`

      Returns the time-low part of the AUID.

      Specified by:
        `getData1` in interface `AUID`
      Returns:
        Time low part of the AUID.

    - #### setData1

          public final void setData1(int data1)

      Description copied from interface: `AUID`

      Sets the time-low part of the AUID.

      Specified by:
        `setData1` in interface `AUID`
      Parameters:
        `data1` - Time-low part of the AUID.

    - #### getData2

          public final short getData2()

      Description copied from interface: `AUID`

      Returns the time-mid part of the AUID.

      Specified by:
        `getData2` in interface `AUID`
      Returns:
        Time-mid part of the AUID.

    - #### setData2

          public final void setData2(short data2)

      Description copied from interface: `AUID`

      Sets the time-mid part of the AUID.

      Specified by:
        `setData2` in interface `AUID`
      Parameters:
        `data2` - Time-mid part of the AUID.

    - #### getData3

          public final short getData3()

      Description copied from interface: `AUID`

      Returns 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.

      Specified by:
        `getData3` in interface `AUID`
      Returns:
        Time-hi and version part of the AUID.

    - #### setData3

          public final void setData3(short data3)

      Description copied from interface: `AUID`

      Sets 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.

      Specified by:
        `setData3` in interface `AUID`
      Parameters:
        `data3` - Time-hi and version part of the AUID.

    - #### getData4

          public final byte[] getData4()

      Description copied from interface: `AUID`

      Returns the variant, clock sequence and node parts of the AUID as an 8-byte array.

      Specified by:
        `getData4` in interface `AUID`
      Returns:
        Variant, clock sequence and node parts of the AUID.

    - #### setData4

          public final void setData4(byte[] data4)

      Description copied from interface: `AUID`

      Sets the variant, clock sequence and node parts of the AUID using an 8-byte array.

      Specified by:
        `setData4` in interface `AUID`
      Parameters:
        `data4` - Variant, clock sequence and node parts of the AUID.
      See Also:
        `AUID.setData4(byte[])`

    - #### getAUIDValue

          public final byte[] getAUIDValue()

      Returns a copy of the array of bytes used to represent this AUID internally.

      Specified by:
        `getAUIDValue` in interface `AUID`
      Returns:
        Array of 16 bytes representing this AUID value.

    - #### setAUIDValue

          public 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.

      Parameters:
        `auidValue` - Array of bytes to use to set the value of this AUID.
      Throws:
        `NullPointerException` - The given value is `null`.

    - #### isNil

          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.

      Specified by:
        `isNil` in interface `AUID`
      Returns:
        True if all the component values of the AUID are 0.
      See Also:
        `PackageID.isZero()`

    - #### equals

          public final boolean equals(Object o)

      Checks to see if two AUID values are equal.

      Overrides:
        `equals` in class `Object`
      Parameters:
        `o` - Object to test for equality with this one.
      Returns:
        Is the given AUID value equal to this AUID?
      See Also:
        `Object.equals(java.lang.Object)`, `#auidsEqual(AUIDImpl, AUIDImpl)`

    - #### auidsEqual

          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.

      Parameters:
        `auid1` - First AUID to test for equality with.
        `auid2` - Second AUID to test for equality with the first.
      Returns:
        Are the values of the two provided AUIDs equal?
      Throws:
        `NullPointerException`

    - #### isUniversalLabel

          public 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.

      Specified by:
        `isUniversalLabel` in interface `AUID`
      Returns:
        Does this AUID represent a SMPTE Universal Label?
      See Also:
        `UL`

    - #### toString

          public 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.01000000`

      The following is the string representation of the UUID for the edgecode type data:

      `urn:uuid:d2bb2af0-d234-11d2-89ee-006097116212`
      Specified by:
        `toString` in interface `AUID`
      Overrides:
        `toString` in class `Object`
      Returns:
        String representation of this AUID as an URN.
      See Also:
        `parseFactory(String)`

    - #### parseFactory

          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.

      Parameters:
        `auidValue` - String value to use to create a new AUID.
      Returns:
        Newly created AUID value corresponding to the given string value.
      Throws:
        `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.
      See Also:
        `toString()`

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### clone

          public final UL clone()

      Description copied from interface: `AUID`

      Create a cloned copy of this AUID value.

      Specified by:
        `clone` in interface `UL`
      Specified by:
        `clone` in interface `AUID`
      Overrides:
        `clone` in class `Object`
      Returns:
        Cloned copy of this AUID value.

    - #### appendXMLChildren

          public final void appendXMLChildren(Node parent)

      Description copied from interface: `XMLSerializable`

      Append 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.

      Specified by:
        `appendXMLChildren` in interface `XMLSerializable`
      Parameters:
        `parent` - XML parent element to append child nodes to.

    - #### getUniversalLabel

          public byte[] getUniversalLabel()

      Specified by:
        `getUniversalLabel` in interface `UL`

    - #### getComment

          public String getComment()

      Description copied from interface: `XMLSerializable`

      Include a comment when serializing a value to XML. The comment will be inserted as the first child node of the element representing the class.

      Specified by:
        `getComment` in interface `XMLSerializable`
      Returns:
        Comment to add as the first child node of the element representing this class.

    - #### compareTo

          public int compareTo(AUID o)

      Specified by:
        `compareTo` in interface `Comparable<AUID>`

    - #### createFromBuffer

          public static final AUID createFromBuffer(ByteBuffer buffer)
                                             throws NullPointerException,
                                                    EndOfDataException

      Throws:
        `NullPointerException`
        `EndOfDataException`

    - #### lengthAsBuffer

          public static final long lengthAsBuffer(AUID value)

    - #### writeToBuffer

          public static final void writeToBuffer(AUID value,
                                                 ByteBuffer buffer)
                                          throws NullPointerException,
                                                 InsufficientSpaceException

      Throws:
        `NullPointerException`
        `InsufficientSpaceException`

    - #### writeToStructuredStorageBuffer

          public static final void writeToStructuredStorageBuffer(AUID value,
                                                                  ByteBuffer buffer)
                                                           throws NullPointerException,
                                                                  InsufficientSpaceException

      Throws:
        `NullPointerException`
        `InsufficientSpaceException`

    - #### generateEmbeddableORM

          public static final void generateEmbeddableORM(Node parent,
                                                         String namespace,
                                                         String prefix)

    - #### generateEmbeddedORM

          public static final void generateEmbeddedORM(Node parent,
                                                       String ownerName,
                                                       String namespace,
                                                       String prefix)

    - #### toPersistentForm

          public static final String toPersistentForm(AUID auid)

    - #### fromPersistentForm

          public static final AUID fromPersistentForm(String persistentForm)

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.