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)
29 - [Overview](#Service_Provider_Overview)
30 - [Provider Configuration File](#Provider_Configuration_File)
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
119 are shown in italic type face.
120
121 ### []{#Section-Specification}Specification:
122
123 ------------------------ ------------------------------------------------------
124 *section:* *\*header +newline*
125 *nonempty-section:* *+header +newline*
126 *newline:* `CR LF | LF | CR` \(*not followed by* `LF`\)
127 *header:* *name* `:` *value*
128 *name:* *alphanum \*headerchar*
129 *value:* SPACE \**otherchar newline \*continuation*
130 *continuation:* SPACE *\*otherchar newline*
131 *alphanum:* {`A-Z`} | {`a-z`} | {`0-9`}
132 *headerchar:* *alphanum* | `-` | `_`
133 *otherchar:* *any UTF-8 character except* `NUL, CR` *and* `LF`
134 ------------------------ ------------------------------------------------------
135
136
137 * Note: To prevent mangling of files sent via straight e-mail, no header will start with the four letters "From".
138
139
140
141 Non-terminal symbols defined in the above specification will be
142 referenced in the following specifications.
143
144 []{#JAR_Manifest}JAR Manifest
145 -----------------------------
146
147 ### []{#Manifest-Overview}Overview
148
149 A JAR file manifest consists of a main section followed by a list of
150 sections for individual JAR file entries, each separated by a newline.
151 Both the main section and individual sections follow the section syntax
152 specified above. They each have their own specific restrictions and
153 rules.
154
155 * The main section contains security and configuration information about
156 the JAR file itself, as well as the application. It also defines main
157 attributes that apply to every individual manifest entry. No attribute
158 in this section can have its name equal to "`Name`". This section is
159 terminated by an empty line.
160
161 * The individual sections define various attributes for packages or files
162 contained in this JAR file. Not all files in the JAR file need to be
163 listed in the manifest as entries, but all files which are to be signed
164 must be listed. The manifest file itself must not be listed. Each
165 section must start with an attribute with the name as "`Name`", and the
166 value must be a relative path to the file, or an absolute URL
167 referencing data outside the archive.
168
169 * If there are multiple individual sections for the same file entry, the
170 attributes in these sections are merged. If a certain attribute have
171 different values in different sections, the last one is recognized.
172
173 * Attributes which are not understood are ignored. Such attributes may
174 include implementation specific information used by applications.
175
176 ### []{#Manifest_Specification}Manifest Specification:
177
178 -------------------------------- --------------------------------------------------------------------------------
179 *manifest-file:* *main-section newline \*individual-section*
180 *main-section:* *version-info newline \*main-attribute*
181 *version-info:* `Manifest-Version :` *version-number*
182 *version-number:* *digit+\{*`.`*digit+\}\**
183 *main-attribute:* *(any legitimate main attribute) newline*
184 *individual-section:* `Name :` *value* *newline \*perentry-attribute*
185 *perentry-attribute:* *(any legitimate perentry attribute) newline*
186 *newline:* `CR LF | LF | CR` (*not followed by* `LF`)
187 *digit:* `{0-9}`
188 -------------------------------- --------------------------------------------------------------------------------
189
190 In the above specification, attributes that can appear in the main
191 section are referred to as main attributes, whereas attributes that can
192 appear in individual sections are referred to as per-entry attributes.
193 Certain attributes can appear both in the main section and the
194 individual sections, in which case the per-entry attribute value
195 overrides the main attribute value for the specified entry. The two
196 types of attributes are defined as follows.
197
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
238 in the JAR file, but can be overridden by per-entry attributes.
239 - Implementation-Title: The value is a string that defines the
240 title of the extension implementation.
241 - Implementation-Version: The value is a string that defines the
242 version of the extension implementation.
243 - Implementation-Vendor: The value is a string that defines the
244 organization that maintains the extension implementation.
245 - Specification-Title: The value is a string that defines the
246 title of the extension specification.
247 - Specification-Version: The value is a string that defines the
248 version of the extension specification.
249 - Specification-Vendor: The value is a string that defines the
250 organization that maintains the extension specification.
251 - Sealed: This attribute defines whether this JAR file is sealed
252 or not. The value can be either "true" or "false", case is
253 ignored. If it is set to "true", then all the packages in the
254 JAR file are defaulted to be sealed, unless they are defined
255 otherwise individually.
256
257 ### []{#Per-Entry_Attributes}Per-Entry Attributes
258
259 Per-entry attributes apply only to the individual JAR file entry to
260 which the manifest entry is associated with. If the same attribute also
261 appeared in the main section, then the value of the per-entry attribute
262 overwrites the main attribute's value. For example, if JAR file a.jar
263 has the following manifest content:
264
265 Manifest-Version: 1.0
266 Created-By: 1.8 (Oracle Inc.)
267 Sealed: true
268 Name: foo/bar/
269 Sealed: false
270
271 It means that all the packages archived in a.jar are sealed, except that
272 package foo.bar is not.
273
274 The per-entry attributes fall into the following groups:
275
276 - attributes defined for file contents:
277 - Content-Type: This attribute can be used to specify the MIME
278 type and subtype of data for a specific file entry in the
279 JAR file. The value should be a string in the form of
280 *type/subtype.* For example "image/bmp" is an image type with a
281 subtype of bmp (representing bitmap). This would indicate the
282 file entry as an image with the data stored as a bitmap. RFC
283 [1521](http://www.ietf.org/rfc/rfc1521.txt) and
284 [1522](http://www.ietf.org/rfc/rfc1522.txt) discuss and define
285 the MIME types definition.
286 - attributes defined for package versioning and sealing information:
287 These are the same set of attributes defined above as main
288 attributes that defines the extension package versioning and sealing
289 information. When used as per-entry attributes, these attributes
290 overwrites the main attributes but only apply to the individual file
291 specified by the manifest entry.
292 - attribute defined for beans objects:
293 - Java-Bean: Defines whether the specific jar file entry is a Java
294 Beans object or not. The value should be either "true" or
295 "false", case is ignored.
296 - attributes defined for signing: These attributes are used for
297 signing and verifying purposes. More details here.
298 - x-Digest-y: The name of this attribute specifies the name of the
299 digest algorithm used to compute the digest value for the
300 corresponding jar file entry. The value of this attribute stores
301 the actual digest value. The prefix 'x' specifies the algorithm
302 name and the optional suffix 'y' indicates to which language
303 the digest value should be verified against.
304 - Magic: This is an optional attribute that can be used by
305 applications to indicate how verifier should compute the digest
306 value contained in the manifest entry. The value of this
307 attribute is a set of comma separated context specific strings.
308 Detailed description is here.
309
310 []{#Signed_JAR_File}Signed JAR File
311 -----------------------------------
312
313 ### []{#SignedJar-Overview}Overview
314
315 A JAR file can be signed by using the command line
316 [jarsigner](http://docs.oracle.com/javase/9/tools/jarsigner.htm#JSWOR-GUID-925E7A1B-B3F3-44D2-8B49-0B3FA2C54864) tool or directly
317 through the `java.security` API. Every file entry, including
318 non-signature related files in the `META-INF` directory, will be signed
319 if the JAR file is signed by the jarsigner tool. The signature related
320 files are:
321
322 - `META-INF/MANIFEST.MF`
323 - `META-INF/*.SF`
324 - `META-INF/*.DSA`
325 - `META-INF/*.RSA`
326 - `META-INF/SIG-*`
327
328 Note that if such files are located in `META-INF` subdirectories, they
329 are not considered signature-related. Case-insensitive versions of these
330 filenames are reserved and will also not be signed.
331
332 Subsets of a JAR file can be signed by using the `java.security` API. A
333 signed JAR file is exactly the same as the original JAR file, except
334 that its manifest is updated and two additional files are added to the
335 `META-INF` directory: a signature file and a signature block file. When
336 jarsigner is not used, the signing program has to construct both the
337 signature file and the signature block file.
338
339 For every file entry signed in the signed JAR file, an individual
340 manifest entry is created for it as long as it does not already exist in
341 the manifest. Each manifest entry lists one or more digest attributes
342 and an optional [Magic attribute](#The_Magic_Attribute).
343
344 ### []{#Signature_File}Signature File
345
346 Each signer is represented by a signature file with extension `.SF`. The
347 major part of the file is similar to the manifest file. It consists of a
348 main section which includes information supplied by the signer but not
349 specific to any particular jar file entry. In addition to the
350 `Signature-Version` and `Created-By` attributes (see [Main
351 Attributes](#Main_Attributes)), the main section can also include the
352 following security attributes:
353
354 - x-Digest-Manifest-Main-Attributes (where x is the standard name of a
355 `java.security.MessageDigest` algorithm): The value of this
356 attribute is the digest value of the main attributes of the
357 manifest.
358 - x-Digest-Manifest (where x is the standard name of a
359 `java.security.MessageDigest` algorithm): The value of this
360 attribute is the digest value of the entire manifest.
361
362 The main section is followed by a list of individual entries whose names
363 must also be present in the manifest file. Each individual entry must
364 contain at least the digest of its corresponding entry in the manifest
365 file.
366
367 Paths or URLs appearing in the manifest file but not in the signature
368 file are not used in the calculation.
369
370 ### []{#Signature_Validation}Signature Validation
371
372 A successful JAR file verification occurs if the signature(s) are valid,
373 and none of the files that were in the JAR file when the signatures were
374 generated have been changed since then. JAR file verification involves
375 the following steps:
376
377 1. Verify the signature over the signature file when the manifest is
378 first parsed. For efficiency, this verification can be remembered.
379 Note that this verification only validates the signature directions
380 themselves, not the actual archive files.
381
382 2. If an `x-Digest-Manifest` attribute exists in the signature file,
383 verify the value against a digest calculated over the entire
384 manifest. If more than one `x-Digest-Manifest` attribute exists in
385 the signature file, verify that at least one of them matches the
386 calculated digest value.
387
388 3. If an `x-Digest-Manifest` attribute does not exist in the signature
389 file or none of the digest values calculated in the previous step
390 match, then a less optimized verification is performed:
391
392 1. If an `x-Digest-Manifest-Main-Attributes` entry exists in the
393 signature file, verify the value against a digest calculated
394 over the main attributes in the manifest file. If this
395 calculation fails, then JAR file verification fails. This
396 decision can be remembered for efficiency. If an
397 `x-Digest-Manifest-Main-Attributes` entry does not exist in the
398 signature file, its nonexistence does not affect JAR file
399 verification and the manifest main attributes are not verified.
400
401 2. Verify the digest value in each source file information section
402 in the signature file against a digest value calculated against
403 the corresponding entry in the manifest file. If any of the
404 digest values don't match, then JAR file verification fails.
405
406 One reason the digest value of the manifest file that is stored in
407 the `x-Digest-Manifest` attribute may not equal the digest value of
408 the current manifest file is that one or more files were added to
409 the JAR file (using the jar tool) after the signature (and thus the
410 signature file) was generated. When the jar tool is used to add
411 files, the manifest file is changed (sections are added to it for
412 the new files), but the signature file is not. A verification is
413 still considered successful if none of the files that were in the
414 JAR file when the signature was generated have been changed since
415 then, which is the case if the digest values in the non-header
416 sections of the signature file equal the digest values of the
417 corresponding sections in the manifest file.
418
419 4. For each entry in the manifest, verify the digest value in the
420 manifest file against a digest calculated over the actual data
421 referenced in the "Name:" attribute, which specifies either a
422 relative file path or URL. If any of the digest values don't match,
423 then JAR file verification fails.
424
425 Example manifest file:
426
427 Manifest-Version: 1.0
428 Created-By: 1.8.0 (Oracle Inc.)
429
430 Name: common/class1.class
431 SHA-256-Digest: (base64 representation of SHA-256 digest)
432
433 Name: common/class2.class
434 SHA1-Digest: (base64 representation of SHA1 digest)
435 SHA-256-Digest: (base64 representation of SHA-256 digest)
436
437 The corresponding signature file would be:
438
439 Signature-Version: 1.0
440 SHA-256-Digest-Manifest: (base64 representation of SHA-256 digest)
441 SHA-256-Digest-Manifest-Main-Attributes: (base64 representation of SHA-256 digest)
442
443 Name: common/class1.class
444 SHA-256-Digest: (base64 representation of SHA-256 digest)
445
446 Name: common/class2.class
447 SHA-256-Digest: (base64 representation of SHA-256 digest)
448
449 ### []{#The_Magic_Attribute}The Magic Attribute
450
451 Another requirement to validate the signature on a given manifest entry
452 is that the verifier understand the value or values of the Magic
453 key-pair value in that entry's manifest entry.
454
455 The Magic attribute is optional but it is required that a parser
456 understand the value of an entry's Magic key if it is verifying that
457 entry's signature.
458
459 The value or values of the Magic attribute are a set of comma-separated
460 context-specific strings. The spaces before and after the commas are
461 ignored. Case is ignored. The exact meaning of the magic attributes is
462 application specific. These values indicate how to compute the hash
463 value contained in the manifest entry, and are therefore crucial to the
464 proper verification of the signature. The keywords may be used for
465 dynamic or embedded content, multiple hashes for multilingual documents,
466 etc.
467
468 Here are two examples of the potential use of Magic attribute in the
469 manifest file:
470
471 Name: http://www.example-scripts.com/index#script1
472 SHA-256-Digest: (base64 representation of SHA-256 hash)
473 Magic: JavaScript, Dynamic
474
475 Name: http://www.example-tourist.com/guide.html
476 SHA-256-Digest: (base64 representation of SHA-256 hash)
477 SHA-256-Digest-French: (base64 representation of SHA-256 hash)
478 SHA-256-Digest-German: (base64 representation of SHA-256 hash)
479 Magic: Multilingual
480
481 In the first example, these Magic values may indicate that the result of
482 an http query is the script embedded in the document, as opposed to the
483 document itself, and also that the script is generated dynamically.
484 These two pieces of information indicate how to compute the hash value
485 against which to compare the manifest's digest value, thus comparing a
486 valid signature.
487
488 In the second example, the Magic value indicates that the document
489 retrieved may have been content-negotiated for a specific language, and
490 that the digest to verify against is dependent on which language the
491 document retrieved is written in.
492
493 []{#Digital_Signatures}Digital Signatures
494 -----------------------------------------
495
496 A digital signature is a signed version of the `.SF` signature file.
497 These are binary files not intended to be interpreted by humans.
498
499 Digital signature files have the same filenames as the .SF files but
500 different extensions. The extension varies depending on the type of
501 digital signature.
502
503 - `.RSA` (PKCS7 signature, SHA-256 + RSA)
504 - `.DSA` (PKCS7 signature, DSA)
505
506 Digital signature files for signature algorithms not listed above must
507 reside in the `META-INF` directory and have the prefix "`SIG-`". The
508 corresonding signature file (`.SF` file) must also have the same prefix.
509
510 For those formats that do not support external signed data, the file
511 shall consist of a signed copy of the `.SF` file. Thus some data may be
512 duplicated and a verifier should compare the two files.
513
514 Formats that support external data either reference the `.SF` file, or
515 perform calculations on it with implicit reference.
516
517 Each `.SF` file may have multiple digital signatures, but those
518 signatures should be generated by the same legal entity.
519
520 File name extensions may be 1 to 3 *alphanum* characters. Unrecognized
521 extensions are ignored.
522
523 []{#Notes_on_Manifest_and_Signature_Files}Notes on Manifest and Signature Files
524 -------------------------------------------------------------------------------
525
526 Following is a list of additional restrictions and rules that apply to
527 manifest and signature files.
528
529 - Before parsing:
530 - If the last character of the file is an EOF character (code 26),
531 the EOF is treated as whitespace. Two newlines are appended (one
532 for editors that don't put a newline at the end of the last
533 line, and one so that the grammar doesn't have to special-case
534 the last entry, which may not have a blank line after it).
535 - Attributes:
536 - In all cases for all sections, attributes which are not
537 understood are ignored.
538 - Attribute names are case insensitive. Programs which generate
539 manifest and signature files should use the cases shown in this
540 specification however.
541 - Attribute names cannot be repeated within a section.
542 - Versions:
543 - Manifest-Version and Signature-Version must be first, and in
544 exactly that case (so that they can be recognized easily as
545 magic strings). Other than that, the order of attributes within
546 a main section is not significant.
547 - Ordering:
548 - The order of individual manifest entries is not significant.
549 - The order of individual signature entries is not significant,
550 except that the digests that get signed are in that order.
551 - Line length:
552 - No line may be longer than 72 bytes (not characters), in its
553 UTF8-encoded form. If a value would make the initial line longer
554 than this, it should be continued on extra lines (each starting
555 with a single SPACE).
556 - Errors:
557 - If a file cannot be parsed according to this spec, a warning
558 should be output, and none of the signatures should be trusted.
559 - Limitations:
560 - Because header names cannot be continued, the maximum length of
561 a header name is 70 bytes (there must be a colon and a SPACE
562 after the name).
563 - NUL, CR, and LF can't be embedded in header values, and NUL, CR,
564 LF and ":" can't be embedded in header names.
565 - Implementations should support 65535-byte (not character) header
566 values, and 65535 headers per file. They might run out of
567 memory, but there should not be hard-coded limits below these
568 values.
569 - Signers:
570 - It is technically possible that different entities may use
571 different signing algorithms to share a single signature file.
572 This violates the standard, and the extra signature may be
573 ignored.
574 - Algorithms:
575 - No digest algorithm or signature algorithm is mandated by this
576 standard. However, at least one of MD5 and SHA1 digest algorithm
577 must be supported.
578
579 []{#JAR_Index}JAR Index
580 -----------------------
581
582 ### []{#Overview}Overview
583
584 Since 1.3, JarIndex is introduced to optimize the class searching
585 process of class loaders for network applications, especially applets.
586 Originally, an applet class loader uses a simple linear search algorithm
587 to search each element on its internal search path, which is constructed
588 from the "ARCHIVE" tag or the "Class-Path" main attribute. The class
589 loader downloads and opens each element in its search path, until the
590 class or resource is found. If the class loader tries to find a
591 nonexistent resource, then all the jar files within the application or
592 applet will have to be downloaded. For large network applications and
593 applets this could result in slow startup, sluggish response and wasted
594 network bandwidth. The JarIndex mechanism collects the contents of all
595 the jar files defined in an applet and stores the information in an
596 index file in the first jar file on the applet's class path. After the
597 first jar file is downloaded, the applet class loader will use the
598 collected content information for efficient downloading of jar files.
599
600 The existing `jar` tool is enhanced to be able to examine a list of jar
601 files and generate directory information as to which classes and
602 resources reside in which jar file. This directory information is stored
603 in a simple text file named `INDEX.LIST` in the `META-INF` directory of
604 the root jar file. When the classloader loads the root jar file, it
605 reads the `INDEX.LIST` file and uses it to construct a hash table of
606 mappings from file and package names to lists of jar file names. In
607 order to find a class or a resource, the class loader queries the
608 hashtable to find the proper jar file and then downloads it if
609 necessary.
610
611 Once the class loader finds a `INDEX.LIST` file in a particular jar
612 file, it always trusts the information listed in it. If a mapping is
613 found for a particular class, but the class loader fails to find it by
614 following the link, an unspecified Error or RuntimeException is thrown.
615 When this occurs, the application developer should rerun the `jar` tool
616 on the extension to get the right information into the index file.
617
618 To prevent adding too much space overhead to the application and to
619 speed up the construction of the in-memory hash table, the INDEX.LIST
620 file is kept as small as possible. For classes with non-null package
621 names, mappings are recorded at the package level. Normally one package
622 name is mapped to one jar file, but if a particular package spans more
623 than one jar file, then the mapped value of this package will be a list
624 of jar files. For resource files with non-empty directory prefixes,
625 mappings are also recorded at the directory level. Only for classes
626 with null package name, and resource files which reside in the root
627 directory, will the mapping be recorded at the individual file level.
628
629 ### []{#Index_File_Specification}Index File Specification
630
631 The `INDEX.LIST` file contains one or more sections each separated by a
632 single blank line. Each section defines the content of a particular jar
633 file, with a header defining the jar file path name, followed by a list
634 of package or file names, one per line. All the jar file paths are
635 relative to the code base of the root jar file. These path names are
636 resolved in the same way as the current extension mechanism does for
637 bundled extensions.
638
639 The UTF-8 encoding is used to support non ASCII characters in file or
640 package names in the index file.
641
642
643 #### Specification
644
645 ------------------ ---------------------------------------------------------------------
646 *index file:* *version-info blankline section\**
647 *version-info:* `JarIndex-Version:` *version-number*
648 *version-number:* *digit+{.digit+}\**
649 *section:* *body blankline*
650 *body:* *header name\**
651 *header:* *char+*`.jar` *newline*
652 *name:* *char+ newline*
653 *char:* *any valid Unicode character except* `NULL, CR` *and*`LF`
654 *blankline:* *newline newline*
655 *newline:* `CR LF | LF | CR` (*not followed by* `LF`)
656 *digit:* {`0-9`}
657 ------------------ ---------------------------------------------------------------------
658
659
660
661 The `INDEX.LIST` file is generated by running `jar -i.` See the
662 [jar](https://docs.oracle.com/javase/9/tools/jar.htm#JSWOR614) man page for more details.
663
664 ### []{#Backward_Compatibility}Backward Compatibility
665
666 The new class loading scheme is totally backward compatible with
667 applications developed on top of the current extension mechanism. When
668 the class loader loads the first jar file and an `INDEX.LIST` file is
669 found in the `META-INF` directory, it would construct the index hash
670 table and use the new loading scheme for the extension. Otherwise, the
671 class loader will simply use the original linear search algorithm.
672
673 []{#Service_Provider}Service Provider
674 -------------------------------------
675
676 ### []{#Service_Provider_Overview}Overview
677
678 Files in the `META-INF/services` directory are service provider
679 configuration files. A service is a well-known set of interfaces and
680 (usually abstract) classes. A service provider is a specific
681 implementation of a service. The classes in a provider typically
682 implement the interfaces and subclass the classes defined in the service
683 itself. Service providers may be installed in an implementation of the
684 Java platform in the form of extensions, that is, jar files placed into
685 any of the usual extension directories. Providers may also be made
686 available by adding them to the applet or application class path or by
687 some other platform-specific means.
688
689 A service is represented by an abstract class. A provider of a given
690 service contains one or more concrete classes that extend this service
691 class with data and code specific to the provider. This provider class
692 will typically not be the entire provider itself but rather a proxy that
693 contains enough information to decide whether the provider is able to
694 satisfy a particular request together with code that can create the
695 actual provider on demand. The details of provider classes tend to be
696 highly service-specific; no single class or interface could possibly
697 unify them, so no such class has been defined. The only requirement
698 enforced here is that provider classes must have a zero-argument
699 constructor so that they may be instantiated during lookup.
700
701 ### []{#Provider_Configuration_File}Provider-Configuration File
702
703 A service provider identifies itself by placing a provider-configuration
704 file in the resource directory `META-INF/services`. The file's name
705 should consist of the fully-qualified name of the abstract service
706 class. The file should contain a newline-separated list of unique
707 concrete provider-class names. Space and tab characters, as well as
708 blank lines, are ignored. The comment character is '\#' (0x23); on each
709 line all characters following the first comment character are ignored.
710 The file must be encoded in UTF-8.
711
712 ### []{#Example}Example
713
714 Suppose we have a service class named java.io.spi.CharCodec. It has two
715 abstract methods:
716
717 - `public abstract CharEncoder getEncoder(String encodingName);`
718 - `public abstract CharDecoder getDecoder(String encodingName);`
719
720 Each method returns an appropriate object or null if it cannot translate
721 the given encoding. Typical CharCodec providers will support more than
722 one encoding.
723
724 If sun.io.StandardCodec is a provider of the CharCodec service then its
725 jar file would contain the file
726 `META-INF/services/java.io.spi.CharCodec`. This file would contain the
727 single line:
728
729 sun.io.StandardCodec # Standard codecs for the platform
730
731 To locate an encoder for a given encoding name, the internal I/O code
732 would do something like this:
733
734 CharEncoder getEncoder(String encodingName) {
735 Iterator ps = Service.providers(CharCodec.class);
736 while (ps.hasNext()) {
737 CharCodec cc = (CharCodec)ps.next();
738 CharEncoder ce = cc.getEncoder(encodingName);
739 if (ce != null) return ce;
740 }
741 return null;
742 }
743
744 The provider-lookup mechanism always executes in the security context of
745 the caller. Trusted system code should typically invoke the methods in
746 this class from within a privileged security context.
747
748 []{#classpath}
749
750 Class-Path Attribute
751 --------------------
752
753 The manifest for an application can specify one or more relative URLs
754 referring to the JAR files and directories for other libraries that it
755 needs. These relative URLs will be treated relative to the code base
756 that the containing application was loaded from.
757
758 An application (or, more generally, JAR file) specifies the relative
759 URLs of the libraries that it needs via the manifest attribute
760 `Class-Path`. This attribute lists the URLs to search for
761 implementations of other libraries if they cannot be found on the host
762 Java Virtual Machine. These relative URLs may include JAR files
763 and directories for any libraries or resources needed by the
764 application. Relative URLs not ending with '/' are assumed to refer to
765 JAR files. For example,
766
767 ``` {style="MARGIN-LEFT: 40px"}
768 Class-Path: servlet.jar infobus.jar acme/beans.jar images/
769 ```
770
771 At most one `Class-Path` header may be specified in a JAR file's
772 manifest..
773
774 Currently, the URLs must be *relative* to the code base of the JAR file
775 for security reasons. Thus, remote optional packages will originate from
776 the same code base as the application.
777
778 Each relative URL is resolved against the code base that the containing
779 application or library was loaded from. If the resulting URL is invalid
780 or refers to a resource that cannot be found then it is ignored.
781
782 The resulting URLs are used to extend the class path for the
783 application, applet, or servlet by inserting the URLs in the class path
784 immediately following the URL of the containing JAR file. Any duplicate
785 URLs are omitted. For example, given the following class path:
786
787 ``` {style="MARGIN-LEFT: 40px"}
788 a.jar b.jar
789 ```
790
791 If `b.jar` contained the following `Class-Path` manifest attribute:
792
793 ``` {style="MARGIN-LEFT: 40px"}
794 Class-Path: x.jar a.jar
795 ```
796
797 Then the resulting application class path would be the following:
798
799 ``` {style="MARGIN-LEFT: 40px"}
800 a.jar b.jar x.jar
801 ```
802
803 Of course, if `x.jar` had dependencies of its own then these would be
804 added according to the same rules and so on for each subsequent URL. In
805 the actual implementation, JAR file dependencies are processed lazily so
806 that the JAR files are not actually opened until needed. []{#sealing}
807
808 Package Sealing
809 ---------------
810
811 JAR files and packages can be optionally *sealed*, so that an package
812 can enforce consistency within a version.
813
814 A package sealed within a JAR specifies that all classes defined in that
815 package must originate from the same JAR. Otherwise, a
816 `SecurityException` is thrown.
817
818 A sealed JAR specifies that all packages defined by that JAR are sealed
819 unless overridden specifically for a package.
820
821 A sealed package is specified via the manifest attribute, `Sealed`,
822 whose value is `true` or `false` (case irrelevant). For example,
823
824 Name: javax/servlet/internal/
825 Sealed: true
826
827
828 specifies that the `javax.servlet.internal` package is sealed, and that
829 all classes in that package must be loaded from the same JAR file.
830
831 If this attribute is missing, the package sealing attribute is that of
832 the containing JAR file.
833
834 A sealed JAR is specified via the same manifest header, `Sealed`, with
835 the value again of either `true` or `false`. For example,
836
837 Sealed: true
838
839
840 specifies that all packages in this archive are sealed unless explicitly
841 overridden for a particular package with the `Sealed` attribute in a
842 manifest entry.
843
844 If this attribute is missing, the JAR file is assumed to *not* be
845 sealed, for backwards compatibility. The system then defaults to
846 examining package headers for sealing information.
847
848 Package sealing is also important for security, because it restricts
849 access to package-protected members to only those classes defined in the
850 package that originated from the same JAR file.
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.