ArchiveOutputStream
Date: 2017-02-08

org.apache.commons.compress.archivers

## Class ArchiveOutputStream

- java.lang.Object
- - java.io.OutputStream
  - - org.apache.commons.compress.archivers.ArchiveOutputStream

- All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable
  Direct Known Subclasses:
    ArArchiveOutputStream, CpioArchiveOutputStream, TarArchiveOutputStream, ZipArchiveOutputStream

      public abstract class ArchiveOutputStream
      extends java.io.OutputStream

  Archive output stream implementations are expected to override the `OutputStream.write(byte[], int, int)` method to improve performance. They should also override `OutputStream.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),
    - `OutputStream.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,
  - `OutputStream.close()`.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ArchiveOutputStream()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `canWriteEntryData(ArchiveEntry archiveEntry)` Whether this stream is able to write the given entry.
    `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 ArchiveEntry` | `createArchiveEntry(java.io.File inputFile, java.lang.String entryName)` Create an archive entry using the inputFile and entryName provided.
    `abstract void` | `finish()` Finishes the addition of entries to this stream, without closing it.
    `long` | `getBytesWritten()` Returns the current number of bytes written to this stream.
    `int` | `getCount()` Deprecated. this method may yield wrong results for large archives, use #getBytesWritten instead
    `abstract void` | `putArchiveEntry(ArchiveEntry 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.OutputStream

      `close, flush, write, write`

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

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

- - ### Constructor Detail

    - #### ArchiveOutputStream

          public ArchiveOutputStream()

  - ### Method Detail

    - #### putArchiveEntry

          public abstract void putArchiveEntry(ArchiveEntry entry)
                                        throws java.io.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:
        `java.io.IOException` - if an I/O error occurs

    - #### closeArchiveEntry

          public abstract void closeArchiveEntry()
                                          throws java.io.IOException

      Closes the archive entry, writing any trailer information that may be required.
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### finish

          public abstract void finish()
                               throws java.io.IOException

      Finishes the addition of entries to this stream, without closing it. Additional data can be written, if the format supports it.
      Throws:
        `java.io.IOException` - if the user forgets to close the entry.

    - #### createArchiveEntry

          public abstract ArchiveEntry createArchiveEntry(java.io.File inputFile,
                                        java.lang.String entryName)
                                                   throws java.io.IOException

      Create 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:
        `java.io.IOException` - if an I/O error occurs

    - #### write

          public void write(int b)
                     throws java.io.IOException

      Writes a byte to the current archive entry.

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

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

      Specified by:
        `write` in class `java.io.OutputStream`
      Parameters:
        `b` - The byte to be written.
      Throws:
        `java.io.IOException` - on error

    - #### 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

    - #### getCount

          @Deprecated
          public int getCount()

      Deprecated. this method may yield wrong results for large archives, use #getBytesWritten instead
      Returns the current number of bytes written to this stream.
      Returns:
        the number of written bytes

    - #### getBytesWritten

          public long getBytesWritten()

      Returns the current number of bytes written to this stream.
      Returns:
        the number of written bytes
      Since:
        1.1

    - #### 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