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

tv.amwa.maj.model

## Interface Component

- All Superinterfaces:
    InterchangeObject, MediaEntity, MetadataObject
  All Known Subinterfaces:
    CommentMarker, DescriptiveClip, DescriptiveMarker, EdgeCodeSegment, EssenceGroup, Event, Filler, GPITrigger, HTMLClip, NestedScope, OperationGroup, Pulldown, QComponent, QOperationGroup, QSegment, QSequence, QSourceClip, QTimecode, ScopeReference, Segment, Selector, Sequence, SourceClip, SourceReferenceSegment, TextClip, TimecodeSegment, TimecodeStream, TimecodeStream12M, Transition
  All Known Implementing Classes:
    CommentMarkerImpl, ComponentImpl, DescriptiveClipImpl, DescriptiveMarkerImpl, EdgeCodeSegmentImpl, EssenceGroupImpl, EventImpl, FillerImpl, GPITriggerImpl, HTMLClipImpl, NestedScopeImpl, OperationGroupImpl, PulldownImpl, ScopeReferenceImpl, SegmentImpl, SelectorImpl, SequenceImpl, SourceClipImpl, SourceReferenceSegmentImpl, TextClipImpl, TimecodeSegmentImpl, TimecodeStream12MImpl, TimecodeStreamImpl, TransitionImpl

      public interface Component
      extends InterchangeObject

  Specifies an essence element.

  The `getComponentLength()` and `setComponentLength(long)` methods apply to all time-varying media and may apply to events but do not apply to static media, so length is an optional property. Whether the property is present or omitted is determined by the kind of track that the component is in:

  - timeline track - time-varying essence where the length property shall be present;
  - event track - instantaneous events shall omit the length property, events marking out a clip shall specify the length property;
  - static track - static data that is not related to time and so the length property shall be omitted.
  See Also:
    `Track.getTrackSegment()`, `Sequence.getComponentObjects()`, `TypeDefinitions.ComponentStrongReference`, `TypeDefinitions.ComponentStrongReferenceVector`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendComponentAttribute(String name, String value)` Append an attribute name/value pair to the attributes collection of of this component, which specify attributes that are under the control of the application (for example filter control).
    `void` | `appendComponentAttribute(TaggedValue attribute)` Append an attribute defined by an existing tagged value to the attributes collection of this component, which specify attributes that are under the control of the application (for example filter control).
    `void` | `appendComponentKLVData(KLVData klvData)` Appends a KLV Data to the collection of KLV data of this component.
    `void` | `appendComponentUserComment(String name, String value)` Append a user comment name/value pair to the collection of user comments of the component, which specify user comments that are directly classified and set up by the operator (for example Bin columns).
    `void` | `appendComponentUserComment(TaggedValue userComment)` Append a user comment defined by an existing tagged value to the collection of user comments of this component, which specify user comments that are directly classified and set up by the operator (for example Bin columns).
    `void` | `clearComponentAttributes()` Clear all attributes from this component, omitting this optional property.
    `void` | `clearComponentKLVData()` Clear the list of KLV data for this component, omitting this optional property.
    `void` | `clearComponentUserComments()` Clears the list of user comments of this components, omitting this optional property.
    `Component` | `clone()` Create a cloned copy of this component.
    `int` | `countComponentAttributes()` Returns the size of the collection of attributes for the component, which specify attributes that are under the control of the application (for example filter control).
    `int` | `countComponentKLVData()` Returns the total number of KLV data in the collection for this component.
    `int` | `countComponentUserComments()` Returns the number of user comments in the collection of user comments of this component, which specify user comments that are directly classified and set up by the operator (for example Bin columns).
    `List<? extends TaggedValue>` | `getComponentAttributes()` Returns the collection of attributes of this component, which specify attributes that are under the control of the application (for example filter control).
    `DataDefinition` | `getComponentDataDefinition()` Returns the data definition of the component, which specifies the kind of data described by this component.
    `List<? extends KLVData>` | `getComponentKLVData()` Returns the list of KLV data of this component.
    `long` | `getComponentLength()` Returns the length of this component, which specifies its duration in edit units.
    `List<? extends TaggedValue>` | `getComponentUserComments()` Returns the collection of user comments of the component, which specify user comments that are directly classified and set up by the operator (for example Bin columns).
    `boolean` | `getLengthPresent()` Determines whether the length property is present for this component.
    `void` | `removeComponentAttribute(TaggedValue attribute)` Remove an attribute from the collection of attributes of this component, which specify attributes that are under the control of the application (for example filter control).
    `void` | `removeComponentKLVData(KLVData klvData)` Removes the given KLV data from the collection of this component.
    `void` | `removeComponentUserComment(TaggedValue userComment)` Removes a given user comment from the collection of user comments of this component, which specify user comments that are directly classified and set up by the operator (for example Bin columns).
    `void` | `setComponentDataDefinition(DataDefinition dataDefinition)` Sets the data definition property for the component, which specifies the kind of data described by this component.
    `void` | `setComponentLength(long componentLength)` Sets the length property of this component, which specifies its duration in edit units.
    `void` | `setLengthPresent(boolean lengthPresent)` Sets whether the length property is present for this component.

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

    - #### setComponentLength

          void setComponentLength(@LengthType
                                  long componentLength)
                           throws BadLengthException

      Sets the length property of this component, which specifies its duration in edit units. This is an optional property, which will only be present for time-varying media.

      Parameters:
        `componentLength` - The duration in edit units of this component.
      Throws:
        `BadLengthException` - Cannot set the length to a negative value.

    - #### getComponentLength

          @LengthType
          long getComponentLength()
                                       throws BadPropertyException

      Returns the length of this component, which specifies its duration in edit units. This is an optional property, which will be present for time-varying media and may be present for events.

      Returns:
        Length of this component in edit units.
      Throws:
        `BadPropertyException` - The optional length property is not present for this object.

    - #### setComponentDataDefinition

          void setComponentDataDefinition(DataDefinition dataDefinition)
                                   throws NullPointerException

      Sets the data definition property for the component, which specifies the kind of data described by this component.

      Parameters:
        `dataDefinition` - Data definition of this component.
      Throws:
        `NullPointerException` - The given data definition is `null`.

    - #### getComponentDataDefinition

          DataDefinition getComponentDataDefinition()

      Returns the data definition of the component, which specifies the kind of data described by this component.

      Returns:
        Data definition of this component.
      See Also:
        `TypeDefinitions.DataDefinitionWeakReference`

    - #### appendComponentKLVData

          void appendComponentKLVData(KLVData klvData)
                               throws NullPointerException

      Appends a KLV Data to the collection of KLV data of this component.

      Parameters:
        `klvData` - KLV data value to add to the set of KLV data values of this component.
      Throws:
        `NullPointerException` - The given KLV data value is `null`.

    - #### countComponentKLVData

          @UInt32
          int countComponentKLVData()

      Returns the total number of KLV data in the collection for this component.

      Returns:
        Number of KLV data objects in this collection for this component.

    - #### clearComponentKLVData

          void clearComponentKLVData()

      Clear the list of KLV data for this component, omitting this optional property.

    - #### getComponentKLVData

          List<? extends KLVData> getComponentKLVData()
                                               throws PropertyNotPresentException

      Returns the list of KLV data of this component. This is an optional property.

      Returns:
        Shallow copy of the list of KLV data of this component.
      Throws:
        `PropertyNotPresentException` - No KLV data items are present for this component.
      See Also:
        `TypeDefinitions.KLVDataStrongReferenceVector`

    - #### removeComponentKLVData

          void removeComponentKLVData(KLVData klvData)
                               throws NullPointerException,
                                      PropertyNotPresentException,
                                      ObjectNotFoundException

      Removes the given KLV data from the collection of this component.

      Parameters:
        `klvData` - KLV data value to remove from the component.
      Throws:
        `NullPointerException` - The given KLV data item is `null`.
        `PropertyNotPresentException` - No KLV data items are present for this component.
        `ObjectNotFoundException` - The given KLV data object is not in the collection of this component.

    - #### appendComponentUserComment

          void appendComponentUserComment(@AAFString
                                          String name,
                                          @AAFString
                                          String value)
                                   throws NullPointerException

      Append a user comment name/value pair to the collection of user comments of the component, which specify user comments that are directly classified and set up by the operator (for example Bin columns).

      This method creates a new tagged value, initializes it with the specified comment name/value pair, and appends it to the comment list.

      Parameters:
        `name` - The name associated with the new comment to create.
        `value` - The corresponding value, or description, of the new comment.
      Throws:
        `NullPointerException` - One or both of the name and/or value values is/are `null`.

    - #### appendComponentUserComment

          void appendComponentUserComment(TaggedValue userComment)
                                   throws NullPointerException

      Append a user comment defined by an existing tagged value to the collection of user comments of this component, which specify user comments that are directly classified and set up by the operator (for example Bin columns).

      Parameters:
        `userComment` - User comment to append to the collection of user comments of this component.
      Throws:
        `NullPointerException` - The given user comment value is `null`.
      See Also:
        `TaggedValueDefinition`

    - #### countComponentUserComments

          @UInt32
          int countComponentUserComments()

      Returns the number of user comments in the collection of user comments of this component, which specify user comments that are directly classified and set up by the operator (for example Bin columns).

      Returns:
        Number of user comments of the component.

    - #### clearComponentUserComments

          void clearComponentUserComments()

      Clears the list of user comments of this components, omitting this optional property.

    - #### getComponentUserComments

          List<? extends TaggedValue> getComponentUserComments()
                                                        throws PropertyNotPresentException

      Returns the collection of user comments of the component, which specify user comments that are directly classified and set up by the operator (for example Bin columns). This is an optional property.

      Returns:
        Shallow copy of the collection of user comments for this component.
      Throws:
        `PropertyNotPresentException` - No user comments are present for this component.
      See Also:
        `TypeDefinitions.TaggedValueStrongReferenceVector`

    - #### removeComponentUserComment

          void removeComponentUserComment(TaggedValue userComment)
                                   throws NullPointerException,
                                          PropertyNotPresentException,
                                          ObjectNotFoundException

      Removes a given user comment from the collection of user comments of this component, which specify user comments that are directly classified and set up by the operator (for example Bin columns).

      Parameters:
        `userComment` - User comment to remove from the collection of user comments of this component.
      Throws:
        `NullPointerException` - The given comment is `null`.
        `PropertyNotPresentException` - No user comments are present for this component.
        `ObjectNotFoundException` - The comment to be removed cannot be found in the collection of comments of this component.

    - #### appendComponentAttribute

          void appendComponentAttribute(@AAFString
                                        String name,
                                        @AAFString
                                        String value)
                                 throws NullPointerException

      Append an attribute name/value pair to the attributes collection of of this component, which specify attributes that are under the control of the application (for example filter control).

      This method creates a new tagged value, initializes it with the specified attribute name/value pair, and appends it to the attribute list.

      Parameters:
        `name` - Name for the new attribute.
        `value` - Corresponding value for the new attribute.
      Throws:
        `NullPointerException` - One or both of the given name and/or value method parameters are `null`.

    - #### appendComponentAttribute

          void appendComponentAttribute(TaggedValue attribute)
                                 throws NullPointerException

      Append an attribute defined by an existing tagged value to the attributes collection of this component, which specify attributes that are under the control of the application (for example filter control).

      Parameters:
        `attribute` - Tagged value to be appended to the collection of attributes for this component.
      Throws:
        `NullPointerException` - The given attribute value is `null`.
      See Also:
        `TaggedValueDefinition`

    - #### countComponentAttributes

          @UInt32
          int countComponentAttributes()

      Returns the size of the collection of attributes for the component, which specify attributes that are under the control of the application (for example filter control).

      Returns:
        Size of the collection of attributes of this component.

    - #### clearComponentAttributes

          void clearComponentAttributes()

      Clear all attributes from this component, omitting this optional property.

    - #### getComponentAttributes

          List<? extends TaggedValue> getComponentAttributes()
                                                      throws PropertyNotPresentException

      Returns the collection of attributes of this component, which specify attributes that are under the control of the application (for example filter control). This is an optional property.

      Returns:
        Shallow copy of the collection of attributes of this component.
      Throws:
        `PropertyNotPresentException` - No attributes are present for this component.
      See Also:
        `TypeDefinitions.TaggedValueStrongReferenceVector`

    - #### removeComponentAttribute

          void removeComponentAttribute(TaggedValue attribute)
                                 throws NullPointerException,
                                        PropertyNotPresentException,
                                        ObjectNotFoundException

      Remove an attribute from the collection of attributes of this component, which specify attributes that are under the control of the application (for example filter control).

      Parameters:
        `attribute` - Attribute to remove from the collection of attributes of the component.
      Throws:
        `NullPointerException` - The given attribute is `null`.
        `PropertyNotPresentException` - No attributes are present for this component.
        `ObjectNotFoundException` - The given tagged value is not currently contained by the list of attributes of this component.

    - #### getLengthPresent

          boolean getLengthPresent()

      Determines whether the length property is present for this component. This method allows a user to prepare a component for a specific kind of `track` according the the length rules of tracks. These rules are:

      - If a component is in a `timeline track` then it shall have a length property.
      - If a component is in a `static trackt` then it shall not have a length property.
      - If a component is in an `event track` then it may have a length property. In this case, if no length property is specified then the component describes an instantaneous `event` that does not have a duration.

      The default value is that length values are not present, although components that are not appropriate for static data override this to be `true`.

      Returns:
        Is the context-dependent length property present for this component?

    - #### setLengthPresent

          void setLengthPresent(boolean lengthPresent)

      Sets whether the length property is present for this component. This method allows a user to prepare a component for a specific kind of `track` according the the length rules of tracks. These rules are:

      - If a component is in a `timeline track` then it shall have a length property.
      - If a component is in a `static track` then it shall not have a length property.
      - If a component is in an `event track` then it may have a length property. In this case, if no length property is specified then the component describes an instantaneous `event` that does not have a duration.

      The default value is that length values are not present, although components that are not appropriate for static data override this to be `true`. The constructors and `setSegment()` methods of `timeline track` and `static track` will set the presence or absence of the length property according to the above rules. Therefore, this method is mainly useful to set whether an `event` should be considered as instantaneous or not.

      Parameters:
        `lengthPresent` - Is the context-dependent length property present for this component?

    - #### clone

          Component clone()

      Create a cloned copy of this component.

      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Returns:
        Cloned copy of this component.

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