Closeable
, AutoCloseable
public class JarFile extends ZipFile
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, Runtime.Version)
constructor. The
Runtime.Version
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, Runtime.Version)
constructor with the value Runtime.version()
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.
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
<= Runtime.version().major()
. The value is used to set the effective
runtime version to something other than the default value obtained by
evaluating Runtime.version().major()
. The effective runtime version
is the version that the JarFile(File, boolean, int, Runtime.Version)
constructor uses when the value of the last argument is
JarFile.runtimeVersion()
.
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, JarFile.runtimeVersion())
.
Manifest
,
ZipFile
,
JarEntry
Modifier and Type | Field | Description |
---|---|---|
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.
|
OPEN_DELETE, OPEN_READ
Constructor | 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,
Runtime.Version 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 . |
Modifier and Type | Method | Description |
---|---|---|
static Runtime.Version |
baseVersion() |
Returns the version that represents the unversioned configuration of a
multi-release jar file.
|
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. |
Runtime.Version |
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.
|
static Runtime.Version |
runtimeVersion() |
Returns the version that represents the effective runtime versioned
configuration of a multi-release jar file.
|
Stream<JarEntry> |
stream() |
Returns an ordered
Stream over the jar file entries. |
public static final String MANIFEST_NAME
public static final long LOCSIG
public static final long EXTSIG
public static final long CENSIG
public static final long ENDSIG
public static final int LOCHDR
public static final int EXTHDR
public static final int CENHDR
public static final int ENDHDR
public static final int LOCVER
public static final int LOCFLG
public static final int LOCHOW
public static final int LOCTIM
public static final int LOCCRC
public static final int LOCSIZ
public static final int LOCLEN
public static final int LOCNAM
public static final int LOCEXT
public static final int EXTCRC
public static final int EXTSIZ
public static final int EXTLEN
public static final int CENVEM
public static final int CENVER
public static final int CENFLG
public static final int CENHOW
public static final int CENTIM
public static final int CENCRC
public static final int CENSIZ
public static final int CENLEN
public static final int CENNAM
public static final int CENEXT
public static final int CENCOM
public static final int CENDSK
public static final int CENATT
public static final int CENATX
public static final int CENOFF
public static final int ENDSUB
public static final int ENDTOT
public static final int ENDSIZ
public static final int ENDOFF
public static final int ENDCOM
public JarFile(String name) throws IOException
JarFile
to read from the specified
file name
. The JarFile
will be verified if
it is signed.name
- the name of the jar file to be opened for readingIOException
- if an I/O error has occurredSecurityException
- if access to the file is denied
by the SecurityManagerpublic JarFile(String name, boolean verify) throws IOException
JarFile
to read from the specified
file name
.name
- the name of the jar file to be opened for readingverify
- whether or not to verify the jar file if
it is signed.IOException
- if an I/O error has occurredSecurityException
- if access to the file is denied
by the SecurityManagerpublic JarFile(File file) throws IOException
JarFile
to read from the specified
File
object. The JarFile
will be verified if
it is signed.file
- the jar file to be opened for readingIOException
- if an I/O error has occurredSecurityException
- if access to the file is denied
by the SecurityManagerpublic JarFile(File file, boolean verify) throws IOException
JarFile
to read from the specified
File
object.file
- the jar file to be opened for readingverify
- whether or not to verify the jar file if
it is signed.IOException
- if an I/O error has occurredSecurityException
- if access to the file is denied
by the SecurityManager.public JarFile(File file, boolean verify, int mode) throws IOException
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
.file
- the jar file to be opened for readingverify
- whether or not to verify the jar file if
it is signed.mode
- the mode in which the file is to be openedIOException
- if an I/O error has occurredIllegalArgumentException
- if the mode
argument is invalidSecurityException
- if access to the file is denied
by the SecurityManagerpublic JarFile(File file, boolean verify, int mode, Runtime.Version version) throws IOException
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, after being converted to a canonical form, is
used to configure the JarFile
for processing
multi-release jar files.
The canonical form derived from the version parameter is
Runtime.Version.parse(Integer.toString(n))
where n
is
Math.max(version.major(), JarFile.baseVersion().major())
.
file
- the jar file to be opened for readingverify
- whether or not to verify the jar file if
it is signed.mode
- the mode in which the file is to be openedversion
- specifies the release version for a multi-release jar fileIOException
- if an I/O error has occurredIllegalArgumentException
- if the mode
argument is invalidSecurityException
- if access to the file is denied
by the SecurityManagerNullPointerException
- if version
is null
public static Runtime.Version baseVersion()
public static Runtime.Version runtimeVersion()
By default the major version number of the returned Version
will
be equal to the major version number of Runtime.version()
.
However, if the jdk.util.jar.version
property is set, the
returned Version
is derived from that property and major version
numbers may not be equal.
public final Runtime.Version getVersion()
If this JarFile
is not a multi-release jar file or is not
configured to be processed as such, then the version returned will be the
same as that returned from baseVersion()
.
public final boolean isMultiRelease()
public Manifest getManifest() throws IOException
null
if none.null
if noneIllegalStateException
- may be thrown if the jar file has been closedIOException
- if an I/O error has occurredpublic JarEntry getJarEntry(String name)
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()
.
getEntry(String)
.
name
- the jar file entry nameJarEntry
for the given entry name, or
the versioned entry name, or null
if not foundIllegalStateException
- may be thrown if the jar file has been closedJarEntry
public ZipEntry getEntry(String name)
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()
.
getEntry
in class ZipFile
super.getEntry(name)
to obtain all versioned entries.
name
- the jar file entry nameZipEntry
for the given entry name or
the versioned entry name or null
if not foundIllegalStateException
- may be thrown if the jar file has been closedZipEntry
public Enumeration<JarEntry> entries()
entries
in class ZipFile
IllegalStateException
- may be thrown if the jar file has been closedpublic Stream<JarEntry> stream()
Stream
over the jar file entries.
Entries appear in the Stream
in the order they appear in
the central directory of the jar file.stream
in class ZipFile
Stream
of entries in this jar fileIllegalStateException
- if the jar file has been closedpublic InputStream getInputStream(ZipEntry ze) throws IOException
getInputStream
in class ZipFile
ze
- the zip file entryZipException
- if a zip file format error has occurredIOException
- if an I/O error has occurredSecurityException
- if any of the jar file entries
are incorrectly signed.IllegalStateException
- may be thrown if the jar file has been closed Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-internal+0-adhoc.mlchung.jdk9-jdeps