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

tv.amwa.maj.record

## Interface AUID

- All Superinterfaces:
    Comparable<AUID>, Serializable
  All Known Subinterfaces:
    UL, UUID
  All Known Implementing Classes:
    AUIDImpl

      public interface AUID
      extends Comparable<AUID>, Serializable

  Specifies a 16-byte unique identifier whose value is a SMPTE 298M Universal Label or a UUID or GUID.

  UUIDs are defined in rfc 4122. For media metadata, SMPTE have defined a dictionary for Universal Labels, which are representable by AUID values, that is defined according to SMPTE 335M "Metadata Dictionary Structure". This current version of the dictionary can be accessed via the SMPTE Registration Authority's website.

  A Universal label is represented as an AUID by storing bytes 9 to 16 of the label in bytes 1 to 8 of an AUID and bytes 1 to 8 of the same Universal label in bytes 9 to 16 of the same AUID.

  The terminology used to describe the methods of this interface is taken from the UUID specification.

  To make values of this type, use the following methods from the MAJ forge:

  - From its underlying bytes: `Forge.makeAUID(byte[])`;
  - From its constituent parts: `Forge.makeAUID(int, short, short, byte[])`;
  - A time-based UUID: `Forge.timebasedAUID()` and `Forge.timebasedAUID(byte[])`;
  - A name-based UUID: `Forge.namebasedAUID(byte[])` and `Forge.namebasedAUID(String)`;
  - A random UUID: `Forge.randomAUID()`;
  - From a URN string representation as generated by `toString()`: `Forge.parseAUID(String)`.
  See Also:
    `TypeDefinitions.AUID`, `TypeDefinitions.AUIDArray`, `TypeDefinitions.AUIDSet`, `PackageID`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `AUID` | `clone()` Create a cloned copy of this AUID value.
    `byte[]` | `getAUIDValue()` Returns a 16-byte array representation of this AUID value.
    `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.
    `boolean` | `isNil()` Tests to see if the AUID is a nil value, which means that the value of each of its components is 0.
    `boolean` | `isUniversalLabel()` Determines whether this AUID value represents a SMPTE universal label.
    `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.
    `String` | `toString()` Generates a string representation of this AUID value as a URN 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:`").

    - ### Methods inherited from interface java.lang.Comparable

      `compareTo`

- - ### Method Detail

    - #### getData1

          @UInt32
          int getData1()

      Returns the time-low part of the AUID.

      Returns:
        Time low part of the AUID.

    - #### setData1

          void setData1(@UInt32
                        int data1)

      Sets the time-low part of the AUID.

      Parameters:
        `data1` - Time-low part of the AUID.

    - #### getData2

          @UInt16
          short getData2()

      Returns the time-mid part of the AUID.

      Returns:
        Time-mid part of the AUID.

    - #### setData2

          void setData2(@UInt16
                        short data2)

      Sets the time-mid part of the AUID.

      Parameters:
        `data2` - Time-mid part of the AUID.

    - #### getData3

          @UInt16
          short getData3()

      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.

      Returns:
        Time-hi and version part of the AUID.

    - #### setData3

          void setData3(@UInt16
                        short data3)

      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.

      Parameters:
        `data3` - Time-hi and version part of the AUID.

    - #### getData4

          @UInt8Array
          byte[] getData4()

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

      Returns:
        Variant, clock sequence and node parts of the AUID.

    - #### setData4

          void setData4(@UInt8Array
                        byte[] data4)

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

      Parameters:
        `data4` - Variant, clock sequence and node parts of the AUID.

    - #### isNil

          boolean isNil()

      Tests to see if the AUID is a nil value, which means that the value of each of its components is 0. As a UUID URN, this looks like:

      `urn:uuid:00000000-0000-0000-0000-000000000000`
      Returns:
        Is the AUID a nil value?
      See Also:
        `PackageID.isZero()`

    - #### clone

          AUID clone()

      Create a cloned copy of this AUID value.

      Returns:
        Cloned copy of this AUID value.

    - #### getAUIDValue

          byte[] getAUIDValue()

      Returns a 16-byte array representation of this AUID value.

      Returns:
        Array representation of this AUID value.

    - #### isUniversalLabel

          boolean isUniversalLabel()

      Determines whether this AUID value represents a SMPTE universal label.

      Returns:
        Does this AUID value represent a universal label?
      See Also:
        `UL`

    - #### toString

          String toString()

      Generates a string representation of this AUID value as a URN 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:`").

      Overrides:
        `toString` in class `Object`
      Returns:
        URN representation of this AUID value.
      See Also:
        `Forge.parseAUID(java.lang.String)`

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