Get Classpath From ClassLoader in Java

1. Overview

In this article, we’ll explore how to obtain the classpath from a ClassLoader in recent OpenJDK distributions.

2. ClassLoaders and Classpath

The Java Virtual Machine uses ClassLoaders to resolve classes or other resources at runtime. Even though a ClassLoader implementation is free to choose a resolution mechanism, the classpath is the standard choice.

A classpath is an abstraction that Java programs use to locate classes and other resources using relative naming syntax. For example, if we start a Java program with:

java -classpath /tmp/program baeldung.Main

The Java Runtime will search for a file on the location /tmp/program/baeldung/Main.class, and, assuming it exists and is valid, the JVM will load the Class and execute the main method.

Once the program starts, any additional classloading will proceed by searching classes by their respective Internal Names, meaning, the fully qualified Class name with ‘.’ (dots) replaced by ‘/’ (slashes), as relative paths from the directory /tmp/program.

Furthermore, the classpath also supports:

• Multiple locations, specified by the ‘:’ separator
• Jar Files

Finally, we can specify any valid URL as classpath locations, not just file system paths. Therefore, objectively speaking a classpath is equivalent to a set of URLs.

3. Common Types of ClassLoaders

To be useful, a ClassLoader implementation must be capable of resolving instances of java.lang.Class objects by overriding the following method:

protected Class<?> findClass(String name) throws ClassNotFoundException {
    throw new ClassNotFoundException(name);
}

Implementing a bespoke ClassLoader can be tricky. ClassLoaders were designed like a LinkedList structure and each may have a parent ClassLoader which can be queried by the getParent() method to support the delegation model.

Lastly, there is no mandatory coupling between a classpath and a ClassLoader and we’ll restrict ourselves to well-known types that effectively employ the classpath mechanism for resource resolution.

3.1. java.net.URLClassLoader

The URLClassLoader exposes its classpath via the method getURLs() and it’s the usual choice when a program needs to handle dynamic classpaths. For instance, Tomcat extends URLClassLoader to segregate the classpath of web applications: the container gives each deployed app its isolated classpath, separate from the others.

In addition, a URLClassLoader is equipped with logic to handle not only local directories but also jar files hosted on disk or remotely accessible via HTTP or other protocols, such as FTP, as long as they support the URL::openConnection() method.

3.2. The Application ClassLoader

The ClassLoader responsible for launching a Java program, that is the ClassLoader that loads a class with a main method and executes it, is called the Application ClassLoader.

In older JDKs (<=9) the Application ClassLoader was a subclass of URLClassLoader. However, the hierarchy has changed since OpenJDK 10 and the Application ClassLoader inherits from the module-private jdk.internal.loader.BuiltinClassLoader, which is not a subclass of URLClassLoader.

By definition, the Application ClassLoader will have its classpath bound to the -classpath startup option. We can retrieve this information at runtime by querying the system property java.class.path, however, this can be inadvertently overwritten at any time and if we want to determine the actual runtime classpath we must query the ClassLoader itself.

4. Obtaining the Classpath From a ClassLoader

To obtain the classpath from a given ClassLoader, let’s start by defining a ClasspathResolver interface, which exposes the capability of querying the classpath of a single ClassLoader and also its whole hierarchy:

package com.baeldung.classloader.spi;

public interface ClasspathResolver {
    void collectClasspath(ClassLoader loader, Set<URL> result);

    default Set<URL> getClasspath(ClassLoader loader) {
        var result = new HashSet<URL>();
        collectClasspath(loader, result);
        return result;
    }

    default Set<URL> getFullClasspath(ClassLoader loader) {
        var result = new HashSet<URL>();
        collectClasspath(loader, result);
        loader = loader.getParent();

        while (loader != null) {
            collectClasspath(loader, result);
            loader = loader.getParent();
        }

        return result;
    }
}

As we mentioned before, Application ClassLoaders do not inherit from URLClassLoader anymore, thus we can’t simply obtain the associated classpath by calling the URLClassLoader::getURLs() method. However, there is still a common denominator to URLClassLoader and BuiltinClassLoader classes: both wrap an instance of jdk.internal.loader.URLClassPath, which is the actual class responsible for locating URL-based resources.

Therefore, an effective implementation of the ClasspathResolver interface will have to tinker with non-visible classes from the JDK, consequently requiring access to non-exported packages.

Since exposing JDK internals to a whole program is a bad practice, it would be better if we isolate this capability by placing the ClasspathResolver interface and its implementations in a modular jar, by also defining a module-info file:

module baeldung.classloader {
    exports com.baeldung.classloader.spi;
}

4.1. Basic Implementation

A basic implementation of ClasspathResolver will only handle URLClassLoaders and will always be available whether the program has access to JDK internals or not:

public class BasicClasspathResolver implements ClasspathResolver {
    @Override
    public void collectClasspath(ClassLoader loader, Set<URL> result) {
        if(loader instanceof URLClassLoader ucl) {
            var urls = Arrays.asList(ucl.getURLs());

            result.addAll(urls);
        }
    }
}

4.2. Extended Implementation

This implementation will demand non-exported OpenJDK classes and a few things can go wrong, namely:

• Consumers of our library might not set proper runtime flags
• The program is running in a different JDK, that may not have BuiltinClassLoaders
• Future versions of OpenJDK may change or remove BuiltinClassLoader, rendering this implementation useless

When using internal JDK APIs we must program defensively, which means taking a few extra steps to compile and run our programs correctly.

First, we must export the jdk.internal.loader package to our module, by adding proper command line options to the compiler. Then, we must also open the package to support reflective access at runtime to test our implementation.

When using Maven as the build and test tool, the plugins have to be set up like this:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <source>22</source>
                <target>22</target>
                <compilerArgs>
                    <arg>--add-exports</arg>
                    <arg>java.base/jdk.internal.loader=baeldung.classloader</arg>
                </compilerArgs>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <argLine>--add-opens java.base/jdk.internal.loader=baeldung.classloader</argLine>
            </configuration>
        </plugin>
    </plugins>
</build>

Note: If you prefer not to use modular projects, you can omit the module-info file. Instead, replace the baeldung.classloader module with ALL-UNNAMED in the exports and open clauses.

Some IDEs might require additional configuration as well. For example, in Eclipse, it is necessary to expose the package in Module Dependencies as shown in the picture below:

Now, we are ready to code our extended implementation. Essentially, the call chain we need is:

BuiltinClassLoader -> URLClassPath -> getURLs()

The URLClassPath instance is hoisted in the BuiltinClassLoader#ucp private field, therefore we must obtain it via reflection. This might fail at runtime and, in case it does what should we do?

We will opt to fall back to BasicClasspathResolver, and to do so we should code a support class that tells whether or not we can access BuiltinClassLoader#ucp:

public class InternalJdkSupport {

    static final Class<?> BUILT_IN_CLASSLOADER;
    static final VarHandle UCP;

    static {
        var log = LoggerFactory.getLogger(InternalJdkSupport.class);
        var version = System.getProperty("java.version");

        Class<?> clazz = null;
        VarHandle ucp = null;

        try {
            var ucpClazz = Class.forName("jdk.internal.loader.URLClassPath");
            clazz = Class.forName("jdk.internal.loader.BuiltinClassLoader");
            var lookup = MethodHandles.privateLookupIn(clazz, MethodHandles.lookup());
            ucp = lookup.findVarHandle(clazz, "ucp", ucpClazz);
        } catch (ClassNotFoundException e) {
            log.warn("JDK {} not supported => {} not available.", version, e.getMessage());
        } catch (NoSuchFieldException e) {
            log.warn("JDK {} not supported => BuiltinClassLoader.ucp not present", version);
        } catch (IllegalAccessException e) {
            log.warn("""
                BuiltinClassLoader.ucp requires \
                --add-opens java.base/jdk.internal.loader=baeldung.classloader
                """);
        }

        BUILT_IN_CLASSLOADER = clazz;
        UCP = ucp;
    }

    public static boolean available() {
        return UCP != null;
    }

    public static Object getURLClassPath(ClassLoader loader) {
        if (!isBuiltIn(loader)) {
            throw new UnsupportedOperationException("Loader not an instance of BuiltinClassLoader");
        }

        if (UCP == null) {
            throw new UnsupportedOperationException("""
                Program must be initialized with \
                --add-opens java.base/jdk.internal.loader=baeldung.classloader
                """);
        }

        try {
            return UCP.get(loader);
        } catch (Exception e) {
            throw new InternalError(e);
        }
    }

    static boolean isBuiltIn(ClassLoader loader) {
        return BUILT_IN_CLASSLOADER != null && BUILT_IN_CLASSLOADER.isInstance(loader);
    }
}

With InternalJdkSupport in place, our extended ClasspathResolver implementation, capable of extracting URLs from Application ClassLoaders becomes simply:

import jdk.internal.loader.BuiltinClassLoader;
import jdk.internal.loader.URLClassPath;

public final class InternalClasspathResolver implements ClasspathResolver {
    @Override
    public void collectClasspath(ClassLoader loader, Set<URL> result) {
        var urls = switch (loader) {
            case URLClassLoader ucl -> Arrays.asList(ucl.getURLs());
            case BuiltinClassLoader bcl -> {
                URLClassPath ucp = (URLClassPath) InternalJdkSupport.getURLClassPath(loader);

                yield ucp == null ? Collections.<URL> emptyList() : Arrays.asList(ucp.getURLs());
            }
            default -> {
                yield Collections.<URL> emptyList();
            }
        };

        result.addAll(urls);
    }
}

4.3. Exposing the ClasspathResolver

Since our module exports only the com.baeldung.classloader.spi package, clients won’t be able to instantiate the implementations directly. Therefore, we should offer access to the implementations through a factory method:

public interface ClasspathResolver {

    static ClasspathResolver get() {
        if (InternalJdkSupport.available()) {
            return new InternalClasspathResolver();
        }

        return new BasicClasspathResolver();
    }

}

5. Conclusion

In this article, we’ve explored how to create a safe modular solution to obtain the classpath of common OpenJDK ClassLoaders.

The extended implementation was designed to work along OpenJDK, since it requires access to implementation-specific classes, however, it will work with other vendors such as Zulu, Graal, and Temurin.

Modularization limits the exposed JDK internals surface to a single, trusted module, preventing unwanted rogue access by third-party dependencies.