Java ClassLoader Deep Dive: Custom Classloaders, Plugin Systems, and Hot Reload in Production

3. Parent-Delegation Model Explained

When a ClassLoader is asked to load a class, the default behavior encoded in ClassLoader.loadClass() follows a strict protocol: delegate to parent first. Only if the parent fails to find the class does the child attempt to load it from its own sources. This propagates all the way up to Bootstrap, meaning the JDK core classes are always loaded by Bootstrap and are shared across the entire JVM.

This design provides two critical guarantees: security (malicious code can't replace java.lang.String with a rogue version, because Bootstrap always wins) and class identity consistency (the same String class is used everywhere, so instanceof checks and casts work correctly across class boundaries). The model breaks down — and ClassCastExceptions become mysterious — when the same class is loaded by two different ClassLoaders. An object of type com.example.Foo loaded by ClassLoader A is not the same type as com.example.Foo loaded by ClassLoader B, even if both loaded the exact same bytecode from the same JAR. They are different types in the JVM's type system.

4. URLClassLoader for Dynamic Plugin Loading

URLClassLoader is the standard JDK mechanism for loading classes from arbitrary JAR files or directories at runtime. Its constructor takes an array of URL objects pointing to your plugin JARs, and its parent is typically the Application ClassLoader (so the plugin can use your application's shared APIs). The key to plugin isolation is creating a separate URLClassLoader per plugin rather than one shared loader for all plugins.

// Simple plugin loader using URLClassLoader
public class PluginLoader {
    private final Map<String, URLClassLoader> pluginLoaders = new ConcurrentHashMap<>();
    private final ClassLoader parentLoader;

    public PluginLoader() {
        // Parent = Application ClassLoader: plugin can see shared API classes
        this.parentLoader = PluginLoader.class.getClassLoader();
    }

    public Plugin load(String pluginId, Path pluginJar) throws Exception {
        URL jarUrl = pluginJar.toUri().toURL();
        // Each plugin gets its OWN classloader — full isolation
        URLClassLoader loader = new URLClassLoader(
            new URL[]{jarUrl}, parentLoader
        );
        pluginLoaders.put(pluginId, loader);

        // Load the plugin entry point — assumes all plugins implement Plugin interface
        Class<?> pluginClass = loader.loadClass("com.example.plugin.PluginImpl");
        return (Plugin) pluginClass.getDeclaredConstructor().newInstance();
    }

    public void unload(String pluginId) throws IOException {
        URLClassLoader loader = pluginLoaders.remove(pluginId);
        if (loader != null) {
            loader.close(); // Java 7+: releases file handles, allows GC of loaded classes
        }
    }
}

The critical detail is loader.close() on Java 7+. Before Java 7, URLClassLoaders held open file locks on the JAR files they loaded, preventing deletion or replacement of the JAR on Windows. close() releases those handles and signals to the GC that the classes loaded by this loader are eligible for collection — but only when no live references to those classes or their instances remain.

The Plugin interface in the cast must be loaded by the same classloader as the caller — the Application ClassLoader or a common ancestor. This is the "shared API contract" pattern: define your plugin interface in a module that is loaded by the parent ClassLoader, so both the host application and all plugins share the same type identity for that interface.

5. Class Isolation and Conflict Resolution

True isolation requires overriding the parent-delegation model for plugin-private classes while still delegating shared API classes to the parent. The standard URLClassLoader delegates everything to the parent first, meaning if the parent's classpath also contains jackson-databind:2.14, the plugin can't use its bundled 2.9 version — the parent wins every time. To fix this, you implement child-first loading by overriding loadClass().

The pattern is: for classes belonging to the shared API package, delegate to parent. For everything else, try the child's own classpath first, and only fall back to parent if not found locally. This is exactly how Tomcat's WebappClassLoader works — it loads your webapp's classes first, then delegates to the container's classloader, allowing different webapps to carry different versions of Commons-Lang without conflicts.

6. Custom ClassLoader Implementation

Implementing a child-first URLClassLoader requires overriding loadClass() with careful handling of the bootstrap classes that must always come from the JDK. Failing to whitelist java.* and javax.* will cause your plugin's JDK classes to be loaded by your custom loader, breaking instanceof checks across the entire JVM.

public class ChildFirstClassLoader extends URLClassLoader {
    // Packages that MUST be loaded by the parent (shared API + JDK)
    private static final List<String> PARENT_FIRST_PREFIXES = List.of(
        "java.", "javax.", "sun.", "com.example.plugin.api." // shared API package
    );

    public ChildFirstClassLoader(URL[] urls, ClassLoader parent) {
        super(urls, parent);
    }

    @Override
    protected Class<?> loadClass(String name, boolean resolve)
            throws ClassNotFoundException {
        // Always delegate JDK and shared API classes to parent
        for (String prefix : PARENT_FIRST_PREFIXES) {
            if (name.startsWith(prefix)) {
                return super.loadClass(name, resolve);
            }
        }

        synchronized (getClassLoadingLock(name)) {
            // Check if already loaded by this loader
            Class<?> alreadyLoaded = findLoadedClass(name);
            if (alreadyLoaded != null) return alreadyLoaded;

            // Try to load from THIS loader's URLs first (child-first)
            try {
                Class<?> clazz = findClass(name);
                if (resolve) resolveClass(clazz);
                return clazz;
            } catch (ClassNotFoundException e) {
                // Fall back to parent if not found locally
                return super.loadClass(name, resolve);
            }
        }
    }
}

The getClassLoadingLock(name) call is essential for thread safety — it returns a per-class-name lock object, preventing multiple threads from loading the same class simultaneously. Without it, you risk loading duplicate class definitions under concurrent plugin loading, which produces the same ClassCastException symptoms as the multiple-ClassLoader problem. Java's built-in loadClass() implementation uses this locking, so overriding loadClass() correctly requires maintaining it.

7. Hot Reload Pattern in Production

Hot reload means replacing a running module with a new version without JVM restart. The pattern is: detect change → create new ClassLoader pointing to the new JAR → load new class instances → atomically swap the reference → close the old ClassLoader. The atomic swap is typically done with a volatile reference or a read-write lock around the object that holds the plugin reference.

The lifecycle looks like: your PluginRegistry holds a volatile Plugin activePlugin. A file-watcher thread detects a new version of the plugin JAR. It creates a new ChildFirstClassLoader over the new JAR, loads and instantiates the plugin, calls activePlugin = newPlugin (atomic due to volatile), and then closes the old ClassLoader. In-flight requests using the old plugin instance finish normally; new requests pick up the new version. This is zero-downtime plugin reload.

8. WeakReferences, GC Leaks, and Metaspace

ClassLoader leaks are one of the most insidious memory problems in Java. The root cause: a ClassLoader is only eligible for GC when all classes it loaded have been unloaded, and a class is only unloaded when its ClassLoader is unreachable. If any strong reference to any class loaded by the ClassLoader survives (in a static field, a thread-local, a JDK cache, a third-party library's static registry), the ClassLoader — and all classes, bytecode, and interned strings it loaded — remains pinned in Metaspace forever.

Common culprits: JDBC drivers that register themselves in DriverManager (a JDK static), preventing the webapp's ClassLoader from unloading; ThreadLocal values holding objects whose class was loaded by the plugin ClassLoader — ThreadLocal entries are held by the thread, which is a GC root; java.util.logging handlers registered globally; and static fields in third-party libraries that cache class references.

The diagnostic tool is a heap dump analyzed with Eclipse MAT or VisualVM. Look for ClassLoader instances in the "Leak Suspects" report and trace the shortest path from GC roots to find the retaining reference. In Tomcat's context, this manifests as java.lang.OutOfMemoryError: Metaspace after a series of webapp redeployments — each redeploy creates a new ClassLoader that never gets collected because the previous ClassLoader is still referenced somewhere.

The fix pattern: use WeakReference<ClassLoader> in caches and registries so the GC can collect the ClassLoader when no strong references remain. For JDBC drivers, explicitly call DriverManager.deregisterDriver() in your plugin's shutdown hook. For ThreadLocals, always call remove() after the task completes — a missing ThreadLocal.remove() in a thread pool thread is a near-guaranteed ClassLoader leak in hot-reload scenarios.

9. OSGi-Style Isolation Without OSGi

OSGi (Open Services Gateway initiative) is the most sophisticated ClassLoader isolation framework in the Java ecosystem. Eclipse IDE, Adobe CQ/AEM, and many enterprise middleware platforms are built on it. OSGi's core innovation is a module graph: each bundle (JAR) declares which packages it exports (visible to other bundles) and which it imports (required from other bundles). The OSGi framework creates one ClassLoader per bundle, configured to see only the exported packages of its explicit dependencies — nothing more.

You can approximate this without the full OSGi container. The pattern: define an ExportedPackages annotation on your shared API modules, have a lightweight module registry that maps package prefixes to their "owning" ClassLoader, and configure each plugin's ClassLoader to consult the registry for cross-plugin package resolution before falling back to its own classpath. This is essentially what Gradle and Maven build tools do when running multi-project builds with isolated classpaths per subproject.

For most production plugin systems, the lightweight approach — child-first URLClassLoader with a well-defined shared API package delegated to the parent — provides 80% of OSGi's value with 5% of its complexity. Reserve full OSGi for systems where dynamic bundle versioning and fine-grained inter-bundle dependency management are genuine requirements.

10. Production War Stories

The Metaspace OOM that took down production: A fintech platform built a rule engine that loaded compliance rules as plugin JARs. Each rule update triggered a hot-reload. After 48 hours in production, the service died with OutOfMemoryError: Metaspace. The investigation revealed that each new plugin ClassLoader was loading slf4j-api (bundled inside the plugin JAR). SLF4J's LoggerFactory maintains a static WeakHashMap of logger bindings — but the map's key was a Class object from the plugin ClassLoader, and the map held a strong reference to the value (the logger binding), which held a strong reference back to the ClassLoader through its class. Classic circular reference defeating the WeakHashMap. The fix: exclude slf4j-api from plugin JARs entirely (move it to the parent ClassLoader's classpath) and let the parent provide logging infrastructure.

For patterns around managing concurrency in these dynamic loading scenarios, the Java Structured Concurrency guide covers how to scope plugin execution lifetimes and ensure safe teardown of in-flight work before ClassLoader disposal.

11. When NOT to Use Custom ClassLoaders

Java 9+ Module System (JPMS) does it better for static isolation: If your goal is isolating internal implementation packages within your own application — not loading JARs at runtime — the Java Platform Module System provides compile-time and runtime package encapsulation without the ClassLoader complexity. Prefer JPMS module-info.java declarations over custom ClassLoaders for this use case.

Microservices boundary is the right isolation unit: If each "plugin" has its own lifecycle, deployment cadence, and team ownership, deploy it as a separate microservice. Custom ClassLoaders provide isolation within a single JVM process — they don't replace service boundaries. Forcing them to do service-level isolation creates the complexity of both worlds.

GraalVM Native Image doesn't support them: If you're targeting GraalVM Native Image compilation for startup performance, custom ClassLoaders with runtime class loading are fundamentally incompatible — native compilation requires closed-world analysis of all reachable classes at build time. Plan your architecture accordingly if native compilation is on your roadmap.

Key Takeaways

• Three-tier ClassLoader hierarchy (Bootstrap → Platform → Application) with parent-delegation ensures JDK class consistency and security across the JVM.
• Per-plugin URLClassLoader provides JAR-level isolation — separate classloader per plugin enables independent versioning of transitive dependencies.
• Child-first loading requires careful PARENT_FIRST_PREFIXES — always delegate java.*, javax.*, and your shared API packages to the parent to avoid type identity breaks.
• ClassCastException despite matching class names means two ClassLoaders — the fix is ensuring shared interfaces live only in the parent ClassLoader's classpath.
• ClassLoader leaks fill Metaspace — audit ThreadLocals, static registries, and JDBC driver registration in plugin shutdown hooks to prevent memory accumulation on hot-reload cycles.
• JPMS is preferred for static module isolation; custom ClassLoaders are the right tool only when dynamic runtime loading is genuinely required.

Conclusion

The ClassLoader subsystem is Java's most powerful extensibility mechanism, and the foundation on which every real plugin system, hot-deploy framework, and application server is built. Mastering it means understanding the parent-delegation model deeply enough to know when to break it, recognizing the ClassCastException signature of ClassLoader boundary violations, and building the lifecycle management discipline that prevents Metaspace leaks from accumulating. The complexity is real, but the reward — a running JVM that can load, isolate, and unload arbitrary business logic without downtime — is one of the most powerful capabilities in the Java platform.

Apply child-first ClassLoaders for plugin isolation, maintain a strict shared-API-in-parent contract, always close URLClassLoaders and clean up ThreadLocals, and reach for JPMS or microservice boundaries when the problem doesn't genuinely require runtime dynamic loading. The ClassLoader story in modern Java is richer than ever — and with the module system, virtual threads, and GraalVM in the picture, it continues to evolve toward safer and more powerful abstractions.

Last updated: March 2026 — Written by Md Sanwar Hossain