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

tv.amwa.maj.model

## Interface NestedScope

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

      public interface NestedScope
      extends Segment

  Specifies a scope and has an ordered set of segments. Typically, nested scopes are used within composition packages.

  The length of each segment contained in the list of segments must be the same as the length of the nested scope itself.

  The value represented by a nested scope is the value specified by the last segment in the list of segments it contains, which must have a compatible essence type to that of the nested scope. Nested scopes are used to encapsulate intermediate results which may be referenced from more than one place, in a similar way to subexpressions within mathematical expressions.

  See Also:
    `ScopeReference`, `CompositionPackage`, `OperationGroup`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendSegment(Segment segment)` Append an input segment to the list of segments of this nested scope.
    `NestedScope` | `clone()` Create a cloned copy of this nested scope.
    `int` | `countSegments()` Returns the number of segments in the list of segments of this nested scope.
    `List<? extends Segment>` | `getNestedScopeTracks()` Returns the list of segments that make up this nested scope.
    `Segment` | `getSegmentAt(int index)` Returns the segment at the given index through the list of segments in this nested scope.
    `void` | `insertSegmentAt(int index, Segment segment)` Insert an input segment into the list of segments of this nested scope at the given index.
    `void` | `prependSegment(Segment segment)` Prepend an input segment to the list of segments of this nested scope.
    `void` | `removeSegmentAt(int index)` Removes the segment at the given index in the list of segments of this nested scope.

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

    - #### appendSegment

          void appendSegment(Segment segment)
                      throws NullPointerException,
                             InvalidDataDefinitionException,
                             BadLengthException

      Append an input segment to the list of segments of this nested scope. The last segment added will be used as the output value of the nested scope. Typically, the given segment contains operations whose inputs are scope references.

      Parameters:
        `segment` - Input segment to append to the list of segments in this nested scope.
      Throws:
        `NullPointerException` - The given segment is `null`.
        `InvalidDataDefinitionException` - The given segment will become the value of this nested scope has an incompatible data definition.
        `BadLengthException` - The given segment has a different length from that of this nested scope.

    - #### prependSegment

          void prependSegment(Segment segment)
                       throws NullPointerException,
                              BadLengthException

      Prepend an input segment to the list of segments of this nested scope.

      Parameters:
        `segment` - Segment to add at the beginning of the list.
      Throws:
        `NullPointerException` - The given segment is `null`.
        `BadLengthException` - The given segment has a different length from that of this nested scope.

    - #### insertSegmentAt

          void insertSegmentAt(@UInt32
                               int index,
                               Segment segment)
                        throws NullPointerException,
                               IndexOutOfBoundsException,
                               InvalidDataDefinitionException,
                               BadLengthException

      Insert an input segment into the list of segments of this nested scope at the given index. Segments already existing at the given and higher indices will be moved up by one index to accommodate.

      Parameters:
        `index` - Index at which the segment is to be inserted into the list of segments of this nested scope.
        `segment` - Segment to be inserted into the list.
      Throws:
        `NullPointerException` - The given segment is `null`.
        `IndexOutOfBoundsException` - Index is outside the range of the indices of the current list.
        `InvalidDataDefinitionException` - The given segment will become the value of this nested scope and has an incompatible data definition.
        `BadLengthException` - The given segment has a different length from that of this nested scope.

    - #### removeSegmentAt

          void removeSegmentAt(@UInt32
                               int index)
                        throws IndexOutOfBoundsException,
                               InvalidDataDefinitionException,
                               IllegalArgumentException

      Removes the segment at the given index in the list of segments of this nested scope. Segments already existing at indices greater than the given index will be moved down by one index to accommodate.

      Parameters:
        `index` - Index corresponding to segment to be removed from the list of segments of this nested scope.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current list of segments.
        `InvalidDataDefinitionException` - The removal operation for the given index will result in the value of the nested scope having an incompatible data definition to the nested scope itself.
        `IllegalArgumentException` - Removal of a segment will leave an empty list.

    - #### countSegments

          @UInt32
          int countSegments()

      Returns the number of segments in the list of segments of this nested scope.

      Returns:
        Number of segments in the list of segments of this nested scope.

    - #### getSegmentAt

          Segment getSegmentAt(@UInt32
                               int index)
                        throws IndexOutOfBoundsException

      Returns the segment at the given index through the list of segments in this nested scope.

      Parameters:
        `index` - 0-based index of the segment to return.
      Returns:
        Segment at the given index.
      Throws:
        `IndexOutOfBoundsException` - Index is outside the range acceptable range for the current list of segments of this nested scope.

    - #### getNestedScopeTracks

          List<? extends Segment> getNestedScopeTracks()

      Returns the list of segments that make up this nested scope.

      Returns:
        Shallow copy of the list of segments of this nested scope.

    - #### clone

          NestedScope clone()

      Create a cloned copy of this nested scope.

      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 nested scope.

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