Improve documentation

Author: basil

core/src/main/java/hudson/PluginManager.java

@@ -2408,6 +2408,18 @@ public static final class UberClassLoader extends DelegatingClassLoader {
         /** Cache of loaded, or known to be unloadable, classes. */
         private final ConcurrentMap<String, Optional<Class<?>>> loaded = new ConcurrentHashMap<>();
 
+        /**
+         * The servlet container's {@link ClassLoader} (the parent of Jenkins core) is
+         * parallel-capable and maintains its own growing {@link Map} of {@link
+         * ClassLoader#getClassLoadingLock} objects per class name for every load attempt (including
+         * misses), and we cannot override this behavior. Wrap the servlet container {@link
+         * ClassLoader} in {@link ExistenceCheckingClassLoader} to avoid calling {@link
+         * ClassLoader#getParent}'s {@link ClassLoader#loadClass(String, boolean)} at all for misses
+         * by first checking if the resource exists. If the resource does not exist, we immediately
+         * throw {@link ClassNotFoundException}. As a result, the servlet container's {@link
+         * ClassLoader} is never asked to try and fail, and it never creates/retains lock objects
+         * for those misses.
+         */
         public UberClassLoader(List<PluginWrapper> activePlugins) {
             super("UberClassLoader", new ExistenceCheckingClassLoader(PluginManager.class.getClassLoader()));
             this.activePlugins = activePlugins;

core/src/main/java/hudson/util/DelegatingClassLoader.java

@@ -5,12 +5,22 @@
 import org.kohsuke.accmod.restrictions.NoExternalUse;
 
 /**
- * A {@link ClassLoader} that does not define any classes itself but delegates class loading
- * to other class loaders. It first attempts to load classes via its {@code getParent()} class loader,
- * then falls back to {@code findClass} to allow for custom delegation logic.
+ * A {@link ClassLoader} that does not define any classes itself but delegates class loading to other class loaders to
+ * avoid the JDK's per-class-name locking and lock retention.
  * <p>
- * This class can also serve as the parent class loader for other class loaders that follow
- * the standard delegation model.
+ * This class first attempts to load classes via its {@link ClassLoader#getParent} class loader, then falls back to
+ * {@link ClassLoader#findClass} to allow for custom delegation logic.
+ * <p>
+ * In a parallel-capable {@link ClassLoader{, the JDK maintains a per-name lock object indefinitely. In Jenkins, many
+ * class loading misses across many loaders can accumulate hundreds of thousands of such locks, retaining significant
+ * memory. This loader never defines classes and bypasses {@link ClassLoader}'s default {@code loadClass} locking; it
+ * delegates to the parent first and then to {@code findClass} for custom delegation.
+ * <p>
+ * The actual defining loader (parent or a delegate) still performs the necessary synchronization and class definition.
+ * A runtime guard ({@link #verify}) throws if this loader ever becomes the defining loader.
+ * <p>
+ * Subclasses must not call {@code defineClass}; implement delegation in {@code findClass} if needed and do not mark
+ * subclasses as parallel-capable.
  *
  * @author Dmytro Ukhlov
  */
@@ -25,18 +35,14 @@ public DelegatingClassLoader(ClassLoader parent) {
     }
 
     /**
-     * Overrides base implementation to skip unnecessary synchronization
-     *
-     * @param   name
-     *          The <a href="#binary-name">binary name</a> of the class
-     *
-     * @param   resolve
-     *          If {@code true} then resolve the class
+     * Parent-first delegation without synchronizing on {@link #getClassLoadingLock(String)}. This
+     * prevents creation/retention of per-name lock objects in a loader that does not define
+     * classes. The defining loader downstream still serializes class definition as required.
      *
-     * @return  The resulting {@code Class} object
-     *
-     * @throws  ClassNotFoundException
-     *          If the class could not be found
+     * @param name The binary name of the class
+     * @param resolve If {@code true} then resolve the class
+     * @return The resulting {@link Class} object
+     * @throws ClassNotFoundException If the class could not be found
      */
     @Override
     protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundException {
@@ -61,6 +67,12 @@ protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundE
         return c;
     }
 
+    /**
+     * Safety check to ensure this delegating loader never becomes the defining loader.
+     *
+     * <p>Fails fast if a subclass erroneously defines a class here, which would violate the
+     * delegation-only contract and could reintroduce locking/retention issues.
+     */
     protected Class<?> verify(Class<?> clazz) {
         if (clazz.getClassLoader() == this) {
             throw new IllegalStateException("DelegatingClassLoader must not be the defining loader: " + clazz.getName());

core/src/main/java/hudson/util/ExistenceCheckingClassLoader.java

@@ -1,20 +1,30 @@
 package hudson.util;
 
 import java.util.Objects;
+import jenkins.util.URLClassLoader2;
 import org.kohsuke.accmod.Restricted;
 import org.kohsuke.accmod.restrictions.NoExternalUse;
 
 /**
- * A class loader that verifies the existence of a class resource before attempting to load the class.
- * <p>
- * This implementation overrides {@link #loadClass(String, boolean)} and uses {@link #getResource(String)}
- * to check whether the corresponding <code>.class</code> file is available in the classpath.
- * If the resource is not found, a {@link ClassNotFoundException} is thrown immediately.
- * </p>
+ * A {@link ClassLoader} that verifies the existence of a {@code .class} resource before attempting
+ * to load the class. Intended to sit in front of servlet container loaders we do not control.
  *
- * <p>This approach can be useful in environments where conditional class availability
- * must be verified without triggering side effects from the loading process.</p>
+ * <p>This implementation overrides {@link #loadClass(String, boolean)} and uses {@link
+ * #getResource(String)} to check whether the corresponding <code>.class</code> file is available in
+ * the classpath. If the resource is not found, a {@link ClassNotFoundException} is thrown
+ * immediately.
  *
+ * <p>Parallel-capable parent loaders retain a per-class-name lock object for every load attempt,
+ * including misses. By checking getResource(name + ".class") first and throwing {@link
+ * ClassNotFoundException} on absence, we avoid calling {@code loadClass} on misses, thus preventing
+ * the parent from populating its lock map for nonexistent classes.
+ *
+ * <p>This class is only needed in {@link hudson.PluginManager.UberClassLoader}. It is unnecessary
+ * for plugin {@link ClassLoader}s (because {@link URLClassLoader2} mitigates lock retention via
+ * {@link ClassLoader#getClassLoadingLock}) and redundant for delegators (because {@link
+ * DelegatingClassLoader} already avoids base locking).
+ *
+ * @author Dmytro Ukhlov
  * @see ClassLoader
  * @see #getResource(String)
  */
@@ -29,6 +39,11 @@ public ExistenceCheckingClassLoader(ClassLoader parent) {
         super(Objects.requireNonNull(parent));
     }
 
+    /**
+     * Short-circuits misses by checking for the {@code .class} resource prior to delegation.
+     * Successful loads behave exactly as the parent would; misses do not touch the parent's
+     * per-name lock map.
+     */
     @Override
     protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundException {
         // Add support for loading of JaCoCo dynamic instrumentation classes

core/src/main/java/jenkins/util/URLClassLoader2.java

@@ -71,12 +71,16 @@ public Class<?> findLoadedClass2(String name) {
     }
 
     /**
-     * Use String.intern() to create ClassLoader/className unique lock object which can be GCed
+     * Replace the JDK's per-name lock map with a GC-collectable lock object.
      *
-     * @param className
-     *         The name of the to-be-loaded class
+     * <p>Parallel-capable {@link ClassLoader} implementations keep a distinct lock object per class
+     * name indefinitely, which can retain huge maps when there are many misses. Returning an
+     * interned {@link String} keyed by this loader and the class name preserves mutual exclusion
+     * for a given (loader, name) pair but allows the JVM to reclaim the lock when no longer
+     * referenced. Interned Strings are heap objects and GC-eligible on modern JDKs (7+).
      *
-     * @return lock object, unique per classloader/classname combination
+     * @param className the binary name of the class being loaded (must not be null)
+     * @return a lock object unique to this classloader/class pair
      */
     @Override
     public Object getClassLoadingLock(String className) {