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

tv.amwa.maj.model

## Interface Selector

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

      public interface Selector
      extends Segment

  Specifies a selected value of a single segment while preserving references to unused alternatives. A selector represents an editing decision, which is in contrast with an essence group that presents a group of alternative versions of the same essence that the application can choose from, based on the most appropriate or efficient essence format among the alternatives.

  The selected item if provided when the selector is created and by calling `setSelectedSegment(Segment)`. Note that the collection of alternates does not contain the selected item. When the selected segment is changed, the segment that has been replaced is automatically added to the collection of alternates.

  See Also:
    `EssenceGroup`, `TypeDefinitions.SegmentStrongReference`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendAlternateSegment(Segment segment)` Append the given segment to collection of alternative segments of this selector.
    `Selector` | `clone()` Create a cloned copy of this selector.
    `int` | `countAlternateSegments()` Returns the number of segments in the collection of alternates of this selector.
    `List<? extends Segment>` | `getAlternateSegments()` Returns a collection of all the segments of the collection of alternates of this selector.
    `Segment` | `getSelectedSegment()` Returns the selected segment of this selector.
    `void` | `removeAlternateSegment(Segment segment)` Removes the given segment from the collection of alternates for this selector.
    `void` | `setSelectedSegment(Segment selectedSegment)` Sets the selected segment of this selector.

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

    - #### getSelectedSegment

          Segment getSelectedSegment()

      Returns the selected segment of this selector.

      Returns:
        Selected segment of this selector.

    - #### setSelectedSegment

          void setSelectedSegment(Segment selectedSegment)
                           throws NullPointerException,
                                  BadLengthException,
                                  InvalidDataDefinitionException

      Sets the selected segment of this selector. If the selected segment currently exists in the set of alternatives, the selected segment is removed from the set. The segment being replaced is appended to the set of alternatives.

      Parameters:
        `selectedSegment` - Selected segment of this selector.
      Throws:
        `NullPointerException` - The given selected segment is `null`.
        `BadLengthException` - The given segment does not have a length that matches the length of this selector.
        `InvalidDataDefinitionException` - The given segment does not have a data definition that is compatible with the essence type of this selector.

    - #### appendAlternateSegment

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

      Append the given segment to collection of alternative segments of this selector. This set represents unused segment alternatives. If currently omitted, the alternates optional property is made present by this method.

      Parameters:
        `segment` - Segment to append to the collection of alternates of this selector.
      Throws:
        `NullPointerException` - The given alternate segment is `null`.
        `BadLengthException` - The given segment does not have a length that matches the length of this selector.
        `InvalidDataDefinitionException` - The given segment does not have a data definition that is compatible with the essence type of this selector.

    - #### countAlternateSegments

          @Int32
          int countAlternateSegments()

      Returns the number of segments in the collection of alternates of this selector. If the alternates property is omitted, this method returns 0.

      Returns:
        Number of segments in the collection of alternates of this selector.

    - #### getAlternateSegments

          List<? extends Segment> getAlternateSegments()
                                                throws PropertyNotPresentException

      Returns a collection of all the segments of the collection of alternates of this selector. If the alternates property is omitted, this method returns an empty list. This is an optional property.

      Returns:
        Shallow copy of the collection of alternates of this selector.
      Throws:
        `PropertyNotPresentException` - No alternates are present for this selector.
      See Also:
        `TypeDefinitions.SegmentStrongReferenceVector`

    - #### removeAlternateSegment

          void removeAlternateSegment(Segment segment)
                               throws NullPointerException,
                                      SegmentNotFoundException

      Removes the given segment from the collection of alternates for this selector.

      Parameters:
        `segment` - Segment to remove from the collection of alternates of this selector.
      Throws:
        `NullPointerException` - The given segment to remove from the list of alternates is `null`.
        `SegmentNotFoundException` - The given segment is not contained in the list of alternates for this selector.

    - #### clone

          Selector clone()

      Create a cloned copy of this selector.

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

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