Module java.base
Package java.util.jar

Class JarFile

java.lang.Object
java.util.zip.ZipFile
java.util.jar.JarFile
所有已实现的接口:
Closeable, AutoCloseable
public class JarFile extends ZipFile
JarFile类用于从可以使用java.io.RandomAccessFile打开的任何文件中读取jar文件的内容。它扩展了带有读取可选Manifest条目的支持以及处理多版本jar文件的支持的java.util.zip.ZipFile类。 Manifest可用于指定关于jar文件及其条目的元信息。

多版本jar文件是一个包含具有名为"Multi-Release"的主属性的清单的jar文件，其中包含一组"基本"条目，其中一些是具有公共或受保护方法的公共类，构成了jar文件的公共接口，并包含在"META-INF/versions"目录的子目录中的一组"版本化"条目。 版本化条目按Java平台的主版本进行分区。 版本化条目，版本为n，8 < n，在"META-INF/versions/{n}"目录中覆盖基本条目以及任何版本号为i的条目，其中8 < i < n。

默认情况下，用于多版本jar文件的JarFile被配置为处理多版本jar文件，就好像它是一个普通（无版本）的jar文件，并且因此一个条目名称最多与一个基本条目关联。 可以通过使用带有JarFile(File, boolean, int, Runtime.Version)构造函数创建JarFile来配置JarFile以处理多版本jar文件。 Runtime.Version对象设置了在搜索版本化条目时使用的最大版本。 配置为这样时，一个条目名称可以对应于最多一个基本条目和零个或多个版本化条目。 需要搜索以将条目名称与其版本小于或等于最大版本的最新版本化条目关联（参见getEntry(String)）。

使用JarFile从JarFile条目的内容中加载类的类加载器应通过调用将值Runtime.version()分配给最后一个参数的JarFile(File, boolean, int, Runtime.Version)构造函数来构造JarFile。 这确保了与运行JVM的主版本兼容的类从多版本jar文件中加载。

如果在打开已签名的jar文件时打开了verify标志，则jar条目的内容将根据与其路径名称关联的清单中嵌入的签名进行验证。 对于多版本jar文件，版本化条目的内容将根据其自身的签名进行验证，并且JarEntry.getCodeSigners()将返回其自己的签名者。 请注意，验证过程不包括验证签名者的证书。 调用者应检查JarEntry.getCodeSigners()的返回值以进一步确定是否可以信任签名。

除非另有说明，在此类中将null参数传递给构造函数或方法将导致抛出NullPointerException。

实现注意:
如果API无法用于配置JarFile（例如，覆盖已编译应用程序或库的配置），则有两个System属性可用。
  • jdk.util.jar.version可以分配一个值，该值是非负整数<= Runtime.version().feature()的String表示。 该值用于将有效运行时版本设置为与通过评估Runtime.version().feature()获得的默认值不同的值。 有效运行时版本是JarFile(File, boolean, int, Runtime.Version)构造函数在最后一个参数的值为JarFile.runtimeVersion()时使用的版本。
  • jdk.util.jar.enableMultiRelease可以分配三个String值之一：true，false或force。 值true，默认值，启用多版本jar文件处理。 值false禁用多版本jar处理，忽略多版本jar文件中存在的"Multi-Release"清单属性和版本化目录。 此外，如果存在，方法isMultiRelease()返回false。 值force导致JarFile在构造后初始化为运行时版本控制。 它实际上与此代码相同：(new JarFile(File, boolean, int, JarFile.runtimeVersion())。
自:
1.2
参见:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    CENATT
    中央目录（CEN）头部内部文件属性字段偏移量。
    static final int
    CENATX
    中央目录（CEN）头部外部文件属性字段偏移量。
    static final int
    CENCOM
    中央目录（CEN）头部注释长度字段偏移量。
    static final int
    CENCRC
    中央目录（CEN）头部未压缩文件crc-32值字段偏移量。
    static final int
    CENDSK
    中央目录（CEN）头部磁盘号起始字段偏移量。
    static final int
    CENEXT
    中央目录（CEN）头部额外字段长度字段偏移量。
    static final int
    CENFLG
    中央目录（CEN）头部加密、解密标志字段偏移量。
    static final int
    CENHDR
    中央目录（CEN）头部字节大小（包括签名）。
    static final int
    CENHOW
    中央目录（CEN）头部压缩方法字段偏移量。
    static final int
    CENLEN
    中央目录（CEN）头部未压缩大小字段偏移量。
    static final int
    CENNAM
    中央目录（CEN）头部文件名长度字段偏移量。
    static final int
    CENOFF
    中央目录（CEN）头部LOC头部偏移量字段偏移量。
    static final long
    CENSIG
    中央目录（CEN）头部签名。
    static final int
    CENSIZ
    中央目录（CEN）头部压缩大小字段偏移量。
    static final int
    CENTIM
    中央目录（CEN）头部修改时间字段偏移量。
    static final int
    CENVEM
    中央目录（CEN）头部创建者版本字段偏移量。
    static final int
    CENVER
    中央目录（CEN）头部需要提取的版本字段偏移量。
    static final int
    ENDCOM
    中央目录（END）头部zip文件注释长度字段偏移量。
    static final int
    ENDHDR
    中央目录（END）头部字节大小（包括签名）。
    static final int
    ENDOFF
    中央目录（END）头部第一个CEN头部字段偏移量。
    static final long
    ENDSIG
    中央目录（END）头部签名。
    static final int
    ENDSIZ
    中央目录（END）头部字节大小字段偏移量。
    static final int
    ENDSUB
    中央目录（END）头部此磁盘上的条目数字段偏移量。
    static final int
    ENDTOT
    中央目录（END）头部总条目数字段偏移量。
    static final int
    EXTCRC
    额外本地（EXT）头部未压缩文件crc-32值字段偏移量。
    static final int
    EXTHDR
    额外本地（EXT）头部字节大小（包括签名）。
    static final int
    EXTLEN
    额外本地（EXT）头部未压缩大小字段偏移量。
    static final long
    EXTSIG
    额外本地（EXT）头部签名。
    static final int
    EXTSIZ
    额外本地（EXT）头部压缩大小字段偏移量。
    static final int
    LOCCRC
    本地文件（LOC）头部未压缩文件crc-32值字段偏移量。
    static final int
    LOCEXT
    本地文件（LOC）头部额外字段长度字段偏移量。
    static final int
    LOCFLG
    本地文件（LOC）头部通用位标志字段偏移量。
    static final int
    LOCHDR
    本地文件（LOC）头部字节大小（包括签名）。
    static final int
    LOCHOW
    本地文件（LOC）头部压缩方法字段偏移量。
    static final int
    LOCLEN
    本地文件（LOC）头部未压缩大小字段偏移量。
    static final int
    LOCNAM
    本地文件（LOC）头部文件名长度字段偏移量。
    static final long
    LOCSIG
    本地文件（LOC）头部签名。
    static final int
    LOCSIZ
    本地文件（LOC）头部压缩大小字段偏移量。
    static final int
    LOCTIM
    本地文件（LOC）头部修改时间字段偏移量。
    static final int
    LOCVER
    本地文件（LOC）头部需要提取的版本字段偏移量。
    static final String
    MANIFEST_NAME
    JAR清单文件名。

    Fields declared in class java.util.zip.ZipFile

    OPEN_DELETE, OPEN_READ

  • Constructor Summary

    Constructors
    Constructor
    Description
    JarFile(File file)
    创建一个新的JarFile以从指定的File对象中读取。
    JarFile(File file, boolean verify)
    创建一个新的JarFile以从指定的File对象中读取。
    JarFile(File file, boolean verify, int mode)
    创建一个新的JarFile以从指定的File对象中以指定模式读取。
    JarFile(File file, boolean verify, int mode, Runtime.Version version)
    创建一个新的JarFile对象，以指定的模式从指定的File对象中读取。
    JarFile(String name)
    创建一个新的JarFile对象，以指定的文件name中读取。
    JarFile(String name, boolean verify)
    创建一个新的JarFile对象，以指定的文件name中读取。

  • Method Summary

    Modifier and Type
    Method
    Description
    static Runtime.Version
    baseVersion()
    返回表示多版本jar文件的未版本化配置的版本。
    Enumeration<JarEntry>
    entries()
    返回jar文件条目的枚举。
    ZipEntry
    getEntry(String name)
    返回给定基本条目名称的ZipEntry，如果未找到则返回null。
    InputStream
    getInputStream(ZipEntry ze)
    返回用于读取指定zip文件条目内容的输入流。
    JarEntry
    getJarEntry(String name)
    返回给定基本条目名称的JarEntry，如果未找到则返回null。
    Manifest
    getManifest()
    返回jar文件清单，如果没有则返回null。
    final Runtime.Version
    getVersion()
    返回搜索版本化条目时使用的最大版本。
    final boolean
    isMultiRelease()
    指示此jar文件是否为多版本jar文件。
    static Runtime.Version
    runtimeVersion()
    返回表示多版本jar文件的有效运行时版本化配置的版本。
    Stream<JarEntry>
    stream()
    返回jar文件条目的有序Stream。
    Stream<JarEntry>
    versionedStream()
    返回版本化jar文件条目的Stream。

    Methods declared in class java.util.zip.ZipFile

    close, getComment, getName, size

    Methods declared in class java.lang.Object

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

  • Field Details

    • MANIFEST_NAME

      public static final String MANIFEST_NAME
      JAR清单文件名称。
      参见：

    • LOCSIG

      static final long LOCSIG
      本地文件（LOC）头签名。
      参见：

    • EXTSIG

      static final long EXTSIG
      额外本地（EXT）头签名。
      参见：

    • CENSIG

      static final long CENSIG
      中央目录（CEN）头签名。
      参见：

    • ENDSIG

      static final long ENDSIG
      中央目录结束（END）头签名。
      参见：

    • LOCHDR

      static final int LOCHDR
      本地文件（LOC）头大小（包括签名）。
      参见：

    • EXTHDR

      static final int EXTHDR
      额外本地（EXT）头大小（包括签名）。
      参见：

    • CENHDR

      static final int CENHDR
      中央目录（CEN）头大小（包括签名）。
      参见：

    • ENDHDR

      static final int ENDHDR
      中央目录结束（END）头大小（包括签名）。
      参见：

    • LOCVER

      static final int LOCVER
      本地文件（LOC）头版本需要提取字段偏移量。
      参见：

    • LOCFLG

      static final int LOCFLG
      本地文件（LOC）头通用位标志字段偏移量。
      参见：

    • LOCHOW

      static final int LOCHOW
      本地文件（LOC）头压缩方法字段偏移量。
      参见：

    • LOCTIM

      static final int LOCTIM
      本地文件（LOC）头修改时间字段偏移量。
      参见：

    • LOCCRC

      static final int LOCCRC
      本地文件（LOC）头未压缩文件crc-32值字段偏移量。
      参见：

    • LOCSIZ

      static final int LOCSIZ
      本地文件（LOC）头压缩大小字段偏移量。
      参见：

    • LOCLEN

      static final int LOCLEN
      本地文件（LOC）头未压缩大小字段偏移量。
      参见：

    • LOCNAM

      static final int LOCNAM
      本地文件（LOC）头文件名长度字段偏移量。
      参见：

    • LOCEXT

      static final int LOCEXT
      本地文件（LOC）头额外字段长度字段偏移量。
      参见：

    • EXTCRC

      static final int EXTCRC
      额外本地（EXT）头未压缩文件crc-32值字段偏移量。
      参见：

    • EXTSIZ

      static final int EXTSIZ
      额外本地（EXT）头压缩大小字段偏移量。
      参见：

    • EXTLEN

      static final int EXTLEN
      额外本地（EXT）头未压缩大小字段偏移量。
      参见：

    • CENVEM

      static final int CENVEM
      中央目录（CEN）头创建者版本字段偏移量。
      参见：

    • CENVER

      static final int CENVER
      中央目录（CEN）头提取所需版本字段偏移量。
      参见：

    • CENFLG

      static final int CENFLG
      中央目录（CEN）头加密、解密标志字段偏移量。
      参见：

    • CENHOW

      static final int CENHOW
      中央目录（CEN）头压缩方法字段偏移量。
      参见：

    • CENTIM

      static final int CENTIM
      中央目录（CEN）头修改时间字段偏移量。
      参见：

    • CENCRC

      static final int CENCRC
      中央目录（CEN）头未压缩文件crc-32值字段偏移量。
      参见：

    • CENSIZ

      static final int CENSIZ
      中央目录（CEN）头压缩大小字段偏移量。
      参见：

    • CENLEN

      static final int CENLEN
      中央目录（CEN）头未压缩大小字段偏移量。
      参见：

    • CENNAM

      static final int CENNAM
      中央目录（CEN）头文件名长度字段偏移量。
      参见：

    • CENEXT

      static final int CENEXT
      中央目录（CEN）头额外字段长度字段偏移量。
      参见：

    • CENCOM

      static final int CENCOM
      中央目录（CEN）头注释长度字段偏移量。
      参见：

    • CENDSK

      static final int CENDSK
      中央目录（CEN）头磁盘起始编号字段偏移量。
      参见：

    • CENATT

      static final int CENATT
      中央目录（CEN）头内部文件属性字段偏移量。
      参见：

    • CENATX

      static final int CENATX
      中央目录（CEN）头外部文件属性字段偏移量。
      参见:

    • CENOFF

      static final int CENOFF
      中央目录（CEN）头部LOC头部偏移字段偏移量。
      参见:

    • ENDSUB

      static final int ENDSUB
      中央目录结束（END）头部此磁盘上的条目数字段偏移量。
      参见:

    • ENDTOT

      static final int ENDTOT
      中央目录结束（END）头部总条目数字段偏移量。
      参见:

    • ENDSIZ

      static final int ENDSIZ
      中央目录结束（END）头部中央目录大小（以字节为单位）字段偏移量。
      参见:

    • ENDOFF

      static final int ENDOFF
      中央目录结束（END）头部第一个CEN头部的偏移量字段偏移量。
      参见:

    • ENDCOM

      static final int ENDCOM
      中央目录结束（END）头部zip文件注释长度字段偏移量。
      参见:

  • Constructor Details

    • JarFile

      public JarFile(String name) throws IOException
      创建一个新的JarFile以从指定文件name读取。如果已签名，则将验证JarFile。
      参数:
      name - 要打开以进行读取的jar文件的名称
      抛出:
      IOException - 如果发生I/O错误
      SecurityException - 如果安全管理器拒绝访问文件

    • JarFile

      public JarFile(String name, boolean verify) throws IOException
      创建一个新的JarFile以从指定文件name读取。
      参数:
      name - 要打开以进行读取的jar文件的名称
      verify - 是否验证已签名的jar文件。
      抛出:
      IOException - 如果发生I/O错误
      SecurityException - 如果安全管理器拒绝访问文件

    • JarFile

      public JarFile(File file) throws IOException
      创建一个新的JarFile以从指定的File对象读取。如果已签名，则将验证JarFile。
      参数:
      file - 要打开以进行读取的jar文件
      抛出:
      IOException - 如果发生I/O错误
      SecurityException - 如果安全管理器拒绝访问文件

    • JarFile

      public JarFile(File file, boolean verify) throws IOException
      创建一个新的JarFile以从指定的File对象读取。
      参数:
      file - 要打开以进行读取的jar文件
      verify - 是否验证已签名的jar文件。
      抛出:
      IOException - 如果发生I/O错误
      SecurityException - 如果安全管理器拒绝访问文件

    • JarFile

      public JarFile(File file, boolean verify, int mode) throws IOException
      创建一个新的JarFile以从指定的File对象以指定模式读取。模式参数必须是OPEN_READ或OPEN_READ | OPEN_DELETE之一。
      参数:
      file - 要打开以进行读取的jar文件
      verify - 是否验证已签名的jar文件。
      mode - 要打开文件的模式
      抛出:
      IOException - 如果发生I/O错误
      IllegalArgumentException - 如果mode参数无效
      SecurityException - 如果安全管理器拒绝访问文件
      自:
      1.3

    • JarFile

      public JarFile(File file, boolean verify, int mode, Runtime.Version version) throws IOException
      创建一个新的JarFile以从指定的File对象以指定模式读取。模式参数必须是OPEN_READ或OPEN_READ | OPEN_DELETE之一。将版本参数转换为规范形式后，用于配置JarFile以处理多版本jar文件。

      从版本参数派生的规范形式为Runtime.Version.parse(Integer.toString(n))，其中n为Math.max(version.feature(), JarFile.baseVersion().feature())。

      参数:
      file - 要打开以进行读取的jar文件
      verify - 是否验证已签名的jar文件。
      mode - 要打开文件的模式
      version - 指定多版本jar文件的发布版本
      抛出:
      IOException - 如果发生I/O错误
      IllegalArgumentException - 如果mode参数无效
      SecurityException - 如果安全管理器拒绝访问文件
      NullPointerException - 如果version为null
      自:
      9

  • Method Details

    • baseVersion

      public static Runtime.Version baseVersion()
      返回表示多版本jar文件的无版本配置的版本。
      返回:
      表示无版本配置的版本
      自:
      9

    • runtimeVersion

      public static Runtime.Version runtimeVersion()
      返回表示多版本jar文件的有效运行时版本化配置的版本。

      默认情况下，返回的Version的特性版本号将等于Runtime.version()的特性版本号。但是，如果设置了jdk.util.jar.version属性，则返回的Version将从该属性派生，并且特性版本号可能不相等。

      返回:
      表示运行时版本化配置的版本
      自:
      9

    • getVersion

      public final Runtime.Version getVersion()
      返回搜索版本化条目时使用的最大版本。

      如果此JarFile不是多版本jar文件或未配置为处理此类文件，则返回的版本将与从baseVersion()返回的版本相同。

      返回:
      最大版本
      自:
      9

    • isMultiRelease

      public final boolean isMultiRelease()
      指示此jar文件是否为多版本jar文件。
      返回:
      如果此JarFile是多版本jar文件，则为true
      自:
      9

    • getManifest

      public Manifest getManifest() throws IOException
      返回jar文件清单，如果没有则返回null。
      返回:
      jar文件清单，如果没有则返回null
      抛出:
      IllegalStateException - 如果jar文件已关闭可能会抛出
      IOException - 如果发生I/O错误

    • getJarEntry

      public JarEntry getJarEntry(String name)
      返回给定基本条目名称的JarEntry，如果未找到则返回null。

      如果此JarFile是多版本jar文件并已配置为处理此类文件，则将执行搜索以查找并返回与给定条目名称关联的最新版本条目的JarEntry。返回的JarEntry是与给定基本条目名称关联的版本化条目，该条目以字符串"META-INF/versions/{n}/"为前缀，其中n的最大值为存在条目的值。如果不存在这样的版本化条目，则返回基本条目的JarEntry，否则如果未找到任何条目，则返回null。版本n的初始值是由方法getVersion()返回的最大版本。

      实现要求:
      此实现调用getEntry(String)。
      参数:
      name - jar文件条目名称
      返回:
      给定条目名称的JarEntry，或版本化条目名称，如果未找到则返回null
      抛出:
      IllegalStateException - 如果jar文件已关闭可能会抛出
      参见:

    • getEntry

      public ZipEntry getEntry(String name)
      返回给定基本条目名称的ZipEntry，如果找不到则返回null。

      如果这个JarFile是一个多版本jar文件，并且已配置为按此方式处理，则将执行搜索以查找并返回与给定条目名称关联的最新版本条目的ZipEntry。返回的ZipEntry是与给定基本条目名称对应的版本化条目，前缀为字符串"META-INF/versions/{n}/"，其中n的值最大，对应存在的条目的最大值。如果这样的版本化条目不存在，则返回基本条目的ZipEntry，否则如果找不到任何条目，则返回null。版本n的初始值是由方法getVersion()返回的最大版本。

      覆盖：
      getEntry 在类 ZipFile中
      实现要求：
      即使没有相应的基本条目，此实现也可以返回请求名称的版本化条目。如果存在与之匹配的私有或包私有版本化条目，则可能会发生这种情况。如果子类覆盖此方法，请确保覆盖方法调用super.getEntry(name)以获取所有版本化条目。
      参数：
      name - jar文件条目名称
      返回：
      给定条目名称的ZipEntry或版本化条目名称或如果找不到则返回null
      抛出：
      IllegalStateException - 如果jar文件已关闭可能会抛出
      参见：

    • entries

      public Enumeration<JarEntry> entries()
      返回jar文件条目的枚举。
      覆盖：
      entries 在类 ZipFile中
      返回：
      jar文件条目的枚举
      抛出：
      IllegalStateException - 如果jar文件已关闭可能会抛出

    • stream

      public Stream<JarEntry> stream()
      返回jar文件条目的有序Stream。条目在Stream中按照它们在jar文件的中央目录中出现的顺序出现。
      覆盖：
      stream 在类 ZipFile中
      返回：
      在此jar文件中条目的有序Stream
      抛出：
      IllegalStateException - 如果jar文件已关闭可能会抛出
      自：
      1.8

    • versionedStream

      public Stream<JarEntry> versionedStream()
      返回版本化jar文件条目的Stream。

      如果这个JarFile是一个多版本jar文件，并且已配置为按此方式处理，则流中的条目是与相应基本条目名称关联的最新版本化条目。最新版本化条目的最大版本是由getVersion()返回的版本。返回的流可能包括仅存在作为版本化条目的条目。如果jar文件不是多版本jar文件或者JarFile未配置为处理多版本jar文件，则此方法返回与stream()返回的相同流。

      返回：
      版本化条目的流
      自：
      10

    • getInputStream

      public InputStream getInputStream(ZipEntry ze) throws IOException
      返回用于读取指定zip文件条目内容的输入流。
      覆盖：
      getInputStream 在类 ZipFile中
      API注释：
      此方法返回的InputStream可以包装一个InflaterInputStream，其read(byte[], int, int)方法可以修改输出缓冲区的任何元素。
      参数：
      ze - zip文件条目
      返回：
      用于读取指定zip文件条目内容的输入流，如果zip文件条目不存在于jar文件中则返回null
      抛出：
      ZipException - 如果发生zip文件格式错误
      IOException - 如果发生I/O错误
      SecurityException - 如果任何jar文件条目签名不正确
      IllegalStateException - 如果jar文件已关闭可能会抛出