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

tv.amwa.maj.model

## Interface Sequence

- All Superinterfaces:
    Component, InterchangeObject, MediaEntity, MetadataObject, Segment
  All Known Subinterfaces:
    QSequence
  All Known Implementing Classes:
    SequenceImpl

      public interface Sequence
      extends Segment

  Specifies the combination of an ordered list of segments and transitions. A sequence is the mechanism for combining sections of essence to be played in a sequential manner. If a sequence object has one segment followed by another segment, after the first segment is played, the following one begins immediately.

  To be considered legal, sequences must satisfy a number of rules. The MAJ API supports the construction of sequences from start to finish, allowing a sequence to temporarily exist in an illegal state, for example with a trailing transition. The application must ensure that the rules for sequences are maintained. These rules are repeated from the AAF specification below:

  1. The first and last components in the ordered set shall be segments.
  2. A transition shall only appear in a sequence between two segments. The length of each of these segments shall be greater than or equal to the length of the transition.
  3. If a segment has a transition before it and after it, the sum of the lengths of the surrounding transitions shall be less than or equal to the length of the segment that they surround.
  4. The length of the sequence shall be equal to the sum of the length of all segments directly owned by the sequence minus the sum of the lengths of all transitions directly owned by the sequence.
  5. The data definition of each component in the sequence shall be the same as the data definition of the sequence itself.
  6. If a sequence has a transition, the last section of the segment that precedes the transition, the transition itself, and the first section of the segment that follows the transition are overlapped. The duration of the transition determines the duration of the section of the preceding and following segments that are overlapped.
  See Also:
    `OperationGroup.isValidTransitionOperation()`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendComponentObject(Component component)` Appends the given component to this sequence.
    `void` | `clearComponentObjects()` Clear all component objects from the sequence.
    `Sequence` | `clone()` Create a cloned copy of this sequence.
    `int` | `countComponentObjects()` Returns the number of components in this sequence.
    `Component` | `getComponentObjectAt(int index)` Returns the component at the given index through this sequence.
    `List<? extends Component>` | `getComponentObjects()` Returns a list of all the components of this sequence.
    `void` | `insertComponentObjectAt(int index, Component component)` Insert the given component into this sequence at the given index.
    `void` | `prependComponentObject(Component component)` Prepends the given component to this sequence.
    `void` | `removeComponentObjectAt(int index)` Removes the component at the given index from this sequence.

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

    - #### appendComponentObject

          void appendComponentObject(Component component)
                              throws NullPointerException,
                                     InvalidDataDefinitionException,
                                     LeadingTransitionException,
                                     EventSemanticsException,
                                     BadPropertyException,
                                     BadLengthException,
                                     AdjacentTransitionException,
                                     InsufficientTransitionMaterialException

      Appends the given component to this sequence. The length of the sequence is incremented by the size of the component or transition.

      If the component is to be the first in the sequence and is a transition, the method fails with a `LeadingTransitionException` as it is not acceptable to have a transition as the first element of a sequence. Note that this method supports the incremental creation of sequences from start to finish and so could be used to create a sequence that ends in a transition, which is an illegal state.

      The method checks that the data definition of the appended component is compatible with that of the sequence.

      Parameters:
        `component` - Component to append to this sequence.
      Throws:
        `NullPointerException` - The given component is `null`.
        `InvalidDataDefinitionException` - The kind of data of the component is not compatible with the data definition of the sequence.
        `LeadingTransitionException` - A transition cannot be appended to a sequence so as to become its first component.
        `EventSemanticsException` - The given component is an event that either: does not match the other kinds of event in the sequence; does not have the contextual position property set; does not follow on from the previous event.
        `BadPropertyException` - The given non-event component does not have a length value set.
        `BadLengthException` - The length of the given components is negative.
        `AdjacentTransitionException` - Appending the given transition component would result in two adjacent transitions.
        `InsufficientTransitionMaterialException` - Appending the given component or transition will result in insufficient material for the last transition in the sequence.
      See Also:
        `Event`

    - #### prependComponentObject

          void prependComponentObject(Component component)
                               throws NullPointerException,
                                      InvalidDataDefinitionException,
                                      LeadingTransitionException

      Prepends the given component to this sequence. The length of the sequence is incremented by the size of the component.

      If the component is a transition, the method fails with a `LeadingTransitionException` as it is not acceptable to have a transition as the first element of a sequence. Use `insertComponentObjectAt(int, Component)` instead.

      The method checks that the `data definition` of the appended component is compatible with that of the sequence.

      Parameters:
        `component` - Component to prepend to this sequence.
      Throws:
        `NullPointerException` - The given component is `null`.
        `InvalidDataDefinitionException` - The kind of data of the component is not compatible with the data definition of the sequence.
        `LeadingTransitionException` - A transition cannot be appended to a sequence so as to become its first or last component.

    - #### insertComponentObjectAt

          void insertComponentObjectAt(@UInt32
                                       int index,
                                       Component component)
                                throws NullPointerException,
                                       IndexOutOfBoundsException,
                                       InvalidDataDefinitionException,
                                       LeadingTransitionException,
                                       AdjacentTransitionException,
                                       InsufficientTransitionMaterialException

      Insert the given component into this sequence at the given index. The length of the sequence is incremented by the size of the component, unless the component is a transition. Indices of components higher than the given index will be increased by one to accommodate the new component.

      If the component is a transition, the method checks that it is not the first object in the sequence, and that it is not neighbouring another transition. It also verifies that there is enough source material on either side of the transition. Note that this method supports the incremental creation of sequences from start to finish and so could be used to create a sequence that ends in a transition, which is an illegal state.

      The method checks that the `data definition` of the appended component is compatible with that of the sequence.

      Parameters:
        `index` - 0-based index to insert the new component at.
        `component` - Component to insert into the sequence.
      Throws:
        `NullPointerException` - The given component to insert is `null`.
        `IndexOutOfBoundsException` - The index is outside the acceptable range for the sequence.
        `InvalidDataDefinitionException` - The kind of data of the component is not compatible with the data definition of the sequence.
        `LeadingTransitionException` - A transition component cannot be inserted as first element of the sequence.
        `AdjacentTransitionException` - Inserting a transition and the given index will result in two neighbouring transitions, which is not permitted.
        `InsufficientTransitionMaterialException` - Not enough source material exists either side of the given transition for the transition to work.

    - #### getComponentObjectAt

          Component getComponentObjectAt(@UInt32
                                         int index)
                                  throws IndexOutOfBoundsException

      Returns the component at the given index through this sequence.

      Parameters:
        `index` - Index of component through this sequence
      Returns:
        Component at the given index of this sequence.
      Throws:
        `IndexOutOfBoundsException` - The index is outside the acceptable range for this sequence.

    - #### removeComponentObjectAt

          void removeComponentObjectAt(@UInt32
                                       int index)
                                throws IndexOutOfBoundsException

      Removes the component at the given index from this sequence. Components already existing at indices higher than the given index will be moved to the next lower index to accommodate.

      Note that removal of a component from a sequence may result in the sequence being in an illegal state.

      Parameters:
        `index` - Index of component to be removed.
      Throws:
        `IndexOutOfBoundsException` - The index is outside the acceptable range for the sequence.

    - #### countComponentObjects

          @UInt32
          int countComponentObjects()

      Returns the number of components in this sequence.

      Returns:
        Number of components in this sequence.

    - #### clearComponentObjects

          void clearComponentObjects()

      Clear all component objects from the sequence.

    - #### getComponentObjects

          List<? extends Component> getComponentObjects()

      Returns a list of all the components of this sequence.

      Returns:
        Shallow copy of the list containing all of the components of the sequence.
      See Also:
        `TypeDefinitions.ComponentStrongReferenceVector`

    - #### clone

          Sequence clone()

      Create a cloned copy of this sequence.

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

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