< prev index next >

src/java.base/share/specs/jar/jar.md

Print this page
rev 17080 : [mq]: mr-jar-orig
rev 17081 : [mq]: JDK-8150681-jar-spec-markdown-with-mr-jar
   1 # JAR File Specification




















   2 




   3 
   4 Contents
   5 --------
   6 
   7 -   [Introduction](#Intro)
   8 -   [Modular JAR files](#Modular)


   9 -   [The META-INF directory](#The_META-INF_directory)
  10 -   [Name-Value pairs and Sections](#Name-Value_pairs_and_Sections)
  11 -   [JAR Manifest](#JAR_Manifest)
  12     -   [Overview](#Manifest-Overview)
  13     -   [Manifest Specification](#Manifest_Specification)
  14     -   [Main Attributes](#Main_Attributes)
  15     -   [Per-Entry Attributes](#Per-Entry_Attributes)
  16 -   [Signed JAR file](#Signed_JAR_File)
  17     -   [Overview](#SignedJar-Overview)
  18     -   [Signature File](#Signature_File)
  19         -   [Signature validation](#Signature_Validation)
  20         -   [The Magic Attribute](#The_Magic_Attribute)
  21     -   [Digital Signatures](#Digital_Signatures)
  22 -   [Notes on Manifest and Signature
  23     Files](#Notes_on_Manifest_and_Signature_Files)
  24 -   [JAR Index](#JAR_Index)
  25     -   [Overview](#Overview)
  26     -   [Index File Specification](#Index_File_Specification)
  27     -   [Backward Compatibility](#Backward_Compatibility)
  28 -   [Service Provider](#Service_Provider)


  31     -   [Example](#Example)
  32 -   [Class-Path attribute](#classpath)
  33 -   [Package Sealing](#sealing)
  34 -   [API Details](#API_Details)
  35 -   [See Also](#See_Also)
  36 
  37 []{#Intro}Introduction
  38 ----------------------
  39 
  40 JAR file is a file format based on the popular ZIP file format and is
  41 used for aggregating many files into one. A JAR file is essentially a
  42 zip file that contains an optional META-INF directory. A JAR file can be
  43 created by the command-line [jar](https://docs.oracle.com/javase/9/tools/jar.htm#JSWOR614) tool, or
  44 by using the [`java.util.jar`](../../api/java/util/jar/package-summary.html) API in the Java platform. There is no
  45 restriction on the name of a JAR file, it can be any legal file name on
  46 a particular platform.
  47 
  48 []{#Modular}Modular JAR files
  49 -----------------------------
  50 
  51 JAR files that are deployed on the module path, as opposed to the class
  52 path, are modules. If the JAR file has a `module-info.class` in the
  53 top-level directory then it is a *Modular JAR* file. The
  54 `module-info.class` file is the binary form of the module declaration.
  55 If the JAR file does not have a `module-info.class` in the top-level
  56 directory then it is considered to be an *automatic module*. The module
  57 name for an automatic module is derived from the name of the JAR file
  58 and its exported packages are determined by the `.class` files in the




















































































  59 JAR file.
  60 
  61 JAR files that are deployed as modules declare (explicitly or
  62 implicitly) their dependences and may declare service providers too. The
  63 [JAR Manifest](#JAR_Manifest) is ignored. On the other hand, JAR files
  64 on the class path use the [META-INF](#The_META-INF_directory) directory
  65 for security, versioning, or service configuration.

























  66 
  67 []{#The_META-INF_directory}The META-INF directory
  68 -------------------------------------------------
  69 
  70 The following files/directories in the META-INF directory are recognized
  71 and interpreted by the Java 2 Platform to configure applications, class
  72 loaders and services:
  73 
  74 -   `MANIFEST.MF`
  75 
  76 The manifest file that is used to define package related data.
  77 
  78 -   `INDEX.LIST`
  79 
  80 This file is generated by the new "`-i"` option of the jar tool, which
  81 contains location information for packages defined in an application.
  82 It is part of the JarIndex implementation and used by class loaders to
  83 speed up their class loading process.
  84 
  85 -   `x.SF`
  86 
  87 The signature file for the JAR file. 'x' stands for the base file name.
  88 
  89 -   `x.DSA`
  90 
  91 The signature block file associated with the signature file with the
  92 same base file name. This file stores the digital signature of the
  93 corresponding signature file.
  94 
  95 -   `services/`
  96 
  97 This directory stores all the service provider configuration files.
  98 





  99 []{#Name-Value_pairs_and_Sections}Name-Value pairs and Sections
 100 ---------------------------------------------------------------
 101 
 102 Before we go to the details of the contents of the individual
 103 configuration files, some format convention needs to be defined. In most
 104 cases, information contained within the manifest file and signature
 105 files is represented as so-called "name: value" pairs inspired by the
 106 RFC822 standard. We also call these pairs headers or attributes.
 107 
 108 Groups of name-value pairs are known as a "section". Sections are
 109 separated from other sections by empty lines.
 110 
 111 Binary data of any form is represented as base64. Continuations are
 112 required for binary data which causes line length to exceed 72 bytes.
 113 Examples of binary data are digests and signatures.
 114 
 115 Implementations shall support header values of up to 65535 bytes.
 116 
 117 All the specifications in this document use the same grammar in which
 118 terminal symbols are shown in fixed width font and non-terminal symbols


 198 
 199 ### []{#Main_Attributes}Main Attributes
 200 
 201 Main attributes are the attributes that are present in the main section
 202 of the manifest. They fall into the following different groups:
 203 
 204 -   general main attributes
 205     -   Manifest-Version: Defines the manifest file version. The value
 206         is a legitimate version number, as described in the above spec.
 207     -   Created-By: Defines the version and the vendor of the java
 208         implementation on top of which this manifest file is generated.
 209         This attribute is generated by the `jar` tool.
 210     -   Signature-Version: Defines the signature version of the jar
 211         file. The value should be a valid *version-number* string.
 212     -   Class-Path: The value of this attribute specifies the relative
 213         URLs of the libraries that this application needs. URLs are
 214         separated by one or more spaces. The application class loader
 215         uses the value of this attribute to construct its internal
 216         search path. See [Class-Path Attribute](#classpath) section for
 217         details.





 218 -   attribute defined for stand-alone applications: This attribute is
 219     used by stand-alone applications that are bundled into executable
 220     jar files which can be invoked by the java runtime directly by
 221     running "`java -jar x.jar`".
 222     -   Main-Class: The value of this attribute is the class name of the
 223         main application class which the launcher will load at startup
 224         time. The value must *not* have the `.class` extension appended
 225         to the class name.
 226     -   Launcher-Agent-Class: If this attribute is present then its
 227         value is the class name of a *java agent* that is started before
 228         the application main method is invoked. This attribute can be
 229         used for cases where a java agent is packaged in the same
 230         executable JAR file as the application. The agent class defines
 231         a public static method name `agentmain` in one of the two forms
 232         specified in the `java.lang.instrument` package description.
 233         Additional attributes (such as `Can-Retransform-Classes`) can be
 234         used to indicate capabilities needed by the agent.
 235 -   attributes defined for package
 236     [versioning](../versioning/index.html) and [sealing](#sealing)
 237     information: The value of these attributes apply to all the packages


 851 
 852 The unnamed package is not sealable, so classes that are to be sealed
 853 must be placed in their own packages.
 854 
 855 []{#API_Details}API Details
 856 ---------------------------
 857 
 858 Package [java.util.jar](../../../api/java/util/jar/package-summary.html)
 859 
 860 []{#See_Also}See Also
 861 ---------------------
 862 
 863 Package
 864 [java.security](../../../api/java/security/package-summary.html)\
 865 Package [java.util.zip](../../../api/java/util/zip/package-summary.html)
 866 
 867 ---------------------------------------
 868 
 869 <meta charset="utf-8" />
 870 
 871 [Copyright &copy;](../../../legal/copyright.html)
 872 1993, 2017, Oracle and/or its affiliates. All rights reserved.
   1 ---
   2 # Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
   3 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4 #
   5 # This code is free software; you can redistribute it and/or modify it
   6 # under the terms of the GNU General Public License version 2 only, as
   7 # published by the Free Software Foundation.
   8 #
   9 # This code is distributed in the hope that it will be useful, but WITHOUT
  10 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12 # version 2 for more details (a copy is included in the LICENSE file that
  13 # accompanied this code).
  14 #
  15 # You should have received a copy of the GNU General Public License version
  16 # 2 along with this work; if not, write to the Free Software Foundation,
  17 # Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  18 #
  19 # Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  20 # or visit www.oracle.com if you need additional information or have any
  21 # questions.
  22 
  23 title: 'JAR File Specification'
  24 ---
  25 
  26 -------------------------------------------------------------------------------
  27 
  28 Contents
  29 --------
  30 
  31 -   [Introduction](#Intro)
  32 -   [Modular JAR files](#Modular)
  33 -   [Multi-release JAR files](#Multi-release)
  34     -   [Modular multi-release JAR files](#Modular-multi-release)
  35 -   [The META-INF directory](#The_META-INF_directory)
  36 -   [Name-Value pairs and Sections](#Name-Value_pairs_and_Sections)
  37 -   [JAR Manifest](#JAR_Manifest)
  38     -   [Overview](#Manifest-Overview)
  39     -   [Manifest Specification](#Manifest_Specification)
  40     -   [Main Attributes](#Main_Attributes)
  41     -   [Per-Entry Attributes](#Per-Entry_Attributes)
  42 -   [Signed JAR file](#Signed_JAR_File)
  43     -   [Overview](#SignedJar-Overview)
  44     -   [Signature File](#Signature_File)
  45         -   [Signature validation](#Signature_Validation)
  46         -   [The Magic Attribute](#The_Magic_Attribute)
  47     -   [Digital Signatures](#Digital_Signatures)
  48 -   [Notes on Manifest and Signature
  49     Files](#Notes_on_Manifest_and_Signature_Files)
  50 -   [JAR Index](#JAR_Index)
  51     -   [Overview](#Overview)
  52     -   [Index File Specification](#Index_File_Specification)
  53     -   [Backward Compatibility](#Backward_Compatibility)
  54 -   [Service Provider](#Service_Provider)


  57     -   [Example](#Example)
  58 -   [Class-Path attribute](#classpath)
  59 -   [Package Sealing](#sealing)
  60 -   [API Details](#API_Details)
  61 -   [See Also](#See_Also)
  62 
  63 []{#Intro}Introduction
  64 ----------------------
  65 
  66 JAR file is a file format based on the popular ZIP file format and is
  67 used for aggregating many files into one. A JAR file is essentially a
  68 zip file that contains an optional META-INF directory. A JAR file can be
  69 created by the command-line [jar](https://docs.oracle.com/javase/9/tools/jar.htm#JSWOR614) tool, or
  70 by using the [`java.util.jar`](../../api/java/util/jar/package-summary.html) API in the Java platform. There is no
  71 restriction on the name of a JAR file, it can be any legal file name on
  72 a particular platform.
  73 
  74 []{#Modular}Modular JAR files
  75 -----------------------------
  76 
  77 A modular JAR file is a JAR file that has a module descriptor,
  78 `module-info.class`, in the top-level directory (or root) directory. The
  79 module descriptor is the binary form of a module declaration. (Note the section
  80 on [multi-release JAR files](#Multi-release) further refines the definition of
  81 modular JAR files.)
  82 
  83 A modular JAR file deployed on the module path, as opposed to the class path, is
  84 an *explicit* module.  Dependences and service providers are declared in the
  85 module descriptor.  The [JAR Manifest](#JAR_Manifest) is ignored as is any
  86 service configuration under the [`META-INF`](#The_META-INF_directory) directory.
  87 However, if the modular JAR file is deployed on the class path then it behaves
  88 as if a non-modular JAR file and the JAR Manifest and configuration under
  89 the `META-INF` directory are not ignored.
  90 
  91 A non-modular JAR file deployed on the module path is an *automatic module*,
  92 where a module declaration is synthesized from the JAR file name and
  93 its contents.  For further details see the specification on the method
  94 [java.lang.module.ModuleFinder.of](../../../api/java/lang/module/ModuleFinder.html#of-java.nio.file.Path...-).
  95 
  96 []{#Multi-release}Multi-release JAR files
  97 -----------------------------------------
  98 
  99 A multi-release JAR file allows for a single JAR file to support multiple
 100 major versions of Java platform releases.  For example, a multi-release JAR file
 101 can depend on both the Java 8 and Java 9 major platform releases, where some
 102 class files depend on APIs in Java 8 and other class files depend on APIs in
 103 Java 9.
 104 This enables library and framework developers to decouple the use of APIs in a
 105 specific major version of a Java platform release from the requirement that all
 106 their users migrate to that major version.  Library and framework developers can
 107 gradually migrate to and support new Java features while still supporting the
 108 old features.
 109 
 110 A multi-release JAR file is identified by the main attribute:
 111 
 112     Multi-Release: true
 113 
 114 declared in the main section of the [JAR Manifest](#JAR_Manifest).
 115 
 116 Classes and resource files dependent on a major version, 9 or greater, of a
 117 Java platform release may be located under a *versioned directory* instead of
 118 under the top-level (or root) directory.  The versioned directory
 119 is located under the [the META-INF directory](#The_META-INF_directory) and is
 120 of the form:
 121 
 122     META-INF/versions/N
 123 
 124 where N is the string representation of the major version number of a Java
 125 platform release.  Specifically `N` must conform to the specification:
 126 
 127 --------------------------------    --------------------------------------------------------------------------------
 128 *N:*                                *`{1-9}` `{0-9}`\**
 129 --------------------------------    --------------------------------------------------------------------------------
 130 
 131 Any versioned directory whose value of `N` is less than `9` is ignored as is
 132 a string representation of `N` that does not conform to the above specification.
 133 
 134 A class file under a versioned directory, of version `N` say, in a multi-release
 135 JAR must have a class file version less than or equal to the class file
 136 version associated with `N`th major version of a Java platform release.
 137 If the class of the class file is public or protected then that class must
 138 *preside over* a class of the same fully qualified name and access modifier
 139 whose class file is present under the top-level directory.  By logical extension
 140 this applies to a class of a class file, if present, under a versioned directory
 141 whose version is less than `N`.
 142 
 143 If a multi-release JAR file is deployed on the class path or module path
 144 (as an automatic module or an explicit [multi-release module](#Modular-multi-release))
 145 of major version `N` of a Java platform release runtime, then a class loader
 146 loading classes from that JAR file will first search for class files under the
 147 `N`th versioned directory, then prior versioned directories in descending order
 148 (if present), down to a lower major version bound of `9`, and finally under the
 149 top-level directory.
 150 
 151 The public API exported by the classes in a multi-release JAR file must be
 152 *exactly* the same across versions, hence at a minimum why versioned public or
 153 protected classes for class files under a versioned directory must preside over
 154 classes for class files under the top-level directory.  It is difficult and
 155 costly to perform extensive API verification checks as such tooling, such as the
 156 `jar` tool, is not required to perform extensive verification and a Java runtime
 157 is not required to perform any verification.  A future release of this
 158 specification may relax the exact same API constraint to support careful
 159 evolution.
 160 
 161 Resources under the `META-INF` directory cannot be versioned (such as for
 162 service configuration).
 163 
 164 A multi-release JAR file can be signed.
 165 
 166 Multi-release JAR files are not supported by the boot class loader of a Java
 167 runtime.  If a multi-release JAR file is appended to the boot class path (with
 168 the `-Xbootclasspath/a` option) then the JAR is treated as if it is an ordinary
 169 JAR file.
 170 
 171 ### []{#Modular-multi-release}Modular multi-release JAR files
 172 
 173 A modular multi-release JAR file is a multi-release JAR file that has a
 174 module descriptor, `module-info.class`, in the top-level directory (as for
 175 a [modular](#Modular) JAR file), or directly in a versioned directory.
 176 
 177 A public or protected class in a non-exported package (that is not declared as
 178 exported in the module descriptor) need not preside over a class of the same
 179 fully qualified name and access modifier whose class file is present under
 180 the top-level directory.
 181 
 182 A module descriptor is generally treated no differently to any other class or
 183 resource file.  A module descriptor may be present under a versioned area but
 184 not present under the top-level directory.  This ensures, for example, only Java
 185 8 versioned classes can be present under the top-level directory while Java 9
 186 versioned classes (including, or perhaps only, the module descriptor) can be
 187 present under the `9` versioned directory.
 188 
 189 Any versioned module descriptor that presides over a lesser versioned module
 190 descriptor or that at the top-level, `M` say, must be identical to `M`, with two
 191 exceptions:
 192 
 193 1. the presiding versioned descriptor can have different non-`transitive`
 194    `requires` clauses of `java.*` and `jdk.*` modules; and
 195 2. the presiding versioned descriptor can have different `uses` clauses, even of
 196    service types defined outside of `java.*` and `jdk.*` modules.
 197 
 198 Tooling, such as the `jar` tool, should perform such verification of versioned
 199 module descriptors but a Java runtime is not required to perform any
 200 verification.
 201 
 202 []{#The_META-INF_directory}The META-INF directory
 203 -------------------------------------------------
 204 
 205 The following files/directories in the META-INF directory are recognized
 206 and interpreted by the Java 2 Platform to configure applications, class
 207 loaders and services:
 208 
 209 -   `MANIFEST.MF`
 210 
 211 The manifest file that is used to define package related data.
 212 
 213 -   `INDEX.LIST`
 214 
 215 This file is generated by the new "`-i"` option of the jar tool, which
 216 contains location information for packages defined in an application.
 217 It is part of the JarIndex implementation and used by class loaders to
 218 speed up their class loading process.
 219 
 220 -   `x.SF`
 221 
 222 The signature file for the JAR file. 'x' stands for the base file name.
 223 
 224 -   `x.DSA`
 225 
 226 The signature block file associated with the signature file with the
 227 same base file name. This file stores the digital signature of the
 228 corresponding signature file.
 229 
 230 -   `services/`
 231 
 232 This directory stores all the service provider configuration files.
 233 
 234 -   `versions/`
 235 
 236 This directory contains underneath it versioned class and resource files
 237 for a [multi-release](#Multi-release) JAR file.
 238 
 239 []{#Name-Value_pairs_and_Sections}Name-Value pairs and Sections
 240 ---------------------------------------------------------------
 241 
 242 Before we go to the details of the contents of the individual
 243 configuration files, some format convention needs to be defined. In most
 244 cases, information contained within the manifest file and signature
 245 files is represented as so-called "name: value" pairs inspired by the
 246 RFC822 standard. We also call these pairs headers or attributes.
 247 
 248 Groups of name-value pairs are known as a "section". Sections are
 249 separated from other sections by empty lines.
 250 
 251 Binary data of any form is represented as base64. Continuations are
 252 required for binary data which causes line length to exceed 72 bytes.
 253 Examples of binary data are digests and signatures.
 254 
 255 Implementations shall support header values of up to 65535 bytes.
 256 
 257 All the specifications in this document use the same grammar in which
 258 terminal symbols are shown in fixed width font and non-terminal symbols


 338 
 339 ### []{#Main_Attributes}Main Attributes
 340 
 341 Main attributes are the attributes that are present in the main section
 342 of the manifest. They fall into the following different groups:
 343 
 344 -   general main attributes
 345     -   Manifest-Version: Defines the manifest file version. The value
 346         is a legitimate version number, as described in the above spec.
 347     -   Created-By: Defines the version and the vendor of the java
 348         implementation on top of which this manifest file is generated.
 349         This attribute is generated by the `jar` tool.
 350     -   Signature-Version: Defines the signature version of the jar
 351         file. The value should be a valid *version-number* string.
 352     -   Class-Path: The value of this attribute specifies the relative
 353         URLs of the libraries that this application needs. URLs are
 354         separated by one or more spaces. The application class loader
 355         uses the value of this attribute to construct its internal
 356         search path. See [Class-Path Attribute](#classpath) section for
 357         details.
 358     -   Multi-Release: This attribute defines whether this JAR file is a
 359         [multi-release](#Modular-multi-release) JAR file. If the value is "true"
 360         , case is ignored, then the JAR file will be processed by the Java
 361         runtime and tooling as a multi-release JAR file.  Otherwise, if the
 362         value is anything other than "true" then this attribute is ignored.
 363 -   attribute defined for stand-alone applications: This attribute is
 364     used by stand-alone applications that are bundled into executable
 365     jar files which can be invoked by the java runtime directly by
 366     running "`java -jar x.jar`".
 367     -   Main-Class: The value of this attribute is the class name of the
 368         main application class which the launcher will load at startup
 369         time. The value must *not* have the `.class` extension appended
 370         to the class name.
 371     -   Launcher-Agent-Class: If this attribute is present then its
 372         value is the class name of a *java agent* that is started before
 373         the application main method is invoked. This attribute can be
 374         used for cases where a java agent is packaged in the same
 375         executable JAR file as the application. The agent class defines
 376         a public static method name `agentmain` in one of the two forms
 377         specified in the `java.lang.instrument` package description.
 378         Additional attributes (such as `Can-Retransform-Classes`) can be
 379         used to indicate capabilities needed by the agent.
 380 -   attributes defined for package
 381     [versioning](../versioning/index.html) and [sealing](#sealing)
 382     information: The value of these attributes apply to all the packages


 996 
 997 The unnamed package is not sealable, so classes that are to be sealed
 998 must be placed in their own packages.
 999 
1000 []{#API_Details}API Details
1001 ---------------------------
1002 
1003 Package [java.util.jar](../../../api/java/util/jar/package-summary.html)
1004 
1005 []{#See_Also}See Also
1006 ---------------------
1007 
1008 Package
1009 [java.security](../../../api/java/security/package-summary.html)\
1010 Package [java.util.zip](../../../api/java/util/zip/package-summary.html)
1011 
1012 ---------------------------------------
1013 
1014 <meta charset="utf-8" />
1015 
1016 *[Copyright](../../../legal/SMICopyright.html) &copy; 1993, 2017, Oracle
1017 and/or its affiliates. All rights reserved.*
< prev index next >