Summary

Clarify the spec of ClassLoader::getClassLoadingLock that this method returns this ClassLoader object if it is a non-parallel-capable class loader.

Problem

The spec of ClassLoader::getClassLoadingLock is unclear that this method is intended for parallel-capable class loader implementations to provide an alternate implementation. For non-parallel-capable class loaders, this method should return this ClassLoader object. The javadoc uses "the default implementation" which could be interpreted that non-parallel-capable class loaders can also override this implementation, which is not the intent. See https://openjdk.org/groups/core-libs/ClassLoaderProposal.html.

Solution

Clarify the spec of ClassLoader::getClassLoadingLock and make it clear that the ClassLoader subclasses are expected to implement per the specification.

Specification

Update the spec of ClassLoader::getClassLoadingLock as follows:

diff --git a/src/java.base/share/classes/java/lang/ClassLoader.java b/src/java.base/share/classes/java/lang/ClassLoader.java
index 2e3d9e550e7..62d0d41a0af 100644
--- a/src/java.base/share/classes/java/lang/ClassLoader.java
+++ b/src/java.base/share/classes/java/lang/ClassLoader.java
@@ -647,11 +647,17 @@ public abstract class ClassLoader {

     /**
      * Returns the lock object for class loading operations.
-     * For backward compatibility, the default implementation of this method
-     * behaves as follows. If this ClassLoader object is registered as
-     * parallel capable, the method returns a dedicated object associated
-     * with the specified class name. Otherwise, the method returns this
-     * ClassLoader object.
+     *
+     * @implSpec
+     * If this {@code ClassLoader} object is registered as parallel capable,
+     * this method returns a dedicated object associated with the specified
+     * class name. Otherwise, this method returns this {@code ClassLoader} object.
+     *
+     * @apiNote
+     * This method allows parallel capable class loaders to implement
+     * finer-grained locking schemes such that multiple threads may load classes
+     * concurrently without deadlocks.  For non-parallel-capable class loaders,
+     * the {@code ClassLoader} object is synchronized on during the class loading
+     * operations.  Class loaders with non-hierarchical delegation should be
+     * {@linkplain #registerAsParallelCapable() registered as parallel capable}
+     * to prevent deadlocks.
      *
      * @param  className
      *         The name of the to-be-loaded class
@@ -659,7 +665,7 @@ public abstract class ClassLoader {
      * @return the lock for class loading operations
      *
      * @throws NullPointerException
-     *         If registered as parallel capable and {@code className} is null
+     *         If registered as parallel capable and {@code className} is {@code null}
      *
      * @see #loadClass(String, boolean)
      *