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:

  • 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.