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

tv.amwa.maj.io.mxf

## Interface RandomIndexPack

- All Superinterfaces:
    MetadataObject, MXFUnit
  All Known Implementing Classes:
    RandomIndexPackImpl

      public interface RandomIndexPack
      extends MXFUnit, MetadataObject

  Represents a random index pack at the end of an MXF file that lists the byte offsets of all the partitions.

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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static UL` | `ripKeyValue` Key defining the start of a random index pack.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRandomIndexItem(int bodySID, long byteOffset)` Add a random index item to this pack by its body stream identifier and byte offset.
    `void` | `addRandomIndexItem(RandomIndexItem randomPartitionItem)` Add an existing random index item to this pack.
    `void` | `clear()` Clears the partition table within this random index pack.
    `RandomIndexPack` | `clone()` Creates a cloned copy of this random index pack.
    `int` | `count()` Returns the number of partitions indexed by this random index pack.
    `int` | `getLength()` Returns the overall length of the random index pack when encoded as bytes, including the key and BER length.
    `RandomIndexItem[]` | `getPartitionIndex()` Returns the array random index items of this random index pack.
    `long[]` | `lookupPartitionOffsets(int bodySID)` Returns an ordered list of the byte offsets for partitions containing the given body stream identifier.
    `void` | `setPartitionIndex(RandomIndexItem[] partitionIndex)` Sets the array of random index items of this random index pack.
    `int` | `writeAsBytes(ByteBuffer buffer)` Serializes this random index pack into its file-based KLV-encoded version in the given buffer.

    - ### Methods inherited from interface tv.amwa.maj.io.mxf.MXFUnit

      `getUnitType`

- - ### Field Detail

    - #### ripKeyValue

          static final UL ripKeyValue

      Key defining the start of a random index pack.

  - ### Method Detail

    - #### getPartitionIndex

          RandomIndexItem[] getPartitionIndex()

      Returns the array random index items of this random index pack. Each partition of the MXF file indexed should have an entry in this array. The array is ordered by the byte offset of the partition.

      Returns:
        Array of random index items of this random index pack.
      See Also:
        `PartitionPack.getThisPartition()`, `TypeDefinitions.RandomIndexItem`, `TypeDefinitions.RandomIndexItemArray`

    - #### setPartitionIndex

          void setPartitionIndex(RandomIndexItem[] partitionIndex)
                          throws NullPointerException

      Sets the array of random index items of this random index pack. Each partition of the MXF file indexed should have an entry in this array. The items will be sorted into byte offset order.

      Parameters:
        `partitionIndex` - Array of random index items of this random index pack.
      Throws:
        `NullPointerException` - Cannot set the partition index with a `null` array.

    - #### count

          @UInt32
          int count()

      Returns the number of partitions indexed by this random index pack.

      Returns:
        Number of partitions indexed by this random index pack.

    - #### lookupPartitionOffsets

          @UInt64
          long[] lookupPartitionOffsets(@UInt32
                                                int bodySID)

      Returns an ordered list of the byte offsets for partitions containing the given body stream identifier. The order of the partitions is the play order of the essence contained in the essence streams.

      Parameters:
        `bodySID` - Body stream identifier to query the partition offsets for.
      Returns:
        List of byte offsets to partitions containing part of the given body SID.

    - #### clear

          void clear()

      Clears the partition table within this random index pack.

    - #### addRandomIndexItem

          void addRandomIndexItem(@UInt32
                                  int bodySID,
                                  @UInt64
                                  long byteOffset)
                           throws IllegalArgumentException

      Add a random index item to this pack by its body stream identifier and byte offset. A random index item describes the location of a partition and which body stream it contains data for.

      Parameters:
        `bodySID` - Body stream identifier of the partition.
        `byteOffset` - Byte offset of the partition in the file, measured from the beginning of the header partition.
      Throws:
        `IllegalArgumentException` - Cannot set the body stream identifier or the byte offset to a negative value.
      See Also:
        `addRandomIndexItem(RandomIndexItem)`, `PartitionPack.getThisPartition()`, `PartitionPack.getBodySID()`

    - #### addRandomIndexItem

          void addRandomIndexItem(RandomIndexItem randomPartitionItem)
                           throws NullPointerException

      Add an existing random index item to this pack. A random index item describes the location of a partition and which body stream it contains data for.

      Parameters:
        `randomPartitionItem` - Item to add to this pack.
      Throws:
        `NullPointerException` - Cannot add a `null` index item.
      See Also:
        `addRandomIndexItem(int, long)`

    - #### getLength

          @UInt32
          int getLength()

      Returns the overall length of the random index pack when encoded as bytes, including the key and BER length.

      Returns:
        Overall length of the random index pack when encoded as bytes, including the key and BER length.
      See Also:
        `writeAsBytes(ByteBuffer)`

    - #### writeAsBytes

          int writeAsBytes(ByteBuffer buffer)
                    throws NullPointerException,
                           InsufficientSpaceException

      Serializes this random index pack into its file-based KLV-encoded version in the given buffer. The buffer must have at least `getLength()` bytes remaining.

      Parameters:
        `buffer` - Buffer to write this random index pack into.
      Returns:
        Number of bytes written.
      Throws:
        `NullPointerException` - Cannot write this random index pack to a null buffer.
        `InsufficientSpaceException` - The given buffer does not have sufficient space remaining.
      See Also:
        `getLength()`

    - #### clone

          RandomIndexPack clone()

      Creates a cloned copy of this random index pack.

      Returns:
        Cloned copy of this random index pack.

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