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