jdk-sandbox: comparison jdk/src/java.base/share/classes/java/lang/ClassLoader.java

equal deleted inserted replaced

-:853b91521c30
+:33342314ce89
 * classes.
 *
 * <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
+* associated parent class loader. When requested to find a class or
-* resource, a {@code ClassLoader} instance will delegate the search for the
+* resource, a {@code ClassLoader} instance will usually delegate the search
-* class or resource to its parent class loader before attempting to find the
+* for the class or resource to its parent class loader before attempting to
-* class or resource itself.
+* 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
 * loaders and are required to register themselves at their class initialization
 * time by invoking the {@link
 *     that can be used as the parent of a {@code ClassLoader} instance.
 *     Platform classes include Java SE platform APIs, their implementation
 *     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
+*     class loader, and where upgraded modules read modules defined to class
-*     classes in modules defined to the application class loader, the
+*     loaders other than the platform class loader and its ancestors, then
-*     platform class loader may delegate to the application class loader.
+*     the platform class loader may have to delegate to other class loaders,
-*     In other words, classes in named modules defined to the application
+*     the application class loader for example.
-*     class loader may be visible to the platform class loader. </li>
+*     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.
 *     The system class loader is typically used to define classes on the
 *     application class path, module path, and JDK-specific tools.
 *   <li><p> Invoke {@link #findLoadedClass(String)} to check if the class
 *   has already been loaded.  </p></li>
 *
 *   <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>
 *
 * </ol>
 /**
 * Finds the class with the specified <a href="#name">binary name</a>.
 * 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
+* parent class loader for the requested class.
-* throws a {@code ClassNotFoundException}.
+*
+* @implSpec The default implementation throws {@code ClassNotFoundException}.
 *
 * @param  name
 *         The <a href="#name">binary name</a> of the class
 *
 * @return  The resulting {@code Class} object
 } else {
 pcerts = ((ConcurrentHashMap<String, Certificate[]>)package2certs).
 putIfAbsent(pname, (certs == null? nocerts:certs));
 }
 if (pcerts != null && !compareCerts(pcerts, certs)) {
-throw new SecurityException("class \""+ name +
+throw new SecurityException("class \"" + name
-"\"'s signer information does not match signer information of other classes in the same package");
++ "\"'s signer information does not match signer information"
++ " of other classes in the same package");
 }
 }
 /**
 * check to make sure the certs for the new class (certs) are the same as
 * Finds the resource with the given name.  A resource is some data
 * (images, audio, text, etc) that can be accessed by class code in a way
 * 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.
+* identifies the resource. </p>
-*
-* <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>
 *
 * <p> Resources in named modules are subject to the encapsulation rules
 * specified by {@link Module#getResourceAsStream Module.getResourceAsStream}.
 * Additionally, and except for the special case where the resource has a
 * 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>
 *
+* @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
 * very unpredictable.
 * When overriding this method it is recommended that an implementation
 * Finds all the resources with the given name. A resource is some data
 * (images, audio, text, etc) that can be accessed by class code in a way
 * 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.
+* identifies the resource. </p>
-*
-* <p> The delegation order for searching is described in the documentation
-* for {@link #getResource(String)}.  </p>
 *
 * <p> Resources in named modules are subject to the encapsulation rules
 * specified by {@link Module#getResourceAsStream Module.getResourceAsStream}.
 * Additionally, and except for the special case where the resource has a
 * 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,
 * then the ordering is not specified and may be very unpredictable.
 * When overriding this method it is recommended that an
 *
 * @throws  IOException
 *          If I/O errors occur
 * @throws  NullPointerException If {@code name} is {@code null}
 *
-* @see  #findResources(String)
-*
 * @since  1.2
 * @revised 9
 * @spec JPMS
 */
 public Enumeration<URL> getResources(String name) throws IOException {
 * location of the code.
 *
 * <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
 * thrown.
 *
 * 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>
 *
+* @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
 * ensure that the first element returned by the stream is the same
 * resource that the {@code getResource(String)} method would return.
 *          for which a {@code URL} cannot be constructed, are in a package
 *          that is not opened unconditionally, or access to the resource
 *          is denied by the security manager, will not be in the stream.
 *
 * @throws  NullPointerException If {@code name} is {@code null}
-*
-* @see  #findResources(String)
 *
 * @since  9
 */
 public Stream<URL> resources(String name) {
 Objects.requireNonNull(name);
 return StreamSupport.stream(si, characteristics, false);
 }
 /**
 * 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
 * Module#getResourceAsStream getResourceAsStream} method. Additionally,
 * it must not find non-"{@code .class}" resources in packages of named
 * modules unless the package is {@link Module#isOpen(String) opened}
 * unconditionally. </p>
 *
+* @implSpec The default implementation returns {@code null}.
+*
 * @param  name
 *         The resource name
 *
 * @return  {@code URL} object for reading the resource; {@code null} if
 *          the resource could not be found, a {@code URL} could not be
 }
 /**
 * 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
+* implementations should override this method.
-* resources from.
 *
 * <p> For resources in named modules then the method must implement the
 * rules for encapsulation specified in the {@code Module} {@link
 * Module#getResourceAsStream getResourceAsStream} method. Additionally,
 * it must not find non-"{@code .class}" resources in packages of named
 * 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
 *
 * @return  An enumeration of {@link java.net.URL URL} objects for
 case 1:
 case 2:
 // 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;
 SecurityManager sm = System.getSecurityManager();
 if (sm != null) {

changeset 45652	33342314ce89
parent 45527	09cded555a99
child 45663	4a0cbf8f2474