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

tv.amwa.maj.io.mxf

## Class MXFFactory

- java.lang.Object
- - tv.amwa.maj.io.mxf.MXFFactory

-     public class MXFFactory
      extends Object

  Factory for reading and creating MXF files.

  To read an MXF file, start by calling `readPartitions(String)` and use the `MXFFile` returned to access the data in the file.

  The ability to dump a description of what an MXF file contains is provided by the `dumpFile(String)` static method. Alternatively, run this class as a Java application.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `logging`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MXFFactory()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `dumpFile(String mxfFileName)` Create a textual dump of some of the information in the MXF file specified by file name.
    `static MXFFile` | `emptyFile()` Create an empty MXF file that is to be built up from scratch.
    `static void` | `main(String[] args)` Dump a description of the contents of the MXF file with the given filename to the system out stream.
    `static DeltaEntry` | `makeDeltaEntry(byte posTableIndex, byte slice, int elementDelta)` Create a new delta entry for an index table segment using fully specified component values.
    `static DeltaEntry` | `makeDeltaEntry(int elementDelta)` Create a new delta entry for an index table segment using the element delta and default values.
    `static MXFFile` | `readPartitions(String fileName)` Read and return access to an MXF file with the given file name, building the partition tables in the process.

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

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

- - ### Field Detail

    - #### logging

          public static final boolean logging

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MXFFactory

          public MXFFactory()

  - ### Method Detail

    - #### readPartitions

          public static final MXFFile readPartitions(String fileName)
                                              throws NullPointerException

      Read and return access to an MXF file with the given file name, building the partition tables in the process. If an error occurs when reading the file, access to the file is still returned for reasons of application-specific diagnosis.

      Parameters:
        `fileName` - Name of an MXF file to read.
      Returns:
        Access to an MXF file, with its partitions table already built.
      Throws:
        `NullPointerException` - Cannot open an MXF file using a `null` file name.

    - #### dumpFile

          public static final String dumpFile(String mxfFileName)
                                       throws NullPointerException,
                                              IOException

      Create a textual dump of some of the information in the MXF file specified by file name. The dump includes:

      - Details of the header partition pack;
      - Details of all body partitions in the file;
      - Details of the footer partition if present;
      - A dump of the mandatory header metadata from the header partition, including the primer pack and preface;
      - If present, a dump of any header metadata from the footer partition, including the primer pack and preface;
      - If present, a dump of the random index pack at the end of the file.
      Parameters:
        `mxfFileName` - Name of the MXF file to produce dump information for.
      Returns:
        String containing the dump information requested.
      Throws:
        `NullPointerException` - Cannot dump an MXF file from a `null` file name.
        `IOException` - Could not open the referenced MXF file for reading.

    - #### emptyFile

          public static final MXFFile emptyFile()

      Create an empty MXF file that is to be built up from scratch. The file is not open at this point and must be opened using `MXFFile.open(String, boolean)` before writing any data.

      Returns:
        Empty MXF file.
      See Also:
        `MXFFile.open(String, boolean)`

    - #### makeDeltaEntry

          public static final DeltaEntry makeDeltaEntry(byte posTableIndex,
                                                        byte slice,
                                                        int elementDelta)
                                                 throws IllegalArgumentException

      Create a new delta entry for an index table segment using fully specified component values.

      Parameters:
        `posTableIndex` - If and how the element is subject to temporal reordering. See `DeltaEntry.setPosTableIndex(byte)`.
        `slice` - Slice number for the slice containing this delta entry.
        `elementDelta` - Offset measured in bytes from the start of the start of the indexed element described by this delta entry and the start of the current slice.
      Returns:
        Newly created delta entry.
      Throws:
        `IllegalArgumentException` - One or more of the given values is out of range.
      See Also:
        `IndexTableSegment.setDeltaEntryArray(DeltaEntry[])`

    - #### makeDeltaEntry

          public static final DeltaEntry makeDeltaEntry(int elementDelta)
                                                 throws IllegalArgumentException

      Create a new delta entry for an index table segment using the element delta and default values.

      Parameters:
        `elementDelta` - Offset measured in bytes from the start of the start of the indexed element described by this delta entry and the start of the current slice.
      Returns:
        Newly created delta entry.
      Throws:
        `IllegalArgumentException` - The value of an element delta offset cannot be negative.
      See Also:
        `IndexTableSegment.setDeltaEntryArray(DeltaEntry[])`, `IndexTableSegment.setDeltaEntries(int[])`

    - #### main

          public static final void main(String[] args)
                                 throws Exception

      Dump a description of the contents of the MXF file with the given filename to the system out stream. The output is as described for `dumpFile(String)`.

      Parameters:
        `args` - Name of the MXF file to dump.
      Throws:
        `Exception` - Exception thrown during the dump process.
      See Also:
        `dumpFile(String)`

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