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

tv.amwa.maj.union.impl

## Class SourceReferenceValueImpl

- java.lang.Object
- - tv.amwa.maj.union.impl.SourceReferenceValueImpl

- All Implemented Interfaces:
    Serializable, Cloneable, XMLSerializable, SourceReferenceValue

      public class SourceReferenceValueImpl
      extends Object
      implements SourceReferenceValue, Serializable, XMLSerializable, Cloneable

  Implementation of a source reference value that targets an item of source material, defined using a package id, source track id and start time. This reference can be used as an argument to methods or as a return value. The class is used to ensure the constraint that if the source id is the zero package id then the source track id is 0 and the start time is 0 .

  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. 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. Use the public constructor of this class to create this kind of source reference.
  2. Source package 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. To manufacture such a reference, call the `originalSource()` static method.
  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 the source reference itself. To manufacture such a reference, call one of the `inContextReference(int)` or `inContextReference(int, Long)` methods.

  As this class is used as a convenience argument to the methods of other persistent classes, it has no persistent representation of its own.

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

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SourceReferenceValueImpl(PackageID sourcePackageID, int sourceTrackID, Long startPosition)` Create a new source reference value that contains a source package id, source track id and start position.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendXMLChildren(Node parent)` Append extra child elements to the given parent node to serialize the value of an object to an XML fragment.
    `SourceReferenceValue` | `clone()`
    `boolean` | `equals(Object o)`
    `String` | `getComment()` Include a comment when serializing a value to XML.
    `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.
    `int` | `hashCode()`
    `static SourceReferenceValueImpl` | `inContextReference(int sourceTrackID)` Manufactures a new source reference to static material in track within the same context as the package in which the reference is specified.
    `static SourceReferenceValueImpl` | `inContextReference(int sourceTrackID, Long startPosition)` Manufactures a new source reference to timeline- or event-based material in a track within the same context as the package in which the reference is specified.
    `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.
    `static SourceReferenceValueImpl` | `originalSource()` Manufactures a new source reference that indicates the reference is to essence that is the original source.
    `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.
    `String` | `toString()` Create a pseudo-XML representation of this source reference, similar to that produced for a source clip.

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### SourceReferenceValueImpl

          public SourceReferenceValueImpl(@PackageIDType
                                          PackageID sourcePackageID,
                                          @TrackID
                                          int sourceTrackID,
                                          @PositionType
                                          Long startPosition)
                                   throws IllegalArgumentException

      Create a new source reference value that contains a source package id, source track id and start position. If the given source package id is the zero package id, values for source track id and start position are set to zero to comply with source reference constraints.

      Parameters:
        `sourcePackageID` - Identifies the package that is the target of the new reference. If the property is set to the zero package id, it means that the package owning the source reference describes the original source. If this optional property is omitted by setting its value to `null`, the given track refers to another track within the same package as the reference.
        `sourceTrackID` - Specifies the track id of a track within the specified package. If the source package id is the zero package id, then the source track id shall have a 0 value.
        `startPosition` - Specifies the position offset from the origin of the referenced package's track in edit units determined by the associated source clip's context. If the source package id is the zero package id, then the start position shall have a 0 value. Set the value to `null` to omit this optional property in the case that the new reference is to static material.
      Throws:
        `IllegalArgumentException` - The source track id cannot be set to a negative value.
      See Also:
        `PackageID.isZero()`, `PackageIDImpl.getZeroPackageID()`

  - ### Method Detail

    - #### originalSource

          public static final SourceReferenceValueImpl originalSource()

      Manufactures a new source reference that indicates the reference is to essence that is the original source. The source package id will be the zero package id, the source track id will be zero and so will the start position.

      Returns:
        Manufactured source reference to original source.
      See Also:
        `SourceReferenceValue.isOriginalSource()`, `PackageID.isZero()`

    - #### inContextReference

          public static final SourceReferenceValueImpl inContextReference(@TrackID
                                                                          int sourceTrackID)
                                                                   throws IllegalArgumentException

      Manufactures a new source reference to static material in track within the same context as the package in which the reference is specified. This method version omits the start position property - use `inContextReference(int, Long)` to set a start position value for timeline- or event-based material.

      Parameters:
        `sourceTrackID` - Track to reference within the same package that this reference is defined in.
      Returns:
        Manufactured contextual source reference.
      Throws:
        `IllegalArgumentException` - The given source track id is a negative value.
      See Also:
        `StaticTrack`, `SourceReferenceValue.isContextual()`

    - #### inContextReference

          public static final SourceReferenceValueImpl inContextReference(@TrackID
                                                                          int sourceTrackID,
                                                                          @PositionType
                                                                          Long startPosition)
                                                                   throws IllegalArgumentException

      Manufactures a new source reference to timeline- or event-based material in a track within the same context as the package in which the reference is specified. Use the `inContextReference(int)` to create a reference to static material.

      Parameters:
        `sourceTrackID` - Track to reference within the same package that this reference is defined in.
        `startPosition` - Specifies the offset from the origin of the referenced package's track in edit units determined by the associated source clip object's context.
      Returns:
        Manufactured contextual source reference.
      Throws:
        `IllegalArgumentException` - The source track id cannot be set to a negative value.
      See Also:
        `TimelineTrack`, `EventTrack`, `SourceReferenceValue.isContextual()`

    - #### getSourcePackageID

          @PackageIDType
          public PackageID getSourcePackageID()
                                                      throws PropertyNotPresentException

      Description copied from interface: `SourceReferenceValue`

      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.

      Specified by:
        `getSourcePackageID` in interface `SourceReferenceValue`
      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

          public void setSourcePackageID(@PackageIDType
                                         PackageID sourcePackageID)

      Description copied from interface: `SourceReferenceValue`

      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.

      Specified by:
        `setSourcePackageID` in interface `SourceReferenceValue`
      Parameters:
        `sourcePackageID` - Source id component of the source reference.

    - #### getSourceTrackID

          @TrackID
          public int getSourceTrackID()

      Description copied from interface: `SourceReferenceValue`

      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.

      Specified by:
        `getSourceTrackID` in interface `SourceReferenceValue`
      Returns:
        Track id part of the source reference.

    - #### setSourceTrackID

          public void setSourceTrackID(@TrackID
                                       int sourceTrackID)
                                throws IllegalArgumentException

      Description copied from interface: `SourceReferenceValue`

      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.

      Specified by:
        `setSourceTrackID` in interface `SourceReferenceValue`
      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
          public long getStartPosition()
                                              throws PropertyNotPresentException

      Description copied from interface: `SourceReferenceValue`

      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.

      Specified by:
        `getStartPosition` in interface `SourceReferenceValue`
      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

          public void setStartPosition(@PositionType
                                       Long startPosition)
                                throws IllegalArgumentException

      Description copied from interface: `SourceReferenceValue`

      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.

      Specified by:
        `setStartPosition` in interface `SourceReferenceValue`
      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

          public boolean isOriginalSource()

      Description copied from interface: `SourceReferenceValue`

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

      Specified by:
        `isOriginalSource` in interface `SourceReferenceValue`
      Returns:
        Is this reference to the original source material?
      See Also:
        `Forge.originalSource()`

    - #### isContextual

          public boolean isContextual()

      Description copied from interface: `SourceReferenceValue`

      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.

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

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### toString

          public String toString()

      Create a pseudo-XML representation of this source reference, similar to that produced for a source clip. No XML schema or DTD defines this element. For example, an original source reference would create the following:

           <?xml version=\"1.0\" encoding=\"UTF-8\"?>
           <!--The SourceReferenceValue tag is not valid AAF XML.-->
           <SourceReferenceValue>
             <SourceID>urn:x-umid:000000000000000000000000-00-000000-00000000000000000000000000000000</SourceID>
             <SourceTrackID>0</SourceTrackID>
             <StartTime>0</StartTime>
           </SourceReferenceValue>

      Overrides:
        `toString` in class `Object`
      Returns:
        An XML representation of this source reference.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### clone

          public SourceReferenceValue clone()

      Overrides:
        `clone` in class `Object`

    - #### appendXMLChildren

          public void appendXMLChildren(Node parent)

      Description copied from interface: `XMLSerializable`

      Append extra child elements to the given parent node to serialize the value of an object to an XML fragment. Methods of the `XMLBuilder` class are provided to help with this process.

      Specified by:
        `appendXMLChildren` in interface `XMLSerializable`
      Parameters:
        `parent` - XML parent element to append child nodes to.

    - #### getComment

          public String getComment()

      Description copied from interface: `XMLSerializable`

      Include a comment when serializing a value to XML. The comment will be inserted as the first child node of the element representing the class.

      Specified by:
        `getComment` in interface `XMLSerializable`
      Returns:
        Comment to add as the first child node of the element representing this class.

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