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 ©](../../../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) © 1993, 2017, Oracle
1017 and/or its affiliates. All rights reserved.*
|