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

tv.amwa.maj.io.mxf

## Interface MXFFile

- All Superinterfaces:
    Cloneable
  All Known Implementing Classes:
    MXFFileImpl

      public interface MXFFile
      extends Cloneable

  Represents and provides access to the components of an MXF file, including the partitions that it contains.

  To open an MXF file and to start reading it, call static method `MXFFactory.readPartitions(String)` and then access the data it contains using the methods of this class.

  See Also:
    `MXFFactory.readPartitions(String)`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `BodyPartition` | `addBodyPartition(boolean closed, boolean complete, long initialSize, int bodySID, int indexSID, UL... containerFormats)`
    `FooterPartition` | `addFooterPartition(boolean complete, long initialSize, int indexSID, UL... containerFormats)`
    `HeaderPartition` | `addHeaderPartition(boolean closed, boolean complete, long initialSize, int bodySID, int indexSID, UL... containerFormats)`
    `boolean` | `atEOF()` Determine if the internal file pointer at the end of the file?
    `boolean` | `buildPartitionsTable()` Build a partition table from this MXF file containing all the byte offsets of all the partitions in this MXF file.
    `boolean` | `buildRIP()`
    `MXFFile` | `clone()` Returns a cloned copy of the MXF file representation.
    `boolean` | `close()` Close this MXF file, preventing further access and releasing any associated resources.
    `int` | `countPartitions()` Count the number of partitions in this file.
    `byte[]` | `getDigestValue()`
    `long` | `getFileSize()`
    `FooterPartition` | `getFooterPartition()` Get access to the footer partition of this file.
    `HeaderPartition` | `getHeaderPartition()` Get access to the header partition of this file.
    `Partition` | `getPartitionAt(int index)` Returns the partition at the given index in the partition table.
    `RandomIndexPack` | `getRandomIndexPack()` Returns the random index pack from the end of the file, or `null` if the file does not have a random index pack.
    `int` | `getRunInSize()` Returns the length of any run in found in the file.
    `boolean` | `hasRunIn()` Determines whether this file has an optional run-in.
    `boolean` | `isOpen()` Determines if this MXF file is open and therefore and ready to be read and written to.
    `boolean` | `lock()`
    `boolean` | `lockForward()`
    `boolean` | `open(String filename, boolean readOnly)` Open the MXF file with the given name for read-only or read-write as required.
    `boolean` | `readRunIn()` Read the internal pointer passed any run-in to the beginning of the header partition.
    `void` | `setFileKAG(int kag)`
    `void` | `setFileMXFByteLevelVersion(short major, short minor)`
    `void` | `setFileOperationalPattern(UL operationalPattern)`
    `void` | `startDigest(String digestType)`
    `void` | `unlock()`
    `void` | `updatePackSizes()`
    `boolean` | `writeRIP()`

- - ### Method Detail

    - #### open

          boolean open(String filename,
                       boolean readOnly)
                throws IOException

      Open the MXF file with the given name for read-only or read-write as required.

      Parameters:
        `filename` - Name of the file to open.
        `readOnly` - Open the file read-only? Set to `true` for read-only and `false` for read-write.
      Returns:
        Was the file successfully opened and the beginning of the header partition found?
      Throws:
        `IOException` - A problem occurred when trying to open the specified file.
      See Also:
        `MXFFactory.readPartitions(String)`

    - #### close

          boolean close()

      Close this MXF file, preventing further access and releasing any associated resources. Applications should close MXF files as soon as they are finished reading or writing them.

      Returns:
        Was the file successfully closed?

    - #### getRunInSize

          @UInt32
          int getRunInSize()

      Returns the length of any run in found in the file. A run-in is optional in an MXF file.

      Returns:
        Length of any run in found in the file.
      See Also:
        `hasRunIn()`, `readRunIn()`

    - #### hasRunIn

          boolean hasRunIn()

      Determines whether this file has an optional run-in.

      Returns:
        Does this file have an optional run-in?
      See Also:
        `getRunInSize()`, `readRunIn()`

    - #### readRunIn

          boolean readRunIn()
                     throws IOException

      Read the internal pointer passed any run-in to the beginning of the header partition.

      Returns:
        Is the position of the MXF file set at the beginning of the header partition, just beyond the run-in.
      Throws:
        `IOException` - Problem reading the underlying MXF file.
      See Also:
        `getRunInSize()`, `hasRunIn()`

    - #### atEOF

          boolean atEOF()

      Determine if the internal file pointer at the end of the file?

      Returns:
        Is the internal file pointer at the end of the file?

    - #### buildPartitionsTable

          boolean buildPartitionsTable()
                                throws IOException,
                                       EndOfDataException

      Build a partition table from this MXF file containing all the byte offsets of all the partitions in this MXF file. It is necessary to call this method before calling any of the other methods that reference partitions.

      Returns:
        Successful creation of the partition table.
      Throws:
        `IOException` - Problem occurred when trying to read the file.
        `EndOfDataException` - Unexpectedly reached the end of the file, for example when reading through a partition table.

    - #### countPartitions

          int countPartitions()

      Count the number of partitions in this file. A value of zero may indicate that the partitions table still needs to be built with `buildPartitionsTable()`.

      Returns:
        Number of partitions in the file.
      See Also:
        `getPartitionAt(int)`, `buildPartitionsTable()`

    - #### getPartitionAt

          Partition getPartitionAt(int index)
                            throws IndexOutOfBoundsException

      Returns the partition at the given index in the partition table. The partitions are ordered in the sequence they occur in the file, with the partition at index zero being the header partition.

      Parameters:
        `index` - Index of the partition table to retrieve.
      Returns:
        Partition at the given index in the index table.
      Throws:
        `IndexOutOfBoundsException` - No parition at the given index, or the partition table has not yet been built with `buildPartitionsTable()`.
      See Also:
        `buildPartitionsTable()`

    - #### getHeaderPartition

          HeaderPartition getHeaderPartition()

      Get access to the header partition of this file. Ensure that the partition table has been built first with `buildPartitionsTable()`.

      Returns:
        Header partition of the file, or `null` if the file is invalid or the partitions table has not yet been built.
      See Also:
        `getHeaderPartition()`, `buildPartitionsTable()`

    - #### getFooterPartition

          FooterPartition getFooterPartition()

      Get access to the footer partition of this file. Ensure that the partition table has been built first with `buildPartitionsTable()` or a `null` may be returned unexpectedly.

      Returns:
        Footer partition of the file or `null` if a footer partition is not found.
      See Also:
        `getFooterPartition()`, `buildPartitionsTable()`

    - #### getRandomIndexPack

          RandomIndexPack getRandomIndexPack()

      Returns the random index pack from the end of the file, or `null` if the file does not have a random index pack.

      Returns:
        Random index pack from the end of the file if it exists, otherwise `null`.

    - #### isOpen

          boolean isOpen()

      Determines if this MXF file is open and therefore and ready to be read and written to.

      Returns:
        Is this MXF file open?
      See Also:
        `close()`

    - #### addHeaderPartition

          HeaderPartition addHeaderPartition(boolean closed,
                                             boolean complete,
                                             long initialSize,
                                             int bodySID,
                                             int indexSID,
                                             UL... containerFormats)

    - #### addBodyPartition

          BodyPartition addBodyPartition(boolean closed,
                                         boolean complete,
                                         long initialSize,
                                         int bodySID,
                                         int indexSID,
                                         UL... containerFormats)

    - #### addFooterPartition

          FooterPartition addFooterPartition(boolean complete,
                                             long initialSize,
                                             int indexSID,
                                             UL... containerFormats)

    - #### updatePackSizes

          void updatePackSizes()

    - #### buildRIP

          boolean buildRIP()

    - #### writeRIP

          boolean writeRIP()
                    throws IOException

      Throws:
        `IOException`

    - #### setFileOperationalPattern

          void setFileOperationalPattern(UL operationalPattern)
                                  throws NullPointerException

      Throws:
        `NullPointerException`

    - #### setFileKAG

          void setFileKAG(@UInt32
                          int kag)
                   throws IllegalArgumentException

      Throws:
        `IllegalArgumentException`

    - #### setFileMXFByteLevelVersion

          void setFileMXFByteLevelVersion(@UInt16
                                          short major,
                                          @UInt16
                                          short minor)
                                   throws IllegalArgumentException

      Throws:
        `IllegalArgumentException`

    - #### lock

          boolean lock()

    - #### lockForward

          boolean lockForward()

    - #### unlock

          void unlock()

    - #### startDigest

          void startDigest(String digestType)
                    throws NoSuchAlgorithmException

      Throws:
        `NoSuchAlgorithmException`

    - #### getDigestValue

          byte[] getDigestValue()

    - #### getFileSize

          long getFileSize()
                    throws IOException

      Throws:
        `IOException`

    - #### clone

          MXFFile clone()

      Returns a cloned copy of the MXF file representation. Note that the MXF file itself is not copied.

      Returns:
        Cloned copy of the MXF file representation.

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