RFRs for 8166914, 8165782 and 8166735 related to multi-release JAR specification

[Paul Sandoz]

Hi,

Please review these specification clarifications for multi-release JARs. They 
are small and two are closely interrelated so though it would be best to 
aggregate them in one email.

Thanks,
Paul.


8166914 URLClassLoader spec needs to mention that it's MR-aware

diff -r 52d732262bfa src/java.base/share/classes/java/net/URLClassLoader.java
--- a/src/java.base/share/classes/java/net/URLClassLoader.java  Thu Nov 03 
13:06:24 2016 -0700
+++ b/src/java.base/share/classes/java/net/URLClassLoader.java  Thu Nov 03 
15:35:29 2016 -0700
@@ -71,6 +71,10 @@
  * <p>
  * The classes that are loaded are by default granted permission only to
  * access the URLs specified when the URLClassLoader was created.
+ * <p>
+ * This class loader supports the loading of classes from the contents of a
+ * multi-release JAR file that is referred to by a given URL. (See
+ * {@link JarFile} for further details on multi-release JAR files.)
  *
  * @author  David Connelly
  * @since   1.2



8165782 java.util.jar.JarFile.runtimeVersion() spec needs clarification

diff -r 3faad5a1703e src/java.base/share/classes/java/util/jar/JarFile.java
--- a/src/java.base/share/classes/java/util/jar/JarFile.java    Thu Nov 03 
14:45:14 2016 -0700
+++ b/src/java.base/share/classes/java/util/jar/JarFile.java    Thu Nov 03 
15:35:07 2016 -0700
@@ -192,9 +192,10 @@
     public static final String MANIFEST_NAME = META_INF + "MANIFEST.MF";

     /**
-     * The version that represents the unversioned configuration of a 
multi-release jar file.
+     * Returns the version that represents the unversioned configuration of a
+     * multi-release jar file.
      *
-     * @return Runtime.Version that represents the unversioned configuration
+     * @return the version that represents the unversioned configuration
      *
      * @since 9
      */
@@ -203,13 +204,16 @@
     }

     /**
-     * The version that represents the effective runtime versioned 
configuration of a
-     * multi-release jar file.  In most cases, {@code runtimeVersion()} is 
equal to
-     * {@code Runtime.version()}.  However, if the {@code 
jdk.util.jar.version} property is set,
-     * {@code runtimeVersion()} is derived from that property and may not be 
equal to
-     * {@code Runtime.version()}.
+     * Returns the version that represents the effective runtime versioned
+     * configuration of a multi-release jar file.
+     * <p>
+     * By default the major version number of the returned {@code Version} will
+     * be equal to the major version number of {@code Runtime.version()}.
+     * However, if the {@code jdk.util.jar.version} property is set, the
+     * returned {@code Version} is derived from that property and major version
+     * numbers may not be equal.
      *
-     * @return Runtime.Version that represents the runtime versioned 
configuration
+     * @return the version that represents the runtime versioned configuration
      *
      * @since 9
      */



8166735 JarFile#getVersion spec clarification for unversioned jars

diff -r 605bff618963 src/java.base/share/classes/java/util/jar/JarFile.java
--- a/src/java.base/share/classes/java/util/jar/JarFile.java    Thu Nov 03 
15:04:13 2016 -0700
+++ b/src/java.base/share/classes/java/util/jar/JarFile.java    Thu Nov 03 
15:27:29 2016 -0700
@@ -339,6 +339,10 @@

     /**
      * Returns the maximum version used when searching for versioned entries.
+     * <p>
+     * If this {@code JarFile} is not a multi-release jar file or is not
+     * configured to be processed as such, then the version returned will be 
the
+     * same as that returned from {@link #baseVersion()}.
      *
      * @return the maximum version
      * @since 9