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

tv.amwa.maj.io.file

## Class EssenceFormat

- java.lang.Object
- - tv.amwa.maj.io.file.EssenceFormat

- All Implemented Interfaces:
    Serializable, EssenceFormat

      public class EssenceFormat
      extends Object
      implements EssenceFormat, Serializable

  TODO implementation, comments and tests

  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `EssenceFormat()` Creates and initializes an empty essence format list.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addFormatSpecifier(AUID essenceFormatCode, byte[] value)` Appends a format specifier to the essence format.
    `static EssenceFormat` | `castFromInterface(EssenceFormat alien)` Cast a `EssenceFormat` value from the generic interface to this implementation of the interface.
    `byte[]` | `getFormatSpecifier(AUID essenceFormatCode)` Data value representing the essence format of the given essence format code.
    `AUIDImpl` | `getIndexedEssenceFormatCode(int index)` Returns the essence format code associated with the format specifier at the given index.
    `byte[]` | `getIndexedFormatSpecifier(int index)` Returns the data value at the given index.
    `int` | `numSpecifiers()` Returns the number of specifiers present in this essence format.

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

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### EssenceFormat

          public EssenceFormat()

      Creates and initializes an empty essence format list.

  - ### Method Detail

    - #### castFromInterface

          public static final EssenceFormat castFromInterface(EssenceFormat alien)
                                                       throws NullPointerException

      Cast a `EssenceFormat` value from the generic interface to this implementation of the interface. If the given value is not a native implementation, a copy will be instanciated using get and set methods.

      Parameters:
        `alien` - A potentially alien implementation of an instance of the EssenceFormat interface.
      Returns:
        Instance of this class that is equal to the given value and that is an instance of this concrete implementation.
      Throws:
        `NullPointerException` - Argument is null.

    - #### addFormatSpecifier

          public void addFormatSpecifier(AUID essenceFormatCode,
                                         byte[] value)
                                  throws NullPointerException

      Description copied from interface: `EssenceFormat`

      Appends a format specifier to the essence format. If a particular essence format code has already been added, then this call replaces the value, otherwise the value is added.

      Specified by:
        `addFormatSpecifier` in interface `EssenceFormat`
      Parameters:
        `essenceFormatCode` - Essence format code (as defined in "`aafdefuids.h`").
        `value` - Data value for format specifier.
      Throws:
        `NullPointerException` - One or more of the arguments is null.
      See Also:
        `EssenceFormat.addFormatSpecifier(tv.amwa.maj.record.AUID, byte[])`

    - #### getFormatSpecifier

          public byte[] getFormatSpecifier(AUID essenceFormatCode)
                                    throws NullPointerException

      Description copied from interface: `EssenceFormat`

      Data value representing the essence format of the given essence format code.

      Specified by:
        `getFormatSpecifier` in interface `EssenceFormat`
      Parameters:
        `essenceFormatCode` - Essence format code (as defined in "`aafdefuids.h`").
      Returns:
        Corresponding data value.
      Throws:
        `NullPointerException` - Argument is null.
      See Also:
        `EssenceFormat.getFormatSpecifier(tv.amwa.maj.record.AUID)`

    - #### getIndexedEssenceFormatCode

          public AUIDImpl getIndexedEssenceFormatCode(int index)
                                               throws IndexOutOfBoundsException

      Description copied from interface: `EssenceFormat`

      Returns the essence format code associated with the format specifier at the given index.

      Specified by:
        `getIndexedEssenceFormatCode` in interface `EssenceFormat`
      Parameters:
        `index` - 0-based index for the format specifier to retrieve.
      Returns:
        Corresponding essence format code.
      Throws:
        `IndexOutOfBoundsException` - The specified index is outside the acceptable range for the current number of specifiers.
      See Also:
        `EssenceFormat.getIndexedEssenceFormatCode(int)`

    - #### getIndexedFormatSpecifier

          public byte[] getIndexedFormatSpecifier(int index)
                                           throws IndexOutOfBoundsException

      Description copied from interface: `EssenceFormat`

      Returns the data value at the given index.

      Specified by:
        `getIndexedFormatSpecifier` in interface `EssenceFormat`
      Parameters:
        `index` - 0-based index for the format specifier to retrieve.
      Returns:
        Data value of the format specifier.
      Throws:
        `IndexOutOfBoundsException` - The specified index is outside the acceptable range for the current number of specifiers.
      See Also:
        `EssenceFormat.getIndexedFormatSpecifier(int)`

    - #### numSpecifiers

          public int numSpecifiers()

      Description copied from interface: `EssenceFormat`

      Returns the number of specifiers present in this essence format.

      Specified by:
        `numSpecifiers` in interface `EssenceFormat`
      Returns:
        Number of specifiers in this essence format.
      See Also:
        `EssenceFormat.numSpecifiers()`

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