ZipOutputStream (Apache Ant API)
Description: declaration: package: org.apache.tools.zip, class: ZipOutputStream

Package org.apache.tools.zip

# Class ZipOutputStream

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

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

public class ZipOutputStream extends 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.

As of Apache Ant 1.9.0 it transparently supports Zip64 extensions and thus individual entries and archives larger than 4 GB or with more than 65536 entries in most cases but explicit control is provided via `setUseZip64(org.apache.tools.zip.Zip64Mode)`. If the stream can not user RandomAccessFile and you try to write a ZipEntry of unknown size then Zip64 extensions will be disabled by default.

- ## Nested Class Summary

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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected byte[]`
  `buf`
  This buffer serves as a Deflater.
  `protected static final byte[]`
  `CFH_SIG`
  central file header signature
  `protected static final byte[]`
  `DD_SIG`
  data descriptor signature
  `protected final Deflater`
  `def`
  This Deflater object is used for output.
  `static final int`
  `DEFAULT_COMPRESSION`
  Default compression level for deflated entries.
  `static final int`
  `DEFLATED`
  Compression method for deflated entries.
  `static final int`
  `EFS_FLAG`
  Deprecated.
  use `GeneralPurposeBit.UFT8_NAMES_FLAG` instead
  `protected static final byte[]`
  `EOCD_SIG`
  end of central dir signature
  `protected static final byte[]`
  `LFH_SIG`
  local file header signature
  `static final int`
  `STORED`
  Compression method for stored entries.

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

  `out`

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected static long`
  `adjustToLong(int i)`
  Deprecated.
  use ZipUtil#adjustToLong
  `boolean`
  `canWriteEntryData(ZipEntry ae)`
  Whether this stream is able to write the given entry.
  `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 final void`
  `deflate()`
  Writes next block of compressed data to the output stream.
  `void`
  `finish()`
  Finish writing the archive.
  `void`
  `flush()`
  Flushes this output stream and forces any buffered output bytes to be written out to the stream.
  `protected byte[]`
  `getBytes(String name)`
  Retrieve the bytes for the given String in the encoding set for this Stream.
  `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 archiveEntry)`
  Put the specified entry into the archive.
  `void`
  `setComment(String comment)`
  Set the file comment.
  `void`
  `setCreateUnicodeExtraFields(ZipOutputStream.UnicodeExtraFieldPolicy b)`
  Whether to create Unicode Extra Fields.
  `void`
  `setEncoding(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.
  `void`
  `setUseZip64(Zip64Mode mode)`
  Whether Zip64 extensions will be used.
  `protected static byte[]`
  `toDosTime(long t)`
  Deprecated.
  use ZipUtil#toDosTime
  `protected static ZipLong`
  `toDosTime(Date time)`
  Deprecated.
  use ZipUtil#toDosTime
  `void`
  `write(byte[] b, int offset, int length)`
  Writes bytes to ZIP entry.
  `void`
  `write(int b)`
  Writes a 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 final void`
  `writeOut(byte[] data)`
  Write bytes to output or random access file.
  `protected final void`
  `writeOut(byte[] data, int offset, int length)`
  Write bytes to output or random access file.
  `protected void`
  `writeZip64CentralDirectory()`
  Writes the "ZIP64 End of central dir record" and "ZIP64 End of central dir locator".

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

  `write`

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

  `nullOutputStream`

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

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

- ## Field Details

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

  - ### EFS_FLAG

    @Deprecated public static final int EFS_FLAG
    Deprecated.
    use `GeneralPurposeBit.UFT8_NAMES_FLAG` instead
    General purpose flag, which indicates that filenames are written in utf-8.
    See Also:
      - Constant Field Values

  - ### def

    protected final Deflater def
    This Deflater object is used for output.

  - ### buf

    protected byte[] buf
    This buffer serves 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 Details

  - ### ZipOutputStream

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

  - ### ZipOutputStream

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

- ## Method Details

  - ### 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(String encoding)
    The encoding to use for filenames and the file comment.

    For a list of possible values see https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html. Defaults to the platform's default character encoding.

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

  - ### getEncoding

    public 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.

    Parameters:
      `b` - boolean

  - ### setCreateUnicodeExtraFields

    public void setCreateUnicodeExtraFields(ZipOutputStream.UnicodeExtraFieldPolicy b)
    Whether to create Unicode Extra Fields.

    Defaults to NEVER.

    Parameters:
      `b` - boolean

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

    Parameters:
      `b` - boolean

  - ### setUseZip64

    public void setUseZip64(Zip64Mode mode)
    Whether Zip64 extensions will be used.

    When setting the mode to `Never`, `putNextEntry(org.apache.tools.zip.ZipEntry)`, `closeEntry()`, `finish()` or `close()` may throw a `Zip64RequiredException` if the entry's size or the total size of the archive exceeds 4GB or there are more than 65536 entries inside the archive. Any archive created in this mode will be readable by implementations that don't support Zip64.

    When setting the mode to `Always`, Zip64 extensions will be used for all entries. Any archive created in this mode may be unreadable by implementations that don't support Zip64 even if all its contents would be.

    When setting the mode to `AsNeeded`, Zip64 extensions will transparently be used for those entries that require them. This mode can only be used if the uncompressed size of the `ZipEntry` is known when calling `putNextEntry(org.apache.tools.zip.ZipEntry)` or the archive is written to a seekable output (i.e. you have used the `File-arg constructor`) - this mode is not valid when the output stream is not seekable and the uncompressed size is unknown when `putNextEntry(org.apache.tools.zip.ZipEntry)` is called.

    If no entry inside the resulting archive requires Zip64 extensions then `Never` will create the smallest archive. `AsNeeded` will create a slightly bigger archive if the uncompressed size of any entry has initially been unknown and create an archive identical to `Never` otherwise. `Always` will create an archive that is at least 24 bytes per entry bigger than the one `Never` would create.

    Defaults to `AsNeeded` unless `putNextEntry(org.apache.tools.zip.ZipEntry)` is called with an entry of unknown size and data is written to a non-seekable stream - in this case the default is `Never`.

    Parameters:
      `mode` - Zip64Mode
    Since:
      1.3

  - ### finish

    public void finish() throws IOException
    Finish writing the archive.
    Throws:
      `Zip64RequiredException` - if the archive's size exceeds 4 GByte or there are more than 65535 entries inside the archive and `setUseZip64(org.apache.tools.zip.Zip64Mode)` is `Zip64Mode.Never`.
      `IOException`

  - ### closeEntry

    public void closeEntry() throws IOException
    Writes all necessary data for this entry.
    Throws:
      `IOException` - on error
      `Zip64RequiredException` - if the entry's uncompressed or compressed size exceeds 4 GByte and `setUseZip64(org.apache.tools.zip.Zip64Mode)` is `Zip64Mode.Never`.
    Since:
      1.1

  - ### putNextEntry

    public void putNextEntry(ZipEntry archiveEntry) throws IOException
    Put the specified entry into the archive.
    Throws:
      `Zip64RequiredException` - if the entry's uncompressed or compressed size is known to exceed 4 GByte and `setUseZip64(org.apache.tools.zip.Zip64Mode)` is `Zip64Mode.Never`.
      `IOException`

  - ### setComment

    public void setComment(String comment)
    Set the file comment.
    Parameters:
      `comment` - the comment

  - ### setLevel

    public void setLevel(int level)
    Sets the compression level for subsequent entries.

    Default is Deflater.DEFAULT_COMPRESSION.

    Parameters:
      `level` - the compression level.
    Throws:
      `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

  - ### canWriteEntryData

    public boolean canWriteEntryData(ZipEntry ae)
    Whether this stream is able to write the given entry.

    May return false if it is set up to use encryption or a compression method that hasn't been implemented yet.

    Parameters:
      `ae` - ZipEntry
    Returns:
      boolean

  - ### write

    public void write(int b) throws IOException
    Writes a byte to ZIP entry.
    Overrides:
      `write` in class `FilterOutputStream`
    Parameters:
      `b` - the byte to write
    Throws:
      `IOException` - on error
    Since:
      Ant 1.10.10

  - ### write

    public void write(byte[] b, int offset, int length) throws IOException
    Writes bytes to ZIP entry.
    Overrides:
      `write` in class `FilterOutputStream`
    Parameters:
      `b` - the byte array to write
      `offset` - the start position to write from
      `length` - the number of bytes to write
    Throws:
      `IOException` - on error

  - ### close

    public void close() throws IOException
    Closes this output stream and releases any system resources associated with the stream.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Overrides:
      `close` in class `FilterOutputStream`
    Throws:
      `IOException` - if an I/O error occurs.
      `Zip64RequiredException` - if the archive's size exceeds 4 GByte or there are more than 65535 entries inside the archive and `setUseZip64(org.apache.tools.zip.Zip64Mode)` is `Zip64Mode.Never`.

  - ### flush

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

  - ### deflate

    protected final void deflate() throws IOException
    Writes next block of compressed data to the output stream.
    Throws:
      `IOException` - on error
    Since:
      1.14

  - ### writeLocalFileHeader

    protected void writeLocalFileHeader(ZipEntry ze) throws IOException
    Writes the local file header entry
    Parameters:
      `ze` - the entry to write
    Throws:
      `IOException` - on error
    Since:
      1.1

  - ### writeDataDescriptor

    protected void writeDataDescriptor(ZipEntry ze) throws IOException
    Writes the data descriptor entry.
    Parameters:
      `ze` - the entry to write
    Throws:
      `IOException` - on error
    Since:
      1.1

  - ### writeCentralFileHeader

    protected void writeCentralFileHeader(ZipEntry ze) throws IOException
    Writes the central file header entry.
    Parameters:
      `ze` - the entry to write
    Throws:
      `IOException` - on error
      `Zip64RequiredException` - if the archive's size exceeds 4 GByte and `#setUseZip64` is `Zip64Mode.Never`.

  - ### writeCentralDirectoryEnd

    protected void writeCentralDirectoryEnd() throws IOException
    Writes the "End of central dir record".
    Throws:
      `IOException` - on error
      `Zip64RequiredException` - if the archive's size exceeds 4 GByte or there are more than 65535 entries inside the archive and `#setUseZip64` is `Zip64Mode.Never`.

  - ### toDosTime

    @Deprecated protected static ZipLong toDosTime(Date time)
    Deprecated.
    use ZipUtil#toDosTime
    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

    @Deprecated protected static byte[] toDosTime(long t)
    Deprecated.
    use ZipUtil#toDosTime
    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(String name) throws 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:
      `ZipException` - on error
    Since:
      1.3

  - ### writeZip64CentralDirectory

    protected void writeZip64CentralDirectory() throws IOException
    Writes the "ZIP64 End of central dir record" and "ZIP64 End of central dir locator".
    Throws:
      `IOException` - on error

  - ### writeOut

    protected final void writeOut(byte[] data) throws IOException
    Write bytes to output or random access file.
    Parameters:
      `data` - the byte array to write
    Throws:
      `IOException` - on error
    Since:
      1.14

  - ### writeOut

    protected final void writeOut(byte[] data, int offset, int length) throws 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:
      `IOException` - on error
    Since:
      1.14

  - ### adjustToLong

    @Deprecated protected static long adjustToLong(int i)
    Deprecated.
    use ZipUtil#adjustToLong
    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