--- old/src/java.base/share/specs/jar/jar.md 2017-05-05 09:44:31.000000000 -0700 +++ new/src/java.base/share/specs/jar/jar.md 2017-05-05 09:44:31.000000000 -0700 @@ -1,11 +1,37 @@ -# JAR File Specification +--- +# 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) @@ -48,21 +74,130 @@ []{#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 +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. -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. +### []{#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 ------------------------------------------------- @@ -96,6 +231,11 @@ 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 --------------------------------------------------------------- @@ -215,6 +355,11 @@ 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 @@ -868,5 +1013,5 @@ -[Copyright ©](../../../legal/copyright.html) -1993, 2017, Oracle and/or its affiliates. All rights reserved. \ No newline at end of file +*[Copyright](../../../legal/SMICopyright.html) © 1993, 2017, Oracle +and/or its affiliates. All rights reserved.* \ No newline at end of file