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

tv.amwa.maj.record.impl

## Class PackageIDImpl

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

- All Implemented Interfaces:
    Serializable, Cloneable, XMLSerializable, PackageID

      public final class PackageIDImpl
      extends Object
      implements PackageID, Serializable, XMLSerializable, Cloneable

  Implementation of a 32 byte package id unique identifier that can hold a SMPTE UMID, as specified in SMPTE 330M. Material object identifiers represented by this class are 32-byte - yes, byte - numbers that can be generated at source with a high degree of likelihood that two independently generated identifiers will not clash. For most systems, package ids are and should be treated as dumb numbers whose bit pattern structure is of no significance. However, for the purposes of id generation and consistent representation between systems, a package id can be viewed as consisting of:

  - a universal label defining the representation of the identifier;
  - a length value;
  - a material number;
  - an instance number representing the version of the material.

  One common form of package id is the SMPTE Unique Material Identifier (UMID), as defined in SMPTE S330M-2004. A number of helper methods are provided that allow the package id to be created and managed as a UMID, including a factory method (`umidFactory()`) and the ability to generate the next UMID instance number for an existing piece of material (`nextInstance()`). To decrease the likelihood of two UMIDs being the same within a network of systems, the adoption of the same material number generation and instance number generation schemes is advisable.

  A package id can be represented as a string in four sections, consisting of the universal label, followed by the length, then instance number and finally the material number. It is an informal convention that the string representation of a UMID, which is generated by a call to `toString()`, starts with "`urn:x-umid:`". For example:

  `urn:x-umid:060a2b340101010101010f13-13-0098ef-4dfc94b90124509571af322ec0a801ba`

  The value above is structured according to the SMPTE UMID specification as follows:

  `urn:x-umid:`<label>`-`<length>`-`<instance number>`-`<material number>

  This class does not represent SMPTE extended UMIDs, which are 64 bytes in length.

  Package ids can be used as embeddable identifiers for entities that represent material. The internal representation of a package id is a 32 byte array, which can be accessed with the `getPackageIDValue()` method and set using the `setPackageIDValue(byte[])` method. A database column defined to hold a package id may be defined as follows:

           `PackageID` binary(32) NOT NULL

  All methods assume network byte order.

  Package ids were previously known as package ids and may still be referred to as such in AAF-specific documentation.

  See Also:
    `AUIDImpl`, `TypeDefinitions.PackageIDType`, `PackageIDType`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `MYSQL_COLUMN_DEFINITION`
    `static char[]` | `persistTemplate`

    - ### Fields inherited from interface tv.amwa.maj.record.PackageID

      `BaseUniversalLabel`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PackageIDImpl()` Generate a new package id using a secure random number generator.
    `PackageIDImpl(byte[] packageID)` Creates a new package id from an array of bytes.
    `PackageIDImpl(byte[] label, byte length, byte instanceHigh, byte instanceMid, byte instanceLow, AUID material)` Create a new package id from the specified parameters.

  - ### 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.
    `PackageID` | `clone()` Create a cloned copy of this package id.
    `static PackageID` | `createFromBuffer(ByteBuffer buffer)`
    `boolean` | `equals(Object o)`
    `static PackageID` | `fromPersistentForm(String packageID)`
    `static void` | `generateEmbeddableORM(Node parent, String namespace, String prefix)`
    `static void` | `generateEmbeddedORM(Node parent, String ownerName, String namespace, String prefix)`
    `static byte[]` | `getBaseUniversalLabel()` Returns a base universal label that identifies a package id as compatible with the SMPTE Unique Material Identifier (UMID) specification, as documented in SMPTE 330M.
    `String` | `getComment()` Include a comment when serializing a value to XML.
    `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.
    `MaterialType` | `getMaterialType()` Returns the material type for this package id.
    `byte[]` | `getPackageIDValue()` Returns a copy of all 32 bytes representing the value of this package id as a byte array.
    `byte[]` | `getUniversalLabel()` Returns the universal label that makes up bytes 1 to 12 of a package id.
    `static PackageID` | `getZeroPackageID()` Returns a copy of the zero package id, for which every component byte of the package id is set to 0.
    `int` | `hashCode()`
    `boolean` | `isZero()` Returns `true` if this package identifier the special zero package identifier, where all 32-bytes of the identifier are zero; otherwise `false`.
    `static long` | `lengthAsBuffer(PackageID packageID)`
    `PackageID` | `nextInstance()` Returns a new package id with the same material number as this one and a newly created instance number.
    `static PackageIDImpl` | `parseFactory(String packageIdURN)` Parse a package id formatted as a URN-style UMID string and convert it into a newly instantiated package id with an equivalent value.
    `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` | `setPackageIDValue(byte[] packageID)` Sets the value of this package id using the given byte array, which should contain 32 bytes of data.
    `void` | `setUniversalLabel(byte[] label)` Sets the universal label that makes up bytes 1 to 12 of a package id.
    `static String` | `toPersistentForm(PackageID packageID)`
    `String` | `toString()` Formats the value of this package id as a URN-style UMID string, starting with "`urn:smpte:umid:`".
    `static PackageIDImpl` | `umidFactory(MaterialType materialType, MaterialNumberGeneration materialNumberGeneration, InstanceNumberGeneration instanceNumberGeneration, byte[] extraData)` Factory that manufactures new package ids according to the given SMPTE UMID generation specification.
    `static void` | `writeToBuffer(PackageID packageID, ByteBuffer buffer)`

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

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

- - ### Field Detail

    - #### persistTemplate

          public static final char[] persistTemplate

    - #### MYSQL_COLUMN_DEFINITION

          public static final String MYSQL_COLUMN_DEFINITION

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PackageIDImpl

          public PackageIDImpl(byte[] label,
                               @UInt8
                               byte length,
                               @UInt8
                               byte instanceHigh,
                               @UInt8
                               byte instanceMid,
                               @UInt8
                               byte instanceLow,
                               AUID material)
                        throws NullPointerException

      Create a new package id from the specified parameters. The label and material values are copied to ensure that subsequent external changes do not effect the newly created package id.

      A default universal label to set the package id to be a SMPTE UMID is available by calling `getBaseUniversalLabel()`.

      Note that this method does not generate a new package id, it creates one using the given parameters. To generate values, use `#PackageID()` or the UMID factory method.

      Parameters:
        `label` - Universal label component of the package id.
        `length` - Length of the following data.
        `instanceHigh` - Most significant part of the instance number component of the package id.
        `instanceMid` - Second most significant part the instance number component of the package id.
        `instanceLow` - Least significant part of the instance number component of the package id.
        `material` - Unique identifier for the identified material, the material number component of the package id.
      Throws:
        `NullPointerException`

    - #### PackageIDImpl

          public PackageIDImpl(byte[] packageID)
                        throws NullPointerException

      Creates a new package id from an array of bytes. The array should be 32 bytes in length and prepared to be considered as a package id. If the array is too short or too long, it will be padded with 0s or truncated to make it 32 bytes. The passed array value is cloned to avoid external changes to the array affecting this value.

      Parameters:
        `packageID` - Byte array to use to create a new package id value.
      Throws:
        `NullPointerException` - The given byte array is `null`.
      See Also:
        `setPackageIDValue(byte[])`, `getPackageIDValue()`

    - #### PackageIDImpl

          public PackageIDImpl()

      Generate a new package id using a secure random number generator. The value created is a SMPTE UMID with the following properties:

      - The material type is set to not identified;
      - The material number generation method is set to not defined and the material number is generated using a 128 bit secure random number generator;
      - The instance number generation method is set to pseudo-random 24 bit and the instance number is generated using a 24 bit secure random number generator.

      This method is provided as a quick way to generate a package id. Statistically, it is highly unlikely that package ids generated this way will clash with one another . For more control over generating globally unique package ids, use the UMID factory method.

  - ### Method Detail

    - #### getBaseUniversalLabel

          public static final byte[] getBaseUniversalLabel()

      Returns a base universal label that identifies a package id as compatible with the SMPTE Unique Material Identifier (UMID) specification, as documented in SMPTE 330M. This default label has:

      - a material type of not identified, which is stored as the 11th byte of the label;
      - a material number generation type set to not defined, which is stored as the upper nibble of the 12th byte of the label;
      - an instance number generation type set to not defined, which is stored as the lower nibble of the 12th byte of the label.
      Returns:
        A universal label that identifies a package id as a SMPTE UMID.
      See Also:
        `getUniversalLabel()`, `setUniversalLabel(byte[])`

    - #### getZeroPackageID

          public static final PackageID getZeroPackageID()

      Returns a copy of the zero package id, for which every component byte of the package id is set to 0. The zero package id is used as a flag in certain properties, such as to indicate that a source clip is the original source.

      Returns:
        Copy of the zero package id.
      See Also:
        `isZero()`, `AUIDImpl.isNil()`, `SourceReferenceValueImpl.isOriginalSource()`

    - #### umidFactory

          public static final PackageIDImpl umidFactory(MaterialType materialType,
                                                        MaterialNumberGeneration materialNumberGeneration,
                                                        InstanceNumberGeneration instanceNumberGeneration,
                                                        byte[] extraData)
                                                 throws GenerationMethodNotSupportedException,
                                                        NullPointerException

      Factory that manufactures new package ids according to the given SMPTE UMID generation specification.

      Some of the generation methods documented in appendix A of SMPTE 330M are difficult to support in Java as the core API does not support all the required features, such as access to the ethernet address of a system. This additional data can be provided using the extra data parameter, as described below. Results produced by this factory are only as good as the extra data provided and so this factory method should be considered as not fully compliant with SMPTE 330M.

      The supported material number generation methods are as follows:

      - `MaterialNumberGeneration.SMPTE` - Creates a material number from the system clock, current date, a two byte random number and a 6 byte system identifier. This approach is documented in section A.1 of SMPTE 330M and should ensure a high degree of identifier uniqueness. The system identifier must be provided as the first 6 bytes of the extra data parameter. Java 1.5 does not provide a means to extract the ethernet address of the system on which a virtual machine is running but a locally administered value that is a combination of bytes taken from the system's IP address and domain name should be sufficient. Just such a value is provided by calling `Utilities.createLocalHostID(6)`.
      - `MaterialNumberGeneration.UUID_UL` - Generates a material number from the UUID or universal label provided as the 16 bytes passed as the extra data parameter. The method assumes that the byte reordering documented in section A.2 of SMPTE 330M has already taken place. No validation of the UUID or universal label is carried out. In fact, this method is implemented here as a dumb pass through of the given value directly to the 16-bytes of the material number of the new package id.
      - `MaterialNumberGeneration.Masked` - Generates a material number according to the SMPTE method and then uses an MD5 function on the value to mask the details, as described in section A.3 of SMPTE 330M. This masking is normally done for security reasons so as to hide details of creation times and systems identification. Once masked, the time and host id values cannot be easily recovered and the masking function ensures the same degree of uniqueness as the SMPTE method.
      - `MaterialNumberGeneration.IEEE1394` - Generates a material number according to the IEEE 1394 network method, as described in section A.4 of SMPTE 330M. The first 8 bytes are generated from the system clock, current date and a random number. The last 8 bytes are the device node identifier that must be provided as the extra bytes parameter. The device node of the system on which the virtual machine is running is not available in the core Java API version 1.5. A locally derived host identifier created from the system's IP address and domain name can be generated by calling `Utilities.createLocalHostID(8)`.
      - `MaterialNumberGeneration.NotDefined` - A pseudo random number is generated for the 128-bits of data representing the material number, using the `SecureRandom` class.

      The supported instance generation methods are documented in more detail in `nextInstance()`, with the instance number initialized as follows:

      - `InstanceNumberGeneration.LocalRegistration` - All three instance bytes are set to zero.
      - `InstanceNumberGeneration.CopyAndPseudoRandom16Bit` - The instance high byte is set to 0 and the other two bytes are set to random values.
      - `InstanceNumberGeneration.PseudoRandom24Bit` - The instance high, middle and low values are set using 24 randomly generated bits.
      - `InstanceNumberGeneration.LiveStream` - Not supported and throws a `GenerationMethodNotSupportedException`.
      - `InstanceNumberGeneration.NotDefined` - Same as PseudoRandom24Bit.

      The chosen type of instance number generated will define the behaviour of subsequent calls to `nextInstance()` for the new package id.

      Parameters:
        `materialType` - Type of material represented by the new package id.
        `materialNumberGeneration` - Method to use to generate the material number of the package id.
        `instanceNumberGeneration` - Method to use to generate the first and next instance numbers for the package id.
        `extraData` - Additional data required by the material number generation method.
      Returns:
        Newly manufactured package id, which is a SMPTE UMID according to the given specification.
      Throws:
        `GenerationMethodNotSupportedException` - The given material or instance number generation method is not supported.
        `NullPointerException` - One or more of the arguments is `null` and all are required.

    - #### getPackageIDValue

          public final byte[] getPackageIDValue()

      Returns a copy of all 32 bytes representing the value of this package id as a byte array. The internal representation of a package id in the MAJ API is as a 32-byte array.

      Returns:
        Copy of the 32-byte value of this package id.

    - #### setPackageIDValue

          public final void setPackageIDValue(byte[] packageID)
                                       throws NullPointerException

      Sets the value of this package id using the given byte array, which should contain 32 bytes of data. If the array is smaller than required, it will be padded with zeros. If the array is larger than required, it will be truncated. The given array is cloned so that subsequent changes do not affect the internal representation within this package id.

      Parameters:
        `packageID` - Data to use to set the value of this package id.
      Throws:
        `NullPointerException` - The given package id data is `null`.
      See Also:
        `#PackageID(byte[])`

    - #### getUniversalLabel

          public final byte[] getUniversalLabel()

      Description copied from interface: `PackageID`

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

      Specified by:
        `getUniversalLabel` in interface `PackageID`
      Returns:
        Universal label component of the package id.
      See Also:
        `getBaseUniversalLabel()`

    - #### setUniversalLabel

          public final void setUniversalLabel(byte[] label)
                                       throws NullPointerException

      Description copied from interface: `PackageID`

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

      Specified by:
        `setUniversalLabel` in interface `PackageID`
      Parameters:
        `label` - Universal label component of the package id.
      Throws:
        `NullPointerException` - The given universal label for this package id is `null`.
      See Also:
        `getBaseUniversalLabel()`

    - #### getLength

          @UInt8
          public final byte getLength()

      Description copied from interface: `PackageID`

      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.

      Specified by:
        `getLength` in interface `PackageID`
      Returns:
        Length component of the package id.

    - #### setLength

          public final void setLength(@UInt8
                                      byte length)

      Description copied from interface: `PackageID`

      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.

      Specified by:
        `setLength` in interface `PackageID`
      Parameters:
        `length` - Length component of the package id.

    - #### getInstanceNumber

          @UInt32
          public final int getInstanceNumber()

      Description copied from interface: `PackageID`

      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.

      Specified by:
        `getInstanceNumber` in interface `PackageID`
      Returns:
        Instance number of this package id represented as an unsigned integer.
      See Also:
        `PackageID.getInstanceGenerator()`

    - #### getInstanceHigh

          @UInt8
          public final byte getInstanceHigh()

      Description copied from interface: `PackageID`

      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.

      Specified by:
        `getInstanceHigh` in interface `PackageID`
      Returns:
        Most significant byte of the instance number component of the package id.

    - #### setInstanceHigh

          public final void setInstanceHigh(@UInt8
                                            byte instanceHigh)

      Description copied from interface: `PackageID`

      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.

      Specified by:
        `setInstanceHigh` in interface `PackageID`
      Parameters:
        `instanceHigh` - Most significant byte of the instance number component of the package id.

    - #### getInstanceMid

          @UInt8
          public final byte getInstanceMid()

      Description copied from interface: `PackageID`

      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.

      Specified by:
        `getInstanceMid` in interface `PackageID`
      Returns:
        Middle byte of the instance number component of the package id.

    - #### setInstanceMid

          public final void setInstanceMid(@UInt8
                                           byte instanceMid)

      Description copied from interface: `PackageID`

      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.

      Specified by:
        `setInstanceMid` in interface `PackageID`
      Parameters:
        `instanceMid` - Middle byte of the instance number component of the package id.

    - #### getInstanceLow

          @UInt8
          public final byte getInstanceLow()

      Description copied from interface: `PackageID`

      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.

      Specified by:
        `getInstanceLow` in interface `PackageID`
      Returns:
        Least significant byte of the instance number component of the package id.

    - #### setInstanceLow

          public final void setInstanceLow(@UInt8
                                           byte instanceLow)

      Description copied from interface: `PackageID`

      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.

      Specified by:
        `setInstanceLow` in interface `PackageID`
      Parameters:
        `instanceLow` - Least significant byte of the instance number component of the package id.

    - #### getMaterial

          public final AUID getMaterial()

      Description copied from interface: `PackageID`

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

      Specified by:
        `getMaterial` in interface `PackageID`
      Returns:
        Material number component of the package id.

    - #### setMaterial

          public final void setMaterial(AUID material)
                                 throws NullPointerException

      Description copied from interface: `PackageID`

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

      Specified by:
        `setMaterial` in interface `PackageID`
      Parameters:
        `material` - Material number component of the package id
      Throws:
        `NullPointerException` - The given material number is `null`.

    - #### isZero

          public final boolean isZero()

      Description copied from interface: `PackageID`

      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.

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

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public final String toString()

      Formats the value of this package id 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 ids using the `parseFactory(String)` static method. The canonical form of formatted values created by this implementation uses lower case letters for hexadecimal digits.

      Specified by:
        `toString` in interface `PackageID`
      Overrides:
        `toString` in class `Object`
      Returns:
        The value of this package id formatted as a URN-style UMID string.
      See Also:
        `Object.toString()`, `parseFactory(String)`

    - #### parseFactory

          public static final PackageIDImpl parseFactory(String packageIdURN)
                                                  throws NullPointerException,
                                                         ParseException

      Parse a package id formatted as a URN-style UMID string and convert it into a newly instantiated package id with an equivalent value. The format of the expected value is the same as that generated by the `toString()` method, for example:

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

      Hexadecimal digits used to express the UMID value may be a mixture of upper or lower case letters.

      Parameters:
        `packageIdURN` - Package id value formatted as a URN-style UMID string.
      Returns:
        Package id created from the given URN-style UMID value.
      Throws:
        `NullPointerException` - The package id urn argument is `null`.
        `ParseException` - The given URN value is the wrong length, a different kind or URN, has path separators in the wrong place or contains digits other than hexadecimal digits where hexadecimal digits are expected.
      See Also:
        `toString()`

    - #### clone

          public final PackageID clone()

      Description copied from interface: `PackageID`

      Create a cloned copy of this package id.

      Specified by:
        `clone` in interface `PackageID`
      Overrides:
        `clone` in class `Object`
      Returns:
        Cloned copy of this package id.

    - #### equals

          public final boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### getMaterialNumberGenerator

          public final MaterialNumberGeneration getMaterialNumberGenerator()

      Returns the material number generation method for this package identifier.

      Specified by:
        `getMaterialNumberGenerator` in interface `PackageID`
      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[])`

    - #### getInstanceGenerator

          public final InstanceNumberGeneration getInstanceGenerator()

      Description copied from interface: `PackageID`

      Returns the instance number generation method for this package identifier.

      Specified by:
        `getInstanceGenerator` in interface `PackageID`
      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[])`, `PackageID.nextInstance()`

    - #### getMaterialType

          public final MaterialType getMaterialType()

      Returns the material type for this package id. This value only makes sense if the package id is a SMPTE UMID.

      Returns:
        Material type for this package id.
      See Also:
        `umidFactory(MaterialType, MaterialNumberGeneration, InstanceNumberGeneration, byte[])`

    - #### nextInstance

          public final PackageID nextInstance()
                                       throws InstanceOverflowException,
                                              GenerationMethodNotSupportedException

      Returns a new package id 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 id's universal label and can be found by calling `getInstanceGenerator()`.

      The package ids 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`.
      Specified by:
        `nextInstance` in interface `PackageID`
      Returns:
        The next package id instance as defined by the instance generation method for this package id.
      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()`

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

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

    - #### createFromBuffer

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

      Throws:
        `NullPointerException`
        `EndOfDataException`

    - #### lengthAsBuffer

          public static final long lengthAsBuffer(PackageID packageID)
                                           throws NullPointerException

      Throws:
        `NullPointerException`

    - #### writeToBuffer

          public static final void writeToBuffer(PackageID packageID,
                                                 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(PackageID packageID)

    - #### fromPersistentForm

          public static final PackageID fromPersistentForm(String packageID)

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