Package org.apache.commons.compress.archivers

# Class ArchiveOutputStream<E extends ArchiveEntry>

java.lang.Object
java.io.OutputStream
java.io.FilterOutputStream
org.apache.commons.compress.archivers.ArchiveOutputStream<E>

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

All Implemented Interfaces:
  `Closeable`, `Flushable`, `AutoCloseable`

Direct Known Subclasses:
  `ArArchiveOutputStream`, `CpioArchiveOutputStream`, `TarArchiveOutputStream`, `ZipArchiveOutputStream`

public abstract class ArchiveOutputStream<E extends ArchiveEntry> extends FilterOutputStream
Archive output stream implementations are expected to override the `FilterOutputStream.write(byte[], int, int)` method to improve performance. They should also override `close()` to ensure that any necessary trailers are added.

The normal sequence of calls when working with ArchiveOutputStreams is:

- Create ArchiveOutputStream object,
- optionally write SFX header (Zip only),
- repeat as needed:
  - `putArchiveEntry(ArchiveEntry)` (writes entry header),
  - `FilterOutputStream.write(byte[])` (writes entry data, as often as needed),
  - `closeArchiveEntry()` (closes entry),
- `finish()` (ends the addition of entries),
- optionally write additional data, provided format supports it,
- `close()`.

- ## Field Summary

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

  `out`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ArchiveOutputStream()`
  Constructs a new instance without a backing OutputStream.
  `ArchiveOutputStream(OutputStream out)`
  Constructs a new instance with the given backing OutputStream.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `canWriteEntryData(ArchiveEntry archiveEntry)`
  Whether this stream is able to write the given entry.
  `protected void`
  `checkFinished()`
  Throws an `IOException` if this instance is already finished.
  `protected void`
  `checkOpen()`
  Check to make sure that this stream has not been closed
  `void`
  `close()`
  `abstract void`
  `closeArchiveEntry()`
  Closes the archive entry, writing any trailer information that may be required.
  `protected void`
  `count(int written)`
  Increments the counter of already written bytes.
  `protected void`
  `count(long written)`
  Increments the counter of already written bytes.
  `abstract E`
  `createArchiveEntry(File inputFile, String entryName)`
  Creates an archive entry using the inputFile and entryName provided.
  `E`
  `createArchiveEntry(Path inputPath, String entryName, LinkOption... options)`
  Creates an archive entry using the inputPath and entryName provided.
  `void`
  `finish()`
  Finishes the addition of entries to this stream, without closing it.
  `long`
  `getBytesWritten()`
  Gets the current number of bytes written to this stream.
  `int`
  `getCount()`
  Deprecated.
  this method may yield wrong results for large archives, use #getBytesWritten instead
  `protected boolean`
  `isClosed()`
  Tests whether this instance was successfully closed.
  `protected boolean`
  `isFinished()`
  Tests whether this instance was successfully finished.
  `abstract void`
  `putArchiveEntry(E entry)`
  Writes the headers for an archive entry to the output stream.
  `void`
  `write(int b)`
  Writes a byte to the current archive entry.

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

  `flush, write, write`

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

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

- ## Constructor Details

  - ### ArchiveOutputStream

    public ArchiveOutputStream()
    Constructs a new instance without a backing OutputStream.

    You must initialize `this.out` after construction.

  - ### ArchiveOutputStream

    public ArchiveOutputStream(OutputStream out)
    Constructs a new instance with the given backing OutputStream.
    Parameters:
      `out` - the underlying output stream to be assigned to the field `this.out` for later use, or `null` if this instance is to be created without an underlying stream.
    Since:
      1.27.0.

- ## Method Details

  - ### canWriteEntryData

    public boolean canWriteEntryData(ArchiveEntry archiveEntry)
    Whether this stream is able to write 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

  - ### checkFinished

    protected void checkFinished() throws IOException
    Throws an `IOException` if this instance is already finished.
    Throws:
      `IOException` - if this instance is already finished.
    Since:
      1.27.0

  - ### close

    public void close() throws IOException
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Overrides:
      `close` in class `FilterOutputStream`
    Throws:
      `IOException`

  - ### closeArchiveEntry

    public abstract void closeArchiveEntry() throws IOException
    Closes the archive entry, writing any trailer information that may be required.
    Throws:
      `IOException` - if an I/O error occurs

  - ### count

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

  - ### count

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

  - ### createArchiveEntry

    public abstract E createArchiveEntry(File inputFile, String entryName) throws IOException
    Creates an archive entry using the inputFile and entryName provided.
    Parameters:
      `inputFile` - the file to create the entry from
      `entryName` - name to use for the entry
    Returns:
      the ArchiveEntry set up with details from the file
    Throws:
      `IOException` - if an I/O error occurs

  - ### createArchiveEntry

    public E createArchiveEntry(Path inputPath, String entryName, LinkOption... options) throws IOException
    Creates an archive entry using the inputPath and entryName provided.

    The default implementation calls simply delegates as:

         return createArchiveEntry(inputFile.toFile(), entryName);

    Subclasses should override this method.

    Parameters:
      `inputPath` - the file to create the entry from
      `entryName` - name to use for the entry
      `options` - options indicating how symbolic links are handled.
    Returns:
      the ArchiveEntry set up with details from the file
    Throws:
      `IOException` - if an I/O error occurs
    Since:
      1.21

  - ### finish

    public void finish() throws IOException
    Finishes the addition of entries to this stream, without closing it. Additional data can be written, if the format supports it.
    Throws:
      `IOException` - Maybe thrown by subclasses if the user forgets to close the entry.

  - ### getBytesWritten

    public long getBytesWritten()
    Gets the current number of bytes written to this stream.
    Returns:
      the number of written bytes
    Since:
      1.1

  - ### getCount

    @Deprecated public int getCount()
    Deprecated.
    this method may yield wrong results for large archives, use #getBytesWritten instead
    Gets the current number of bytes written to this stream.
    Returns:
      the number of written bytes

  - ### isClosed

    protected boolean isClosed()
    Tests whether this instance was successfully closed.
    Returns:
      whether this instance was successfully closed.
    Since:
      1.27.0

  - ### isFinished

    protected boolean isFinished()
    Tests whether this instance was successfully finished.
    Returns:
      whether this instance was successfully finished.
    Since:
      1.27.0

  - ### putArchiveEntry

    public abstract void putArchiveEntry(E entry) throws IOException
    Writes the headers for an archive entry to the output stream. The caller must then write the content to the stream and call `closeArchiveEntry()` to complete the process.
    Parameters:
      `entry` - describes the entry
    Throws:
      `IOException` - if an I/O error occurs

  - ### write

    public void write(int b) throws IOException
    Writes a byte to the current archive entry.

    This method simply calls `write( byte[], 0, 1 )`.

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

    Overrides:
      `write` in class `FilterOutputStream`
    Parameters:
      `b` - The byte to be written.
    Throws:
      `IOException` - on error

  - ### checkOpen

    protected void checkOpen() throws IOException
    Check to make sure that this stream has not been closed
    Throws:
      `IOException` - if the stream is already closed
    Since:
      1.27.0