RFR 8150681 Update JAR specification for multi-release jar files

[Paul Sandoz]

> On 5 May 2017, at 03:51, Alan Bateman <Alan.Bateman at oracle.com> wrote:
> 
> 
> 
> On 04/05/2017 22:14, Paul Sandoz wrote:
>> New update here:
>> 
>> http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8150681-jar-spec-markdown-with-mr-jar/webrev/src/java.base/share/specs/jar/jar.md.sdiff.html <http://cr.openjdk.java.net/%7Epsandoz/jdk9/JDK-8150681-jar-spec-markdown-with-mr-jar/webrev/src/java.base/share/specs/jar/jar.md.sdiff.html>
>> 
>> I accepted most comments directly. I shuffled around the paragraphs in the modular jar section, partially in preparation for any changes and further explanations for automatic modules.
>> 
> This looks much better.
> 
> L85 adds the word "security" which I don't think was in the previous iteration. Do mean the signature related files detailed in the "Signed JAR File" section? If so then they apply to modular JAR files too. The simplest might be to just drop the word "security" from the sentence.
> 

Done.


> L91-95 - This could link to ModuleFinder.of(Path...) so that it can avoid the details as to how the module name and packages are derived.
> 

Thanks, yes, that simplifies and reduced possible updated.


> L177 still has "A non-exported public or protected class". Did you consider changing this to "A public or protected class in a non-exported package”?

Sorry, i forgot to apply with the other reshuffling going on. Done.

See below for the diff on the previous changeset.

Paul.

diff -r 8811f1594a29 src/java.base/share/specs/jar/jar.md
--- a/src/java.base/share/specs/jar/jar.md	Thu May 04 14:07:32 2017 -0700
+++ b/src/java.base/share/specs/jar/jar.md	Fri May 05 09:43:14 2017 -0700
@@ -81,18 +81,17 @@
 modular JAR files.)

 A modular JAR file deployed on the module path, as opposed to the class path, is
-a module.  Dependences and service providers are declared in the module
-descriptor.  The [JAR Manifest](#JAR_Manifest) is ignored as is any security or
+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 configurations under
+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 deployed on the module path is an *automatic module*, where
-a module name and a module declaration is synthesized from the JAR file name and
-it's contents.  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.
+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
 -----------------------------------------
@@ -141,12 +140,13 @@
 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 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.
+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
@@ -174,7 +174,7 @@
 module descriptor, `module-info.class`, in the top-level directory (as for
 a [modular](#Modular) JAR file), or directly in a versioned directory.

-A non-exported public or protected class (whose package is not declared as
+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.
@@ -195,11 +195,6 @@
 2. the presiding versioned descriptor can have different `uses` clauses, even of
    service types defined outside of `java.*` and `jdk.*` modules.

-If a modular multi-release JAR is deployed on the module path then a class
-loader loading classes from that JAR file will behave, in regards to searching
-for classes, in the same manner as that specified for a multi-release JAR
-deployed on the class path.
-
 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.