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:

    • DEFAULT_COMPRESSION

      public static final int DEFAULT_COMPRESSION
      Default compression level for deflated entries.
      Since:
      Ant 1.7
      See Also:

    • STORED

      public static final int STORED
      Compression method for stored entries.
      Since:
      1.1
      See Also:

    • 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:

    • 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