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

tv.amwa.maj.model

## Interface DescriptiveMarker

- All Superinterfaces:
    CommentMarker, Component, Event, InterchangeObject, MediaEntity, MetadataObject, Segment
  All Known Implementing Classes:
    DescriptiveMarkerImpl

      public interface DescriptiveMarker
      extends CommentMarker

  Specifies descriptive metadata associated with a point in time and the tracks that the description refers to. A descriptive marker may contain a descriptive framework that specifies the metadata.

  If a descriptive marker refers to a static track, the extent of the description is for the entire package.

  See Also:
    `DescriptiveFramework`, `DescriptiveClip`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `DescriptiveMarker.AllTracksDescribed` Contrived inner class that represents the set of all positive integers and zero.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Set<Integer>` | `AllTracksDescribed` Default value for the described tracks parameter.
    `static Set<Integer>` | `NoTracksDescribed` No tracks are described by the marker.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `DescriptiveMarker` | `clone()` Create a cloned copy of this descriptive marker.
    `Set<Integer>` | `getDescribedTrackIDs()` Returns the set of described track ids that are referenced by this descriptive marker.
    `int` | `getDescribedTrackIDsSize()` Returns the number of track ids referred to by this descriptive marker.
    `DescriptiveFramework` | `getDescriptiveFrameworkObject()` Returns the `descriptive framework` that specifies the metadata for this descriptive marker.
    `String` | `getDescriptiveMetadataApplicationEnvironmentID()` Returns the application environment identifier, an Uniform Resource Identifier (RFC 3986) that identifies the application to which the information in this plugin object applies.
    `AUID` | `getDescriptiveMetadataPluginID()` Returns the immutable identifier for this descriptive metadata plugin instance.
    `ExtensionScheme` | `getDescriptiveMetadataScheme()` Returns the descriptive metadata scheme that is referenced by the descriptive framework object.
    `void` | `setDescribedTrackIDs(Set<Integer> describedTrackIDs)` Specifies the track ids in the package to which this descriptive marker refers.
    `void` | `setDescriptiveFrameworkObject(DescriptiveFramework descriptiveFramework)` Sets the `descriptive framework` that specifies the metadata for this descriptive marker.
    `void` | `setDescriptiveMetadataApplicationEnvironmentID(String descriptiveMetadataApplicationEnvironmentID)` Sets the application environment identifier, an Uniform Resource Identifier (RFC 3986) that identifies the application to which the information in this plugin object applies.
    `void` | `setDescriptiveMetadataPluginID(AUID descriptiveMetadataPluginID)` Sets the immutable identifier for this descriptive metadata plugin instance.
    `void` | `setDescriptiveMetadataScheme(ExtensionScheme extensionScheme)` Sets the descriptive metadata scheme that is referenced by the descriptive framework object.

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

      `getAnnotationSource, setAnnotation`

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

      `getEventComment, getEventPosition, setEventComment, setEventPosition`

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

- - ### Field Detail

    - #### AllTracksDescribed

          static final Set<Integer> AllTracksDescribed

      Default value for the described tracks parameter. This value is a set that contains all track indexes from `0` to `Integer.MAX_VALUE`.

    - #### NoTracksDescribed

          static final Set<Integer> NoTracksDescribed

      No tracks are described by the marker.

  - ### Method Detail

    - #### setDescribedTrackIDs

          void setDescribedTrackIDs(@TrackID
                                    Set<Integer> describedTrackIDs)
                             throws IllegalArgumentException

      Specifies the track ids in the package to which this descriptive marker refers. Set this optional property to `null` to omit it, which indicates that all tracks are described. Set to `NoTracksDescribed` to indicate that the marker does not refer to any tracks.

      Parameters:
        `describedTrackIDs` - Track id for the tracks in the associated package that this descriptive marker describes.
      Throws:
        `IllegalArgumentException` - One or more of the track ids in the given set is negative.
      See Also:
        `AllTracksDescribed`, `Track`

    - #### getDescribedTrackIDs

          @TrackID
          Set<Integer> getDescribedTrackIDs()
                                              throws PropertyNotPresentException

      Returns the set of described track ids that are referenced by this descriptive marker. If the value returned is equal to `AllTracksDescribed`, this descriptive marker describes all tracks in the associated package.

      Returns:
        Track ids in this package that this descriptive marker describes.
      Throws:
        `PropertyNotPresentException` - The optional described tracks property is not present in this descriptive marker.

    - #### getDescribedTrackIDsSize

          @UInt32
          int getDescribedTrackIDsSize()
                                        throws PropertyNotPresentException

      Returns the number of track ids referred to by this descriptive marker.Note that the default value is `AllTracksDescribed`, which has `Integer.MAX_VALUE` track ids. Care should be taken not to end up iterating over all of these entries!

      Returns:
        Number of track ids stored.
      Throws:
        `PropertyNotPresentException` - The optional described tracks property is not present in this descriptive marker.

    - #### setDescriptiveFrameworkObject

          void setDescriptiveFrameworkObject(DescriptiveFramework descriptiveFramework)

      Sets the `descriptive framework` that specifies the metadata for this descriptive marker. Set this optional property to `null` to omit it.

      Parameters:
        `descriptiveFramework` - Specifies the descriptive framework.
      See Also:
        `DescriptiveFramework`

    - #### getDescriptiveFrameworkObject

          DescriptiveFramework getDescriptiveFrameworkObject()
                                                      throws PropertyNotPresentException

      Returns the `descriptive framework` that specifies the metadata for this descriptive marker.

      Returns:
        The associated descriptive framework.
      Throws:
        `PropertyNotPresentException` - The optional descriptive framework property is not present in this descriptive marker.
      See Also:
        `DescriptiveFramework`

    - #### getDescriptiveMetadataPluginID

          AUID getDescriptiveMetadataPluginID()
                                       throws PropertyNotPresentException

      Returns the immutable identifier for this descriptive metadata plugin instance.

      Returns:
        Immutable identifier for this descriptive metadata plugin instance.
      Throws:
        `PropertyNotPresentException` - The optional descriptive metadata plugin identifier is not present for this descriptive marker.

    - #### setDescriptiveMetadataPluginID

          void setDescriptiveMetadataPluginID(AUID descriptiveMetadataPluginID)

      Sets the immutable identifier for this descriptive metadata plugin instance.

      Parameters:
        `descriptiveMetadataPluginID` - Immutable identifier for this descriptive metadata plugin instance.

    - #### getDescriptiveMetadataScheme

          ExtensionScheme getDescriptiveMetadataScheme()
                                                throws PropertyNotPresentException

      Returns the descriptive metadata scheme that is referenced by the descriptive framework object. A descriptive metadata scheme is represented by an extension scheme. This is an optional property.

      Returns:
        Descriptive metadata scheme that is referenced by the descriptive framework object.
      Throws:
        `PropertyNotPresentException` - The optional descriptive metadata scheme property is not present for this descriptive marker.
      See Also:
        `getDescriptiveFrameworkObject()`, `Root.getRootExtensions()`

    - #### setDescriptiveMetadataScheme

          void setDescriptiveMetadataScheme(ExtensionScheme extensionScheme)

      Sets the descriptive metadata scheme that is referenced by the descriptive framework object. A descriptive metadata scheme is represented by an extension scheme. Set this optional property to `null` to omit it.

      Parameters:
        `extensionScheme` - Descriptive metadata scheme that is referenced by the descriptive framework object.
      See Also:
        `setDescriptiveFrameworkObject(DescriptiveFramework)`

    - #### getDescriptiveMetadataApplicationEnvironmentID

          String getDescriptiveMetadataApplicationEnvironmentID()
                                                         throws PropertyNotPresentException

      Returns the application environment identifier, an Uniform Resource Identifier (RFC 3986) that identifies the application to which the information in this plugin object applies. This is an optional property.

      Returns:
        Application environment identifier.
      Throws:
        `PropertyNotPresentException` - The optional descriptive metadata application environment identifier is not present for this descriptive marker.

    - #### setDescriptiveMetadataApplicationEnvironmentID

          void setDescriptiveMetadataApplicationEnvironmentID(String descriptiveMetadataApplicationEnvironmentID)

      Sets the application environment identifier, an Uniform Resource Identifier (RFC 3986) that identifies the application to which the information in this plugin object applies. Set this optional property to `null` to omit it.

      Parameters:
        `descriptiveMetadataApplicationEnvironmentID` - Application environment identifier.

    - #### clone

          DescriptiveMarker clone()

      Create a cloned copy of this descriptive marker.

      Specified by:
        `clone` in interface `CommentMarker`
      Specified by:
        `clone` in interface `Component`
      Specified by:
        `clone` in interface `Event`
      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Specified by:
        `clone` in interface `Segment`
      Returns:
        Cloned copy of this descriptive marker.

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