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

Package org.apache.tools.zip

# Class ZipFile

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

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public class ZipFile extends Object implements 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(File f)`
  Opens the given file for reading, assuming the platform's native encoding for file names.
  `ZipFile(File f, String encoding)`
  Opens the given file for reading, assuming the specified encoding for file names and scanning for unicode extra fields.
  `ZipFile(File f, String encoding, boolean useUnicodeExtraFields)`
  Opens the given file for reading, assuming the specified encoding for file names.
  `ZipFile(String name)`
  Opens the given file for reading, assuming the platform's native encoding for file names.
  `ZipFile(String name, String encoding)`
  Opens the given file for reading, assuming the specified encoding for file names, scanning unicode extra fields.

- ## Method Summary

  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.
  `String`
  `getEncoding()`
  The encoding to use for filenames and the file comment.
  `Enumeration<ZipEntry>`
  `getEntries()`
  Returns all entries.
  `Iterable<ZipEntry>`
  `getEntries(String name)`
  Returns all named entries in the same order they appear within the archive's central directory.
  `Enumeration<ZipEntry>`
  `getEntriesInPhysicalOrder()`
  Returns all entries in physical order.
  `Iterable<ZipEntry>`
  `getEntriesInPhysicalOrder(String name)`
  Returns all named entries in the same order their contents appear within the archive.
  `ZipEntry`
  `getEntry(String name)`
  Returns a named entry - or `null` if no entry by that name exists.
  `InputStream`
  `getInputStream(ZipEntry ze)`
  Returns an InputStream for reading the contents of the given entry.
  `String`
  `getName()`

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

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

- ## Constructor Details

  - ### ZipFile

    public ZipFile(File f) throws IOException
    Opens the given file for reading, assuming the platform's native encoding for file names.
    Parameters:
      `f` - the archive.
    Throws:
      `IOException` - if an error occurs while reading the file.

  - ### ZipFile

    public ZipFile(String name) throws IOException
    Opens the given file for reading, assuming the platform's native encoding for file names.
    Parameters:
      `name` - name of the archive.
    Throws:
      `IOException` - if an error occurs while reading the file.

  - ### ZipFile

    public ZipFile(String name, String encoding) throws 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:
      `IOException` - if an error occurs while reading the file.

  - ### ZipFile

    public ZipFile(File f, String encoding) throws 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:
      `IOException` - if an error occurs while reading the file.

  - ### ZipFile

    public ZipFile(File f, String encoding, boolean useUnicodeExtraFields) throws 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:
      `IOException` - if an error occurs while reading the file.

- ## Method Details

  - ### getEncoding

    public 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 IOException
    Closes the archive.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Throws:
      `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 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 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(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 Iterable<ZipEntry> getEntries(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 Iterable<ZipEntry> getEntriesInPhysicalOrder(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 InputStream getInputStream(ZipEntry ze) throws IOException, 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:
      `IOException` - if unable to create an input stream from the zipentry
      `ZipException` - if the zipentry uses an unsupported feature

  - ### getName

    public String getName()

  - ### finalize

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