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

[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 the proposed text, I'll file a CSR for this change. I've marked the issue as fix version "26" since there's no rush for this change. But if we settle down on this text and the change looks good, this week, then I'll go ahead and propose this for 25.

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

Commit messages:
 - 8228773: URLClassLoader constructors should include API note warning that the parent should not be null

Changes: https://git.openjdk.org/jdk/pull/25517/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=25517&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8228773
  Stats: 45 lines in 2 files changed: 30 ins; 0 del; 15 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