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

tv.amwa.maj.model

## Interface InterchangeObject

- All Superinterfaces:
    MediaEntity, MetadataObject
  All Known Subinterfaces:
    AAFFileDescriptor, AES3PCMDescriptor, AIFCDescriptor, ANCDataDescriptor, ApplicationObject, ApplicationPluginObject, ApplicationReferencedObject, AuxiliaryDescriptor, AVCSubDescriptor, Avid_MC_Mob_Reference, BWFImportDescriptor, CDCIDescriptor, CDCIDescriptor, CodecDefinition, CommentMarker, Component, CompositionPackage, ConstantValue, ContainerDefinition, ContentStorage, Contributor, ControlPoint, DataDefinition, DataEssenceDescriptor, DefinitionObject, DescriptiveClip, DescriptiveFramework, DescriptiveMarker, DescriptiveObject, Dictionary, EdgeCodeSegment, EssenceData, EssenceDescriptor, EssenceGroup, Event, EventTrack, Filler, FilmDescriptor, GPITrigger, HTMLClip, HTMLDescriptor, Identification, ImportDescriptor, InterpolationDefinition, KLVData, KLVDataDefinition, Locator, MaterialPackage, MPEGVideoDescriptor, MultipleDescriptor, NestedScope, NetworkLocator, OperationDefinition, OperationGroup, Organisation, Package, Package, PackageMarker, Parameter, ParameterDefinition, Person, PhysicalDescriptor, PictureDescriptor, PictureDescriptor, PluginDefinition, PolyFileDescriptor, Preface, Pulldown, QAAFFileDescriptor, QComponent, QCompositionPackage, QLocator, QMaterialPackage, QOperationGroup, QPreface, QSegment, QSequence, QSourceClip, QTimecode, RecordingDescriptor, RGBADescriptor, RIFFChunk, ScopeReference, Segment, Selector, Sequence, SimpleDescription, SoundDescriptor, SourceClip, SourcePackage, SourceReferenceSegment, StaticTrack, SubDescriptor, TaggedValue, TaggedValue, TaggedValueDefinition, TapeDescriptor, TapeDescriptor, TextClip, TextLocator, TIFFDescriptor, TimecodeSegment, TimecodeStream, TimecodeStream12M, TimelineTrack, Track, Transition, VaryingValue, VBIDataDescriptor, WAVEDescriptor, WAVEPCMDescriptor, WAVEPCMDescriptor
  All Known Implementing Classes:
    AAFFileDescriptorImpl, AES3PCMDescriptorImpl, AIFCDescriptorImpl, ANCDataDescriptorImpl, ApplicationObjectImpl, ApplicationPluginObjectImpl, ApplicationReferencedObjectImpl, AuxiliaryDescriptorImpl, AVCSubDescriptorImpl, Avid_MC_Mob_ReferenceImpl, BWFImportDescriptorImpl, CDCIDescriptorImpl, CodecDefinitionImpl, CommentMarkerImpl, ComponentImpl, CompositionPackageImpl, ConstantValueImpl, ContainerDefinitionImpl, ContentStorageImpl, ContributorImpl, ControlPointImpl, DataDefinitionImpl, DataEssenceDescriptorImpl, DefinitionObjectImpl, DescriptiveClipImpl, DescriptiveFrameworkImpl, DescriptiveMarkerImpl, DescriptiveObjectImpl, DictionaryImpl, EdgeCodeSegmentImpl, EssenceDataImpl, EssenceDescriptorImpl, EssenceGroupImpl, EventImpl, EventTrackImpl, FillerImpl, FilmDescriptorImpl, GPITriggerImpl, HTMLClipImpl, HTMLDescriptorImpl, IdentificationImpl, ImportDescriptorImpl, InterchangeObjectImpl, InterpolationDefinitionImpl, KLVDataDefinitionImpl, KLVDataImpl, LocatorImpl, MaterialPackageImpl, MPEGVideoDescriptorImpl, MultipleDescriptorImpl, NestedScopeImpl, NetworkLocatorImpl, OperationDefinitionImpl, OperationGroupImpl, OrganisationImpl, PackageImpl, PackageMarkerImpl, ParameterDefinitionImpl, ParameterImpl, PersonImpl, PhysicalDescriptorImpl, PictureDescriptorImpl, PluginDefinitionImpl, PolyFileDescriptorImpl, PrefaceImpl, PulldownImpl, RecordingDescriptorImpl, RGBADescriptorImpl, RIFFChunkImpl, ScopeReferenceImpl, SegmentImpl, SelectorImpl, SequenceImpl, SimpleDescriptionImpl, SoundDescriptorImpl, SourceClipImpl, SourcePackageImpl, SourceReferenceSegmentImpl, StaticTrackImpl, SubDescriptorImpl, TaggedValueDefinitionImpl, TaggedValueImpl, TapeDescriptorImpl, TextClipImpl, TextLocatorImpl, TIFFDescriptorImpl, TimecodeSegmentImpl, TimecodeStream12MImpl, TimecodeStreamImpl, TimelineTrackImpl, TrackImpl, TransitionImpl, VaryingValueImpl, VBIDataDescriptorImpl, WAVEDescriptorImpl, WAVEPCMDescriptorImpl

      public interface InterchangeObject
      extends MediaEntity

  Specifies the root class for all AAF persistent classes. All classes defined in an AAF file shall be sub-classes of interchange object with the exception of the meta definition classes.

  In addition to methods which all clients can use, it provides methods for direct property access which should not be used unless the client programmer is aware of the liabilities. Note that extending the set of optional properties of a class is not fully supported in the current implementation of the MAJ API.

  Note that generation tracking is not automatically supported by the MAJ API.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addApplicationPlugin(ApplicationPluginObject applicationPlugin)` Add an application metadata plugin so as to this object to enhance its application-specific description.
    `void` | `clearApplicationPlugins()` Clear the set of application metadata plugins, omitting the optional property.
    `InterchangeObject` | `clone()` Create a cloned copy of this interchange object.
    `boolean` | `containsApplicationPlugin(ApplicationPluginObject applicationPlugin)` Determines whether the given application metadata plugin instance is attached to this interchange object.
    `boolean` | `containsApplicationPlugin(AUID applicationPluginInstanceID)` Determines whether the given identifier for a application metadata plugin instance is attached to this interchange object.
    `int` | `countApplicationPlugins()` Returns the number of application metadata plugins attached to this interchange object.
    `boolean` | `deepEquals(Object o)` Tests if this interchangeable object is equal to the given object by comparing every property and the properties of any referenced values.
    `void` | `disableGenerationTracking()` Calling this method will cause generation tracking to be disabled for the object.
    `void` | `enableGenerationTracking()` Calling this method will cause generation tracking to be enabled for the object.
    `boolean` | `equals(Object o)` Tests if this interchangeable object is equal to the given object by comparing unique identifiers where available, or property-by-property if not.
    `Set<ApplicationPluginObject>` | `getApplicationPlugins()` Returns the set of application metadata plugins attached to this interchange object, where each attached object contains application-specific description.
    `Identification` | `getGeneration()` Gets the generation of this object, which identifies when this object was created or last modified.
    `AUID` | `getLinkedGenerationID()` Shortcut to get the AUID of the identification representing this object's generation.
    `ClassDefinition` | `getObjectClass()` Returns the class definition that identifies the class of this interchange object.
    `boolean` | `isGenerationTracked()` Returns `true` if generations are being tracked by the object.
    `boolean` | `removeApplicationPlugin(ApplicationPluginObject applicationPlugin)` Remove the given application metadata plugin from the set of application plugins attached to this interchange object.
    `boolean` | `removeApplicationPlugin(AUID applicationPluginInstanceID)` Remove the application metadata plugin with the given identifier from the set of application plugins attached to this interchange object.
    `void` | `setLinkedGenerationID(AUID linkedGenerationID)` Sets the linked generation identification for this object that represents this object's generation.
    `void` | `setObjectClass(ClassDefinition objectClass)` Sets the class definition that identifies the class of this interchange object.
    `String` | `toString()` Provides an XML representation of this value.

    - ### Methods inherited from interface tv.amwa.maj.industry.MediaEntity

      `getPersistentID, setPersistentIndex`

- - ### Method Detail

    - #### getGeneration

          Identification getGeneration()
                                throws InvalidParameterException,
                                       ObjectNotAttachedException

      Gets the generation of this object, which identifies when this object was created or last modified.

      This method will succeed if generation tracking is enabled for this object. Call `enableGenerationTracking()` and `disableGenerationTracking()` to control generation tracking for this object. Call `isGenerationTracked()` to determine if generation tracking is currently enabled for this object.

      Returns:
        Identification for when this object was last modified.
      Throws:
        `InvalidParameterException` - Generation tracking is not enabled for this object.
        `ObjectNotAttachedException` - This object is not attached to a file from which generation information can be obtained.

    - #### getLinkedGenerationID

          AUID getLinkedGenerationID()
                              throws PropertyNotPresentException,
                                     ObjectNotAttachedException

      Shortcut to get the AUID of the identification representing this object's generation.

      This method will succeed if generation tracking is enabled for this object. Call `enableGenerationTracking()` and `disableGenerationTracking()` to control generation tracking for this object. Call `isGenerationTracked()` to determine if generation tracking is currently enabled for this object.

      Returns:
        AUID of the identification representing this object's generation.
      Throws:
        `PropertyNotPresent` - Generation tracking is not enabled for this object and so this optional property is omitted.
        `ObjectNotAttachedException` - This object is not attached to a file from which generation information can be obtained.
        `PropertyNotPresentException`
      See Also:
        `getGeneration()`, `getLinkedGenerationID()`

    - #### setLinkedGenerationID

          void setLinkedGenerationID(AUID linkedGenerationID)

      Sets the linked generation identification for this object that represents this object's generation. In a file, all objects added or modified at the same time have the same generation identification and that generation is described by an identification.

      Passing a `null` value into to this method will omit the linked generation property and disable generation tracking. Passing in a nil value will indicate that this object is not attached to a file where its identification can be resolved. Passing in a non-nil value will enable generation tracking and a means to resolve the identification should be provided.

      Parameters:
        `linkedGenerationID` - Linked generation identification for this interchangeable object.
      See Also:
        `getLinkedGenerationID()`, `getGeneration()`, `getLinkedGenerationID()`, `Preface.getIdentifications()`

    - #### getObjectClass

          ClassDefinition getObjectClass()

      Returns the class definition that identifies the class of this interchange object.

      Returns:
        Class definition that describes this object instance.
      See Also:
        `MediaEngine.getClassDefinition(tv.amwa.maj.industry.MetadataObject)`, `TypeDefinitions.ClassDefinitionWeakReference`

    - #### setObjectClass

          void setObjectClass(ClassDefinition objectClass)

      Sets the class definition that identifies the class of this interchange object.

      Setting this property used by application metadata plugins to indicate the defined class of an extension to this class. In this case, the base class property can be used to hold the identifier of this class.

      Parameters:
        `objectClass` - Class definition that describes this object instance.
      See Also:
        `ExtensionScheme.getMetaDefinitions()`, `ApplicationObject.getBaseClass()`

    - #### enableGenerationTracking

          void enableGenerationTracking()

      Calling this method will cause generation tracking to be enabled for the object. Generation information will then be available through the `getGeneration()` and `getLinkedGenerationID()` methods.

      Calling the `disableGenerationTracking()` method will disable generation tracking for this object.

      Generation tracking is disabled by default.

    - #### disableGenerationTracking

          void disableGenerationTracking()

      Calling this method will cause generation tracking to be disabled for the object. Generation information will then not be available through the `getGeneration()` and `getLinkedGenerationID()` methods.

      Calling the `enableGenerationTracking()` method will enable generation tracking for this object.

      Generation tracking is disabled by default.

    - #### isGenerationTracked

          @Bool
          boolean isGenerationTracked()

      Returns `true` if generations are being tracked by the object. A value of `true` indicates that generation information will be available through the `getGeneration()` and `getLinkedGenerationID()` methods.

      Calling the `enableGenerationTracking()` method will enable generation tracking for this object; calling the `disableGenerationTracking()` method will disable generation tracking for this object.

      Generation tracking is disabled by default.

      See Also:
        `enableGenerationTracking()`, `disableGenerationTracking()`

    - #### getApplicationPlugins

          Set<ApplicationPluginObject> getApplicationPlugins()
                                                      throws PropertyNotPresentException

      Returns the set of application metadata plugins attached to this interchange object, where each attached object contains application-specific description. This is an optional property.

      Returns:
        Set of application metadata plugins attached to this object.
      Throws:
        `PropertyNotPresentException` - The optional application plugins extension is not present for this interchange object.
      See Also:
        `Root.getRootExtensions()`, `ApplicationPluginObject.getApplicationScheme()`

    - #### addApplicationPlugin

          void addApplicationPlugin(ApplicationPluginObject applicationPlugin)
                             throws NullPointerException

      Add an application metadata plugin so as to this object to enhance its application-specific description.

      Parameters:
        `applicationPlugin` - Application plugin object to add to the set of application plugins.
      Throws:
        `NullPointerException` - Cannot add a `null` application plugin object to the set of plugins.
      See Also:
        `getApplicationPlugins()`

    - #### containsApplicationPlugin

          boolean containsApplicationPlugin(ApplicationPluginObject applicationPlugin)
                                     throws NullPointerException

      Determines whether the given application metadata plugin instance is attached to this interchange object.

      Parameters:
        `applicationPlugin` - Application plugin object to check for.
      Returns:
        Is the given application plugin object attached to this interchange object?
      Throws:
        `NullPointerException` - Cannot check for attachment using a `null` value.
      See Also:
        `containsApplicationPlugin(AUID)`, `getApplicationPlugins()`

    - #### containsApplicationPlugin

          boolean containsApplicationPlugin(AUID applicationPluginInstanceID)
                                     throws NullPointerException

      Determines whether the given identifier for a application metadata plugin instance is attached to this interchange object.

      Parameters:
        `applicationPluginInstanceID` - Identifier for the application plugin object to check for.
      Returns:
        Is the given identifier for an application plugin object attached to this interchange object?
      Throws:
        `NullPointerException` - Cannot check for attachment using a `null` value for an identifier.
      See Also:
        `containsApplicationPlugin(ApplicationPluginObject)`, `getApplicationPlugins()`

    - #### clearApplicationPlugins

          void clearApplicationPlugins()

      Clear the set of application metadata plugins, omitting the optional property.

      See Also:
        `getApplicationPlugins()`

    - #### countApplicationPlugins

          int countApplicationPlugins()

      Returns the number of application metadata plugins attached to this interchange object.

      Returns:
        Number of application metadata plugins attached to this object.
      See Also:
        `getApplicationPlugins()`

    - #### removeApplicationPlugin

          boolean removeApplicationPlugin(ApplicationPluginObject applicationPlugin)
                                   throws NullPointerException

      Remove the given application metadata plugin from the set of application plugins attached to this interchange object.

      Parameters:
        `applicationPlugin` - Application plugin object to remove.
      Returns:
        Was the application plugin object removed successfully? A value of `false` is returned if the plugin object was not already attached.
      Throws:
        `NullPointerException` - Cannot remove an application metadata plugin object using a `null` value.
      See Also:
        `getApplicationPlugins()`

    - #### removeApplicationPlugin

          boolean removeApplicationPlugin(AUID applicationPluginInstanceID)
                                   throws NullPointerException

      Remove the application metadata plugin with the given identifier from the set of application plugins attached to this interchange object.

      Parameters:
        `applicationPluginInstanceID` - Identifier of this application plugin object to remove.
      Returns:
        Was the application plugin object removed successfully? A value of `false` is returned if the plugin object was not already attached.
      Throws:
        `NullPointerException` - Cannot remove an application metadata plugin object using a `null` identifier.
      See Also:
        `getApplicationPlugins()`

    - #### deepEquals

          boolean deepEquals(Object o)

      Tests if this interchangeable object is equal to the given object by comparing every property and the properties of any referenced values. Two objects are equal if and only if the following conditions are all met:

      - the given object is not `null`;
      - they are the same object;
      - they are of the same type;
      - they have the same properties omitted or present;
      - the value of each property non-reference or collection property is the same;
      - an array-type property contains the same number of values and a deep equals comparison of each element, index-for-index, is the same;
      - a set-type property contains the same number of values and the same elements, determined by a deep equals comparison;
      - a referenced property is the same according to a deep equals comparison.

      The main difference between this method and `equals(Object)` is that this method compares every property, even when a unique identifier is provided.

      Parameters:
        `o` - Object to test deep equality with this one.
      Returns:
        Do this object and the given object represent the same value?
      See Also:
        `equals(Object)`, `MediaEngine.deepEquals(tv.amwa.maj.industry.MetadataObject, Object)`

    - #### toString

          String toString()

      Provides an XML representation of this value. This value is useful for debugging and understanding the internal structure of an item of media.

      Note that this interface does not guarantee to provide valid XML. Use `XMLBuilder.toXML(tv.amwa.maj.industry.MetadataObject)` for this.

      Overrides:
        `toString` in class `Object`
      Returns:
        An XML representation of the value of this interchange object.
      See Also:
        `XMLBuilder.toXML(tv.amwa.maj.industry.MetadataObject)`, `MediaEngine.toString(tv.amwa.maj.industry.MetadataObject)`

    - #### equals

          boolean equals(Object o)

      Tests if this interchangeable object is equal to the given object by comparing unique identifiers where available, or property-by-property if not. Two objects are equal if and only if the following conditions are all met:

      - the given object is not `null`;
      - they are the same object;
      - they are of the same type;
      - Either:
        - they have the same unique identifier, or
        - the following conditions are met:
          - they have the same properties omitted or present;
          - the value of each property non-reference or collection property is the same using `Object.equals(Object)`;
          - an array-type property contains the same number of values and an equals comparison of each element, index-for-index, is the same;
          - a set-type property contains the same number of values and the same elements, determined by an equals comparison;
          - a referenced property is the same according to an equals comparison.

      For a property-by-property comparison of each value, use `deepEquals(Object)`.

      Overrides:
        `equals` in class `Object`
      Parameters:
        `o` - Object to test equality with this one.
      Returns:
        Do this object and the given object represent the same value?
      See Also:
        `deepEquals(Object)`, `MediaEngine.equals(tv.amwa.maj.industry.MetadataObject, Object)`, `Object.equals(Object)`

    - #### clone

          InterchangeObject clone()

      Create a cloned copy of this interchange object.

      Specified by:
        `clone` in interface `MediaEntity`
      Returns:
        Cloned copy of this interchange object.

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