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
`static class` `ZipOutputStream.UnicodeExtraFieldPolicy` enum that represents the possible policies for creating Unicode extra fields.

### Field Summary

Fields
`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
`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