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

tv.amwa.maj.model

## Interface EssenceGroup

- All Superinterfaces:
    Component, InterchangeObject, MediaEntity, MetadataObject, Segment
  All Known Implementing Classes:
    EssenceGroupImpl

      public interface EssenceGroup
      extends Segment

  Specifies the description of multiple digital representations of the same original content source. The essence type and length of all choices must be the same.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendChoice(Segment choice)` Append a choice to the collection of segment choices of this essence group, which identify the alternate representations that may be chosen.
    `EssenceGroup` | `clone()` Create a cloned copy of this essence group.
    `int` | `countChoices()` Returns the number of choices in the collection of alternates of this essence group, which identify the alternate representations that may be chosen.
    `Segment` | `getChoiceAt(int index)` Returns the source clip choice at the given index in the collection of choices of this essence group, which identify the alternate representations that may be chosen.
    `List<Segment>` | `getChoices()` Returns the list of segment choices of this essence group, which identify the alternate representations that may be chosen.
    `SourceReferenceSegment` | `getStillFrame()` Gets the still frame property of this essence group, which identifies the essence for a single-frame image representation of the group.
    `void` | `insertChoiceAt(int index, Segment choice)` Insert another choice to the collections of choices of this essence group at the given index.
    `void` | `prependChoice(Segment choice)` Prepend a choice to the collection of segment choices of this essence group, which identify the alternate representations that may be chosen.
    `void` | `removeChoiceAt(int index)` Removes the choice at the given index in the collection of choices of this essence group, which identify the alternate representations that may be chosen.
    `void` | `setStillFrame(SourceReferenceSegment stillFrame)` Sets the still frame property of this essence group, which identifies the essence for a single-frame image representation of the group.

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

      `generateSequence, segmentOffsetToTC, segmentTCToOffset`

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

      `appendComponentAttribute, appendComponentAttribute, appendComponentKLVData, appendComponentUserComment, appendComponentUserComment, clearComponentAttributes, clearComponentKLVData, clearComponentUserComments, countComponentAttributes, countComponentKLVData, countComponentUserComments, getComponentAttributes, getComponentDataDefinition, getComponentKLVData, getComponentLength, getComponentUserComments, getLengthPresent, removeComponentAttribute, removeComponentKLVData, removeComponentUserComment, setComponentDataDefinition, setComponentLength, setLengthPresent`

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

    - #### setStillFrame

          void setStillFrame(SourceReferenceSegment stillFrame)
                      throws InvalidDataDefinitionException,
                             BadLengthException

      Sets the still frame property of this essence group, which identifies the essence for a single-frame image representation of the group. Call this method with `null` to omit this optional property.

      Parameters:
        `stillFrame` - Still frame representation for the essence group.
      Throws:
        `InvalidDataDefinitionException` - The given source clip does not have a compatible data definition that can convert to the data definition of this essence group.
        `BadLengthException` - The given source reference segment does not represent a still frame with a length of exactly 1.

    - #### getStillFrame

          SourceReferenceSegment getStillFrame()
                                        throws PropertyNotPresentException

      Gets the still frame property of this essence group, which identifies the essence for a single-frame image representation of the group. This is an optional property.

      Returns:
        Still frame representation of this essence group.
      Throws:
        `PropertyNotPresentException` - The still frame property is not present within this essence group.
      See Also:
        `TypeDefinitions.SourceReferenceStrongReference`

    - #### getChoices

          List<Segment> getChoices()

      Returns the list of segment choices of this essence group, which identify the alternate representations that may be chosen. The order of the items in the collection is not necessarily meaningful.

      Returns:
        List of segment choices of this essence group.
      See Also:
        `getChoiceAt(int)`

    - #### appendChoice

          void appendChoice(Segment choice)
                     throws NullPointerException,
                            InvalidDataDefinitionException,
                            BadLengthException

      Append a choice to the collection of segment choices of this essence group, which identify the alternate representations that may be chosen. The order of the items in the collection is not necessarily meaningful.

      The segment shall either be a source clip or a sequence. If the segment is a sequence, it shall contain only source clip and filler objects.

      Parameters:
        `choice` - Segment to add in as a choice to the collection of choices of this essence group.
      Throws:
        `NullPointerException` - The given segment choice is `null`.
        `InvalidDataDefinitionException` - The data definition of the given segment does not convert to an acceptable definition for this group.
        `BadLengthException` - The length of the given segment is different to the length of other choices of this group.

    - #### prependChoice

          void prependChoice(Segment choice)
                      throws NullPointerException,
                             InvalidDataDefinitionException,
                             BadLengthException

      Prepend a choice to the collection of segment choices of this essence group, which identify the alternate representations that may be chosen. The order of the items in the collection is not necessarily meaningful.

      The segment shall either be a source clip or a sequence. If the segment is a sequence, it shall contain only source clip and filler objects.

      Parameters:
        `choice` - Segment to add as a choice to the collection of choices of this essence group.
      Throws:
        `NullPointerException` - The given choice segment is `null`.
        `InvalidDataDefinitionException` - The data definition of the given segment does not convert to an acceptable definition for this group.
        `BadLengthException` - The length of the given segment is different to the length of other choices of the group.

    - #### insertChoiceAt

          void insertChoiceAt(@UInt32
                              int index,
                              Segment choice)
                       throws NullPointerException,
                              IndexOutOfBoundsException,
                              InvalidDataDefinitionException,
                              BadLengthException

      Insert another choice to the collections of choices of this essence group at the given index. The choices identify the alternate representations that may be chosen. Choices already existing at the given and higher indices will be moved up by one index to accommodate.

      The segment shall either be a source clip or a sequence. If the segment is a sequence, it shall contain only source clip and filler objects.

      Parameters:
        `index` - Index at which to insert a new choice into the collection of choices of this essence group.
        `choice` - Segment to add as a choice.
      Throws:
        `NullPointerException` - The given choice segment is `null`.
        `IndexOutOfBoundsException` - Index is outside the acceptable range for this group.
        `InvalidDataDefinitionException` - The data definition of the given segment does not convert to an acceptable definition for this group.
        `BadLengthException` - The length of the given segment is different to the length for other choices of the group.

    - #### countChoices

          @UInt32
          int countChoices()

      Returns the number of choices in the collection of alternates of this essence group, which identify the alternate representations that may be chosen. The count does not include the still frame.

      Returns:
        Number of choices in this essence group

    - #### getChoiceAt

          Segment getChoiceAt(@UInt32
                              int index)
                       throws IndexOutOfBoundsException

      Returns the source clip choice at the given index in the collection of choices of this essence group, which identify the alternate representations that may be chosen.

      Parameters:
        `index` - The 0-based index into the collection of choices of this essence group.
      Returns:
        The corresponding choice at the given index.
      Throws:
        `IndexOutOfBoundsException` - Index is outside the acceptable range for the collection of this essence group.

    - #### removeChoiceAt

          void removeChoiceAt(@UInt32
                              int index)
                       throws IndexOutOfBoundsException

      Removes the choice at the given index in the collection of choices of this essence group, which identify the alternate representations that may be chosen. Items already existing at higher indices will be moved down by one index to accommodate. The essence group should always contain at least one choice, although the implementation may not check this.

      Parameters:
        `index` - The 0-based index into the collection of choices indicating which choice to remove.
      Throws:
        `IndexOutOfBoundsException` - Index is outside the acceptable range for this group.

    - #### clone

          EssenceGroup clone()

      Create a cloned copy of this essence group.

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

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