Package org.apache.commons.compress.archivers

# Class ArchiveInputStream<E extends ArchiveEntry>

java.lang.Object
java.io.InputStream
java.io.FilterInputStream
org.apache.commons.compress.archivers.ArchiveInputStream<E>

Type Parameters:
  `E` - The type of `ArchiveEntry` produced.

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

Direct Known Subclasses:
  `ArArchiveInputStream`, `ArjArchiveInputStream`, `CpioArchiveInputStream`, `DumpArchiveInputStream`, `TarArchiveInputStream`, `ZipArchiveInputStream`

public abstract class ArchiveInputStream<E extends ArchiveEntry> extends FilterInputStream
Archive input streams MUST override the `FilterInputStream.read(byte[], int, int)` - or `read()` - method so that reading from the stream generates EOF for the end of data in each entry as well as at the end of the file proper.

The `getNextEntry()` method is used to reset the input stream ready for reading the data from the next entry.

The input stream classes must also implement a method with the signature:

     public static boolean matches(byte[] signature, int length)

which is used by the `ArchiveStreamFactory` to autodetect the archive type from the first few bytes of a stream.

- ## Field Summary

  ### Fields inherited from class java.io.FilterInputStream

  `in`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `ArchiveInputStream()`
  Constructs a new instance.
  `protected`
  `ArchiveInputStream(InputStream inputStream, String charsetName)`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `canReadEntryData(ArchiveEntry archiveEntry)`
  Tests whether this stream is able to read the given entry.
  `protected void`
  `count(int read)`
  Increments the counter of already read bytes.
  `protected void`
  `count(long read)`
  Increments the counter of already read bytes.
  `void`
  `forEach(IOConsumer<? super E> action)`
  Performs the given action for each element of the stream until all elements have been processed or the action throws an exception.
  `long`
  `getBytesRead()`
  Gets the current number of bytes read from this stream.
  `Charset`
  `getCharset()`
  Gets the Charset.
  `int`
  `getCount()`
  Deprecated.
  this method may yield wrong results for large archives, use `getBytesRead()` instead.
  `abstract E`
  `getNextEntry()`
  Gets the next Archive Entry in this Stream.
  `IOIterator<E>`
  `iterator()`
  Returns an iterator over the SubField elements in this extra field in proper sequence.
  `void`
  `mark(int readlimit)`
  Does nothing.
  `boolean`
  `markSupported()`
  Always returns false.
  `protected void`
  `pushedBackBytes(long pushedBack)`
  Decrements the counter of already read bytes.
  `int`
  `read()`
  Reads a byte of data.
  `void`
  `reset()`
  Does nothing.

  ### Methods inherited from class java.io.FilterInputStream

  `available, close, read, read, skip`

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

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

- ## Constructor Details

  - ### ArchiveInputStream

    public ArchiveInputStream()
    Constructs a new instance.

  - ### ArchiveInputStream

    protected ArchiveInputStream(InputStream inputStream, String charsetName)
    Constructs a new instance.
    Parameters:
      `inputStream` - the underlying input stream, or `null` if this instance is to be created without an underlying stream.
      `charsetName` - charset name.
    Since:
      1.26.0

- ## Method Details

  - ### canReadEntryData

    public boolean canReadEntryData(ArchiveEntry archiveEntry)
    Tests whether this stream is able to read the given entry.

    Some archive formats support variants or details that are not supported (yet).

    Parameters:
      `archiveEntry` - the entry to test.
    Returns:
      This implementation always returns true.
    Since:
      1.1

  - ### count

    protected void count(int read)
    Increments the counter of already read bytes. Doesn't increment if the EOF has been hit (read == -1).
    Parameters:
      `read` - the number of bytes read.

  - ### count

    protected void count(long read)
    Increments the counter of already read bytes. Doesn't increment if the EOF has been hit (read == -1).
    Parameters:
      `read` - the number of bytes read.
    Since:
      1.1

  - ### forEach

    public void forEach(IOConsumer<? super E> action) throws IOException
    Performs the given action for each element of the stream until all elements have been processed or the action throws an exception. Actions are performed in the order of iteration. Exceptions thrown by the action are relayed to the caller.

    The behavior of this method is unspecified if the action performs side-effects that modify the underlying source of elements, unless an overriding class has specified a concurrent modification policy.

    Parameters:
      `action` - The action to be performed for each element.
    Throws:
      `IOException` - if an I/O error occurs.
      `NullPointerException` - if the specified action is null.
    Since:
      1.27.0

  - ### getBytesRead

    public long getBytesRead()
    Gets the current number of bytes read from this stream.
    Returns:
      the number of read bytes.
    Since:
      1.1

  - ### getCharset

    public Charset getCharset()
    Gets the Charset.
    Returns:
      the Charset.

  - ### getCount

    @Deprecated public int getCount()
    Deprecated.
    this method may yield wrong results for large archives, use `getBytesRead()` instead.
    Gets the current number of bytes read from this stream.
    Returns:
      the number of read.

  - ### getNextEntry

    public abstract E getNextEntry() throws IOException
    Gets the next Archive Entry in this Stream.
    Returns:
      the next entry, or `null` if there are no more entries.
    Throws:
      `IOException` - if the next entry could not be read.

  - ### iterator

    public IOIterator<E> iterator()
    Returns an iterator over the SubField elements in this extra field in proper sequence.
    Returns:
      an iterator over the SubField elements in this extra field in proper sequence.
    Since:
      1.27.0

  - ### mark

    public void mark(int readlimit)
    Does nothing.

    TODO [COMPRESS-670] Support mark() and reset() in ArchiveInputStream.

    Overrides:
      `mark` in class `FilterInputStream`
    Parameters:
      `readlimit` - ignored.

  - ### markSupported

    public boolean markSupported()
    Always returns false.

    TODO [COMPRESS-670] Support mark() and reset() in ArchiveInputStream.

    Overrides:
      `markSupported` in class `FilterInputStream`
    Returns:
      Always returns false.

  - ### pushedBackBytes

    protected void pushedBackBytes(long pushedBack)
    Decrements the counter of already read bytes.
    Parameters:
      `pushedBack` - the number of bytes pushed back.
    Since:
      1.1

  - ### read

    public int read() throws IOException
    Reads a byte of data. This method will block until enough input is available.

    Simply calls the `FilterInputStream.read(byte[], int, int)` method.

    MUST be overridden if the `FilterInputStream.read(byte[], int, int)` method is not overridden; may be overridden otherwise.

    Overrides:
      `read` in class `FilterInputStream`
    Returns:
      the byte read, or -1 if end of input is reached.
    Throws:
      `IOException` - if an I/O error has occurred.

  - ### reset

    public void reset() throws IOException
    Does nothing.

    TODO [COMPRESS-670] Support mark() and reset() in ArchiveInputStream.

    Overrides:
      `reset` in class `FilterInputStream`
    Throws:
      `IOException` - not thrown here but may be thrown from a subclass.