ZipFile (Apache Ant API)
Date: 2018-09-11

Package org.apache.tools.zip

## Class ZipFile

- java.lang.Object
- - org.apache.tools.zip.ZipFile

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

      public class ZipFile
      extends java.lang.Object
      implements java.io.Closeable

  Replacement for `java.util.ZipFile`.

  This class adds support for file name encodings other than UTF-8 (which is required to work on ZIP files created by native zip tools and is able to skip a preamble like the one found in self extracting archives. Furthermore it returns instances of `org.apache.tools.zip.ZipEntry` instead of `java.util.zip.ZipEntry`.

  It doesn't extend `java.util.zip.ZipFile` as it would have to reimplement all methods anyway. Like `java.util.ZipFile`, it uses RandomAccessFile under the covers and supports compressed and uncompressed entries. As of Apache Ant 1.9.0 it also transparently supports Zip64 extensions and thus individual entries and archives larger than 4 GB or with more than 65536 entries.

  The method signatures mimic the ones of `java.util.zip.ZipFile`, with a couple of exceptions:

  - There is no getName method.
  - entries has been renamed to getEntries.
  - getEntries and getEntry return `org.apache.tools.zip.ZipEntry` instances.
  - close is allowed to throw IOException.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ZipFile​(java.io.File f)` | Opens the given file for reading, assuming the platform's native encoding for file names.
    `ZipFile​(java.io.File f, java.lang.String encoding)` | Opens the given file for reading, assuming the specified encoding for file names and scanning for unicode extra fields.
    `ZipFile​(java.io.File f, java.lang.String encoding, boolean useUnicodeExtraFields)` | Opens the given file for reading, assuming the specified encoding for file names.
    `ZipFile​(java.lang.String name)` | Opens the given file for reading, assuming the platform's native encoding for file names.
    `ZipFile​(java.lang.String name, java.lang.String encoding)` | Opens the given file for reading, assuming the specified encoding for file names, scanning unicode extra fields.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `canReadEntryData​(ZipEntry ze)` | Whether this class is able to read the given entry.
    `void` | `close()` | Closes the archive.
    `static void` | `closeQuietly​(ZipFile zipfile)` | close a zipfile quietly; throw no io fault, do nothing on a null parameter
    `protected void` | `finalize()` | Ensures that the close method of this zipfile is called when there are no more references to it.
    `java.lang.String` | `getEncoding()` | The encoding to use for filenames and the file comment.
    `java.util.Enumeration<ZipEntry>` | `getEntries()` | Returns all entries.
    `java.lang.Iterable<ZipEntry>` | `getEntries​(java.lang.String name)` | Returns all named entries in the same order they appear within the archive's central directory.
    `java.util.Enumeration<ZipEntry>` | `getEntriesInPhysicalOrder()` | Returns all entries in physical order.
    `java.lang.Iterable<ZipEntry>` | `getEntriesInPhysicalOrder​(java.lang.String name)` | Returns all named entries in the same order their contents appear within the archive.
    `ZipEntry` | `getEntry​(java.lang.String name)` | Returns a named entry - or `null` if no entry by that name exists.
    `java.io.InputStream` | `getInputStream​(ZipEntry ze)` | Returns an InputStream for reading the contents of the given entry.

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

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

- - ### Constructor Detail

    - #### ZipFile

          public ZipFile​(java.io.File f)
                  throws java.io.IOException

      Opens the given file for reading, assuming the platform's native encoding for file names.
      Parameters:
        `f` - the archive.
      Throws:
        `java.io.IOException` - if an error occurs while reading the file.

    - #### ZipFile

          public ZipFile​(java.lang.String name)
                  throws java.io.IOException

      Opens the given file for reading, assuming the platform's native encoding for file names.
      Parameters:
        `name` - name of the archive.
      Throws:
        `java.io.IOException` - if an error occurs while reading the file.

    - #### ZipFile

          public ZipFile​(java.lang.String name,
                         java.lang.String encoding)
                  throws java.io.IOException

      Opens the given file for reading, assuming the specified encoding for file names, scanning unicode extra fields.
      Parameters:
        `name` - name of the archive.
        `encoding` - the encoding to use for file names, use null for the platform's default encoding
      Throws:
        `java.io.IOException` - if an error occurs while reading the file.

    - #### ZipFile

          public ZipFile​(java.io.File f,
                         java.lang.String encoding)
                  throws java.io.IOException

      Opens the given file for reading, assuming the specified encoding for file names and scanning for unicode extra fields.
      Parameters:
        `f` - the archive.
        `encoding` - the encoding to use for file names, use null for the platform's default encoding
      Throws:
        `java.io.IOException` - if an error occurs while reading the file.

    - #### ZipFile

          public ZipFile​(java.io.File f,
                         java.lang.String encoding,
                         boolean useUnicodeExtraFields)
                  throws java.io.IOException

      Opens the given file for reading, assuming the specified encoding for file names.
      Parameters:
        `f` - the archive.
        `encoding` - the encoding to use for file names, use null for the platform's default encoding
        `useUnicodeExtraFields` - whether to use InfoZIP Unicode Extra Fields (if present) to set the file names.
      Throws:
        `java.io.IOException` - if an error occurs while reading the file.

  - ### Method Detail

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

    - #### close

          public void close()
                     throws java.io.IOException

      Closes the archive.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.io.Closeable`
      Throws:
        `java.io.IOException` - if an error occurs closing the archive.

    - #### closeQuietly

          public static void closeQuietly​(ZipFile zipfile)

      close a zipfile quietly; throw no io fault, do nothing on a null parameter
      Parameters:
        `zipfile` - file to close, can be null

    - #### getEntries

          public java.util.Enumeration<ZipEntry> getEntries()

      Returns all entries.

      Entries will be returned in the same order they appear within the archive's central directory.

      Returns:
        all entries as `ZipEntry` instances

    - #### getEntriesInPhysicalOrder

          public java.util.Enumeration<ZipEntry> getEntriesInPhysicalOrder()

      Returns all entries in physical order.

      Entries will be returned in the same order their contents appear within the archive.

      Returns:
        all entries as `ZipEntry` instances
      Since:
        Ant 1.9.0

    - #### getEntry

          public ZipEntry getEntry​(java.lang.String name)

      Returns a named entry - or `null` if no entry by that name exists.

      If multiple entries with the same name exist the first entry in the archive's central directory by that name is returned.

      Parameters:
        `name` - name of the entry.
      Returns:
        the ZipEntry corresponding to the given name - or `null` if not present.

    - #### getEntries

          public java.lang.Iterable<ZipEntry> getEntries​(java.lang.String name)

      Returns all named entries in the same order they appear within the archive's central directory.
      Parameters:
        `name` - name of the entry.
      Returns:
        the Iterable<ZipEntry> corresponding to the given name
      Since:
        1.9.2

    - #### getEntriesInPhysicalOrder

          public java.lang.Iterable<ZipEntry> getEntriesInPhysicalOrder​(java.lang.String name)

      Returns all named entries in the same order their contents appear within the archive.
      Parameters:
        `name` - name of the entry.
      Returns:
        the Iterable<ZipEntry> corresponding to the given name
      Since:
        1.9.2

    - #### canReadEntryData

          public boolean canReadEntryData​(ZipEntry ze)

      Whether this class is able to read 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:
        `ze` - ZipEntry
      Returns:
        boolean

    - #### getInputStream

          public java.io.InputStream getInputStream​(ZipEntry ze)
                                             throws java.io.IOException,
                                                    java.util.zip.ZipException

      Returns an InputStream for reading the contents of the given entry.
      Parameters:
        `ze` - the entry to get the stream for.
      Returns:
        a stream to read the entry from.
      Throws:
        `java.io.IOException` - if unable to create an input stream from the zipentry
        `java.util.zip.ZipException` - if the zipentry uses an unsupported feature

    - #### finalize

          protected void finalize()
                           throws java.lang.Throwable

      Ensures that the close method of this zipfile is called when there are no more references to it.
      Overrides:
        `finalize` in class `java.lang.Object`
      Throws:
        `java.lang.Throwable`
      See Also:
        `close()`