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

tv.amwa.maj.io.mxf

## Interface IndexTableSegment

- All Superinterfaces:
    Cloneable, MetadataObject, MXFUnit
  All Known Implementing Classes:
    IndexTableSegmentImpl

      public interface IndexTableSegment
      extends Cloneable, MetadataObject, MXFUnit

  An index table segment makes up part or all of an index table. A index segment provides details of stream offsets that map an edit unit to its position within an essence container.

  See Also:
    `IndexEntry`, `DeltaEntry`, `IndexTable`, `Partition.readIndexTableSegment()`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `EDITUNITBYTECOUNT_DEFAULT` Default value for the edit unit byte count value for the index table segment, which when set to zero as in this default indicates that the index entry array elements should be used to determine stream offsets.
    `static long` | `EXTSTARTOFFSET_DEFAULT` Default value for the external start offset property that gives the the byte offset to the first essence data in a CBE (Constant Bytes per Element) essence stream.
    `static UL` | `key` Universal label identifying an index table segment.
    `static int` | `SLICECOUNT_DEFAULT` Default value for the number of slices dividing up the elements of a single edit unit.
    `static long` | `VBEBYTECOUNT_DEFAULT` Default value for the VBE byte count property that gives the byte offset to the end of the final essence unit in a VBE (Variable Bytes per Element) essence stream.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `IndexTableSegment` | `clone()` Creates a cloned copy of this index table segment.
    `int` | `getBodySID()` Returns the stream identifier of the indexed essence container.
    `DeltaEntry[]` | `getDeltaEntryArray()` Returns the array of delta entries for this index table segment that describe the layout of each element stored within an edit unit.
    `int` | `getEditUnitByteCount()` Returns the byte count of each and every edit unit in the indexed essence container, which is greater than zero when this is a fixed size for all edit units.
    `long` | `getExtStartOffset()` Get the external start offset property of this index table segment that the byte offset to the first essence data in a CBE (Constant Bytes per Element) essence stream.
    `long` | `getIndexDuration()` Returns the time duration of this table segment measured in number of edit units of the referenced package.
    `Rational` | `getIndexEditRate()` Returns the edit rate of the master track in the indexed essence container, measured in hertz.
    `IndexEntry[]` | `getIndexEntryArray()` Returns the array of index entries for this index table segment that describes the stream offset of each edit unit.
    `int` | `getIndexSID()` Returns the stream identifier for this index table.
    `long` | `getIndexStartPosition()` Returns the first editable unit indexed by this index table segment measured in file package edit units.
    `byte` | `getPosTableCount()` Returns the number of entries in the position offsets table per edit unit, minus one as only offsets are recorded in the array.
    `byte` | `getSliceCount()` Returns the number of slices used to group the elements within an edit unit, minus one as only slice offsets are recorded in an array.
    `long` | `getVBEByteCount()` Get the VBE byte count value that gives the byte offset to the end of the final essence unit in a VBE (Variable Bytes per Element) essence stream.
    `void` | `setBodySID(int bodySID)` Sets the stream identifier of the indexed essence container.
    `void` | `setDeltaEntries(int[] elementDeltas)` Sets the array of delta entries for this index table segment using element delta offsets only.
    `void` | `setDeltaEntryArray(DeltaEntry[] deltaEntryArray)` Sets the array of delta entries for this index table segment that describe the layout of each element stored within an edit unit.
    `void` | `setEditUnitByteCount(int editUnitByteCount)` Sets the byte count of each and every edit unit in the indexed essence container, which is greater than zero when this is a fixed size for all edit units.
    `void` | `setExtStartOffset(Long extStartOffset)` Sets the external start offset property of this index table segment that the byte offset to the first essence data in a CBE (Constant Bytes per Element) essence stream.
    `void` | `setIndexDuration(long indexDuration)` Sets the time duration of this table segment measured in number of edit units of the referenced package.
    `void` | `setIndexEditRate(Rational indexEditRate)` Sets the edit rate of the master track in the indexed essence container, measured in hertz.
    `void` | `setIndexEntryArray(IndexEntry[] indexEntryArray)` Sets the array of index entries for this index table segment that describes the stream offset of each edit unit.
    `void` | `setIndexSID(int indexSID)` Sets the stream identifier for this index table.
    `void` | `setIndexStartPosition(long indexStartPosition)` Sets the first editable unit indexed by this index table segment measured in file package edit units.
    `void` | `setPosTableCount(Byte posTableCount)` Sets the number of entries in the position offsets table per edit unit, minus one as only offsets are recorded in the array.
    `void` | `setSliceCount(byte sliceCount)` Sets the number of slices used to group the elements within an edit unit, minus one as only slice offsets are recorded in an array.
    `void` | `setVBEByteCount(Long vbeByteCount)` Sets the VBE byte count value that gives the byte offset to the end of the final essence unit in a VBE (Variable Bytes per Element) essence stream.

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

      `getUnitType`

- - ### Field Detail

    - #### EDITUNITBYTECOUNT_DEFAULT

          static final int EDITUNITBYTECOUNT_DEFAULT

      Default value for the edit unit byte count value for the index table segment, which when set to zero as in this default indicates that the index entry array elements should be used to determine stream offsets.

      See Also:
        `getEditUnitByteCount()`, `setEditUnitByteCount(int)`, Constant Field Values

    - #### SLICECOUNT_DEFAULT

          static final int SLICECOUNT_DEFAULT

      Default value for the number of slices dividing up the elements of a single edit unit.

      See Also:
        `getSliceCount()`, `setSliceCount(byte)`, `IndexEntry.getSliceOffset()`, Constant Field Values

    - #### EXTSTARTOFFSET_DEFAULT

          static final long EXTSTARTOFFSET_DEFAULT

      Default value for the external start offset property that gives the the byte offset to the first essence data in a CBE (Constant Bytes per Element) essence stream.

      See Also:
        `getExtStartOffset()`, `setExtStartOffset(java.lang.Long)`, Constant Field Values

    - #### VBEBYTECOUNT_DEFAULT

          static final long VBEBYTECOUNT_DEFAULT

      Default value for the VBE byte count property that gives the byte offset to the end of the final essence unit in a VBE (Variable Bytes per Element) essence stream.

      See Also:
        `getVBEByteCount()`, `setVBEByteCount(java.lang.Long)`, Constant Field Values

    - #### key

          static final UL key

      Universal label identifying an index table segment.

  - ### Method Detail

    - #### getIndexEditRate

          Rational getIndexEditRate()

      Returns the edit rate of the master track in the indexed essence container, measured in hertz. If the container has only one track, this is the edit rate of that track. If the essence container interleaves video and audio, it is standard practice to use the picture track to provide the index edit rate.

      Returns:
        Edit rate of the master track in the essence container, measured in hertz.

    - #### setIndexEditRate

          void setIndexEditRate(Rational indexEditRate)
                         throws NullPointerException,
                                BadRateException

      Sets the edit rate of the master track in the indexed essence container, measured in hertz. If the container has only one track, this is the edit rate of that track. If the essence container interleaves video and audio, it is standard practice to use the picture track to provide the index edit rate.

      Parameters:
        `indexEditRate` - Edit rate of the master track in the essence container, measured in hertz.
      Throws:
        `NullPointerException` - Cannot set the index edit rate with a `null` value.
        `BadRateException` - The given rate is not acceptable because it is negative or has a zero denominator.

    - #### getIndexStartPosition

          @PositionType
          long getIndexStartPosition()

      Returns the first editable unit indexed by this index table segment measured in file package edit units.

      Returns:
        First editable unit indexed by this index table segment,

    - #### setIndexStartPosition

          void setIndexStartPosition(@PositionType
                                     long indexStartPosition)

      Sets the first editable unit indexed by this index table segment measured in file package edit units.

      Parameters:
        `indexStartPosition` - First editable unit indexed by this index table segment.

    - #### getIndexDuration

          @LengthType
          long getIndexDuration()

      Returns the time duration of this table segment measured in number of edit units of the referenced package.

      Returns:
        Time duration of this table segment measured in number of edit units.

    - #### setIndexDuration

          void setIndexDuration(@LengthType
                                long indexDuration)

      Sets the time duration of this table segment measured in number of edit units of the referenced package.

      Parameters:
        `indexDuration` - Time duration of this table segment measured in number of edit units.

    - #### getEditUnitByteCount

          @UInt32
          int getEditUnitByteCount()

      Returns the byte count of each and every edit unit in the indexed essence container, which is greater than zero when this is a fixed size for all edit units. The default value of 0 defines that the byte count for each edit unit may be variables and shall be looked up in the index entry array.

      Returns:
        Byte count of each and every edit unit in the essence container.
      See Also:
        `EDITUNITBYTECOUNT_DEFAULT`

    - #### setEditUnitByteCount

          void setEditUnitByteCount(@UInt32
                                    int editUnitByteCount)
                             throws IllegalArgumentException

      Sets the byte count of each and every edit unit in the indexed essence container, which is greater than zero when this is a fixed size for all edit units. The default value of 0 defines that the byte count for each edit unit may be variables and shall be looked up in the index entry array.

      Parameters:
        `editUnitByteCount` - Byte count of each and every edit unit in the essence container.
      Throws:
        `IllegalArgumentException` - The edit unit byte count cannot be a negative value.
      See Also:
        `EDITUNITBYTECOUNT_DEFAULT`

    - #### getIndexSID

          @UInt32
          int getIndexSID()

      Returns the stream identifier for this index table. A partition can only hold one index table. All index table segments within a partition and making up the same index table must have the same identifier. The identifier is unique within the scope of an MXF file.

      Returns:
        Stream identifier for this index table.

    - #### setIndexSID

          void setIndexSID(@UInt32
                           int indexSID)
                    throws IllegalArgumentException

      Sets the stream identifier for this index table. A partition can only hold one index table. All index table segments within a partition and making up the same index table must have the same identifier. The identifier is unique within the scope of an MXF file.

      Parameters:
        `indexSID` - Stream identifier for this index table.
      Throws:
        `IllegalArgumentException` - A stream identifier cannot be a negative value.

    - #### getBodySID

          int getBodySID()

      Returns the stream identifier of the indexed essence container. The indexed container may be in the same partition as the index or a different one, but the identifier is always unique within the scope of an MXF file.

      Returns:
        Stream identifier of the indexed essence container.

    - #### setBodySID

          void setBodySID(@UInt32
                          int bodySID)
                   throws IllegalArgumentException

      Sets the stream identifier of the indexed essence container. The indexed container may be in the same partition as the index or a different one, but the identifier is always unique within the scope of an MXF file.

      Parameters:
        `bodySID` - Stream identifier of the indexed essence container.
      Throws:
        `IllegalArgumentException` - Cannot set the stream identifier to a negative value.

    - #### getSliceCount

          @UInt8
          byte getSliceCount()

      Returns the number of slices used to group the elements within an edit unit, minus one as only slice offsets are recorded in an array. A new slice is required after any variable bit rate element in an interleaved stream of essence and the offset to the essence is recorded in the edit unit's index entry.

      The default value for this property is 0.

      Note that the slice count is required to resolve bytes to slice offsets for an index entry.

      Returns:
        Number of slices used to group the elements within an edit unit, minus one.
      See Also:
        `SLICECOUNT_DEFAULT`, `IndexEntry.getSliceOffset()`, `IndexEntry.resolveBytes(IndexTableSegment)`

    - #### setSliceCount

          void setSliceCount(@UInt8
                             byte sliceCount)
                      throws IllegalArgumentException

      Sets the number of slices used to group the elements within an edit unit, minus one as only slice offsets are recorded in an array. A new slice is required after any variable bit rate element in an interleaved stream of essence and the offset to the essence is recorded in the edit unit's index entry.

      The default value for this property is 0.

      Note that the slice count is required to resolve bytes to slice offsets for an index entry.

      Parameters:
        `sliceCount` - Number of slices used to group the elements within an edit unit, minus one.
      Throws:
        `IllegalArgumentException` - Cannot set the slice count to a negative value.
      See Also:
        `SLICECOUNT_DEFAULT`, `IndexEntry.getSliceOffset()`, `IndexEntry.resolveBytes(IndexTableSegment)`

    - #### getPosTableCount

          @UInt8
          byte getPosTableCount()
                                throws PropertyNotPresentException

      Returns the number of entries in the position offsets table per edit unit, minus one as only offsets are recorded in the array. Position table offsets record the temporal fractional offset from the edit unit of the indexes master track, normally the picture track, and the start of other interleaved elements, such as sound tracks. This is an optional property that is omitted when all elements are temporally aligned or streams are not interleaved.

      Note that the slice count is required to resolve bytes to slice offsets for an index entry.

      Returns:
        Number of slices used to group the elements within an edit unit, minus one.
      Throws:
        `PropertyNotPresentException` - The optional position table count property is not present for this index table segment.
      See Also:
        `IndexEntry.getPosTable()`, `IndexEntry.resolveBytes(IndexTableSegment)`

    - #### setPosTableCount

          void setPosTableCount(@UInt8
                                Byte posTableCount)
                         throws IllegalArgumentException

      Sets the number of entries in the position offsets table per edit unit, minus one as only offsets are recorded in the array. Position table offsets record the temporal fractional offset from the edit unit of the indexes master track, normally the picture track, and the start of other interleaved elements, such as sound tracks. This is an optional property that is omitted when all elements are temporally aligned or streams are not interleaved.

      Note that the slice count is required to resolve bytes to slice offsets for an index entry.

      Parameters:
        `posTableCount` - Number of slices used to group the elements within an edit unit, minus one.
      Throws:
        `IllegalArgumentException` - Cannot set the position table count to a negative value.
      See Also:
        `IndexEntry.getPosTable()`, `IndexEntry.resolveBytes(IndexTableSegment)`

    - #### getDeltaEntryArray

          DeltaEntry[] getDeltaEntryArray()
                                   throws PropertyNotPresentException

      Returns the array of delta entries for this index table segment that describe the layout of each element stored within an edit unit. This is an optional property and, when omitted, indicates only one element per edit unit.

      Returns:
        Array of delta entries for this index table segment.
      Throws:
        `PropertyNotPresentException` - The optional delta entry array is not present for this index table segment.
      See Also:
        `getSliceCount()`, `TypeDefinitions.DeltaEntry`, `TypeDefinitions.DeltaEntryArray`

    - #### setDeltaEntryArray

          void setDeltaEntryArray(DeltaEntry[] deltaEntryArray)
                           throws NullPointerException

      Sets the array of delta entries for this index table segment that describe the layout of each element stored within an edit unit. Set this optional property to `null` to omit it, indicating that only one element exists per edit unit.

      Parameters:
        `deltaEntryArray` - Array of delta entries for this index table segment.
      Throws:
        `NullPointerException` - One or more of the given delta elements is `null`.
      See Also:
        `setDeltaEntries(int[])`, `setSliceCount(byte)`, `MXFFactory.makeDeltaEntry(byte, byte, int)`, `MXFFactory.makeDeltaEntry(int)`

    - #### setDeltaEntries

          void setDeltaEntries(int[] elementDeltas)
                        throws NullPointerException,
                               IllegalArgumentException

      Sets the array of delta entries for this index table segment using element delta offsets only. The delta entries describe the layout of each element stored within an edit unit. Default values are set for the position table index and slice components of each entry.

      Parameters:
        `elementDeltas` - List of element delta offsets for the elements stored within each frame.
      Throws:
        `NullPointerException` - Cannot set the element deltas using a `null` array.
        `IllegalArgumentException` - Offsets cannot be negative values.
      See Also:
        `setDeltaEntryArray(DeltaEntry[])`

    - #### getIndexEntryArray

          IndexEntry[] getIndexEntryArray()
                                   throws PropertyNotPresentException

      Returns the array of index entries for this index table segment that describes the stream offset of each edit unit. The index entry array is required when variable bit rate coding is in use. This is an optional property that is omitted when each edit unit can be found using a multiple of the edit unit byte count.

      Returns:
        Array of index entries for this index table segment.
      Throws:
        `PropertyNotPresentException` - The optional index entry array property is not present for this index table segment.
      See Also:
        `getEditUnitByteCount()`, `EDITUNITBYTECOUNT_DEFAULT`, `TypeDefinitions.IndexEntry`, `TypeDefinitions.IndexEntryArray`

    - #### setIndexEntryArray

          void setIndexEntryArray(IndexEntry[] indexEntryArray)
                           throws NullPointerException

      Sets the array of index entries for this index table segment that describes the stream offset of each edit unit. The index entry array is required when variable bit rate coding is in use. Set this optional property to `null` to omit it, which should be the case when each edit unit can be found using a multiple of the edit unit byte count.

      Parameters:
        `indexEntryArray` - Array of index entries for this index table segment.
      Throws:
        `NullPointerException` - One or more of the given index entries in the given array is `null`.
      See Also:
        `setEditUnitByteCount(int)`, `EDITUNITBYTECOUNT_DEFAULT`

    - #### getExtStartOffset

          @UInt64
          long getExtStartOffset()
                                  throws PropertyNotPresentException

      Get the external start offset property of this index table segment that the byte offset to the first essence data in a CBE (Constant Bytes per Element) essence stream. This is an optional property.

      Returns:
        External start offset of this index table segment.
      Throws:
        `PropertyNotPresentException`
      See Also:
        `EXTSTARTOFFSET_DEFAULT`

    - #### setExtStartOffset

          void setExtStartOffset(@UInt64
                                 Long extStartOffset)
                          throws IllegalArgumentException

      Sets the external start offset property of this index table segment that the byte offset to the first essence data in a CBE (Constant Bytes per Element) essence stream. Set this property to `null` to omit it.

      The default value for this property is 0L.

      Parameters:
        `extStartOffset` - External start offset of this index table segment.
      Throws:
        `IllegalArgumentException` - The external start offset property cannot be negative.
      See Also:
        `EXTSTARTOFFSET_DEFAULT`

    - #### getVBEByteCount

          @UInt64
          long getVBEByteCount()
                                throws PropertyNotPresentException

      Get the VBE byte count value that gives the byte offset to the end of the final essence unit in a VBE (Variable Bytes per Element) essence stream. This value can be used to calculate the size of the final essence unit. This is an optional property.

      The default value for this property is 0L.

      Returns:
        VBE byte count for this index table segment.
      Throws:
        `PropertyNotPresentException` - The optional VBE byte count property is not present.
      See Also:
        `VBEBYTECOUNT_DEFAULT`

    - #### setVBEByteCount

          void setVBEByteCount(@UInt64
                               Long vbeByteCount)
                        throws IllegalArgumentException

      Sets the VBE byte count value that gives the byte offset to the end of the final essence unit in a VBE (Variable Bytes per Element) essence stream. This value can be used to calculate the size of the final essence unit. Set this optional property to `null` to omit it.

      The default value for this property is 0L.

      Parameters:
        `vbeByteCount` - VBE byte count for this index table segment.
      Throws:
        `IllegalArgumentException` - The VBE byte count property cannot be negative.
      See Also:
        `VBEBYTECOUNT_DEFAULT`

    - #### clone

          IndexTableSegment clone()

      Creates a cloned copy of this index table segment.

      Returns:
        Cloned copy of this index table segment.

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