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

tv.amwa.maj.union

## Interface SourceReferenceValue

- All Known Implementing Classes:
    SourceReferenceValueImpl

      public interface SourceReferenceValue

  Specifies a reference to a clip of source material, by material identifier, track number and start time offset. Source reference values are used to specify source clip segments.

  The interpretation of a source reference value depends on the context where it is used. The value of a source reference can be explicit or relative to its context. Source references are often used to build a chain of references that can be used to trace the original source of some material.

  Three different kinds of reference can be identified from the value of the source id property of a source reference. These are defined as:

  1. The source package id property is present and has a non-nil value. An explicit reference to a package by its unique package id and track id. An optional offset starting frame may also be provided.
  2. Source id property is present and is the zero package id. This specifies that the source package containing the source reference represents the original source material. Such references are the final link in source reference chains.
  3. The source package id property is not present. This specifies that the reference is to another track within the same package, the package owning source reference itself.

  Original C name: `aafSourceRef_t`

  See Also:
    `SourceReferenceSegment`, `PackageID`, `SourceClip`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `PackageID` | `getSourcePackageID()` Returns the identifier of the package that is the target of the reference.
    `int` | `getSourceTrackID()` Returns the track id of a track within the referenced package.
    `long` | `getStartPosition()` Returns the position offset from the origin of the referenced package's track in edit units determined by the source clip's context.
    `boolean` | `isContextual()` Returns `true` if this source reference is to another track within the context of the same package, or `false` if it is a reference to a track in another package.
    `boolean` | `isOriginalSource()` Returns `true` if this source reference is to the original source material and `false` if it requires further resolution.
    `void` | `setSourcePackageID(PackageID sourcePackageID)` Sets the identity of package that is the target of the reference.
    `void` | `setSourceTrackID(int sourceTrackID)` Sets the track id of the referenced track within the referenced package.
    `void` | `setStartPosition(Long startPosition)` Returns the position offset from the origin of the referenced package's track in edit units determined by the source clip's context.

- - ### Method Detail

    - #### getSourcePackageID

          @PackageIDType
          PackageID getSourcePackageID()
                                               throws PropertyNotPresentException

      Returns the identifier of the package that is the target of the reference. If the property is the zero package id, it means that the package owning this source reference describes the original source.

      Returns:
        Source package id component of the source reference.
      Throws:
        `PropertyNotPresentException` - The optional source package id property is not present in this source reference, implying that the reference is to a track in the same package as the reference itself.

    - #### setSourcePackageID

          void setSourcePackageID(@PackageIDType
                                  PackageID sourcePackageID)

      Sets the identity of package that is the target of the reference. If the property is the zero package id, it means that the package owning this source reference describes the original source. Set the source package id to `null` to indicate that the reference is to a track in the package owning this reference.

      Parameters:
        `sourcePackageID` - Source id component of the source reference.

    - #### getSourceTrackID

          @TrackID
          int getSourceTrackID()

      Returns the track id of a track within the referenced package. If the source package id of this value is the zero package id then the source track value shall also be set to 0.

      Returns:
        Track id part of the source reference.

    - #### setSourceTrackID

          void setSourceTrackID(@TrackID
                                int sourceTrackID)
                         throws IllegalArgumentException

      Sets the track id of the referenced track within the referenced package. If the source package id of this value is the zero package id then the source track value shall also be set to 0.

      Parameters:
        `sourceTrackID` - Track id part of the source reference.
      Throws:
        `IllegalArgumentException` - Trying to set a non-zero value when the source id is the zero package id or the track id is negative.

    - #### getStartPosition

          @PositionType
          long getStartPosition()
                                       throws PropertyNotPresentException

      Returns the position offset from the origin of the referenced package's track in edit units determined by the source clip's context. If the source package id of this value is the zero package id, then the start position shall also be set to 0.

      Returns:
        Position offset from the origin of the referenced content.
      Throws:
        `PropertyNotPresentException` - The optional start time property is not present, indicating that the reference is in the context of a static track rather than a timeline or event track.

    - #### setStartPosition

          void setStartPosition(@PositionType
                                Long startPosition)
                         throws IllegalArgumentException

      Returns the position offset from the origin of the referenced package's track in edit units determined by the source clip's context. If the source package id of this value is the zero package id then the start position shall be set to 0.

      Set this optional property to `null` to omit it, indicating that this reference is in the context of a static track rather than a timeline or event track.

      Parameters:
        `startPosition` - Position offset from the origin of the referenced content.
      Throws:
        `IllegalArgumentException` - Trying to set a non-zero value when the source id is the zero package id.

    - #### isOriginalSource

          boolean isOriginalSource()

      Returns `true` if this source reference is to the original source material and `false` if it requires further resolution.

      Returns:
        Is this reference to the original source material?
      See Also:
        `Forge.originalSource()`

    - #### isContextual

          boolean isContextual()

      Returns `true` if this source reference is to another track within the context of the same package, or `false` if it is a reference to a track in another package.

      Returns:
        Does this reference target another track in the context of the same package?
      See Also:
        `isContextual()`, `Forge.inContextReference(int)`, `Forge.inContextReference(int, Long)`

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