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

tv.amwa.maj.model

## Interface EssenceData

- All Superinterfaces:
    InterchangeObject, MediaEntity, MetadataObject
  All Known Implementing Classes:
    EssenceDataImpl

      public interface EssenceData
      extends InterchangeObject

  Specifies 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.

  All methods of this interface use bytes to measure the size of buffers. Access to sample-sized sections can only be provided with reference to the associated `codec`, which is provided by an implementation of `EssenceAccess` or `EssenceMultiAccess`.

  See Also:
    `EssenceAccess`, `EssenceMultiAccess`, `MaterialPackage`, `ContentStorage.enumEssenceDataObjects()`, `TypeDefinitions.EssenceDataStrongReference`, `TypeDefinitions.EssenceDataStrongReferenceSet`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `EssenceData` | `clone()` Create a cloned copy of this essence data.
    `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.
    `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.
    `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 essenceStream)` Sets the underlying essence stream of this essence data.
    `void` | `setFilePackage(SourcePackage sourcePackage)` 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` | `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 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

    - #### write

          @UInt32
          int write(@DataBuffer
                            ByteBuffer buffer)
                     throws EndOfDataException,
                            IOException

      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.

      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.

    - #### read

          @DataBuffer
          ByteBuffer read(@UInt32
                                      int bytes)
                               throws IOException,
                                      EndOfDataException

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

      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.

    - #### setPosition

          void setPosition(@PositionType
                           long offset)
                    throws IllegalArgumentException,
                           IOException

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

      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.

    - #### getPosition

          @PositionType
          long getPosition()
                                  throws IOException

      Get the absolute position within the stream of essence data.

      Returns:
        Absolute position within the essence data.
      Throws:
        `IOException` - Error trying to determine position from the underlying stream.

    - #### getSize

          @LengthType
          long getSize()
                            throws IOException

      Returns the total size of the stream of essence data.

      Returns:
        Total size of the essence data.
      Throws:
        `IOException` - Error accessing the underlying stream to determine the length.

    - #### writeSampleIndex

          @UInt32
          int writeSampleIndex(@DataBuffer
                                       ByteBuffer buffer)
                                throws PropertyNotPresentException,
                                       EndOfDataException,
                                       IOException

      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 `setSampleIndexSize(long)` first with sufficient size to write the required buffer.

      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:
        `getSampleIndexPosition()`

    - #### readSampleIndex

          @DataBuffer
          ByteBuffer readSampleIndex(@UInt32
                                                 int size)
                                          throws PropertyNotPresentException,
                                                 IOException,
                                                 EndOfDataException

      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.

      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.

    - #### setSampleIndexPosition

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

      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.

      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.

    - #### getSampleIndexPosition

          @PositionType
          long getSampleIndexPosition()
                                             throws PropertyNotPresentException,
                                                    IOException

      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.

      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

          @LengthType
          long getSampleIndexSize()
                                       throws PropertyNotPresentException,
                                              IOException

      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.

      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.

    - #### setSampleIndex

          void setSampleIndex(Stream sampleIndex)

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

      Parameters:
        `sampleIndex` - Stream of sample index data.

    - #### setSampleIndexSize

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

      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.

      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.

    - #### setFilePackage

          void setFilePackage(SourcePackage sourcePackage)
                       throws NullPointerException

      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.

      Parameters:
        `sourcePackage` - Reference to a source package that describes this essence data.
      Throws:
        `NullPointerException` - The given file source package is `null`.

    - #### getFilePackage

          SourcePackage getFilePackage()

      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 `setFilePackage(SourcePackage)`.

      Returns:
        Reference to a source package.

    - #### getLinkedPackageID

          PackageID getLinkedPackageID()

      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.

      Returns:
        The linked source package identifier associated with the essence.

    - #### getEssenceStream

          Stream getEssenceStream()
                           throws PropertyNotPresentException

      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.

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

    - #### setEssenceStream

          void setEssenceStream(Stream essenceStream)

      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.

      Parameters:
        `essenceStream` - Underlying essence stream of this essence data.
      See Also:
        `read(int)`, `write(ByteBuffer)`, `getPosition()`, `setPosition(long)`, `getSize()`

    - #### getSampleIndex

          Stream getSampleIndex()
                         throws PropertyNotPresentException

      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.

      Returns:
        Sample index for the essence data.
      Throws:
        `PropertyNotPresentException` - The optional sample index is not present for this essence data.

    - #### getIndexSID

          @UInt32
          int getIndexSID()
                           throws PropertyNotPresentException

      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.

      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

          void setIndexSID(@UInt32
                           Integer indexSID)
                    throws IllegalArgumentException

      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.

      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

          @UInt32
          int getBodySID()
                          throws PropertyNotPresentException

      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.

      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

          void setBodySID(@UInt32
                          Integer bodySID)
                   throws IllegalArgumentException

      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.

      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()`

    - #### clone

          EssenceData clone()

      Create a cloned copy of this essence data. The essence data itself is not cloned, just the references to the essence data.

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

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