< prev index next >

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

Print this page
rev 17080 : [mq]: mr-jar-orig
rev 17081 : [mq]: JDK-8150681-jar-spec-markdown-with-mr-jar

*** 1,13 **** ! # JAR File Specification Contents -------- - [Introduction](#Intro) - [Modular JAR files](#Modular) - [The META-INF directory](#The_META-INF_directory) - [Name-Value pairs and Sections](#Name-Value_pairs_and_Sections) - [JAR Manifest](#JAR_Manifest) - [Overview](#Manifest-Overview) - [Manifest Specification](#Manifest_Specification) --- 1,39 ---- ! --- ! # Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. ! # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ! # ! # This code is free software; you can redistribute it and/or modify it ! # under the terms of the GNU General Public License version 2 only, as ! # published by the Free Software Foundation. ! # ! # This code is distributed in the hope that it will be useful, but WITHOUT ! # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ! # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ! # version 2 for more details (a copy is included in the LICENSE file that ! # accompanied this code). ! # ! # You should have received a copy of the GNU General Public License version ! # 2 along with this work; if not, write to the Free Software Foundation, ! # Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ! # ! # Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ! # or visit www.oracle.com if you need additional information or have any ! # questions. + title: 'JAR File Specification' + --- + + ------------------------------------------------------------------------------- Contents -------- - [Introduction](#Intro) - [Modular JAR files](#Modular) + - [Multi-release JAR files](#Multi-release) + - [Modular multi-release JAR files](#Modular-multi-release) - [The META-INF directory](#The_META-INF_directory) - [Name-Value pairs and Sections](#Name-Value_pairs_and_Sections) - [JAR Manifest](#JAR_Manifest) - [Overview](#Manifest-Overview) - [Manifest Specification](#Manifest_Specification)
*** 46,70 **** a particular platform. []{#Modular}Modular JAR files ----------------------------- ! JAR files that are deployed on the module path, as opposed to the class ! path, are modules. If the JAR file has a `module-info.class` in the ! top-level directory then it is a *Modular JAR* file. The ! `module-info.class` file is the binary form of the module declaration. ! If the JAR file does not have a `module-info.class` in the top-level ! directory then it is considered to be an *automatic module*. The module ! name for an automatic module is derived from the name of the JAR file ! and its exported packages are determined by the `.class` files in the JAR file. ! JAR files that are deployed as modules declare (explicitly or ! implicitly) their dependences and may declare service providers too. The ! [JAR Manifest](#JAR_Manifest) is ignored. On the other hand, JAR files ! on the class path use the [META-INF](#The_META-INF_directory) directory ! for security, versioning, or service configuration. []{#The_META-INF_directory}The META-INF directory ------------------------------------------------- The following files/directories in the META-INF directory are recognized --- 72,205 ---- a particular platform. []{#Modular}Modular JAR files ----------------------------- ! A modular JAR file is a JAR file that has a module descriptor, ! `module-info.class`, in the top-level directory (or root) directory. The ! module descriptor is the binary form of a module declaration. (Note the section ! on [multi-release JAR files](#Multi-release) further refines the definition of ! modular JAR files.) ! ! A modular JAR file deployed on the module path, as opposed to the class path, is ! an *explicit* module. Dependences and service providers are declared in the ! module descriptor. The [JAR Manifest](#JAR_Manifest) is ignored as is any ! service configuration under the [`META-INF`](#The_META-INF_directory) directory. ! However, if the modular JAR file is deployed on the class path then it behaves ! as if a non-modular JAR file and the JAR Manifest and configuration under ! the `META-INF` directory are not ignored. ! ! A non-modular JAR file deployed on the module path is an *automatic module*, ! where a module declaration is synthesized from the JAR file name and ! its contents. For further details see the specification on the method ! [java.lang.module.ModuleFinder.of](../../../api/java/lang/module/ModuleFinder.html#of-java.nio.file.Path...-). ! ! []{#Multi-release}Multi-release JAR files ! ----------------------------------------- ! ! A multi-release JAR file allows for a single JAR file to support multiple ! major versions of Java platform releases. For example, a multi-release JAR file ! can depend on both the Java 8 and Java 9 major platform releases, where some ! class files depend on APIs in Java 8 and other class files depend on APIs in ! Java 9. ! This enables library and framework developers to decouple the use of APIs in a ! specific major version of a Java platform release from the requirement that all ! their users migrate to that major version. Library and framework developers can ! gradually migrate to and support new Java features while still supporting the ! old features. ! ! A multi-release JAR file is identified by the main attribute: ! ! Multi-Release: true ! ! declared in the main section of the [JAR Manifest](#JAR_Manifest). ! ! Classes and resource files dependent on a major version, 9 or greater, of a ! Java platform release may be located under a *versioned directory* instead of ! under the top-level (or root) directory. The versioned directory ! is located under the [the META-INF directory](#The_META-INF_directory) and is ! of the form: ! ! META-INF/versions/N ! ! where N is the string representation of the major version number of a Java ! platform release. Specifically `N` must conform to the specification: ! ! -------------------------------- -------------------------------------------------------------------------------- ! *N:* *`{1-9}` `{0-9}`\** ! -------------------------------- -------------------------------------------------------------------------------- ! ! Any versioned directory whose value of `N` is less than `9` is ignored as is ! a string representation of `N` that does not conform to the above specification. ! ! A class file under a versioned directory, of version `N` say, in a multi-release ! JAR must have a class file version less than or equal to the class file ! version associated with `N`th major version of a Java platform release. ! If the class of the class file is public or protected then that class must ! *preside over* a class of the same fully qualified name and access modifier ! whose class file is present under the top-level directory. By logical extension ! this applies to a class of a class file, if present, under a versioned directory ! whose version is less than `N`. ! ! If a multi-release JAR file is deployed on the class path or module path ! (as an automatic module or an explicit [multi-release module](#Modular-multi-release)) ! of major version `N` of a Java platform release runtime, then a class loader ! loading classes from that JAR file will first search for class files under the ! `N`th versioned directory, then prior versioned directories in descending order ! (if present), down to a lower major version bound of `9`, and finally under the ! top-level directory. ! ! The public API exported by the classes in a multi-release JAR file must be ! *exactly* the same across versions, hence at a minimum why versioned public or ! protected classes for class files under a versioned directory must preside over ! classes for class files under the top-level directory. It is difficult and ! costly to perform extensive API verification checks as such tooling, such as the ! `jar` tool, is not required to perform extensive verification and a Java runtime ! is not required to perform any verification. A future release of this ! specification may relax the exact same API constraint to support careful ! evolution. ! ! Resources under the `META-INF` directory cannot be versioned (such as for ! service configuration). ! ! A multi-release JAR file can be signed. ! ! Multi-release JAR files are not supported by the boot class loader of a Java ! runtime. If a multi-release JAR file is appended to the boot class path (with ! the `-Xbootclasspath/a` option) then the JAR is treated as if it is an ordinary JAR file. ! ### []{#Modular-multi-release}Modular multi-release JAR files ! ! A modular multi-release JAR file is a multi-release JAR file that has a ! module descriptor, `module-info.class`, in the top-level directory (as for ! a [modular](#Modular) JAR file), or directly in a versioned directory. ! ! A public or protected class in a non-exported package (that is not declared as ! exported in the module descriptor) need not preside over a class of the same ! fully qualified name and access modifier whose class file is present under ! the top-level directory. ! ! A module descriptor is generally treated no differently to any other class or ! resource file. A module descriptor may be present under a versioned area but ! not present under the top-level directory. This ensures, for example, only Java ! 8 versioned classes can be present under the top-level directory while Java 9 ! versioned classes (including, or perhaps only, the module descriptor) can be ! present under the `9` versioned directory. ! ! Any versioned module descriptor that presides over a lesser versioned module ! descriptor or that at the top-level, `M` say, must be identical to `M`, with two ! exceptions: ! ! 1. the presiding versioned descriptor can have different non-`transitive` ! `requires` clauses of `java.*` and `jdk.*` modules; and ! 2. the presiding versioned descriptor can have different `uses` clauses, even of ! service types defined outside of `java.*` and `jdk.*` modules. ! ! Tooling, such as the `jar` tool, should perform such verification of versioned ! module descriptors but a Java runtime is not required to perform any ! verification. []{#The_META-INF_directory}The META-INF directory ------------------------------------------------- The following files/directories in the META-INF directory are recognized
*** 94,103 **** --- 229,243 ---- - `services/` This directory stores all the service provider configuration files. + - `versions/` + + This directory contains underneath it versioned class and resource files + for a [multi-release](#Multi-release) JAR file. + []{#Name-Value_pairs_and_Sections}Name-Value pairs and Sections --------------------------------------------------------------- Before we go to the details of the contents of the individual configuration files, some format convention needs to be defined. In most
*** 213,222 **** --- 353,367 ---- URLs of the libraries that this application needs. URLs are separated by one or more spaces. The application class loader uses the value of this attribute to construct its internal search path. See [Class-Path Attribute](#classpath) section for details. + - Multi-Release: This attribute defines whether this JAR file is a + [multi-release](#Modular-multi-release) JAR file. If the value is "true" + , case is ignored, then the JAR file will be processed by the Java + runtime and tooling as a multi-release JAR file. Otherwise, if the + value is anything other than "true" then this attribute is ignored. - attribute defined for stand-alone applications: This attribute is used by stand-alone applications that are bundled into executable jar files which can be invoked by the java runtime directly by running "`java -jar x.jar`". - Main-Class: The value of this attribute is the class name of the
*** 866,872 **** --------------------------------------- <meta charset="utf-8" /> ! [Copyright &copy;](../../../legal/copyright.html) ! 1993, 2017, Oracle and/or its affiliates. All rights reserved. \ No newline at end of file --- 1011,1017 ---- --------------------------------------- <meta charset="utf-8" /> ! *[Copyright](../../../legal/SMICopyright.html) &copy; 1993, 2017, Oracle ! and/or its affiliates. All rights reserved.* \ No newline at end of file
< prev index next >