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

tv.amwa.maj.model.impl

## Class EssenceDataImpl

- java.lang.Object
- - tv.amwa.maj.model.impl.InterchangeObjectImpl
  - - tv.amwa.maj.model.impl.EssenceDataImpl

- All Implemented Interfaces:
    Serializable, Cloneable, MediaEntity, MetadataObject, EssenceData, InterchangeObject

      @MediaClass(uuid1=218169601,
                  uuid2=257,
                  uuid3=8960,
                  uuid4={6,14,43,52,2,6,1,1},
                  definedName="EssenceData",
                  description="The EssenceData class contains essence.",
                  symbol="EssenceData")
      public class EssenceDataImpl
      extends InterchangeObjectImpl
      implements EssenceData, Serializable, Cloneable

  Implements an essence container. The methods can be used to modify essence data objects that contain the actual essence data (excluding WAVE) when it is contained within an AAF file. Normally, the client application would access the essence through the essence access interface, which handles the work of finding and (de)compressing the data. However, in rare cases direct access to the data is required, the read and write methods of this interface are provided.

  See Also:
    `TypeDefinitions.EssenceDataStrongReference`, `TypeDefinitions.EssenceDataStrongReferenceSet`, Serialized Form

- - ### Field Summary

    - ### Fields inherited from class tv.amwa.maj.model.impl.InterchangeObjectImpl

      `ObjectClassPropertyID`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EssenceDataImpl()`
    `EssenceDataImpl(SourcePackage sourcePackage, Stream data)` Creates and initializes a new essence data object that contains essence.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `EssenceData` | `clone()` Cloned essence data contains the same file package and data, which are not themselves cloned.
    `int` | `getBodySID()` Returns the identifier for the essence container of this this essence data, known as the body stream identifier.
    `Stream` | `getEssenceStream()` Returns the underlying essence stream of this essence data.
    `SourcePackage` | `getFilePackage()` Returns a reference to the file source package that describes this essence data.
    `int` | `getIndexSID()` Returns the identifier of the index table for the essence container of this essence data.
    `PackageID` | `getLinkedPackageID()` Returns the oackage id of the file source package that describes this essence data.
    `String` | `getLinkedPackageIDString()`
    `long` | `getPosition()` Get the absolute position within the stream of essence data.
    `Stream` | `getSampleIndex()` Returns the sample index for the essence data, which contains an index to the samples or frames.
    `long` | `getSampleIndexPosition()` Returns the current sample index position, measured in bytes rather than samples.
    `long` | `getSampleIndexSize()` Returns the total size of the sample index data, measured in bytes rather than the total number of samples.
    `long` | `getSize()` Returns the total size of the stream of essence data.
    `static PackageID` | `initializeLinkedPackageID()`
    `ByteBuffer` | `read(int bytes)` Read the given number of bytes from the pre-interleaved data of an essence stream at the current position.
    `ByteBuffer` | `readSampleIndex(int size)` Reads raw data from a sample index stream at the current sample index position.
    `void` | `setBodySID(Integer bodySID)` Sets the identifier for the essence container of this essence data, known as the body stream identifier.
    `void` | `setEssenceStream(Stream data)` Sets the underlying essence stream of this essence data.
    `void` | `setFilePackage(SourcePackage packageToSet)` Sets a reference to the file source package that describes this essence data.
    `void` | `setIndexSID(Integer indexSID)` Sets the identifier of the index table for the essence container of this essence data.
    `void` | `setLinkedPackageID(PackageID linkedPackageID)`
    `void` | `setLinkedPackageIDString(String linkedPackageID)`
    `void` | `setPosition(long offset)` Seek to an absolute position within the stream of essence data.
    `void` | `setSampleIndex(Stream sampleIndex)` Set the sample index of this essence data to the given stream.
    `void` | `setSampleIndexPosition(long offset)` Seek to an absolute position within the sample index data, measured in bytes rather than samples.
    `void` | `setSampleIndexSize(long sampleIndexSize)` Sets the size of the sample index.
    `int` | `write(ByteBuffer buffer)` Write a pre-interleaved data item into the essence stream, starting at the current position.
    `int` | `writeSampleIndex(ByteBuffer buffer)` Writes the given sample index data to the sample index data at the current sample index stream position.

    - ### Methods inherited from class tv.amwa.maj.model.impl.InterchangeObjectImpl

      `addApplicationPlugin, appendXMLChildren, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getComment, getGeneration, getLinkedGenerationID, getLinkedGenerationIDString, getObjectClass, getPersistentID, getPersistentIndex, hashCode, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setLinkedGenerationIDString, setObjectClass, setPersistentID, setPersistentIndex, toString`

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

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

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

- - ### Constructor Detail

    - #### EssenceDataImpl

          public EssenceDataImpl()

    - #### EssenceDataImpl

          public EssenceDataImpl(SourcePackage sourcePackage,
                                 Stream data)
                          throws NullPointerException

      Creates and initializes a new essence data object that contains essence. This method requires a weak reference to the corresponding metadata source package of the essence data itself.

      Parameters:
        `sourcePackage` - Identifies the source package that describes the essence.
        `data` - The essence data.
      Throws:
        `NullPointerException` - One or both of the arguments is/are `null`.

  - ### Method Detail

    - #### getLinkedPackageID

          @MediaProperty(uuid1=100729094,
                         uuid2=256,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,2},
                         definedName="LinkedPackageID",
                         aliases={"MobID","EssenceDataMobID"},
                         typeName="PackageIDType",
                         optional=false,
                         uniqueIdentifier=true,
                         pid=9985,
                         symbol="LinkedPackageID")
          public PackageID getLinkedPackageID()

      Description copied from interface: `EssenceData`

      Returns the oackage id of the file source package that describes this essence data. The linked source package must exist in the same file as the essence data.

      This is a required persistent property of essence data.

      Specified by:
        `getLinkedPackageID` in interface `EssenceData`
      Returns:
        The linked source package identifier associated with the essence.

    - #### setLinkedPackageID

          @MediaPropertySetter(value="LinkedPackageID")
          public void setLinkedPackageID(PackageID linkedPackageID)

    - #### initializeLinkedPackageID

          public static final PackageID initializeLinkedPackageID()

    - #### getFilePackage

          public SourcePackage getFilePackage()

      Description copied from interface: `EssenceData`

      Returns a reference to the file source package that describes this essence data. This method will return `null` unless the file package reference has previously been set using `EssenceData.setFilePackage(SourcePackage)`.

      Specified by:
        `getFilePackage` in interface `EssenceData`
      Returns:
        Reference to a source package.

    - #### setFilePackage

          public void setFilePackage(SourcePackage packageToSet)
                              throws NullPointerException

      Description copied from interface: `EssenceData`

      Sets a reference to the file source package that describes this essence data. This reference will provide the persistent file package id property for this essence data.

      Specified by:
        `setFilePackage` in interface `EssenceData`
      Parameters:
        `packageToSet` - Reference to a source package that describes this essence data.
      Throws:
        `NullPointerException` - The given file source package is `null`.

    - #### getPosition

          public long getPosition()
                           throws IOException

      Description copied from interface: `EssenceData`

      Get the absolute position within the stream of essence data.

      Specified by:
        `getPosition` in interface `EssenceData`
      Returns:
        Absolute position within the essence data.
      Throws:
        `IOException` - Error trying to determine position from the underlying stream.

    - #### getSampleIndexPosition

          public long getSampleIndexPosition()
                                      throws PropertyNotPresentException,
                                             IOException

      Description copied from interface: `EssenceData`

      Returns the current sample index position, measured in bytes rather than samples. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. The sample index property is optional.

      Specified by:
        `getSampleIndexPosition` in interface `EssenceData`
      Returns:
        Current sample index position.
      Throws:
        `PropertyNotPresentException` - The optional sample index data is not present for this essence data.
        `IOException` - Error trying to retrieve the position from the underlying stream.

    - #### getSampleIndexSize

          public long getSampleIndexSize()
                                  throws PropertyNotPresentException,
                                         IOException

      Description copied from interface: `EssenceData`

      Returns the total size of the sample index data, measured in bytes rather than the total number of samples. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. The sample index property is optional.

      Specified by:
        `getSampleIndexSize` in interface `EssenceData`
      Returns:
        Size of the sample index data measured in bytes.
      Throws:
        `PropertyNotPresentException` - The optional sample index data is not present for this essence data.
        `IOException` - Error accessing the underlying stream to determine the stream length.

    - #### setSampleIndexSize

          public void setSampleIndexSize(@LengthType
                                         long sampleIndexSize)
                                  throws IllegalArgumentException,
                                         NotImplementedException

      Description copied from interface: `EssenceData`

      Sets the size of the sample index. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. Set this value to 0 to omit this optional property.

      This method will extend an existing buffer but will not truncate it. To decrease the size of the buffer, copy the data, call this method with 0 and then write the copied bytes back into the buffer.

      Specified by:
        `setSampleIndexSize` in interface `EssenceData`
      Parameters:
        `sampleIndexSize` - Size for the sample index data.
      Throws:
        `IllegalArgumentException` - The given sample index size is negative or smaller than the sample index already stored.
        `NotImplementedException` - Creating a non existent buffer is not supported in this version of MAJ.

    - #### getSize

          public long getSize()
                       throws IOException

      Description copied from interface: `EssenceData`

      Returns the total size of the stream of essence data.

      Specified by:
        `getSize` in interface `EssenceData`
      Returns:
        Total size of the essence data.
      Throws:
        `IOException` - Error accessing the underlying stream to determine the length.

    - #### read

          public ByteBuffer read(int bytes)
                          throws IOException,
                                 EndOfDataException

      Description copied from interface: `EssenceData`

      Read the given number of bytes from the pre-interleaved data of an essence stream at the current position.

      Specified by:
        `read` in interface `EssenceData`
      Parameters:
        `bytes` - Number of bytes to read from the data stream
      Returns:
        Buffer containing the requested data.
      Throws:
        `IOException` - Error when trying to read data from the underlying stream.
        `EndOfDataException` - Attempting to read beyond the bounds of the data stream.

    - #### readSampleIndex

          public ByteBuffer readSampleIndex(int size)
                                     throws PropertyNotPresentException,
                                            IOException,
                                            EndOfDataException

      Description copied from interface: `EssenceData`

      Reads raw data from a sample index stream at the current sample index position. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec which is why the parameter of this method is measured in bytes rather than number of samples. The sample index property is optional.

      Specified by:
        `readSampleIndex` in interface `EssenceData`
      Parameters:
        `size` - Read this many bytes from the sample index stream.
      Returns:
        The buffer containing the required number of samples.
      Throws:
        `PropertyNotPresentException` - The optional sample index property is not present for this essence data.
        `IOException` - Error trying to read data from the underlying stream.
        `EndOfDataException` - Cannot read data beyond the end of the sample index.

    - #### setPosition

          public void setPosition(long offset)
                           throws IllegalArgumentException,
                                  IOException

      Description copied from interface: `EssenceData`

      Seek to an absolute position within the stream of essence data.

      Specified by:
        `setPosition` in interface `EssenceData`
      Parameters:
        `offset` - Offset from the beginning of the essence.
      Throws:
        `IllegalArgumentException` - Cannot set the position outside the bounds of the underlying stream.
        `IOException` - An error occurred when trying to set the position for the underlying stream.

    - #### setSampleIndexPosition

          public void setSampleIndexPosition(@PositionType
                                             long offset)
                                      throws PropertyNotPresentException,
                                             IllegalArgumentException,
                                             IOException

      Description copied from interface: `EssenceData`

      Seek to an absolute position within the sample index data, measured in bytes rather than samples. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. If the given offset is beyond the end of the stream, the position is set to be the end of the stream.

      Specified by:
        `setSampleIndexPosition` in interface `EssenceData`
      Parameters:
        `offset` - Offset from the beginning of the data measured in bytes.
      Throws:
        `PropertyNotPresentException` - The optional sample index property is not present for this essence data.
        `IllegalArgumentException` - Cannot set the position outside the bounds of the underlying stream.
        `IOException` - Error trying to set the position for the underlying stream.

    - #### write

          public int write(ByteBuffer buffer)
                    throws EndOfDataException,
                           IOException

      Description copied from interface: `EssenceData`

      Write a pre-interleaved data item into the essence stream, starting at the current position. The number of bytes actually written into the essence data is returned.

      Specified by:
        `write` in interface `EssenceData`
      Parameters:
        `buffer` - Buffer containing the data to be written.
      Returns:
        Buffer containing the data.
      Throws:
        `EndOfDataException` - Cannot write beyond the end of the bounds of the underlying stream.
        `IOException` - Error occurred when trying to write data to the underlying stream.

    - #### writeSampleIndex

          public int writeSampleIndex(ByteBuffer buffer)
                               throws PropertyNotPresentException,
                                      EndOfDataException,
                                      IOException

      Description copied from interface: `EssenceData`

      Writes the given sample index data to the sample index data at the current sample index stream position. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. The number of samples actually written is returned and may be less than those requested at the end of the buffer.

      The sample index property is optional. It is not possible to write sample index data if the property is not present. To write data, call `EssenceData.setSampleIndexSize(long)` first with sufficient size to write the required buffer.

      Specified by:
        `writeSampleIndex` in interface `EssenceData`
      Parameters:
        `buffer` - Buffer of sample data to write into the essence data.
      Returns:
        Number of samples actually written.
      Throws:
        `PropertyNotPresentException` - The optional sample index data is not present for this essence data.
        `EndOfDataException` - Cannot write data beyond the bounds of the sample index stream.
        `IOException` - Error occurred when trying to write data to the underlying stream.
      See Also:
        `EssenceData.getSampleIndexPosition()`

    - #### getEssenceStream

          @MediaProperty(uuid1=67568128,
                         uuid2=0,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,2},
                         definedName="EssenceStream",
                         aliases="Data",
                         typeName="Stream",
                         optional=true,
                         uniqueIdentifier=false,
                         pid=9986,
                         symbol="EssenceStream")
          public Stream getEssenceStream()
                                                                                                                                                                                                                                                                                                                                                                                                              throws PropertyNotPresentException

      Description copied from interface: `EssenceData`

      Returns the underlying essence stream of this essence data. This is an optional property for MXF applications only, where the body stream identifier is used instead.

      Specified by:
        `getEssenceStream` in interface `EssenceData`
      Returns:
        Underlying essence stream of this essence data.
      Throws:
        `PropertyNotPresentException` - The essence stream data is not (yet) present for this essence data.
      See Also:
        `EssenceData.read(int)`, `EssenceData.write(ByteBuffer)`, `EssenceData.getPosition()`, `EssenceData.setPosition(long)`, `EssenceData.getSize()`

    - #### setEssenceStream

          @MediaPropertySetter(value="EssenceStream")
          public void setEssenceStream(Stream data)

      Description copied from interface: `EssenceData`

      Sets the underlying essence stream of this essence data. This is an optional property for MXF applications only, where the body stream identifier is used instead. Set this optional property to `null` to omit it.

      Specified by:
        `setEssenceStream` in interface `EssenceData`
      Parameters:
        `data` - Underlying essence stream of this essence data.
      See Also:
        `EssenceData.read(int)`, `EssenceData.write(ByteBuffer)`, `EssenceData.getPosition()`, `EssenceData.setPosition(long)`, `EssenceData.getSize()`

    - #### getSampleIndex

          @MediaProperty(uuid1=100729090,
                         uuid2=256,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,2},
                         definedName="SampleIndex",
                         typeName="Stream",
                         optional=true,
                         uniqueIdentifier=false,
                         pid=11009,
                         symbol="SampleIndex")
          public Stream getSampleIndex()
                                                                                                                                                                                                                                                                                                                                                                             throws PropertyNotPresentException

      Description copied from interface: `EssenceData`

      Returns the sample index for the essence data, which contains an index to the samples or frames. The format of the index is determined by the associated codec. This is an optional property.

      Specified by:
        `getSampleIndex` in interface `EssenceData`
      Returns:
        Sample index for the essence data.
      Throws:
        `PropertyNotPresentException` - The optional sample index is not present for this essence data.

    - #### setSampleIndex

          @MediaPropertySetter(value="SampleIndex")
          public void setSampleIndex(Stream sampleIndex)

      Description copied from interface: `EssenceData`

      Set the sample index of this essence data to the given stream. Set this optional property to `null` to omit it.

      Specified by:
        `setSampleIndex` in interface `EssenceData`
      Parameters:
        `sampleIndex` - Stream of sample index data.

    - #### clone

          public EssenceData clone()

      Cloned essence data contains the same file package and data, which are not themselves cloned.

      Specified by:
        `clone` in interface `MediaEntity`
      Specified by:
        `clone` in interface `EssenceData`
      Specified by:
        `clone` in interface `InterchangeObject`
      Overrides:
        `clone` in class `InterchangeObjectImpl`
      Returns:
        Cloned copy of this interchange object.
      See Also:
        `Object.clone()`

    - #### getLinkedPackageIDString

          public String getLinkedPackageIDString()

    - #### setLinkedPackageIDString

          public void setLinkedPackageIDString(String linkedPackageID)

    - #### getIndexSID

          @MediaProperty(uuid1=16974853,
                         uuid2=0,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,4},
                         definedName="IndexSID",
                         typeName="UInt32",
                         optional=true,
                         uniqueIdentifier=false,
                         pid=16134,
                         symbol="IndexSID")
           @UInt32
          public int getIndexSID()
                                                                                                                                                                                                                                                                                                                                                                       throws PropertyNotPresentException

      Description copied from interface: `EssenceData`

      Returns the identifier of the index table for the essence container of this essence data. The index stream identifier is an optional property used in the encoding of essence streams in MXF files.

      Specified by:
        `getIndexSID` in interface `EssenceData`
      Returns:
        Identifier of the index table for the essence container of this essence data.
      Throws:
        `PropertyNotPresentException` - The optional index table stream identifier property is not present for this essence data.
      See Also:
        `IndexTableSegment`, `PartitionPack.getIndexSID()`

    - #### setIndexSID

          @MediaPropertySetter(value="IndexSID")
          public void setIndexSID(@UInt32
                                                                         Integer indexSID)
                                                                  throws IllegalArgumentException

      Description copied from interface: `EssenceData`

      Sets the identifier of the index table for the essence container of this essence data. The index stream identifier is an optional property used in the encoding of essence streams in MXF files. Set this optional property to `null` to omit it.

      Specified by:
        `setIndexSID` in interface `EssenceData`
      Parameters:
        `indexSID` - Identifier of the index table for the essence container of this essence data.
      Throws:
        `IllegalArgumentException` - Cannot set the index stream identifier to a negative value.
      See Also:
        `IndexTableSegment`, `PartitionPack.getIndexSID()`

    - #### getBodySID

          @MediaProperty(uuid1=16974852,
                         uuid2=0,
                         uuid3=0,
                         uuid4={6,14,43,52,1,1,1,4},
                         definedName="BodySID",
                         typeName="UInt32",
                         optional=true,
                         uniqueIdentifier=false,
                         pid=16135,
                         symbol="BodySID")
           @UInt32
          public int getBodySID()
                                                                                                                                                                                                                                                                                                                                                                    throws PropertyNotPresentException

      Description copied from interface: `EssenceData`

      Returns the identifier for the essence container of this this essence data, known as the body stream identifier. The body stream identifier is an optional property used in the encoding of essence streams in MXF files.

      Specified by:
        `getBodySID` in interface `EssenceData`
      Returns:
        bodySID Identifier for the essence container of this essence data.
      Throws:
        `PropertyNotPresentException` - The optional body stream identifier property is not present for this essence data.
      See Also:
        `EssencePartition`, `PartitionPack.getBodySID()`

    - #### setBodySID

          @MediaPropertySetter(value="BodySID")
          public void setBodySID(@UInt32
                                                                       Integer bodySID)
                                                                throws IllegalArgumentException

      Description copied from interface: `EssenceData`

      Sets the identifier for the essence container of this essence data, known as the body stream identifier. The body stream identifier is an optional property used in the encoding of essence streams in MXF files. Set this optional property to `null` to omit it.

      Specified by:
        `setBodySID` in interface `EssenceData`
      Parameters:
        `bodySID` - Identifier for the essence container of this essence data.
      Throws:
        `IllegalArgumentException` - Cannot set the body stream identifier to a negative value.
      See Also:
        `EssencePartition`, `PartitionPack.getBodySID()`

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