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

tv.amwa.maj.io.file

## Class EssenceAccess

- java.lang.Object
- - tv.amwa.maj.io.file.EssenceMultiAccess
  - - tv.amwa.maj.io.file.EssenceAccess

- All Implemented Interfaces:
    Serializable, EssenceAccess, EssenceMultiAccess

      public class EssenceAccess
      extends EssenceMultiAccess
      implements EssenceAccess, Serializable

  TODO implementation, comments and tests

  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `EssenceAccess(MaterialPackage masterMob, AUIDImpl mediaKind, AUIDImpl codecID, Rational editRate, Rational sampleRate, Rational compEnable, EssenceType essencetype)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static EssenceAccess` | `castFromInterface(EssenceAccess alien)` Cast a `EssenceAccess` value from the generic interface to this implementation of the interface.
    `void` | `completeWrite()` Handle any format related writing at the end of the essence and adjust package lengths as required.
    `long` | `countSamples(DataDefinition dataDef)` Returns the number of samples of the given essence type on the essence stream.
    `AUIDImpl` | `getCodecID()` Returns the identifier of the codec being used to handle the specified essence.
    `String` | `getCodecName()` Returns the friendly name of the codec expanded for human consumption.
    `EssenceFormat` | `getEmptyFileFormat()` Returns an empty `EssenceFormat` object.
    `EssenceFormat` | `getFileFormat(EssenceFormat opsTemplate)` Given an AAFEssenceFormat, read the essence parameters inside and set the values from the file format.
    `EssenceFormat` | `getFileFormatParametersList()` Returns a list of all file format parameters supported by the current codec.
    `long` | `getIndexedSampleSize(DataDefinition dataDef, long frameNum)` Returns the size in bytes of the given sample for a given essence type.
    `long` | `getLargestSampleSize(DataDefinition dataDef)` Returns the size in bytes of the largest sample for a given essence type.
    `int` | `getSamplesActuallyRead()` Returns the number of samples actually read by the last call to `EssenceAccess.readSamples(int)`.
    `void` | `putFileFormat(EssenceFormat ops)` Given an `EssenceFormat`, read the essence parameters inside and change the file format.
    `byte[]` | `readSamples(int samples)` Read a given number of samples from an opened essence stream.
    `void` | `seek(long sampleFrameNum)` The seek function for essence.
    `void` | `setEssenceCodecFlavour(AUID flavour)` Sets which flavour of the codec for the essence is to be used.
    `void` | `setTransformParameters(List<? extends EssenceFormat> op)` Sets a series of format objects which will be used to describe the in-memory format.
    `int` | `writeSamples(int samples, byte[] buffer)` Writes data to the essence stream.

    - ### Methods inherited from class tv.amwa.maj.io.file.EssenceMultiAccess

      `castFromInterface, readMultiSamples, writeMultiSamples`

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

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface tv.amwa.maj.model.EssenceMultiAccess

      `readMultiSamples, writeMultiSamples`

- - ### Constructor Detail

    - #### EssenceAccess

          public EssenceAccess(MaterialPackage masterMob,
                               AUIDImpl mediaKind,
                               AUIDImpl codecID,
                               Rational editRate,
                               Rational sampleRate,
                               Rational compEnable,
                               EssenceType essencetype)

  - ### Method Detail

    - #### castFromInterface

          public static final EssenceAccess castFromInterface(EssenceAccess alien)
                                                       throws NullPointerException

      Cast a `EssenceAccess` value from the generic interface to this implementation of the interface. If the given value is not a native implementation, a copy will be instanciated using get and set methods.

      Parameters:
        `alien` - A potentially alien implementation of an instance of the EssenceAccess interface.
      Returns:
        Instance of this class that is equal to the given value and that is an instance of this concrete implementation.
      Throws:
        `NullPointerException` - Argument is null.

    - #### completeWrite

          public void completeWrite()
                             throws StreamFullException

      Description copied from interface: `EssenceAccess`

      Handle any format related writing at the end of the essence and adjust package lengths as required. Must be called before releasing a write essence access.

      Specified by:
        `completeWrite` in interface `EssenceAccess`
      Throws:
        `StreamFullException` - The stream has insufficient capacity to complete the write operation.
      See Also:
        `EssenceAccess.completeWrite()`

    - #### countSamples

          public long countSamples(DataDefinition dataDef)
                            throws NullPointerException

      Description copied from interface: `EssenceAccess`

      Returns the number of samples of the given essence type on the essence stream. A video sample is one frame.

      Specified by:
        `countSamples` in interface `EssenceAccess`
      Parameters:
        `dataDef` - Type of essence to count.
      Returns:
        Number of samples that are present for the given essence type.
      Throws:
        `NullPointerException` - The given essence type is `null`.
      See Also:
        `EssenceAccess.countSamples(tv.amwa.maj.model.DataDefinition)`

    - #### getCodecID

          public AUIDImpl getCodecID()

      Description copied from interface: `EssenceAccess`

      Returns the identifier of the codec being used to handle the specified essence. This will be required in order to be able to send private data to the codec.

      Specified by:
        `getCodecID` in interface `EssenceAccess`
      Returns:
        The current codec used for accessing the essence.
      See Also:
        `EssenceAccess.getCodecID()`

    - #### getCodecName

          public String getCodecName()

      Description copied from interface: `EssenceAccess`

      Returns the friendly name of the codec expanded for human consumption. No other call uses this name, so it may be fully descriptive, especially of limitations.

      Specified by:
        `getCodecName` in interface `EssenceAccess`
      Returns:
        Human-readable name and optional description of codec.
      See Also:
        `EssenceAccess.getCodecName()`

    - #### getEmptyFileFormat

          public EssenceFormat getEmptyFileFormat()

      Description copied from interface: `EssenceAccess`

      Returns an empty `EssenceFormat` object. This is the factory method for EssenceFormat.

      Specified by:
        `getEmptyFileFormat` in interface `EssenceAccess`
      Returns:
        An empty essence format object.
      See Also:
        `EssenceAccess.getEmptyFileFormat()`

    - #### getFileFormat

          public EssenceFormat getFileFormat(EssenceFormat opsTemplate)
                                      throws NullPointerException,
                                             InvalidParameterException

      Description copied from interface: `EssenceAccess`

      Given an AAFEssenceFormat, read the essence parameters inside and set the values from the file format.

      Specified by:
        `getFileFormat` in interface `EssenceAccess`
      Parameters:
        `opsTemplate` - An `EssenceFormat` with parameter codes set but no values.
      Returns:
        Another `EssenceFormat` with values set.
      Throws:
        `NullPointerException` - Argument is null.
        `InvalidParameterException` - Matching parameter not found.
      See Also:
        `EssenceAccess.getFileFormat(tv.amwa.maj.model.EssenceFormat)`

    - #### getFileFormatParametersList

          public EssenceFormat getFileFormatParametersList()

      Description copied from interface: `EssenceAccess`

      Returns a list of all file format parameters supported by the current codec.

      Specified by:
        `getFileFormatParametersList` in interface `EssenceAccess`
      Returns:
        List of file format parameters.
      See Also:
        `EssenceAccess.getFileFormatParametersList()`

    - #### getIndexedSampleSize

          public long getIndexedSampleSize(DataDefinition dataDef,
                                           long frameNum)
                                    throws NullPointerException,
                                           BadSampleOffsetException

      Description copied from interface: `EssenceAccess`

      Returns the size in bytes of the given sample for a given essence type. For uncompressed data, or the output of the software codec, the sample size is likely be a constant value.

      The essence type parameter exists to support codecs with multiple interleaved essence types.

      Specified by:
        `getIndexedSampleSize` in interface `EssenceAccess`
      Parameters:
        `dataDef` - The essence type.
        `frameNum` - The 0-based index of a sample frame number.
      Returns:
        Size of the sample frame at the given index for the given type of data.
      Throws:
        `NullPointerException` - The given essence type is `null`.
        `BadSampleOffsetException` - The supplied sample offset is outside the acceptable range for the essence.
      See Also:
        `EssenceAccess.getIndexedSampleSize(tv.amwa.maj.model.DataDefinition, long)`

    - #### getLargestSampleSize

          public long getLargestSampleSize(DataDefinition dataDef)
                                    throws NullPointerException

      Description copied from interface: `EssenceAccess`

      Returns the size in bytes of the largest sample for a given essence type.

      For uncompressed data, or the output of the software codec, the sample size is likely to be a constant value.

      The essence type parameter exists to support codecs with multiple interleaved essence types.

      Specified by:
        `getLargestSampleSize` in interface `EssenceAccess`
      Parameters:
        `dataDef` - The essence type.
      Returns:
        The largest sample size for the given essence type.
      Throws:
        `NullPointerException` - The given essence type is `null`
      See Also:
        `EssenceAccess.getLargestSampleSize(tv.amwa.maj.model.DataDefinition)`

    - #### getSamplesActuallyRead

          public int getSamplesActuallyRead()

      Description copied from interface: `EssenceAccess`

      Returns the number of samples actually read by the last call to `EssenceAccess.readSamples(int)`.

      Specified by:
        `getSamplesActuallyRead` in interface `EssenceAccess`
      Returns:
        Number of samples actually read. Will return 0 if `EssenceAccess.readSamples(int)` has not previously been called or 0 samples were read.
      See Also:
        `EssenceAccess.getSamplesActuallyRead()`

    - #### putFileFormat

          public void putFileFormat(EssenceFormat ops)
                             throws NullPointerException

      Description copied from interface: `EssenceAccess`

      Given an `EssenceFormat`, read the essence parameters inside and change the file format.

      Specified by:
        `putFileFormat` in interface `EssenceAccess`
      Parameters:
        `ops` - An `EssenceFormat` with one or more parameter/value pairs.
      Throws:
        `NullPointerException` - Argument is null.
      See Also:
        `EssenceAccess.putFileFormat(tv.amwa.maj.model.EssenceFormat)`

    - #### readSamples

          public byte[] readSamples(int samples)
                             throws EndOfDataException

      Description copied from interface: `EssenceAccess`

      Read a given number of samples from an opened essence stream. This call will only return a single channel of essence from an interleaved stream. A signle video sample is a frame.

      Specified by:
        `readSamples` in interface `EssenceAccess`
      Parameters:
        `samples` - Read this many samples.
      Returns:
        Buffer containing samples.
      Throws:
        `EndOfDataException` - Hit the end of the essence (like EOF) while reading.
      See Also:
        `EssenceAccess.readSamples(int)`

    - #### seek

          public void seek(long sampleFrameNum)
                    throws BadSampleOffsetException

      Description copied from interface: `EssenceAccess`

      The seek function for essence. Useful only on reading as you cannot seek around while writing essence.

      An audio frame is one sample across all channels.

      Specified by:
        `seek` in interface `EssenceAccess`
      Parameters:
        `sampleFrameNum` - A 0-based offset in units of the sample rate to seek to.
      Throws:
        `BadSampleOffsetException` - Hit the end of the essence (like EOF) while reading.
      See Also:
        `EssenceAccess.seek(long)`

    - #### setEssenceCodecFlavour

          public void setEssenceCodecFlavour(AUID flavour)
                                      throws NullPointerException

      Description copied from interface: `EssenceAccess`

      Sets which flavour of the codec for the essence is to be used.

      Specified by:
        `setEssenceCodecFlavour` in interface `EssenceAccess`
      Parameters:
        `flavour` - The codec flavour to be used.
      Throws:
        `NullPointerException` - The given codec flavour is `null`.
      See Also:
        `EssenceAccess.setEssenceCodecFlavour(tv.amwa.maj.record.AUID)`

    - #### setTransformParameters

          public void setTransformParameters(List<? extends EssenceFormat> op)
                                      throws NullPointerException

      Description copied from interface: `EssenceAccess`

      Sets a series of format objects which will be used to describe the in-memory format. This is the format expected on writes and produced on reads. On writes, the data will be written in this format, except where a software codec may be used. On reads, the data will be translated to this format.

      The order of the parameters does matter, as transformations will be applied in that order to get from the on-disk format to the in-memory format.

      Specified by:
        `setTransformParameters` in interface `EssenceAccess`
      Parameters:
        `op` - An ordered list iterator over transforms to apply to the essence if required.
      Throws:
        `NullPointerException` - Argument is null.
      See Also:
        `tv.amwa.maj.model.EssenceAccess#setTransformParameters(java.util.ListIterator)`

    - #### writeSamples

          public int writeSamples(int samples,
                                  byte[] buffer)
                           throws NullPointerException,
                                  SingleChannelOpException

      Description copied from interface: `EssenceAccess`

      Writes data to the essence stream.

      A single video frame is one sample.

      Specified by:
        `writeSamples` in interface `EssenceAccess`
      Parameters:
        `samples` - Write this many samples.
        `buffer` - Buffer to write data from.
      Returns:
        The number of samples actually written.
      Throws:
        `NullPointerException` - The given buffer is `null`.
        `SingleChannelOpException` - Tried to write to an interleaved stream.
      See Also:
        `EssenceAccess.writeSamples(int, byte[])`

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