1 # JAR File Specification
   4 Contents
   5 --------
   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)
  37 []{#Intro}Introduction
  38 ----------------------
  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.
  48 []{#Modular}Modular JAR files
  49 -----------------------------
  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.
  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.
  67 []{#The_META-INF_directory}The META-INF directory
  68 -------------------------------------------------
  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:
  74 -   `MANIFEST.MF`
  76 The manifest file that is used to define package related data.
  78 -   `INDEX.LIST`
  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.
  85 -   `x.SF`
  87 The signature file for the JAR file. 'x' stands for the base file name.
  89 -   `x.DSA`
  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.
  95 -   `services/`
  97 This directory stores all the service provider configuration files.
  99 []{#Name-Value_pairs_and_Sections}Name-Value pairs and Sections
 100 ---------------------------------------------------------------
 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.
 108 Groups of name-value pairs are known as a "section". Sections are
 109 separated from other sections by empty lines.
 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.
 115 Implementations shall support header values of up to 65535 bytes.
 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.
 121 ### []{#Section-Specification}Specification:
 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 ------------------------         ------------------------------------------------------
 137 *    Note: To prevent mangling of files sent via straight e-mail, no header will start with the four letters "From".
 141 Non-terminal symbols defined in the above specification will be
 142 referenced in the following specifications.
 144 []{#JAR_Manifest}JAR Manifest
 145 -----------------------------
 147 ### []{#Manifest-Overview}Overview
 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.
 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.
 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.
 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.
 173 * Attributes which are not understood are ignored. Such attributes may
 174 include implementation specific information used by applications.
 176 ### []{#Manifest_Specification}Manifest Specification:
 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 --------------------------------    --------------------------------------------------------------------------------
 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.
 199 ### []{#Main_Attributes}Main Attributes
 201 Main attributes are the attributes that are present in the main section
 202 of the manifest. They fall into the following different groups:
 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.
 257 ### []{#Per-Entry_Attributes}Per-Entry Attributes
 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:
 265         Manifest-Version: 1.0
 266         Created-By: 1.8 (Oracle Inc.)
 267         Sealed: true
 268         Name: foo/bar/
 269         Sealed: false
 271 It means that all the packages archived in a.jar are sealed, except that
 272 package foo.bar is not.
 274 The per-entry attributes fall into the following groups:
 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.
 310 []{#Signed_JAR_File}Signed JAR File
 311 -----------------------------------
 313 ### []{#SignedJar-Overview}Overview
 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:
 323 -   `META-INF/*.SF`
 324 -   `META-INF/*.DSA`
 325 -   `META-INF/*.RSA`
 326 -   `META-INF/SIG-*`
 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.
 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.
 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).
 344 ### []{#Signature_File}Signature File
 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:
 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.
 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.
 367 Paths or URLs appearing in the manifest file but not in the signature
 368 file are not used in the calculation.
 370 ### []{#Signature_Validation}Signature Validation
 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:
 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.
 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.
 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:
 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.
 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.
 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.
 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.
 425 Example manifest file:
 427         Manifest-Version: 1.0
 428         Created-By: 1.8.0 (Oracle Inc.)
 430         Name: common/class1.class
 431         SHA-256-Digest: (base64 representation of SHA-256 digest)
 433         Name: common/class2.class
 434         SHA1-Digest: (base64 representation of SHA1 digest)
 435         SHA-256-Digest: (base64 representation of SHA-256 digest)
 437 The corresponding signature file would be:
 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)
 443         Name: common/class1.class
 444         SHA-256-Digest: (base64 representation of SHA-256 digest)
 446         Name: common/class2.class
 447         SHA-256-Digest: (base64 representation of SHA-256 digest)
 449 ### []{#The_Magic_Attribute}The Magic Attribute
 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.
 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.
 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.
 468 Here are two examples of the potential use of Magic attribute in the
 469 manifest file:
 471             Name: http://www.example-scripts.com/index#script1
 472             SHA-256-Digest: (base64 representation of SHA-256 hash)
 473             Magic: JavaScript, Dynamic
 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
 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.
 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.
 493 []{#Digital_Signatures}Digital Signatures
 494 -----------------------------------------
 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.
 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.
 503 -   `.RSA` (PKCS7 signature, SHA-256 + RSA)
 504 -   `.DSA` (PKCS7 signature, DSA)
 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.
 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.
 514 Formats that support external data either reference the `.SF` file, or
 515 perform calculations on it with implicit reference.
 517 Each `.SF` file may have multiple digital signatures, but those
 518 signatures should be generated by the same legal entity.
 520 File name extensions may be 1 to 3 *alphanum* characters. Unrecognized
 521 extensions are ignored.
 523 []{#Notes_on_Manifest_and_Signature_Files}Notes on Manifest and Signature Files
 524 -------------------------------------------------------------------------------
 526 Following is a list of additional restrictions and rules that apply to
 527 manifest and signature files.
 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.
 579 []{#JAR_Index}JAR Index
 580 -----------------------
 582 ### []{#Overview}Overview
 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.
 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.
 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.
 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.
 629 ### []{#Index_File_Specification}Index File Specification
 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.
 639 The UTF-8 encoding is used to support non ASCII characters in file or
 640 package names in the index file.
 643 #### Specification
 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 ------------------     ---------------------------------------------------------------------
 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.
 664 ### []{#Backward_Compatibility}Backward Compatibility
 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.
 673 []{#Service_Provider}Service Provider
 674 -------------------------------------
 676 ### []{#Service_Provider_Overview}Overview
 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.
 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.
 701 ### []{#Provider_Configuration_File}Provider-Configuration File
 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.
 712 ### []{#Example}Example
 714 Suppose we have a service class named java.io.spi.CharCodec. It has two
 715 abstract methods:
 717 -   `public abstract CharEncoder getEncoder(String encodingName);`
 718 -   `public abstract CharDecoder getDecoder(String encodingName);`
 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.
 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:
 729         sun.io.StandardCodec    # Standard codecs for the platform
 731 To locate an encoder for a given encoding name, the internal I/O code
 732 would do something like this:
 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         }
 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.
 748 []{#classpath}
 750 Class-Path Attribute
 751 --------------------
 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.
 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,
 767 ``` {style="MARGIN-LEFT: 40px"}
 768 Class-Path: servlet.jar infobus.jar acme/beans.jar images/
 769 ```
 771 At most one `Class-Path` header may be specified in a JAR file's
 772 manifest..
 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.
 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.
 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:
 787 ``` {style="MARGIN-LEFT: 40px"}
 788 a.jar b.jar
 789 ```
 791 If `b.jar` contained the following `Class-Path` manifest attribute:
 793 ``` {style="MARGIN-LEFT: 40px"}
 794 Class-Path: x.jar a.jar
 795 ```
 797 Then the resulting application class path would be the following:
 799 ``` {style="MARGIN-LEFT: 40px"}
 800 a.jar b.jar x.jar
 801 ```
 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}
 808 Package Sealing
 809 ---------------
 811 JAR files and packages can be optionally *sealed*, so that an package
 812 can enforce consistency within a version.
 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.
 818 A sealed JAR specifies that all packages defined by that JAR are sealed
 819 unless overridden specifically for a package.
 821 A sealed package is specified via the manifest attribute, `Sealed`,
 822 whose value is `true` or `false` (case irrelevant). For example,
 824         Name: javax/servlet/internal/
 825         Sealed: true
 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.
 831 If this attribute is missing, the package sealing attribute is that of
 832 the containing JAR file.
 834 A sealed JAR is specified via the same manifest header, `Sealed`, with
 835 the value again of either `true` or `false`. For example,
 837         Sealed: true
 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.
 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.
 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.
 852 The unnamed package is not sealable, so classes that are to be sealed
 853 must be placed in their own packages.
 855 []{#API_Details}API Details
 856 ---------------------------
 858 Package [java.util.jar](../../../api/java/util/jar/package-summary.html)
 860 []{#See_Also}See Also
 861 ---------------------
 863 Package
 864 [java.security](../../../api/java/security/package-summary.html)\
 865 Package [java.util.zip](../../../api/java/util/zip/package-summary.html)
 867 ---------------------------------------
 869 <meta charset="utf-8" />
 871 [Copyright &copy;](../../../legal/copyright.html)
 872 1993, 2017, Oracle and/or its affiliates. All rights reserved.