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

tv.amwa.maj.record

## Interface PackageID

- All Known Subinterfaces:
    UMID
  All Known Implementing Classes:
    PackageIDImpl

      public interface PackageID

  Specifies a 32 byte package identifier unique identifier that can hold a SMPTE UMID, as specified in SMPTE 330M. Bytes 14 to 32 of a UMID can be treated as a dumb number, the value of which has no intrinsic meaning.

  A package identifer is globally unique. Please see section 4.3.1 of the AAF object specification v1.1 for details of the immutability of package ids.

  Note that the description of byte positions used in the documentation for each method of this interface use 1-based indexing.

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

  - From its underlying bytes: `Forge.makePackageID(byte[])`;
  - From its constituent parts: `Forge.makePackageID(byte[], byte, byte, byte, byte, AUID)`;
  - According to a specific generation strategy: `Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration)`, `Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID)` and `Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])`;
  - A D-Cinema UMID: `Forge.dCinemaUMID()`;
  - From a URN string representation as generated by `toString()`: `Forge.parsePackageID(String)`.

  Package ids were previously known as mob ids (media object ids) and may still be referred to that way in AAF-specific documentation.

  See Also:
    `TypeDefinitions.PackageIDType`, `PackageIDType`, `AUID`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte[]` | `BaseUniversalLabel` Base universal label to use to create SMPTE-compliant package identifiers.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `PackageID` | `clone()` Create a cloned copy of this package id.
    `InstanceNumberGeneration` | `getInstanceGenerator()` Returns the instance number generation method for this package identifier.
    `byte` | `getInstanceHigh()` Returns the most significant bit of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id.
    `byte` | `getInstanceLow()` Returns the least significant byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id.
    `byte` | `getInstanceMid()` Returns the middle byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id.
    `int` | `getInstanceNumber()` Returns the instance number as an unsigned integer made up from its constituent high, middle and low parts.
    `byte` | `getLength()` Returns the length of the package id in terms of the number of bytes following this byte, as stored at byte 13 of the package id.
    `AUID` | `getMaterial()` Returns the material number of the package id, represented as an AUID, which is taken from bytes 17 to 32 of the package id.
    `MaterialNumberGeneration` | `getMaterialNumberGenerator()` Returns the material number generation method for this package identifier.
    `byte[]` | `getUniversalLabel()` Returns the universal label that makes up bytes 1 to 12 of a package id.
    `boolean` | `isZero()` Returns `true` if this package identifier the special zero package identifier, where all 32-bytes of the identifier are zero; otherwise `false`.
    `PackageID` | `nextInstance()` Returns a new package identifier with the same material number as this one and a newly created instance number.
    `void` | `setInstanceHigh(byte instanceHigh)` Sets the most significant bit of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id.
    `void` | `setInstanceLow(byte instanceLow)` Sets the least significant byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id.
    `void` | `setInstanceMid(byte instanceMid)` Sets the middle byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id.
    `void` | `setLength(byte length)` Returns the length of the package id in terms of the number of bytes following this byte, as stored at byte 13 of the package id.
    `void` | `setMaterial(AUID material)` Sets the material number of the package id, represented as an AUID, which is taken from bytes 17 to 32 of the package id.
    `void` | `setUniversalLabel(byte[] label)` Sets the universal label that makes up bytes 1 to 12 of a package id.
    `String` | `toString()` Formats the value of this package identifier as a URN-style UMID string, starting with "`urn:smpte:umid:`".

- - ### Field Detail

    - #### BaseUniversalLabel

          static final byte[] BaseUniversalLabel

      Base universal label to use to create SMPTE-compliant package identifiers. This value represents a UMID value with material type and generation methods not identified.

  - ### Method Detail

    - #### getUniversalLabel

          @UInt8
          byte[] getUniversalLabel()

      Returns the universal label that makes up bytes 1 to 12 of a package id.

      Returns:
        Universal label component of the package id.

    - #### setUniversalLabel

          void setUniversalLabel(@UInt8
                                 byte[] label)
                          throws NullPointerException

      Sets the universal label that makes up bytes 1 to 12 of a package id.

      Parameters:
        `label` - Universal label component of the package id.
      Throws:
        `NullPointerException` - The given universal label for this package id is `null`.

    - #### getLength

          @UInt8
          byte getLength()

      Returns the length of the package id in terms of the number of bytes following this byte, as stored at byte 13 of the package id. This value is normally 19 (`0x13`) for a 32 byte package id.

      Returns:
        Length component of the package id.

    - #### setLength

          void setLength(@UInt8
                         byte length)

      Returns the length of the package id in terms of the number of bytes following this byte, as stored at byte 13 of the package id. This value is normally 19 (`0x13`) for a 32 byte package id.

      Parameters:
        `length` - Length component of the package id.

    - #### getInstanceHigh

          @UInt8
          byte getInstanceHigh()

      Returns the most significant bit of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 14th byte of the package id.

      Returns:
        Most significant byte of the instance number component of the package id.

    - #### setInstanceHigh

          void setInstanceHigh(@UInt8
                               byte instanceHigh)

      Sets the most significant bit of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 14th byte of the package id.

      Parameters:
        `instanceHigh` - Most significant byte of the instance number component of the package id.

    - #### getInstanceMid

          @UInt8
          byte getInstanceMid()

      Returns the middle byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 15th byte of the package id.

      Returns:
        Middle byte of the instance number component of the package id.

    - #### setInstanceMid

          void setInstanceMid(@UInt8
                              byte instanceMid)

      Sets the middle byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 15th byte of the package id.

      Parameters:
        `instanceMid` - Middle byte of the instance number component of the package id.

    - #### getInstanceLow

          @UInt8
          byte getInstanceLow()

      Returns the least significant byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 16th byte of the package id.

      Returns:
        Least significant byte of the instance number component of the package id.

    - #### setInstanceLow

          void setInstanceLow(@UInt8
                              byte instanceLow)

      Sets the least significant byte of the 3 byte instance number, which is stored as bytes 14 to 16 of the package id. This value is the 16th byte of the package id.

      Parameters:
        `instanceLow` - Least significant byte of the instance number component of the package id.

    - #### getMaterial

          AUID getMaterial()

      Returns the material number of the package id, represented as an AUID, which is taken from bytes 17 to 32 of the package id.

      Returns:
        Material number component of the package id.

    - #### setMaterial

          void setMaterial(AUID material)
                    throws NullPointerException

      Sets the material number of the package id, represented as an AUID, which is taken from bytes 17 to 32 of the package id.

      Parameters:
        `material` - Material number component of the package id
      Throws:
        `NullPointerException` - The given material number is `null`.

    - #### isZero

          boolean isZero()

      Returns `true` if this package identifier the special zero package identifier, where all 32-bytes of the identifier are zero; otherwise `false`. The zero package identifier is represented as a URN as follows:

      `urn:x-umid:000000000000000000000000-00-000000-00000000000000000000000000000000`

      Zero package ids are used to specify original source references for source clips, indicating that a package represents the original source of essence or data.

      Returns:
        Is the package identifier the special zero package identifier?
      See Also:
        `Forge.zeroPackageID()`, `SourceReferenceValue.isOriginalSource()`, `SourceReferenceSegment.getSourcePackageID()`, `AUID.isNil()`

    - #### nextInstance

          PackageID nextInstance()
                          throws InstanceOverflowException,
                                 GenerationMethodNotSupportedException

      Returns a new package identifier with the same material number as this one and a newly created instance number. The method of generation of the instance number is set as part of the package identifier's universal label and can be found by calling `getInstanceGenerator()`.

      The package identifiers generated by this method are only unique within the local context and are not thread safe where clones exist or safe for use across more than one virtual machine. It is up to a user of this method to ensure instance uniqueness in their own local context, using techniques such as transaction management and persistence mapping to a central store.

      The relationship between the current and new instance number for each type of generator is:

      - `InstanceNumberGeneration.LocalRegistration` - The instance high, mid and low bytes are treated as the most significant, middle and least significant bytes of an unsigned 24-bit integer value representing the local registration number of the package id for the given material number. The instance number of the new package id is set to be one greater than current instance number, as returned by `getInstanceNumber()`.
      - `InstanceNumberGeneration.CopyAndPseudoRandom16Bit` - The instance high byte is incremented by one to make the instance high byte of the new package id. If the counter exceeds `255`, an `InstanceOverflowException` is thrown, which gives the caller the option of resetting the counter to `0` or to take their own choice of action. The middle and low instance bytes are set using a random number generator. This implementation ensures that any two consecutive current and new instances do not have the same middle and low instance values.
      - `InstanceNumberGeneration.PseudoRandom24Bit` - The instance high, middle and low values are set using 24 randomly generated bits. The method ensures that any two consecutive current and new instance numbers do not have the same values.
      - `InstanceNumberGeneration.LiveStream` - Not supported by the MAJ API and throws a `GenerationMethodNotSupportedException`.
      - `InstanceNumberGeneration.NotDefined` - Same as `InstanceNumberGeneration.PseudoRandom24Bit`.
      Returns:
        The next package id instance as defined by the instance generation method for this package identifier.
      Throws:
        `InstanceOverflowException` - For methods that increment counters to define the next instance package id, the counter has overflowed.
        `GenerationMethodNotSupportedException` - The instance number generation method is not supported, which is currently the case for the live stream method.
      See Also:
        `getInstanceGenerator()`, `getInstanceNumber()`, `getInstanceHigh()`, `getInstanceMid()`, `getInstanceLow()`

    - #### clone

          PackageID clone()

      Create a cloned copy of this package id.

      Returns:
        Cloned copy of this package id.

    - #### toString

          String toString()

      Formats the value of this package identifier as a URN-style UMID string, starting with "`urn:smpte:umid:`". For example:

      `urn:smpte:umid:060a2b34.01010101.01010f13.1300b347.53b933d9.18245095.ca82322e.c0a801ba`

      Values from this method can be turned back into package identifiers using the `Forge.parsePackageID(String)` method.

      The canonical form of formatted values created by this implementation uses lower case letters for hexadecimal digits.

      Overrides:
        `toString` in class `Object`
      Returns:
        The value of this package id formatted as a URN-style UMID string.
      See Also:
        `Forge.parsePackageID(String)`

    - #### getInstanceGenerator

          InstanceNumberGeneration getInstanceGenerator()

      Returns the instance number generation method for this package identifier.

      Returns:
        Instance number generation method for this package identifier.
      See Also:
        `Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration)`, `Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID)`, `Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])`, `nextInstance()`

    - #### getMaterialNumberGenerator

          MaterialNumberGeneration getMaterialNumberGenerator()

      Returns the material number generation method for this package identifier.

      Returns:
        Material number generation method for this package identifier.
      See Also:
        `Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration)`, `Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, AUID)`, `Forge.generatePackageID(MaterialType, InstanceNumberGeneration, MaterialNumberGeneration, byte[])`

    - #### getInstanceNumber

          @UInt32
          int getInstanceNumber()

      Returns the instance number as an unsigned integer made up from its constituent high, middle and low parts. This method is intended for use with the local registration instance number generation strategy.

      Returns:
        Instance number of this package id represented as an unsigned integer.
      See Also:
        `getInstanceGenerator()`

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