Package org.apache.commons.compress.compressors.gzip

# Class ExtraField

java.lang.Object
org.apache.commons.compress.compressors.gzip.ExtraField

All Implemented Interfaces:
  `Iterable<ExtraField.SubField>`

public final class ExtraField extends Object implements Iterable<ExtraField.SubField>
If the `FLG.FEXTRA` bit is set, an "extra field" is present in the header, with total length XLEN bytes.

     +---+---+=================================+
     | XLEN  |...XLEN bytes of "extra field"...| (more...)
     +---+---+=================================+

This class represents the extra field payload (excluding the XLEN 2 bytes). The ExtraField payload consists of a series of subfields, each of the form:

     +---+---+---+---+==================================+
     |SI1|SI2|  LEN  |... LEN bytes of subfield data ...|
     +---+---+---+---+==================================+

This class does not expose the internal subfields list to prevent adding subfields without total extra length validation. The class is iterable, but this iterator is immutable.

Since:
  1.28.0
See Also:
  - RFC 1952 GZIP File Format Specification

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `ExtraField.SubField`
  If the `FLG.FEXTRA` bit is set, an "extra field" is present in the header, with total length XLEN bytes.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ExtraField()`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ExtraField`
  `addSubField(String id, byte[] payload)`
  Append a subfield by a 2-chars ISO-8859-1 string.
  `void`
  `clear()`
  Removes all subfields from this instance.
  `boolean`
  `equals(Object obj)`
  `ExtraField.SubField`
  `findFirstSubField(String id)`
  Finds the first subfield that matched the id if found, null otherwise.
  `int`
  `getEncodedSize()`
  Gets the size in bytes of the encoded extra field.
  `ExtraField.SubField`
  `getSubField(int index)`
  Gets the subfield at the given index.
  `int`
  `hashCode()`
  `boolean`
  `isEmpty()`
  Tests is this extra field has no subfields.
  `Iterator<ExtraField.SubField>`
  `iterator()`
  Returns an unmodifiable iterator over the elements in the SubField list in proper sequence.
  `int`
  `size()`
  Gets the count of subfields currently in in this extra field.

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

  `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

- ## Constructor Details

  - ### ExtraField

    public ExtraField()
    Constructs a new instance.

- ## Method Details

  - ### addSubField

    public ExtraField addSubField(String id, byte[] payload) throws IOException
    Append a subfield by a 2-chars ISO-8859-1 string. The char at index 0 and 1 are respectively si1 and si2 (subfield id 1 and 2).
    Parameters:
      `id` - The subfield ID.
      `payload` - The subfield payload.
    Returns:
      this instance.
    Throws:
      `NullPointerException` - if `id` is `null`.
      `NullPointerException` - if `payload` is `null`.
      `IllegalArgumentException` - if the subfield is not 2 characters or the payload is null
      `IOException` - if appending this subfield would exceed the max size 65535 of the extra header.

  - ### clear

    public void clear()
    Removes all subfields from this instance.

  - ### equals

    public boolean equals(Object obj)
    Overrides:
      `equals` in class `Object`

  - ### findFirstSubField

    public ExtraField.SubField findFirstSubField(String id)
    Finds the first subfield that matched the id if found, null otherwise.
    Parameters:
      `id` - The ID to find.
    Returns:
      The first SubField that matched or null.

  - ### getEncodedSize

    public int getEncodedSize()
    Gets the size in bytes of the encoded extra field. This does not include its own 16 bits size when embeded in the gzip header. For N sub fields, the total is all subfields payloads bytes + 4N.
    Returns:
      the bytes count of this extra payload when encoded.

  - ### getSubField

    public ExtraField.SubField getSubField(int index)
    Gets the subfield at the given index.
    Parameters:
      `index` - index of the element to return.
    Returns:
      the subfield at the specified position in this list.
    Throws:
      `IndexOutOfBoundsException` - if the index is out of range (`index &lt; 0 || index &gt;= size()`).

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### isEmpty

    public boolean isEmpty()
    Tests is this extra field has no subfields.
    Returns:
      true if there are no subfields, false otherwise.

  - ### iterator

    public Iterator<ExtraField.SubField> iterator()
    Returns an unmodifiable iterator over the elements in the SubField list in proper sequence.
    Specified by:
      `iterator` in interface `Iterable<ExtraField.SubField>`
    Returns:
      an unmodifiable naturally ordered iterator over the SubField elements.

  - ### size

    public int size()
    Gets the count of subfields currently in in this extra field.
    Returns:
      the count of subfields contained in this instance.