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

tv.amwa.maj.model

## Interface CodecDefinition

- All Superinterfaces:
    DefinitionObject, InterchangeObject, MediaEntity, MetadataObject, WeakReferenceTarget
  All Known Implementing Classes:
    CodecDefinitionImpl

      public interface CodecDefinition
      extends DefinitionObject

  Specifies the definition of an essence codec. A codec is a program or system capable of performing encoding and decoding on a digital data stream, which is often the case for the data streams represented by essence data in the MAJ API.

  See Also:
    `CodecConstant`, `CodecFlavour`, `Warehouse.lookup(Class, String)`, `Dictionary.getCodecDefinitions()`, `AAFFileDescriptor.getCodec()`, `TypeDefinitions.CodecDefinitionWeakReference`, `TypeDefinitions.CodecDefinitionStrongReference`, `TypeDefinitions.CodecDefinitionStrongReferenceSet`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendEssenceKind(DataDefinition essenceKind)` Appends the given essence kind to the list of those supported by the codec, which specify the data definitions of the essence formats that the defined codec processes.
    `void` | `clearEssenceKinds()` Clears the list of essence kinds for this codec definition.
    `CodecDefinition` | `clone()` Create a cloned copy of this codec definition.
    `int` | `countEssenceKinds()` Returns the number of supported essence kinds of this codec definition, which specify the data definitions of the essence formats that the defined codec processes.
    `DataDefinition` | `getEssenceKindAt(int index)` Returns the essence kind at the given index in the list of supported essence kinds of this codec.
    `List<? extends DataDefinition>` | `getEssenceKinds()` Returns a set of the essence kinds for the defined codec, which specify the data definitions of the essence formats that the defined codec processes.
    `ClassDefinition` | `getFileDescriptorClass()` Returns the file descriptor class object associated with the defined codec, which specifies the class definition of the sub-class of file descriptor that identifies the essence format that the defined codec processes.
    `void` | `insertEssenceKind(int index, DataDefinition essenceKind)` Inserts the given essence kind to the list of those supported by the codec at the given index.
    `boolean` | `isEssenceKindSupported(DataDefinition essenceKind)` Returns `true` if the given codec supports transfers to essence of the given essence kind.
    `void` | `prependEssenceKind(DataDefinition essenceKind)` Prepends the given essence kind to the list of those supported by the codec, which specify the data definitions of the essence formats that the defined codec processes.
    `void` | `removeEssenceKind(DataDefinition essenceKind)` Removes the given essence kind from the list of those supported by the codec, which specify the data definitions of the essence formats that the defined codec processes.
    `void` | `removeEssenceKindAt(int index)` Removes the essence kind at the given index in the list of essence kinds for this codec definition.
    `void` | `setFileDescriptorClass(ClassDefinition fileClass)` Sets the file descriptor class associated with this codec, which specifies the class definition of the sub-class of `FileDescriptor` that identifies the essence format that the defined codec processes.

    - ### Methods inherited from interface tv.amwa.maj.model.DefinitionObject

      `getAUID, getDescription, getName, setDescription, setName`

    - ### Methods inherited from interface tv.amwa.maj.model.InterchangeObject

      `addApplicationPlugin, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getGeneration, getLinkedGenerationID, getObjectClass, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setObjectClass, toString`

    - ### Methods inherited from interface tv.amwa.maj.industry.MediaEntity

      `getPersistentID, setPersistentIndex`

    - ### Methods inherited from interface tv.amwa.maj.industry.WeakReferenceTarget

      `getWeakTargetReference`

- - ### Method Detail

    - #### isEssenceKindSupported

          @Bool
          boolean isEssenceKindSupported(DataDefinition essenceKind)
                                        throws NullPointerException

      Returns `true` if the given codec supports transfers to essence of the given essence kind.

      Parameters:
        `essenceKind` - The essence kind to test.
      Returns:
        Is this essence kind supported by the codec?
      Throws:
        `NullPointerException` - The given essence kind is `null`.
      See Also:
        `DataDefinitionConstant`

    - #### appendEssenceKind

          void appendEssenceKind(DataDefinition essenceKind)
                          throws NullPointerException,
                                 DuplicateEssenceKindException

      Appends the given essence kind to the list of those supported by the codec, which specify the data definitions of the essence formats that the defined codec processes. The content of the list is dependent upon the specified format for the codec, not on whether an implementation supports all parts of the format.

      Parameters:
        `essenceKind` - The essence kind to append.
      Throws:
        `NullPointerException` - The given essence kind is `null`.
        `DuplicateEssenceKindException` - The given essence kind is already contained.
      See Also:
        `prependEssenceKind(DataDefinition)`, `insertEssenceKind(int, DataDefinition)`, `DataDefinitionConstant`

    - #### prependEssenceKind

          void prependEssenceKind(DataDefinition essenceKind)
                           throws NullPointerException,
                                  DuplicateEssenceKindException

      Prepends the given essence kind to the list of those supported by the codec, which specify the data definitions of the essence formats that the defined codec processes. The content of the list is dependent upon the specified format for the codec, not on whether an implementation supports all parts of the format.

      Parameters:
        `essenceKind` - The essence kind to prepend.
      Throws:
        `NullPointerException` - The given essence kind is `null`.
        `DuplicateEssenceKindException` - The given essence kind is already contained.
      See Also:
        `appendEssenceKind(DataDefinition)`, `insertEssenceKind(int, DataDefinition)`, `DataDefinitionConstant`

    - #### insertEssenceKind

          void insertEssenceKind(int index,
                                 DataDefinition essenceKind)
                          throws NullPointerException,
                                 DuplicateEssenceKindException,
                                 IndexOutOfBoundsException

      Inserts the given essence kind to the list of those supported by the codec at the given index. Essence kinds specify the data definitions of the essence formats that the defined codec processes. The content of the list is dependent upon the specified format for the codec, not on whether an implementation supports all parts of the format.

      Parameters:
        `index` - Index in the list where the essence kind is to be inserted.
        `essenceKind` - The essence kind to insert.
      Throws:
        `NullPointerException` - The given essence kind is `null`.
        `DuplicateEssenceKindException` - The given essence kind is already contained.
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current list of supported essence kinds.
      See Also:
        `appendEssenceKind(DataDefinition)`, `prependEssenceKind(DataDefinition)`, `DataDefinitionConstant`

    - #### getEssenceKindAt

          DataDefinition getEssenceKindAt(int index)
                                   throws IndexOutOfBoundsException

      Returns the essence kind at the given index in the list of supported essence kinds of this codec.

      Parameters:
        `index` - Index of the essence kind to retrieve.
      Returns:
        Data definition defining the essence kind at the given index.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current list of supported essence kinds.
      See Also:
        `getEssenceKinds()`

    - #### clearEssenceKinds

          void clearEssenceKinds()

      Clears the list of essence kinds for this codec definition. Note that the list of essence kinds is a required property and so a call to this method should be followed by a call to add another essence kind.

    - #### removeEssenceKind

          void removeEssenceKind(DataDefinition essenceKind)
                          throws NullPointerException,
                                 ObjectNotFoundException,
                                 IllegalArgumentException

      Removes the given essence kind from the list of those supported by the codec, which specify the data definitions of the essence formats that the defined codec processes.

      Parameters:
        `essenceKind` - The essence kind to remove.
      Throws:
        `NullPointerException` - Argument is null.
        `ObjectNotFoundException` - The given kind of essence is not already contained.
        `IllegalArgumentException` - Cannot remove an item from the set if it will become empty.
      See Also:
        `removeEssenceKindAt(int)`, `DataDefinitionConstant`

    - #### removeEssenceKindAt

          void removeEssenceKindAt(int index)
                            throws IndexOutOfBoundsException

      Removes the essence kind at the given index in the list of essence kinds for this codec definition.

      Parameters:
        `index` - Index of the essence kind to remove.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current list of supported essence kinds.
      See Also:
        `removeEssenceKind(DataDefinition)`

    - #### countEssenceKinds

          @UInt32
          int countEssenceKinds()

      Returns the number of supported essence kinds of this codec definition, which specify the data definitions of the essence formats that the defined codec processes.

      Returns:
        The number of supported essence kinds.

    - #### getEssenceKinds

          List<? extends DataDefinition> getEssenceKinds()

      Returns a set of the essence kinds for the defined codec, which specify the data definitions of the essence formats that the defined codec processes.

      Returns:
        Shallow copy of a set of the essence kinds that the defined codec processes.
      See Also:
        `getEssenceKindAt(int)`, `DataDefinitionConstant`, `TypeDefinitions.DataDefinitionWeakReferenceSet`, `TypeDefinitions.DataDefinitionWeakReferenceVector`

    - #### getFileDescriptorClass

          ClassDefinition getFileDescriptorClass()

      Returns the file descriptor class object associated with the defined codec, which specifies the class definition of the sub-class of file descriptor that identifies the essence format that the defined codec processes.

      Returns:
        The class definition of the sub-class of `FileDescriptor` that identifies the essence format that the defined codec processes.

    - #### setFileDescriptorClass

          void setFileDescriptorClass(ClassDefinition fileClass)
                               throws NullPointerException,
                                      IllegalArgumentException

      Sets the file descriptor class associated with this codec, which specifies the class definition of the sub-class of `FileDescriptor` that identifies the essence format that the defined codec processes.

      Parameters:
        `fileClass` - Specifies the class definition of the sub-class of `AAFFileDescriptor` that identifies the essence format that the defined codec processes.
      Throws:
        `NullPointerException` - The given class definition for a sub-class of file descriptor is `null`.
        `IllegalArgumentException` - The given class definition is not for a sub-class of `FileDescriptor`.
      See Also:
        `CodecConstant`

    - #### clone

          CodecDefinition clone()

      Create a cloned copy of this codec definition.

      Specified by:
        `clone` in interface `DefinitionObject`
      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Returns:
        Cloned copy of this codec definition.

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