RFR: 8228773: URLClassLoader constructors should include API note warning that the parent should not be null [v4]

[Jaikiran Pai]

> Can I please get a review of this doc-only change which proposes to add an `@apiNote` on the constructors of `URLClassLoader` and `SecureClassLoader` to explain the current implementation of these constructors? This addresses https://bugs.openjdk.org/browse/JDK-8228773?
> 
> As noted in that issue, this updated documentation is to help applications be aware that a `null` value which represents the bootstrap class loader when passed for `parent` class loader will mean that the constructed `URLClassLoader` may not be able to load all platform classes.
> 
> Specifically, only a specific set of modules are mapped (at JDK build time) to the bootstrap class loader. Some modules like `java.sql` are visible to the platform class loader but not to the bootstrap classloader. The distinction between these class loaders is explained in the API documentation of `ClassLoader` class https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/ClassLoader.html#builtinLoaders.
> 
> Using `null` (which represents a bootstrap class loader) for `parent` when constructing the `URLClassLoader` then means that the class loader would not be able to load some of these platform classes. For example, consider:
> 
> 
> import java.net.*;
> 
> public class Test {
>     public static void main(String[] args) throws Exception {
>         System.out.println("testing against Java " + System.getProperty("java.version"));
> 
>         final ClassLoader cl = new URLClassLoader(new URL[0], null);
>         final Class<?> klass = cl.loadClass("java.sql.ResultSet"); // load a platform class that belongs to the java.sql module
>         System.out.println("loaded " + klass + " using classloader: " + klass.getClassLoader());
> 
>     }
> }
> 
> which constructs the `URLClassLoader` with the bootstrap class loader as its parent and then attempts to load a platform class `java.sql.ResultSet`. Since this class' module is mapped to the platform class loader and not the bootstrap class loader, running this code against Java 9+ will result in a `ClassNotFoundException`:
> 
> 
> testing against Java 24
> Exception in thread "main" java.lang.ClassNotFoundException: java.sql.ResultSet
>     at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:349)
>     at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:557)
>     at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:490)
>     at Test.main(Test.java:8)
> 
> 
> No new tests have been introduced and existing tests in tier1, tier2 and tier3 continue to pass.
> 
> Once we settle on th...

Jaikiran Pai has updated the pull request incrementally with three additional commits since the last revision:

 - replace system class loader reference with bootstrap class loader
 - remove "the"
 - {@code null} instead of null

-------------

Changes:
  - all: https://git.openjdk.org/jdk/pull/25517/files
  - new: https://git.openjdk.org/jdk/pull/25517/files/12f70566..9897bec3

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=25517&range=03
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=25517&range=02-03

  Stats: 18 lines in 2 files changed: 0 ins; 0 del; 18 mod
  Patch: https://git.openjdk.org/jdk/pull/25517.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/25517/head:pull/25517

PR: https://git.openjdk.org/jdk/pull/25517