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

Class ExtraField

  • All Implemented Interfaces:
    java.lang.Iterable<ExtraField.SubField>
    public final class ExtraField
extends java.lang.Object
implements java.lang.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 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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      ExtraField addSubField​(java.lang.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​(java.lang.Object obj)  
      ExtraField.SubField findFirstSubField​(java.lang.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.
      java.util.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 Detail

      • ExtraField

        public ExtraField()
        Constructs a new instance.

    • Method Detail

      • addSubField

        public ExtraField addSubField​(java.lang.String id,
                              byte[] payload)
                       throws java.io.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:
        java.lang.NullPointerException - if id is null.
        java.lang.NullPointerException - if payload is null.
        java.lang.IllegalArgumentException - if the subfield is not 2 characters or the payload is null
        java.io.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​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • findFirstSubField

        public ExtraField.SubField findFirstSubField​(java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is out of range (index &lt; 0 || index &gt;= size()).

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • isEmpty

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

      • iterator

        public java.util.Iterator<ExtraField.SubField> iterator()
        Returns an unmodifiable iterator over the elements in the SubField list in proper sequence.
        Specified by:
        iterator in interface java.lang.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.