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

tv.amwa.maj.io.mxf

## Interface Partition

- All Superinterfaces:
    Cloneable
  All Known Subinterfaces:
    BodyPartition, EssencePartition, FooterPartition, HeaderPartition
  All Known Implementing Classes:
    BodyPartitionImpl, EssencePartitionImpl, FooterPartitionImpl, HeaderPartitionImpl, PartitionImpl

      public interface Partition
      extends Cloneable

  Represents a partition of an MXF file, which is the top-level sub-division of an MXF file. An MXF file is made up of a sequence of a header partition, followed by zero or more body partitions and an optional footer partition. All partitions are self-describing with a partition pack at the start. Depending on their type, partitions may contain header metadata, stream data and index table segments.

  See Also:
    `MXFFile.buildPartitionsTable()`, `PartitionPack`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `SIZE_UNKNOWN` Size of the partition is not known and will need to be calculated.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `Partition` | `clone()` Create a cloned copy of this partition.
    `long` | `getActualSize()` Returns the current size allocated for the partition, including any fill.
    `long` | `getInitialSize()` Returns the initial partition size given for this partition that is used to calculate the minimum allowed size for the partition.
    `PartitionPack` | `getPartitionPack()` Returns the partition pack that describes this partition, including its size and what it contains.
    `boolean` | `hasEssenceContainer()` Determines whether this partition has an essence container, indicating the presence of (part of) a body stream.
    `boolean` | `hasHeaderMetadata()` Determines whether this partition contains header metadata.
    `boolean` | `hasIndexTable()` Determines whether this partition contains index table data.
    `HeaderMetadata` | `readHeaderMetadata()` Returns the header metadata contained within the partition, if any.
    `IndexTableSegment` | `readIndexTableSegment()` Reads the index table segment of this partition, if any is present.
    `void` | `setInitialDataSize(long initialSize)` Sets the initial partition size for this partition that is used to calculate the minimum allowed size for the partition.
    `void` | `setPartitionPackPadding(long paddingFillSize)` Set the amount of padding to include after each significant entry in the partition, allowing space for the metadata to expand over time.
    `void` | `updateSizes()` Update the size of partition based on the best information known at this time.
    `void` | `writeHeaderMetadata(Preface preface, long headerSize)` Write the header metadata of this partition using that provided in the given preface.
    `void` | `writeIndexTableSegment(IndexTableSegment indexSegment, long segmentLength)`
    `void` | `writeSingleIndexSegment(IndexTableSegment indexTableSegment)`

- - ### Field Detail

    - #### SIZE_UNKNOWN

          static final long SIZE_UNKNOWN

      Size of the partition is not known and will need to be calculated.

      See Also:
        `setInitialDataSize(long)`, Constant Field Values

  - ### Method Detail

    - #### getPartitionPack

          PartitionPack getPartitionPack()

      Returns the partition pack that describes this partition, including its size and what it contains.

      Returns:
        Partition pack that describes this partition.
      See Also:
        `HeaderPartition.getPartitionPack()`, `FooterPartition.getPartitionPack()`, `BodyPartition.getPartitionPack()`

    - #### setPartitionPackPadding

          void setPartitionPackPadding(long paddingFillSize)
                                throws IllegalArgumentException

      Set the amount of padding to include after each significant entry in the partition, allowing space for the metadata to expand over time.

      Parameters:
        `paddingFillSize` - Size of padding to include after the partition.
      Throws:
        `IllegalArgumentException` - Cannot set the padding size to a negative value.
      See Also:
        `Padded.getPaddingFillSize()`, `Padded.setPaddingFillSize(long)`

    - #### readHeaderMetadata

          HeaderMetadata readHeaderMetadata()
                                     throws NullPointerException

      Returns the header metadata contained within the partition, if any.

      Returns:
        Header metadata of this partition, or `null` if no header metadata is present.
      Throws:
        `NullPointerException` - The partition's MXF file is `null` which may occur if this partition is being created unattached.
      See Also:
        `hasHeaderMetadata()`, `writeHeaderMetadata(Preface, long)`

    - #### hasHeaderMetadata

          boolean hasHeaderMetadata()

      Determines whether this partition contains header metadata. All header partitions must contain header metadata. Other partitions may contain header metadata.

      Returns:
        Does this partition have header metadata?
      See Also:
        `readHeaderMetadata()`, `writeHeaderMetadata(Preface, long)`

    - #### writeHeaderMetadata

          void writeHeaderMetadata(Preface preface,
                                   long headerSize)
                            throws NullPointerException,
                                   InsufficientSpaceException,
                                   IOException

      Write the header metadata of this partition using that provided in the given preface. Previous header metadata will be overwritten. Note that sufficient space must be available.

      Parameters:
        `headerMetadata` - Header metadata to associate with this partition.
        `headerSize` - Number of bytes the encoded header should fit within, including filler.
      Throws:
        `NullPointerException` - Cannot associate `null` header metadata with this partition.
        `InsufficientSpaceException` - Calculations based on partition sizes shows that insufficient space is available to write this header metadata.
        `IOException` - Problem occurred writing to the filesystem.
      See Also:
        `readHeaderMetadata()`, `hasHeaderMetadata()`, `#calculateMinimumHeaderMetadataSize(Preface)`

    - #### readIndexTableSegment

          IndexTableSegment readIndexTableSegment()
                                           throws NullPointerException

      Reads the index table segment of this partition, if any is present.

      Returns:
        The index data segment of this partition, or `null` if no index data is present.
      Throws:
        `NullPointerException` - The partition's MXF file is `null` which may occur if this partition is being created unattached.
      See Also:
        `hasIndexTable()`

    - #### writeIndexTableSegment

          void writeIndexTableSegment(IndexTableSegment indexSegment,
                                      long segmentLength)
                               throws NullPointerException,
                                      InsufficientSpaceException,
                                      IOException

      Throws:
        `NullPointerException`
        `InsufficientSpaceException`
        `IOException`

    - #### writeSingleIndexSegment

          void writeSingleIndexSegment(IndexTableSegment indexTableSegment)
                                throws NullPointerException,
                                       InsufficientSpaceException,
                                       IOException

      Throws:
        `NullPointerException`
        `InsufficientSpaceException`
        `IOException`

    - #### hasIndexTable

          boolean hasIndexTable()

      Determines whether this partition contains index table data. The partition may contain a complete index table or just a segment of an index table stream.

      Returns:
        Does this partition have index table data?
      See Also:
        `readIndexTableSegment()`

    - #### hasEssenceContainer

          boolean hasEssenceContainer()

      Determines whether this partition has an essence container, indicating the presence of (part of) a body stream.

      Returns:
        Does this partition have an essence container?

    - #### getInitialSize

          long getInitialSize()

      Returns the initial partition size given for this partition that is used to calculate the minimum allowed size for the partition. Note that this value does not necessarily reflect the actual size of the partition.

      Returns:
        Initial partition size.
      See Also:
        `SIZE_UNKNOWN`, `getActualSize()`

    - #### setInitialDataSize

          void setInitialDataSize(long initialSize)

      Sets the initial partition size for this partition that is used to calculate the minimum allowed size for the partition. Use a value of `SIZE_UNKNOWN` to get MAJ to calculate the size. Note that the implementation will expand the size of the partition beyond the minimum given with this method if required. The size is specified excluding the size of the partition pack.

      Parameters:
        `initialSize` - Initial partition size.
      See Also:
        `SIZE_UNKNOWN`, `getActualSize()`

    - #### updateSizes

          void updateSizes()

      Update the size of partition based on the best information known at this time.

      See Also:
        `MXFFile.updatePackSizes()`

    - #### getActualSize

          long getActualSize()

      Returns the current size allocated for the partition, including any fill. This size may be updated during writing.

      Returns:
        Current size allocated for the partition.
      See Also:
        `getInitialSize()`

    - #### clone

          Partition clone()

      Create a cloned copy of this partition.

      Returns:
        Cloned copy of this partition.

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