Module java.base
Package java.util.jar

## Class JarFile

- java.lang.Object
- - java.util.zip.ZipFile
  - - java.util.jar.JarFile

All Implemented Interfaces:
  Closeable, AutoCloseable

    public class JarFile
    extends ZipFile

The `JarFile` class is used to read the contents of a jar file from any file that can be opened with `java.io.RandomAccessFile`. It extends the class `java.util.zip.ZipFile` with support for reading an optional `Manifest` entry, and support for processing multi-release jar files. The `Manifest` can be used to specify meta-information about the jar file and its entries.

A multi-release jar file is a jar file that contains a manifest with a main attribute named "Multi-Release", a set of "base" entries, some of which are public classes with public or protected methods that comprise the public interface of the jar file, and a set of "versioned" entries contained in subdirectories of the "META-INF/versions" directory. The versioned entries are partitioned by the major version of the Java platform. A versioned entry, with a version `n`, `8 < n`, in the "META-INF/versions/{n}" directory overrides the base entry as well as any entry with a version number `i` where `8 < i < n`.

By default, a `JarFile` for a multi-release jar file is configured to process the multi-release jar file as if it were a plain (unversioned) jar file, and as such an entry name is associated with at most one base entry. The `JarFile` may be configured to process a multi-release jar file by creating the `JarFile` with the `JarFile(File, boolean, int, Release)` constructor. The `Release` object sets a maximum version used when searching for versioned entries. When so configured, an entry name can correspond with at most one base entry and zero or more versioned entries. A search is required to associate the entry name with the latest versioned entry whose version is less than or equal to the maximum version (see `getEntry(String)`).

Class loaders that utilize `JarFile` to load classes from the contents of `JarFile` entries should construct the `JarFile` by invoking the `JarFile(File, boolean, int, Release)` constructor with the value `Release.RUNTIME` assigned to the last argument. This assures that classes compatible with the major version of the running JVM are loaded from multi-release jar files.

If the verify flag is on when opening a signed jar file, the content of the file is verified against its signature embedded inside the file. Please note that the verification process does not include validating the signer's certificate. A caller should inspect the return value of `JarEntry.getCodeSigners()` to further determine if the signature can be trusted.

Unless otherwise noted, passing a `null` argument to a constructor or method in this class will cause a `NullPointerException` to be thrown.

Implementation Note:
  If the API can not be used to configure a `JarFile` (e.g. to override the configuration of a compiled application or library), two `System` properties are available.
  - `jdk.util.jar.version` can be assigned a value that is the `String` representation of a non-negative integer `<= Version.current().major()`. The value is used to set the effective runtime version to something other than the default value obtained by evaluating `Version.current().major()`. The effective runtime version is the version that the `JarFile(File, boolean, int, Release)` constructor uses when the value of the last argument is `Release.RUNTIME`.
  - `jdk.util.jar.enableMultiRelease` can be assigned one of the three `String` values true, false, or force. The value true, the default value, enables multi-release jar file processing. The value false disables multi-release jar processing, ignoring the "Multi-Release" manifest attribute, and the versioned directories in a multi-release jar file if they exist. Furthermore, the method `isMultiRelease()` returns false. The value force causes the `JarFile` to be initialized to runtime versioning after construction. It effectively does the same as this code: `(new JarFile(File, boolean, int, Release.RUNTIME)`.
Since:
  1.2
See Also:
  `Manifest`, `ZipFile`, `JarEntry`

### Nested Class Summary

Nested Classes
`static class` `JarFile.Release` A set of constants that represent the entries in either the base directory or one of the versioned directories in a multi-release jar file.

### Field Summary

Fields
`static int` `CENATT`
`static int` `CENATX`
`static int` `CENCOM`
`static int` `CENCRC`
`static int` `CENDSK`
`static int` `CENEXT`
`static int` `CENFLG`
`static int` `CENHDR`
`static int` `CENHOW`
`static int` `CENLEN`
`static int` `CENNAM`
`static int` `CENOFF`
`static long` `CENSIG`
`static int` `CENSIZ`
`static int` `CENTIM`
`static int` `CENVEM`
`static int` `CENVER`
`static int` `ENDCOM`
`static int` `ENDHDR`
`static int` `ENDOFF`
`static long` `ENDSIG`
`static int` `ENDSIZ`
`static int` `ENDSUB`
`static int` `ENDTOT`
`static int` `EXTCRC`
`static int` `EXTHDR`
`static int` `EXTLEN`
`static long` `EXTSIG`
`static int` `EXTSIZ`
`static int` `LOCCRC`
`static int` `LOCEXT`
`static int` `LOCFLG`
`static int` `LOCHDR`
`static int` `LOCHOW`
`static int` `LOCLEN`
`static int` `LOCNAM`
`static long` `LOCSIG`
`static int` `LOCSIZ`
`static int` `LOCTIM`
`static int` `LOCVER`
`static String` `MANIFEST_NAME` The JAR manifest file name.

### Fields inherited from class java.util.zip.ZipFile

`OPEN_DELETE, OPEN_READ`

### Constructor Summary

Constructors
Constructor and Description
`JarFile(File file)` Creates a new `JarFile` to read from the specified `File` object.
`JarFile(File file, boolean verify)` Creates a new `JarFile` to read from the specified `File` object.
`JarFile(File file, boolean verify, int mode)` Creates a new `JarFile` to read from the specified `File` object in the specified mode.
`JarFile(File file, boolean verify, int mode, JarFile.Release version)` Creates a new `JarFile` to read from the specified `File` object in the specified mode.
`JarFile(String name)` Creates a new `JarFile` to read from the specified file `name`.
`JarFile(String name, boolean verify)` Creates a new `JarFile` to read from the specified file `name`.

### Method Summary

All Methods Instance Methods Concrete Methods
`Enumeration<JarEntry>` `entries()` Returns an enumeration of the jar file entries.
`ZipEntry` `getEntry(String name)` Returns the `ZipEntry` for the given base entry name or `null` if not found.
`InputStream` `getInputStream(ZipEntry ze)` Returns an input stream for reading the contents of the specified zip file entry.
`JarEntry` `getJarEntry(String name)` Returns the `JarEntry` for the given base entry name or `null` if not found.
`Manifest` `getManifest()` Returns the jar file manifest, or `null` if none.
`JarFile.Release` `getVersion()` Returns the maximum version used when searching for versioned entries.
`boolean` `isMultiRelease()` Indicates whether or not this jar file is a multi-release jar file.
`Stream<JarEntry>` `stream()` Returns an ordered `Stream` over all the jar file entries.

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

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

### Methods inherited from class java.util.zip.ZipFile

`close, finalize, getComment, getName, size`

### Field Detail

#### CENATT

    public static final int CENATT

See Also:
  Constant Field Values

#### CENATX

    public static final int CENATX

See Also:
  Constant Field Values

#### CENCOM

    public static final int CENCOM

See Also:
  Constant Field Values

#### CENCRC

    public static final int CENCRC

See Also:
  Constant Field Values

#### CENDSK

    public static final int CENDSK

See Also:
  Constant Field Values

#### CENEXT

    public static final int CENEXT

See Also:
  Constant Field Values

#### CENFLG

    public static final int CENFLG

See Also:
  Constant Field Values

#### CENHDR

    public static final int CENHDR

See Also:
  Constant Field Values

#### CENHOW

    public static final int CENHOW

See Also:
  Constant Field Values

#### CENLEN

    public static final int CENLEN

See Also:
  Constant Field Values

#### CENNAM

    public static final int CENNAM

See Also:
  Constant Field Values

#### CENOFF

    public static final int CENOFF

See Also:
  Constant Field Values

#### CENSIG

    public static final long CENSIG

See Also:
  Constant Field Values

#### CENSIZ

    public static final int CENSIZ

See Also:
  Constant Field Values

#### CENTIM

    public static final int CENTIM

See Also:
  Constant Field Values

#### CENVEM

    public static final int CENVEM

See Also:
  Constant Field Values

#### CENVER

    public static final int CENVER

See Also:
  Constant Field Values

#### ENDCOM

    public static final int ENDCOM

See Also:
  Constant Field Values

#### ENDHDR

    public static final int ENDHDR

See Also:
  Constant Field Values

#### ENDOFF

    public static final int ENDOFF

See Also:
  Constant Field Values

#### ENDSIG

    public static final long ENDSIG

See Also:
  Constant Field Values

#### ENDSIZ

    public static final int ENDSIZ

See Also:
  Constant Field Values

#### ENDSUB

    public static final int ENDSUB

See Also:
  Constant Field Values

#### ENDTOT

    public static final int ENDTOT

See Also:
  Constant Field Values

#### EXTCRC

    public static final int EXTCRC

See Also:
  Constant Field Values

#### EXTHDR

    public static final int EXTHDR

See Also:
  Constant Field Values

#### EXTLEN

    public static final int EXTLEN

See Also:
  Constant Field Values

#### EXTSIG

    public static final long EXTSIG

See Also:
  Constant Field Values

#### EXTSIZ

    public static final int EXTSIZ

See Also:
  Constant Field Values

#### LOCCRC

    public static final int LOCCRC

See Also:
  Constant Field Values

#### LOCEXT

    public static final int LOCEXT

See Also:
  Constant Field Values

#### LOCFLG

    public static final int LOCFLG

See Also:
  Constant Field Values

#### LOCHDR

    public static final int LOCHDR

See Also:
  Constant Field Values

#### LOCHOW

    public static final int LOCHOW

See Also:
  Constant Field Values

#### LOCLEN

    public static final int LOCLEN

See Also:
  Constant Field Values

#### LOCNAM

    public static final int LOCNAM

See Also:
  Constant Field Values

#### LOCSIG

    public static final long LOCSIG

See Also:
  Constant Field Values

#### LOCSIZ

    public static final int LOCSIZ

See Also:
  Constant Field Values

#### LOCTIM

    public static final int LOCTIM

See Also:
  Constant Field Values

#### LOCVER

    public static final int LOCVER

See Also:
  Constant Field Values

#### MANIFEST_NAME

    public static final String MANIFEST_NAME

The JAR manifest file name.

See Also:
  Constant Field Values

### Constructor Detail

#### JarFile

    public JarFile(File file)
            throws IOException

Creates a new `JarFile` to read from the specified `File` object. The `JarFile` will be verified if it is signed.

Parameters:
  `file` - the jar file to be opened for reading
Throws:
  `IOException` - if an I/O error has occurred
  `SecurityException` - if access to the file is denied by the SecurityManager

#### JarFile

    public JarFile(File file,
                   boolean verify)
            throws IOException

Creates a new `JarFile` to read from the specified `File` object.

Parameters:
  `file` - the jar file to be opened for reading
  `verify` - whether or not to verify the jar file if it is signed.
Throws:
  `IOException` - if an I/O error has occurred
  `SecurityException` - if access to the file is denied by the SecurityManager.

#### JarFile

    public JarFile(File file,
                   boolean verify,
                   int mode)
            throws IOException

Creates a new `JarFile` to read from the specified `File` object in the specified mode. The mode argument must be either `OPEN_READ` or `OPEN_READ | OPEN_DELETE`.

Parameters:
  `file` - the jar file to be opened for reading
  `verify` - whether or not to verify the jar file if it is signed.
  `mode` - the mode in which the file is to be opened
Throws:
  `IOException` - if an I/O error has occurred
  `IllegalArgumentException` - if the `mode` argument is invalid
  `SecurityException` - if access to the file is denied by the SecurityManager
Since:
  1.3

#### JarFile

    public JarFile(File file,
                   boolean verify,
                   int mode,
                   JarFile.Release version)
            throws IOException

Creates a new `JarFile` to read from the specified `File` object in the specified mode. The mode argument must be either `OPEN_READ` or `OPEN_READ | OPEN_DELETE`. The version argument configures the `JarFile` for processing multi-release jar files.

Parameters:
  `file` - the jar file to be opened for reading
  `verify` - whether or not to verify the jar file if it is signed.
  `mode` - the mode in which the file is to be opened
  `version` - specifies the release version for a multi-release jar file
Throws:
  `IOException` - if an I/O error has occurred
  `IllegalArgumentException` - if the `mode` argument is invalid
  `SecurityException` - if access to the file is denied by the SecurityManager
  `NullPointerException` - if `version` is `null`
Since:
  9

#### JarFile

    public JarFile(String name)
            throws IOException

Creates a new `JarFile` to read from the specified file `name`. The `JarFile` will be verified if it is signed.

Parameters:
  `name` - the name of the jar file to be opened for reading
Throws:
  `IOException` - if an I/O error has occurred
  `SecurityException` - if access to the file is denied by the SecurityManager

#### JarFile

    public JarFile(String name,
                   boolean verify)
            throws IOException

Creates a new `JarFile` to read from the specified file `name`.

Parameters:
  `name` - the name of the jar file to be opened for reading
  `verify` - whether or not to verify the jar file if it is signed.
Throws:
  `IOException` - if an I/O error has occurred
  `SecurityException` - if access to the file is denied by the SecurityManager

### Method Detail

#### getVersion

    public final JarFile.Release getVersion()

Returns the maximum version used when searching for versioned entries.

Returns:
  the maximum version, or `Release.BASE` if this jar file is processed as if it is an unversioned jar file or is not a multi-release jar file
Since:
  9

#### isMultiRelease

    public final boolean isMultiRelease()

Indicates whether or not this jar file is a multi-release jar file.

Returns:
  true if this JarFile is a multi-release jar file
Since:
  9

#### getManifest

    public Manifest getManifest()
                         throws IOException

Returns the jar file manifest, or `null` if none.

Returns:
  the jar file manifest, or `null` if none
Throws:
  `IllegalStateException` - may be thrown if the jar file has been closed
  `IOException` - if an I/O error has occurred

#### getJarEntry

    public JarEntry getJarEntry(String name)

Returns the `JarEntry` for the given base entry name or `null` if not found.

If this `JarFile` is a multi-release jar file and is configured to be processed as such, then a search is performed to find and return a `JarEntry` that is the latest versioned entry associated with the given entry name. The returned `JarEntry` is the versioned entry corresponding to the given base entry name prefixed with the string `"META-INF/versions/{n}/"`, for the largest value of `n` for which an entry exists. If such a versioned entry does not exist, then the `JarEntry` for the base entry is returned, otherwise `null` is returned if no entries are found. The initial value for the version `n` is the maximum version as returned by the method `getVersion()`.

Implementation Requirements:
  This implementation invokes `getEntry(String)`.
Parameters:
  `name` - the jar file entry name
Returns:
  the `JarEntry` for the given entry name, or the versioned entry name, or `null` if not found
Throws:
  `IllegalStateException` - may be thrown if the jar file has been closed
See Also:
  `JarEntry`

#### getEntry

    public ZipEntry getEntry(String name)

Returns the `ZipEntry` for the given base entry name or `null` if not found.

If this `JarFile` is a multi-release jar file and is configured to be processed as such, then a search is performed to find and return a `ZipEntry` that is the latest versioned entry associated with the given entry name. The returned `ZipEntry` is the versioned entry corresponding to the given base entry name prefixed with the string `"META-INF/versions/{n}/"`, for the largest value of `n` for which an entry exists. If such a versioned entry does not exist, then the `ZipEntry` for the base entry is returned, otherwise `null` is returned if no entries are found. The initial value for the version `n` is the maximum version as returned by the method `getVersion()`.

Overrides:
  `getEntry` in class `ZipFile`
Implementation Requirements:
  This implementation may return a versioned entry for the requested name even if there is not a corresponding base entry. This can occur if there is a private or package-private versioned entry that matches. If a subclass overrides this method, assure that the override method invokes `super.getEntry(name)` to obtain all versioned entries.
Parameters:
  `name` - the jar file entry name
Returns:
  the `ZipEntry` for the given entry name or the versioned entry name or `null` if not found
Throws:
  `IllegalStateException` - may be thrown if the jar file has been closed
See Also:
  `ZipEntry`

#### entries

    public Enumeration<JarEntry> entries()

Returns an enumeration of the jar file entries. The set of entries returned depends on whether or not the jar file is a multi-release jar file, and on the constructor used to create the `JarFile`. If the jar file is not a multi-release jar file, all entries are returned, regardless of how the `JarFile` is created. If the constructor does not take a `Release` argument, all entries are returned. If the jar file is a multi-release jar file and the constructor takes a `Release` argument, then the set of entries returned is equivalent to the set of entries that would be returned if the set was built by invoking `getEntry(String)` or `getJarEntry(String)` with the name of each base entry in the jar file. A base entry is an entry whose path name does not start with "META-INF/versions/".

Overrides:
  `entries` in class `ZipFile`
Returns:
  an enumeration of the jar file entries
Throws:
  `IllegalStateException` - may be thrown if the jar file has been closed

#### stream

    public Stream<JarEntry> stream()

Returns an ordered `Stream` over all the jar file entries. Entries appear in the `Stream` in the order they appear in the central directory of the jar file. The set of entries returned depends on whether or not the jar file is a multi-release jar file, and on the constructor used to create the `JarFile`. If the jar file is not a multi-release jar file, all entries are returned, regardless of how the `JarFile` is created. If the constructor does not take a `Release` argument, all entries are returned. If the jar file is a multi-release jar file and the constructor takes a `Release` argument, then the set of entries returned is equivalent to the set of entries that would be returned if the set was built by invoking `getEntry(String)` or `getJarEntry(String)` with the name of each base entry in the jar file. A base entry is an entry whose path name does not start with "META-INF/versions/".

Overrides:
  `stream` in class `ZipFile`
Returns:
  an ordered `Stream` of entries in this jar file
Throws:
  `IllegalStateException` - if the jar file has been closed
Since:
  1.8

#### getInputStream

    public InputStream getInputStream(ZipEntry ze)
                               throws IOException

Returns an input stream for reading the contents of the specified zip file entry.

Overrides:
  `getInputStream` in class `ZipFile`
Parameters:
  `ze` - the zip file entry
Returns:
  an input stream for reading the contents of the specified zip file entry
Throws:
  `ZipException` - if a zip file format error has occurred
  `IOException` - if an I/O error has occurred
  `SecurityException` - if any of the jar file entries are incorrectly signed.
  `IllegalStateException` - may be thrown if the jar file has been closed