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, 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.
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)
.
Manifest
,
ZipFile
,
JarEntry
Modifier and Type | Class and Description |
---|---|
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.
|
Modifier and Type | Field and 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 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 . |
Modifier and Type | Method and Description |
---|---|
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. |
public static final int CENATT
public static final int CENATX
public static final int CENCOM
public static final int CENCRC
public static final int CENDSK
public static final int CENEXT
public static final int CENFLG
public static final int CENHDR
public static final int CENHOW
public static final int CENLEN
public static final int CENNAM
public static final int CENOFF
public static final long CENSIG
public static final int CENSIZ
public static final int CENTIM
public static final int CENVEM
public static final int CENVER
public static final int ENDCOM
public static final int ENDHDR
public static final int ENDOFF
public static final long ENDSIG
public static final int ENDSIZ
public static final int ENDSUB
public static final int ENDTOT
public static final int EXTCRC
public static final int EXTHDR
public static final int EXTLEN
public static final long EXTSIG
public static final int EXTSIZ
public static final int LOCCRC
public static final int LOCEXT
public static final int LOCFLG
public static final int LOCHDR
public static final int LOCHOW
public static final int LOCLEN
public static final int LOCNAM
public static final long LOCSIG
public static final int LOCSIZ
public static final int LOCTIM
public static final int LOCVER
public static final String MANIFEST_NAME
public 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, JarFile.Release 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 configures the JarFile
for processing
multi-release jar files.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 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 final JarFile.Release getVersion()
Release.BASE
if this jar file is
processed as if it is an unversioned jar file or is not a
multi-release jar filepublic 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()
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/".entries
in class ZipFile
IllegalStateException
- may be thrown if the jar file has been closedpublic Stream<JarEntry> stream()
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/".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, 2016, Oracle and/or its affiliates. All rights reserved.
DRAFT 9-internal+0-2016-06-25-232344.buildd.src