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

tv.amwa.maj.model

## Interface EssenceDescriptor

- All Superinterfaces:
    InterchangeObject, MediaEntity, MetadataObject
  All Known Subinterfaces:
    AAFFileDescriptor, AES3PCMDescriptor, AIFCDescriptor, ANCDataDescriptor, AuxiliaryDescriptor, BWFImportDescriptor, CDCIDescriptor, CDCIDescriptor, DataEssenceDescriptor, FilmDescriptor, HTMLDescriptor, ImportDescriptor, MPEGVideoDescriptor, MultipleDescriptor, PhysicalDescriptor, PictureDescriptor, PictureDescriptor, PolyFileDescriptor, QAAFFileDescriptor, RecordingDescriptor, RGBADescriptor, SoundDescriptor, TapeDescriptor, TapeDescriptor, TIFFDescriptor, VBIDataDescriptor, WAVEDescriptor, WAVEPCMDescriptor, WAVEPCMDescriptor
  All Known Implementing Classes:
    AAFFileDescriptorImpl, AES3PCMDescriptorImpl, AIFCDescriptorImpl, ANCDataDescriptorImpl, AuxiliaryDescriptorImpl, BWFImportDescriptorImpl, CDCIDescriptorImpl, DataEssenceDescriptorImpl, EssenceDescriptorImpl, FilmDescriptorImpl, HTMLDescriptorImpl, ImportDescriptorImpl, MPEGVideoDescriptorImpl, MultipleDescriptorImpl, PhysicalDescriptorImpl, PictureDescriptorImpl, PolyFileDescriptorImpl, RecordingDescriptorImpl, RGBADescriptorImpl, SoundDescriptorImpl, TapeDescriptorImpl, TIFFDescriptorImpl, VBIDataDescriptorImpl, WAVEDescriptorImpl, WAVEPCMDescriptorImpl

      public interface EssenceDescriptor
      extends InterchangeObject

  Specifies the description of the format of the content data associated with a file source package or of the media associated with a physical source package.

  See Also:
    `SourcePackage.getEssenceDescriptor()`, `TypeDefinitions.EssenceDescriptorStrongReference`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendLocator(Locator locator)` Append a locator to the list of locators of this essence descriptors, with each locator having operating-system-dependent data or text information that provide hints for finding files or physical media.
    `void` | `appendSubDescriptor(SubDescriptor subDescriptor)` Append a sub descriptor to the list of sub descriptors of this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy.
    `void` | `clearLocators()` Clear all the locators attached to this essence descriptor, omitting this optional property.
    `EssenceDescriptor` | `clone()` Create a cloned copy of this essence descriptor.
    `int` | `countLocators()` Return the number of locators attached to this essence descriptor, which each have operating-system-dependent data or text information that provide hints for finding files or physical media.
    `int` | `countSubDescriptors()` Returns the number of sub descriptors attached to this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy.
    `Locator` | `getLocatorAt(int index)` Retrieves the locator at the given index, where each locator has operating-system-dependent data or text information that provide hints for finding files or physical media.
    `List<? extends Locator>` | `getLocators()` Returns a list of all the locators in this essence descriptors, where each locator has operating-system-dependent data or text information that provide hints for finding files or physical media.
    `SubDescriptor` | `getSubDescriptorAt(int index)` Returns the sub descriptor at the given index through the list of sub descriptors of this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy.
    `List<? extends SubDescriptor>` | `getSubDescriptors()` Returns the list of sub descriptors of this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy.
    `void` | `insertLocatorAt(int index, Locator locator)` Inserts a locator into the list of locators of this essence descriptors at the given index.
    `void` | `insertSubDescriptorAt(int index, SubDescriptor subDescriptor)` Inserts the given sub descriptor into the list of sub descriptors of this essence descriptor at the given index.
    `void` | `prependLocator(Locator locator)` Prepend a locator to the list of locators of this essence descriptor, with each locator having operating-system-dependent data or text information that provide hints for finding files or physical media.
    `void` | `prependSubDescriptor(SubDescriptor subDescriptor)` Prepend a sub descriptor to the list of sub descriptors of this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy.
    `void` | `removeLocatorAt(int index)` Removes the locator at the given index, where each locator has operating-system-dependent data or text information that provide hints for finding files or physical media.
    `void` | `removeSubDescriptorAt(int index)` Removes the sub descriptor at the given index through the list of sub descriptors of this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy.

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

- - ### Method Detail

    - #### countLocators

          @UInt32
          int countLocators()

      Return the number of locators attached to this essence descriptor, which each have operating-system-dependent data or text information that provide hints for finding files or physical media. The number of locators may be zero if the essence is located within the current file.

      Returns:
        Number of locators in this essence descriptor.

    - #### clearLocators

          void clearLocators()

      Clear all the locators attached to this essence descriptor, omitting this optional property.

    - #### appendLocator

          void appendLocator(Locator locator)
                      throws NullPointerException

      Append a locator to the list of locators of this essence descriptors, with each locator having operating-system-dependent data or text information that provide hints for finding files or physical media. Use this function to add a locator to be scanned last when searching for the essence, providing a secondary location for the essence.

      Parameters:
        `locator` - Locator to append to the list of locators in this essence descriptor.
      Throws:
        `NullPointerException` - The given locator is `null`.

    - #### prependLocator

          void prependLocator(Locator locator)
                       throws NullPointerException

      Prepend a locator to the list of locators of this essence descriptor, with each locator having operating-system-dependent data or text information that provide hints for finding files or physical media. Use this function to add a locator to be scanned first when searching for the essence, providing a new primary location for the essence.

      Parameters:
        `locator` - Locator to prepend to the list of locators in this essence descriptor.
      Throws:
        `NullPointerException`

    - #### insertLocatorAt

          void insertLocatorAt(@UInt32
                               int index,
                               Locator locator)
                        throws NullPointerException,
                               IndexOutOfBoundsException

      Inserts a locator into the list of locators of this essence descriptors at the given index. Each locator has operating-system-dependent data or text information that provide hints for finding files or physical media. The locators already existing at the given and higher indices will be moved to the next higher index to accommodate.

      Parameters:
        `index` - Index at which locator is to be inserted
        `locator` - Locator to insert.
      Throws:
        `NullPointerException` - Argument is null.
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current list of essence descriptors.

    - #### getLocatorAt

          Locator getLocatorAt(@UInt32
                               int index)
                        throws IndexOutOfBoundsException

      Retrieves the locator at the given index, where each locator has operating-system-dependent data or text information that provide hints for finding files or physical media.

      Parameters:
        `index` - Index of locator to retrieve from the list of locators of the essence descriptor.
      Returns:
        Locator at given index.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current list of essence descriptors.

    - #### removeLocatorAt

          void removeLocatorAt(@UInt32
                               int index)
                        throws IndexOutOfBoundsException

      Removes the locator at the given index, where each locator has operating-system-dependent data or text information that provide hints for finding files or physical media. Locators already existing at indices higher than the given index will be moved to the next lower index to accommodate.

      Parameters:
        `index` - Index of locator to remove from the list of locators of this essence descriptor.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current list of essence descriptors.

    - #### getLocators

          List<? extends Locator> getLocators()
                                       throws PropertyNotPresentException

      Returns a list of all the locators in this essence descriptors, where each locator has operating-system-dependent data or text information that provide hints for finding files or physical media. This is an optional property and is omitted when the essence is in the current file.

      Returns:
        A shallow copy of the list of locators in the essence descriptor.
      Throws:
        `PropertyNotPresentException` - No locators are present for this essence descriptor.
      See Also:
        `TypeDefinitions.LocatorStrongReferenceVector`

    - #### countSubDescriptors

          int countSubDescriptors()

      Returns the number of sub descriptors attached to this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy. This list of sub-descriptors may be empty.

      Returns:
        Number of sub descriptors attached to this essence descriptor.

    - #### appendSubDescriptor

          void appendSubDescriptor(SubDescriptor subDescriptor)
                            throws NullPointerException

      Append a sub descriptor to the list of sub descriptors of this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy.

      Parameters:
        `subDescriptor` - Sub descriptor to append to the list of sub descriptors for this essence descriptor.
      Throws:
        `NullPointerException` - The given sub descriptor is `null`.

    - #### prependSubDescriptor

          void prependSubDescriptor(SubDescriptor subDescriptor)
                             throws NullPointerException

      Prepend a sub descriptor to the list of sub descriptors of this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy.

      Parameters:
        `subDescriptor` - Sub descriptor to prepend to the list of sub descriptors for this essence descriptor.
      Throws:
        `NullPointerException` - The sub descriptor argument is `null`.

    - #### insertSubDescriptorAt

          void insertSubDescriptorAt(@UInt32
                                     int index,
                                     SubDescriptor subDescriptor)
                              throws NullPointerException,
                                     IndexOutOfBoundsException

      Inserts the given sub descriptor into the list of sub descriptors of this essence descriptor at the given index. Sub descriptors specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy.

      Parameters:
        `index` - Index at which the sub descriptor should be inserted into the list of sub descriptors of this essence descriptor.
        `subDescriptor` - Sub descriptor to insert.
      Throws:
        `NullPointerException` - The sub descriptor argument is `null`.
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the list of sub descriptors of this essence descriptor.

    - #### getSubDescriptorAt

          SubDescriptor getSubDescriptorAt(@UInt32
                                           int index)
                                    throws IndexOutOfBoundsException

      Returns the sub descriptor at the given index through the list of sub descriptors of this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy.

      Parameters:
        `index` - Index of the sub descriptor value to retrieve.
      Returns:
        Sub descriptor at the given index.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current list of sub descriptors.

    - #### removeSubDescriptorAt

          void removeSubDescriptorAt(@UInt32
                                     int index)
                              throws IndexOutOfBoundsException

      Removes the sub descriptor at the given index through the list of sub descriptors of this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy. Sub descriptors at higher indices will be moved to fill the gap made by the removal.

      Parameters:
        `index` - Index of the sub descriptor to remove.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current list of sub descriptors.

    - #### getSubDescriptors

          List<? extends SubDescriptor> getSubDescriptors()
                                                   throws PropertyNotPresentException

      Returns the list of sub descriptors of this essence descriptor, which specify additional descriptor metadata that is not included in the main essence descriptor class hierarchy. This is an optional property.

      Returns:
        Shallow copy of the list of sub descriptors of this essence descriptor.
      Throws:
        `PropertyNotPresentException` - No sub descriptors are present for this essence descriptor.
      See Also:
        `TypeDefinitions.SubDescriptorStrongReferenceVector`

    - #### clone

          EssenceDescriptor clone()

      Create a cloned copy of this essence descriptor.

      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Returns:
        Cloned copy of this essence descriptor.

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