モジュール java.base
パッケージ 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ファイルは、main属性"Multi-Release"のマニフェストを含むjarファイルです。baseエントリのセットであり、その一部は、jarファイルのpublicインタフェースを構成するpublicメソッドまたはprotectedメソッドを持つpublicクラスであり、"META-INF/versions"ディレクトリのサブディレクトリに含まれるバージョニングされたエントリのセットです。 バージョン管理されたエントリは、Javaプラットフォームのメジャー・バージョンによってパーティション化されます。 バージョンn、8 < nがMETA-INF/versions/{n}"ディレクトリにあるバージョニング済エントリは、ベース・エントリと、バージョン番号i (8 < i < n)のエントリをオーバーライドします。

    デフォルトでは、マルチリリースjarファイルのJarFileは、プレーン(バージョニングされていない)jarファイルであるかのようにマルチリリースjarファイルを処理するように構成されており、このようなエントリ名は最大で1つのベース・エントリに関連付けられています。 JarFileは、JarFile(File, boolean, int, Runtime.Version)コンストラクタを使用してJarFileを作成することで、マルチリリースjarファイルを処理するように構成できます。 Runtime.Versionオブジェクトは、バージョニングされたエントリの検索時に使用される最大バージョンを設定します。 設定されている場合、エントリ名は最大1つの基本エントリと、0個以上のバージョン管理されたエントリに対応できます。 バージョンが最大バージョン以下である最新バージョン・エントリにエントリ名を関連付けるには、検索が必要です(getEntry(String)を参照)。

    JarFileを利用してJarFileエントリの内容からクラスをロードするクラス・ローダーは、最後の引数に割り当てられた値Runtime.version()を持つJarFile(File, boolean, int, Runtime.Version)コンストラクタを呼び出して、JarFileを構築する必要があります。 これにより、実行中のJVMのメジャー・バージョンと互換性のあるクラスが、マルチリリースjarファイルからロードされるようになります。

    シグネチャ付きjarファイル・ファイルを開くときにverifyフラグがオンになっている場合、そのjarエントリの内容は、path nameに関連付けられているマニフェスト内に埋め込まれたシグネチャに対して検証されます。 複数文字のjarファイルの場合、バージョニングされたエントリの内容はそのシグネチャに対してverfieidとなり、JarEntry.getCodeSigners()は独自のシグネチャ者を戻します。 検証プロセスには、署名者の証明書の検証は含まれていないことに注意してください。 呼出し側は、JarEntry.getCodeSigners()の戻り値を検査して、シグネチャを信頼できるかどうかをさらに判断する必要があります。

    ほかで指定がない場合、null引数をコンストラクタまたはこのクラスのメソッドへ渡すと、NullPointerExceptionがスローされます。

    実装上のノート:
    APIを使用してJarFileを構成できない場合(コンパイル済アプリケーションまたはライブラリの構成をオーバーライドする場合など)、2つのSystemプロパティを使用できます。
    • jdk.util.jar.versionには、負でない整数<= Runtime.version().feature()のString表現の値を割り当てることができます。 この値は、有効なランタイム・バージョンを、Runtime.version().feature()を評価して取得したデフォルト値以外のものに設定するために使用されます。 有効なランタイム・バージョンは、最後の引数の値がJarFile.runtimeVersion()の場合にJarFile(File, boolean, int, Runtime.Version)コンストラクタが使用するバージョンです。
    • jdk.util.jar.enableMultiReleaseには、3つのString値true、falseまたはforceのいずれかを割り当てることができます。 値 true (デフォルト値)は、マルチリリースjarファイル処理を有効にします。 値 falseは、マルチリリースjar処理を無効にし、「マルチリリース」マニフェスト属性を無視し、マルチリリースjarファイル内のバージョン管理されたディレクトリが存在する場合はそれを無視します。 さらに、メソッドisMultiRelease()はfalseを返します。 値forceを指定すると、作成後にJarFileが実行時のバージョニングに初期化されます。 これは事実上、(new JarFile(File, boolean, int, JarFile.runtimeVersion())というコードと同じことを行います。
    導入されたバージョン:
    1.2
    関連項目:
    Manifest, ZipFile, JarEntry

    • コンストラクタの詳細

      • JarFile

        public JarFile​(String name)
        throws IOException
        指定されたファイルnameから読み込む新しいJarFileを作成します。 JarFileが署名されているかどうかが確認されます。
        パラメータ:
        name - 読込みのために開くjarファイルの名前
        例外:
        IOException - 入出力エラーが発生した場合
        SecurityException - ファイルへのアクセスがSecurityManagerによって拒否された場合

      • JarFile

        public JarFile​(String name,
               boolean verify)
        throws IOException
        指定されたファイルnameから読み込む新しいJarFileを作成します。
        パラメータ:
        name - 読込みのために開くjarファイルの名前
        verify - jarファイルが署名されていることを確認するかどうか。
        例外:
        IOException - 入出力エラーが発生した場合
        SecurityException - ファイルへのアクセスがSecurityManagerによって拒否された場合

      • JarFile

        public JarFile​(File file)
        throws IOException
        指定されたFileオブジェクトから読み込む新しいJarFileを作成します。 JarFileが署名されているかどうかが確認されます。
        パラメータ:
        file - 読込みのために開かれるjarファイル
        例外:
        IOException - 入出力エラーが発生した場合
        SecurityException - ファイルへのアクセスがSecurityManagerによって拒否された場合

      • JarFile

        public JarFile​(File file,
               boolean verify)
        throws IOException
        指定されたFileオブジェクトから読み込む新しいJarFileを作成します。
        パラメータ:
        file - 読込みのために開かれるjarファイル
        verify - jarファイルが署名されていることを確認するかどうか。
        例外:
        IOException - 入出力エラーが発生した場合
        SecurityException - ファイルへのアクセスがSecurityManagerによって拒否された場合。

      • JarFile

        public JarFile​(File file,
               boolean verify,
               int mode)
        throws IOException
        指定されたモードで指定のFileオブジェクトから読み込む新しいJarFileを作成します。 モード引数は、OPEN_READまたはOPEN_READ|OPEN_DELETEである必要があります。
        パラメータ:
        file - 読込みのために開かれるjarファイル
        verify - jarファイルが署名されていることを確認するかどうか。
        mode - ファイルが開かれるモード
        例外:
        IOException - 入出力エラーが発生した場合
        IllegalArgumentException - mode引数が無効な場合
        SecurityException - ファイルへのアクセスがSecurityManagerによって拒否された場合
        導入されたバージョン:
        1.3

      • JarFile

        public JarFile​(File file,
               boolean verify,
               int mode,
               Runtime.Version version)
        throws IOException
        指定されたモードで指定のFileオブジェクトから読み込む新しいJarFileを作成します。 モード引数は、OPEN_READまたはOPEN_READ|OPEN_DELETEである必要があります。 version引数は、標準形式に変換された後、マルチリリースjarファイルを処理するためのJarFileの構成に使用されます。

        バージョン・パラメータから導出された正規形はRuntime.Version.parse(Integer.toString(n))で、nはMath.max(version.feature(), JarFile.baseVersion().feature())です。

        パラメータ:
        file - 読込みのために開かれるjarファイル
        verify - jarファイルが署名されていることを確認するかどうか。
        mode - ファイルが開かれるモード
        version - マルチリリースjarファイルのリリース・バージョンを指定します。
        例外:
        IOException - 入出力エラーが発生した場合
        IllegalArgumentException - mode引数が無効な場合
        SecurityException - ファイルへのアクセスがSecurityManagerによって拒否された場合
        NullPointerException - versionがnullの場合
        導入されたバージョン:
        9

    • メソッドの詳細

      • 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 - 入出力エラーが発生した場合

      • getJarEntry

        public JarEntry getJarEntry​(String name)
        指定されたベース・エントリ名のJarEntry、または見つからない場合はnullを返します。

        このJarFileがマルチリリースjarファイルであり、そのように処理されるように構成されている場合、検索が実行され、指定されたエントリ名に関連付けられた最新バージョン・エントリであるJarEntryが検索されて返されます。 戻されるJarEntryは、エントリが存在するnの最大値について、文字列"META-INF/versions/{n}/"の接頭辞が付いた指定されたベース・エントリ名に対応するバージョニングされたエントリです。 このようなバージョニングされたエントリが存在しない場合は、ベース・エントリのJarEntryが戻されます。存在しない場合は、エントリが見つからない場合はnullが返されます。 バージョンnの初期値は、メソッドgetVersion()によって返される最大バージョンです。

        実装要件:
        この実装は、getEntry(String)を呼び出します。
        パラメータ:
        name - jarファイルのエントリ名
        戻り値:
        指定されたエントリ名のJarEntry、バージョニングされたエントリ名、または見つからない場合はnull
        例外:
        IllegalStateException - jarファイルが閉じられている場合に、スローされることがある
        関連項目:
        JarEntry

      • getEntry

        public ZipEntry getEntry​(String name)
        指定されたベース・エントリ名のZipEntry、または見つからない場合はnullを返します。

        このJarFileがマルチリリースjarファイルであり、そのように処理されるように構成されている場合、検索が実行され、指定されたエントリ名に関連付けられた最新バージョン・エントリであるZipEntryが検索されて返されます。 戻されるZipEntryは、エントリが存在するnの最大値について、文字列"META-INF/versions/{n}/"の接頭辞が付いた指定されたベース・エントリ名に対応するバージョニングされたエントリです。 このようなバージョニングされたエントリが存在しない場合は、ベース・エントリのZipEntryが戻されます。存在しない場合は、エントリが見つからない場合はnullが返されます。 バージョンnの初期値は、メソッドgetVersion()によって返される最大バージョンです。

        オーバーライド:
        getEntry、クラスZipFile
        実装要件:
        この実装は、対応するベース・エントリがない場合でも、要求された名前のバージョン付きエントリを返すことがあります。 これは、一致するプライベートまたはパッケージプライベートのバージョン付きエントリがある場合に発生することがあります。 サブクラスがこのメソッドをオーバーライドする場合は、オーバーライド・メソッドがsuper.getEntry(name)を呼び出して、すべてのバージョニング済エントリを取得するようにしてください。
        パラメータ:
        name - jarファイルのエントリ名
        戻り値:
        指定されたエントリ名またはバージョニングされたエントリ名のZipEntry、または見つからない場合はnull
        例外:
        IllegalStateException - jarファイルが閉じられている場合に、スローされることがある
        関連項目:
        ZipEntry

      • entries

        public Enumeration<JarEntry> entries()
        jarファイル・エントリの列挙を返します。
        オーバーライド:
        entries、クラスZipFile
        戻り値:
        jarファイル・エントリの列挙
        例外:
        IllegalStateException - jarファイルが閉じられている場合に、スローされることがある

      • stream

        public Stream<JarEntry> stream()
        jarファイル・エントリに対して順序付けられたStreamを返します。 エントリは、jarファイルの中央ディレクトリに表示される順序でStreamに表示されます。
        オーバーライド:
        クラスZipFileのstream
        戻り値:
        この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
        パラメータ:
        ze - ZIPファイル・エントリ
        戻り値:
        指定されたzipファイル・エントリの内容を読み取るための、入力ストリーム
        例外:
        ZipException - zipファイル形式エラーが発生した場合
        IOException - 入出力エラーが発生した場合
        SecurityException - jarファイル・エントリが誤って署名された場合。
        IllegalStateException - jarファイルが閉じられている場合に、スローされることがある