--- a/jdk/src/java.base/share/classes/java/lang/ClassLoader.java Thu Jun 22 15:53:24 2017 +0200
+++ b/jdk/src/java.base/share/classes/java/lang/ClassLoader.java Wed Jul 05 18:22:22 2017 -0700
@@ -92,12 +92,20 @@
* <p> Class loaders may typically be used by security managers to indicate
* security domains.
*
+ * <p> In addition to loading classes, a class loader is also responsible for
+ * locating resources. A resource is some data (a "{@code .class}" file,
+ * configuration data, or an image for example) that is identified with an
+ * abstract '/'-separated path name. Resources are typically packaged with an
+ * application or library so that they can be located by code in the
+ * application or library. In some cases, the resources are included so that
+ * they can be located by other libraries.
+ *
* <p> The {@code ClassLoader} class uses a delegation model to search for
* classes and resources. Each instance of {@code ClassLoader} has an
- * associated parent class loader. When requested to find a class or
- * resource, a {@code ClassLoader} instance will delegate the search for the
- * class or resource to its parent class loader before attempting to find the
- * class or resource itself.
+ * associated parent class loader. When requested to find a class or
+ * resource, a {@code ClassLoader} instance will usually delegate the search
+ * for the class or resource to its parent class loader before attempting to
+ * find the class or resource itself.
*
* <p> Class loaders that support concurrent loading of classes are known as
* <em>{@linkplain #isRegisteredAsParallelCapable() parallel capable}</em> class
@@ -128,11 +136,13 @@
* classes and JDK-specific run-time classes that are defined by the
* platform class loader or its ancestors.
* <p> To allow for upgrading/overriding of modules defined to the platform
- * class loader, and where classes in the upgraded version link to
- * classes in modules defined to the application class loader, the
- * platform class loader may delegate to the application class loader.
- * In other words, classes in named modules defined to the application
- * class loader may be visible to the platform class loader. </li>
+ * class loader, and where upgraded modules read modules defined to class
+ * loaders other than the platform class loader and its ancestors, then
+ * the platform class loader may have to delegate to other class loaders,
+ * the application class loader for example.
+ * In other words, classes in named modules defined to class loaders
+ * other than the platform class loader and its ancestors may be visible
+ * to the platform class loader. </li>
* <li><p>{@linkplain #getSystemClassLoader() System class loader}.
* It is also known as <em>application class loader</em> and is distinct
* from the platform class loader.
@@ -497,7 +507,7 @@
*
* <li><p> Invoke the {@link #loadClass(String) loadClass} method
* on the parent class loader. If the parent is {@code null} the class
- * loader built-in to the virtual machine is used, instead. </p></li>
+ * loader built into the virtual machine is used, instead. </p></li>
*
* <li><p> Invoke the {@link #findClass(String)} method to find the
* class. </p></li>
@@ -680,8 +690,9 @@
* This method should be overridden by class loader implementations that
* follow the delegation model for loading classes, and will be invoked by
* the {@link #loadClass loadClass} method after checking the
- * parent class loader for the requested class. The default implementation
- * throws a {@code ClassNotFoundException}.
+ * parent class loader for the requested class.
+ *
+ * @implSpec The default implementation throws {@code ClassNotFoundException}.
*
* @param name
* The <a href="#name">binary name</a> of the class
@@ -1126,8 +1137,9 @@
putIfAbsent(pname, (certs == null? nocerts:certs));
}
if (pcerts != null && !compareCerts(pcerts, certs)) {
- throw new SecurityException("class \""+ name +
- "\"'s signer information does not match signer information of other classes in the same package");
+ throw new SecurityException("class \"" + name
+ + "\"'s signer information does not match signer information"
+ + " of other classes in the same package");
}
}
@@ -1328,12 +1340,7 @@
* that is independent of the location of the code.
*
* <p> The name of a resource is a '{@code /}'-separated path name that
- * identifies the resource.
- *
- * <p> This method will first search the parent class loader for the
- * resource; if the parent is {@code null} the path of the class loader
- * built-in to the virtual machine is searched. That failing, this method
- * will invoke {@link #findResource(String)} to find the resource. </p>
+ * identifies the resource. </p>
*
* <p> Resources in named modules are subject to the encapsulation rules
* specified by {@link Module#getResourceAsStream Module.getResourceAsStream}.
@@ -1343,6 +1350,11 @@
* opened} unconditionally (even if the caller of this method is in the
* same module as the resource). </p>
*
+ * @implSpec The default implementation will first search the parent class
+ * loader for the resource; if the parent is {@code null} the path of the
+ * class loader built into the virtual machine is searched. If not found,
+ * this method will invoke {@link #findResource(String)} to find the resource.
+ *
* @apiNote Where several modules are defined to the same class loader,
* and where more than one module contains a resource with the given name,
* then the ordering that modules are searched is not specified and may be
@@ -1386,10 +1398,7 @@
* that is independent of the location of the code.
*
* <p> The name of a resource is a {@code /}-separated path name that
- * identifies the resource.
- *
- * <p> The delegation order for searching is described in the documentation
- * for {@link #getResource(String)}. </p>
+ * identifies the resource. </p>
*
* <p> Resources in named modules are subject to the encapsulation rules
* specified by {@link Module#getResourceAsStream Module.getResourceAsStream}.
@@ -1397,7 +1406,15 @@
* name ending with "{@code .class}", this method will only find resources in
* packages of named modules when the package is {@link Module#isOpen(String)
* opened} unconditionally (even if the caller of this method is in the
- * same module as the resource).</p>
+ * same module as the resource). </p>
+ *
+ * @implSpec The default implementation will first search the parent class
+ * loader for the resource; if the parent is {@code null} the path of the
+ * class loader built into the virtual machine is searched. It then
+ * invokes {@link #findResources(String)} to find the resources with the
+ * name in this class loader. It returns an enumeration whose elements
+ * are the URLs found by searching the parent class loader followed by
+ * the elements found with {@code findResources}.
*
* @apiNote Where several modules are defined to the same class loader,
* and where more than one module contains a resource with the given name,
@@ -1423,8 +1440,6 @@
* If I/O errors occur
* @throws NullPointerException If {@code name} is {@code null}
*
- * @see #findResources(String)
- *
* @since 1.2
* @revised 9
* @spec JPMS
@@ -1452,9 +1467,6 @@
* <p> The name of a resource is a {@code /}-separated path name that
* identifies the resource.
*
- * <p> The search order is described in the documentation for {@link
- * #getResource(String)}.
- *
* <p> The resources will be located when the returned stream is evaluated.
* If the evaluation results in an {@code IOException} then the I/O
* exception is wrapped in an {@link UncheckedIOException} that is then
@@ -1468,6 +1480,10 @@
* opened} unconditionally (even if the caller of this method is in the
* same module as the resource). </p>
*
+ * @implSpec The default implementation invokes {@link #getResources(String)
+ * getResources} to find all the resources with the given name and returns
+ * a stream with the elements in the enumeration as the source.
+ *
* @apiNote When overriding this method it is recommended that an
* implementation ensures that any delegation is consistent with the {@link
* #getResource(java.lang.String) getResource(String)} method. This should
@@ -1485,8 +1501,6 @@
*
* @throws NullPointerException If {@code name} is {@code null}
*
- * @see #findResources(String)
- *
* @since 9
*/
public Stream<URL> resources(String name) {
@@ -1505,7 +1519,7 @@
/**
* Finds the resource with the given name. Class loader implementations
- * should override this method to specify where to find resources.
+ * should override this method.
*
* <p> For resources in named modules then the method must implement the
* rules for encapsulation specified in the {@code Module} {@link
@@ -1514,6 +1528,8 @@
* modules unless the package is {@link Module#isOpen(String) opened}
* unconditionally. </p>
*
+ * @implSpec The default implementation returns {@code null}.
+ *
* @param name
* The resource name
*
@@ -1534,8 +1550,7 @@
/**
* Returns an enumeration of {@link java.net.URL URL} objects
* representing all the resources with the given name. Class loader
- * implementations should override this method to specify where to load
- * resources from.
+ * implementations should override this method.
*
* <p> For resources in named modules then the method must implement the
* rules for encapsulation specified in the {@code Module} {@link
@@ -1544,6 +1559,9 @@
* modules unless the package is {@link Module#isOpen(String) opened}
* unconditionally. </p>
*
+ * @implSpec The default implementation returns an enumeration that
+ * contains no elements.
+ *
* @param name
* The resource name
*
@@ -1898,7 +1916,8 @@
// the system class loader is the built-in app class loader during startup
return getBuiltinAppClassLoader();
case 3:
- throw new InternalError("getSystemClassLoader should only be called after VM booted");
+ String msg = "getSystemClassLoader should only be called after VM booted";
+ throw new InternalError(msg);
case 4:
// system fully initialized
assert VM.isBooted() && scl != null;
@@ -2145,7 +2164,7 @@
* @revised 9
* @spec JPMS
*
- * @see <a href="../../../technotes/guides/jar/jar.html#sealing">
+ * @see <a href="{@docRoot}/../specs/jar/jar.html#sealing">
* The JAR File Specification: Package Sealing</a>
*/
protected Package definePackage(String name, String specTitle,