org.apache.tools.zip

## Class ZipOutputStream

- java.lang.Object
- - java.io.OutputStream
  - - java.io.FilterOutputStream
    - - org.apache.tools.zip.ZipOutputStream

- All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

      public class ZipOutputStream
      extends java.io.FilterOutputStream

  Reimplementation of `java.util.zip.ZipOutputStream` that does handle the extended functionality of this package, especially internal/external file attributes and extra fields with different layouts for local file data and central directory entries.

  This class will try to use `RandomAccessFile` when you know that the output is going to go to a file.

  If RandomAccessFile cannot be used, this implementation will use a Data Descriptor to store size and CRC information for `DEFLATED` entries, this means, you don't need to calculate them yourself. Unfortunately this is not possible for the `STORED` method, here setting the CRC and uncompressed size information is required before `putNextEntry` can be called.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ZipOutputStream.UnicodeExtraFieldPolicy` enum that represents the possible policies for creating Unicode extra fields.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected byte[]` | `buf` This buffer servers as a Deflater.
    `protected static byte[]` | `CFH_SIG` central file header signature
    `protected static byte[]` | `DD_SIG` data descriptor signature
    `protected java.util.zip.Deflater` | `def` This Deflater object is used for output.
    `static int` | `DEFAULT_COMPRESSION` Default compression level for deflated entries.
    `static int` | `DEFLATED` Compression method for deflated entries.
    `static int` | `EFS_FLAG` Deprecated. use `UFT8_NAMES_FLAG` instead
    `protected static byte[]` | `EOCD_SIG` end of central dir signature
    `protected static byte[]` | `LFH_SIG` local file header signature
    `static int` | `STORED` Compression method for stored entries.
    `static int` | `UFT8_NAMES_FLAG` General purpose flag, which indicates that filenames are written in utf-8.

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

      `out`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ZipOutputStream(java.io.File file)` Creates a new ZIP OutputStream writing to a File.
    `ZipOutputStream(java.io.OutputStream out)` Creates a new ZIP OutputStream filtering the underlying stream.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static long` | `adjustToLong(int i)` Assumes a negative integer really is a positive integer that has wrapped around and re-creates the original value.
    `void` | `close()` Closes this output stream and releases any system resources associated with the stream.
    `void` | `closeEntry()` Writes all necessary data for this entry.
    `protected void` | `deflate()` Writes next block of compressed data to the output stream.
    `void` | `finish()` Finishs writing the contents and closes this as well as the underlying stream.
    `void` | `flush()` Flushes this output stream and forces any buffered output bytes to be written out to the stream.
    `protected byte[]` | `getBytes(java.lang.String name)` Retrieve the bytes for the given String in the encoding set for this Stream.
    `java.lang.String` | `getEncoding()` The encoding to use for filenames and the file comment.
    `boolean` | `isSeekable()` This method indicates whether this archive is writing to a seekable stream (i.e., to a random access file).
    `void` | `putNextEntry(ZipEntry ze)` Begin writing next entry.
    `void` | `setComment(java.lang.String comment)` Set the file comment.
    `void` | `setCreateUnicodeExtraFields(ZipOutputStream.UnicodeExtraFieldPolicy b)` Whether to create Unicode Extra Fields.
    `void` | `setEncoding(java.lang.String encoding)` The encoding to use for filenames and the file comment.
    `void` | `setFallbackToUTF8(boolean b)` Whether to fall back to UTF and the language encoding flag if the file name cannot be encoded using the specified encoding.
    `void` | `setLevel(int level)` Sets the compression level for subsequent entries.
    `void` | `setMethod(int method)` Sets the default compression method for subsequent entries.
    `void` | `setUseLanguageEncodingFlag(boolean b)` Whether to set the language encoding flag if the file name encoding is UTF-8.
    `protected static ZipLong` | `toDosTime(java.util.Date time)` Convert a Date object to a DOS date/time field.
    `protected static byte[]` | `toDosTime(long t)` Convert a Date object to a DOS date/time field.
    `void` | `write(byte[] b, int offset, int length)` Writes bytes to ZIP entry.
    `void` | `write(int b)` Writes a single byte to ZIP entry.
    `protected void` | `writeCentralDirectoryEnd()` Writes the "End of central dir record".
    `protected void` | `writeCentralFileHeader(ZipEntry ze)` Writes the central file header entry.
    `protected void` | `writeDataDescriptor(ZipEntry ze)` Writes the data descriptor entry.
    `protected void` | `writeLocalFileHeader(ZipEntry ze)` Writes the local file header entry
    `protected void` | `writeOut(byte[] data)` Write bytes to output or random access file.
    `protected void` | `writeOut(byte[] data, int offset, int length)` Write bytes to output or random access file.

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

      `write`

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

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

- - ### Field Detail

    - #### DEFLATED

          public static final int DEFLATED

      Compression method for deflated entries.
      Since:
        1.1
      See Also:
        Constant Field Values

    - #### DEFAULT_COMPRESSION

          public static final int DEFAULT_COMPRESSION

      Default compression level for deflated entries.
      Since:
        Ant 1.7
      See Also:
        Constant Field Values

    - #### STORED

          public static final int STORED

      Compression method for stored entries.
      Since:
        1.1
      See Also:
        Constant Field Values

    - #### UFT8_NAMES_FLAG

          public static final int UFT8_NAMES_FLAG

      General purpose flag, which indicates that filenames are written in utf-8.
      See Also:
        Constant Field Values

    - #### EFS_FLAG

          public static final int EFS_FLAG

      Deprecated. use `UFT8_NAMES_FLAG` instead
      General purpose flag, which indicates that filenames are written in utf-8.
      See Also:
        Constant Field Values

    - #### def

          protected java.util.zip.Deflater def

      This Deflater object is used for output.

      This attribute is only protected to provide a level of API backwards compatibility. This class used to extend `DeflaterOutputStream` up to Revision 1.13.

      Since:
        1.14

    - #### buf

          protected byte[] buf

      This buffer servers as a Deflater.

      This attribute is only protected to provide a level of API backwards compatibility. This class used to extend `DeflaterOutputStream` up to Revision 1.13.

      Since:
        1.14

    - #### LFH_SIG

          protected static final byte[] LFH_SIG

      local file header signature
      Since:
        1.1

    - #### DD_SIG

          protected static final byte[] DD_SIG

      data descriptor signature
      Since:
        1.1

    - #### CFH_SIG

          protected static final byte[] CFH_SIG

      central file header signature
      Since:
        1.1

    - #### EOCD_SIG

          protected static final byte[] EOCD_SIG

      end of central dir signature
      Since:
        1.1

  - ### Constructor Detail

    - #### ZipOutputStream

          public ZipOutputStream(java.io.OutputStream out)

      Creates a new ZIP OutputStream filtering the underlying stream.
      Parameters:
        `out` - the outputstream to zip
      Since:
        1.1

    - #### ZipOutputStream

          public ZipOutputStream(java.io.File file)
                          throws java.io.IOException

      Creates a new ZIP OutputStream writing to a File. Will use random access if possible.
      Parameters:
        `file` - the file to zip to
      Throws:
        `java.io.IOException` - on error
      Since:
        1.14

  - ### Method Detail

    - #### isSeekable

          public boolean isSeekable()

      This method indicates whether this archive is writing to a seekable stream (i.e., to a random access file).

      For seekable streams, you don't need to calculate the CRC or uncompressed size for `STORED` entries before invoking `putNextEntry(org.apache.tools.zip.ZipEntry)`.

      Returns:
        true if seekable
      Since:
        1.17

    - #### setEncoding

          public void setEncoding(java.lang.String encoding)

      The encoding to use for filenames and the file comment.

      For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html. Defaults to the platform's default character encoding.

      Parameters:
        `encoding` - the encoding value
      Since:
        1.3

    - #### getEncoding

          public java.lang.String getEncoding()

      The encoding to use for filenames and the file comment.
      Returns:
        null if using the platform's default character encoding.
      Since:
        1.3

    - #### setUseLanguageEncodingFlag

          public void setUseLanguageEncodingFlag(boolean b)

      Whether to set the language encoding flag if the file name encoding is UTF-8.

      Defaults to true.

    - #### setCreateUnicodeExtraFields

          public void setCreateUnicodeExtraFields(ZipOutputStream.UnicodeExtraFieldPolicy b)

      Whether to create Unicode Extra Fields.

      Defaults to NEVER.

    - #### setFallbackToUTF8

          public void setFallbackToUTF8(boolean b)

      Whether to fall back to UTF and the language encoding flag if the file name cannot be encoded using the specified encoding.

      Defaults to false.

    - #### finish

          public void finish()
                      throws java.io.IOException

      Finishs writing the contents and closes this as well as the underlying stream.
      Throws:
        `java.io.IOException` - on error
      Since:
        1.1

    - #### closeEntry

          public void closeEntry()
                          throws java.io.IOException

      Writes all necessary data for this entry.
      Throws:
        `java.io.IOException` - on error
      Since:
        1.1

    - #### putNextEntry

          public void putNextEntry(ZipEntry ze)
                            throws java.io.IOException

      Begin writing next entry.
      Parameters:
        `ze` - the entry to write
      Throws:
        `java.io.IOException` - on error
      Since:
        1.1

    - #### setComment

          public void setComment(java.lang.String comment)

      Set the file comment.
      Parameters:
        `comment` - the comment
      Since:
        1.1

    - #### setLevel

          public void setLevel(int level)

      Sets the compression level for subsequent entries.

      Default is Deflater.DEFAULT_COMPRESSION.

      Parameters:
        `level` - the compression level.
      Throws:
        `java.lang.IllegalArgumentException` - if an invalid compression level is specified.
      Since:
        1.1

    - #### setMethod

          public void setMethod(int method)

      Sets the default compression method for subsequent entries.

      Default is DEFLATED.

      Parameters:
        `method` - an `int` from java.util.zip.ZipEntry
      Since:
        1.1

    - #### write

          public void write(byte[] b,
                   int offset,
                   int length)
                     throws java.io.IOException

      Writes bytes to ZIP entry.
      Overrides:
        `write` in class `java.io.FilterOutputStream`
      Parameters:
        `b` - the byte array to write
        `offset` - the start position to write from
        `length` - the number of bytes to write
      Throws:
        `java.io.IOException` - on error

    - #### write

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

      Writes a single byte to ZIP entry.

      Delegates to the three arg method.

      Overrides:
        `write` in class `java.io.FilterOutputStream`
      Parameters:
        `b` - the byte to write
      Throws:
        `java.io.IOException` - on error
      Since:
        1.14

    - #### close

          public void close()
                     throws java.io.IOException

      Closes this output stream and releases any system resources associated with the stream.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `java.io.FilterOutputStream`
      Throws:
        `java.io.IOException` - if an I/O error occurs.
      Since:
        1.14

    - #### flush

          public void flush()
                     throws java.io.IOException

      Flushes this output stream and forces any buffered output bytes to be written out to the stream.
      Specified by:
        `flush` in interface `java.io.Flushable`
      Overrides:
        `flush` in class `java.io.FilterOutputStream`
      Throws:
        `java.io.IOException` - if an I/O error occurs.
      Since:
        1.14

    - #### deflate

          protected final void deflate()
                                throws java.io.IOException

      Writes next block of compressed data to the output stream.
      Throws:
        `java.io.IOException` - on error
      Since:
        1.14

    - #### writeLocalFileHeader

          protected void writeLocalFileHeader(ZipEntry ze)
                                       throws java.io.IOException

      Writes the local file header entry
      Parameters:
        `ze` - the entry to write
      Throws:
        `java.io.IOException` - on error
      Since:
        1.1

    - #### writeDataDescriptor

          protected void writeDataDescriptor(ZipEntry ze)
                                      throws java.io.IOException

      Writes the data descriptor entry.
      Parameters:
        `ze` - the entry to write
      Throws:
        `java.io.IOException` - on error
      Since:
        1.1

    - #### writeCentralFileHeader

          protected void writeCentralFileHeader(ZipEntry ze)
                                         throws java.io.IOException

      Writes the central file header entry.
      Parameters:
        `ze` - the entry to write
      Throws:
        `java.io.IOException` - on error
      Since:
        1.1

    - #### writeCentralDirectoryEnd

          protected void writeCentralDirectoryEnd()
                                           throws java.io.IOException

      Writes the "End of central dir record".
      Throws:
        `java.io.IOException` - on error
      Since:
        1.1

    - #### toDosTime

          protected static ZipLong toDosTime(java.util.Date time)

      Convert a Date object to a DOS date/time field.
      Parameters:
        `time` - the `Date` to convert
      Returns:
        the date as a `ZipLong`
      Since:
        1.1

    - #### toDosTime

          protected static byte[] toDosTime(long t)

      Convert a Date object to a DOS date/time field.

      Stolen from InfoZip's `fileio.c`

      Parameters:
        `t` - number of milliseconds since the epoch
      Returns:
        the date as a byte array
      Since:
        1.26

    - #### getBytes

          protected byte[] getBytes(java.lang.String name)
                             throws java.util.zip.ZipException

      Retrieve the bytes for the given String in the encoding set for this Stream.
      Parameters:
        `name` - the string to get bytes from
      Returns:
        the bytes as a byte array
      Throws:
        `java.util.zip.ZipException` - on error
      Since:
        1.3

    - #### writeOut

          protected final void writeOut(byte[] data)
                                 throws java.io.IOException

      Write bytes to output or random access file.
      Parameters:
        `data` - the byte array to write
      Throws:
        `java.io.IOException` - on error
      Since:
        1.14

    - #### writeOut

          protected final void writeOut(byte[] data,
                      int offset,
                      int length)
                                 throws java.io.IOException

      Write bytes to output or random access file.
      Parameters:
        `data` - the byte array to write
        `offset` - the start position to write from
        `length` - the number of bytes to write
      Throws:
        `java.io.IOException` - on error
      Since:
        1.14

    - #### adjustToLong

          protected static long adjustToLong(int i)

      Assumes a negative integer really is a positive integer that has wrapped around and re-creates the original value.
      Parameters:
        `i` - the value to treat as unsigned int.
      Returns:
        the unsigned int as a long.
      Since:
        1.34