Classpath API

The classgraph-classpath library works out where a running JVM loads its classes and resources from: the classpath elements, the module path, and the locations that a container's custom classloaders load from. It is the classpath finder that ClassGraph itself scans with, and it can be used on its own, without scanning anything.

<dependency>
    <groupId>io.github.classgraph</groupId>
    <artifactId>classgraph-classpath</artifactId>
    <version>LATEST</version>
</dependency>

If you already depend on classgraph, you have this library too: classgraph depends on classgraph-classpath, which depends on classgraph-vfs, which depends on classgraph-base.

• Finding the classpath
• What is searched, by default
• ClasspathFinder
• Classpath
• ClasspathEntry
• ModulePathInfo

import io.github.classgraph.classpath.*;

try (Classpath classpath = new ClasspathFinder().find()) {
    for (ClasspathEntry entry : classpath) {
        System.out.println(entry.location() + " (from " + entry.classLoaderName() + ")");
    }
    for (java.lang.module.ModuleReference module : classpath.getNonSystemModules()) {
        System.out.println(module.descriptor().name());
    }
}

find() opens the jarfiles on the classpath, in order to read their manifests, so Classpath is AutoCloseable: closing it closes those jarfiles again, and deletes any temporary files that were needed to open a jarfile nested inside another jarfile. The classpath elements and the modules can still be read after close(), so if you only want the list of locations, you can close the Classpath immediately:

List<String> locations;
try (Classpath classpath = new ClasspathFinder().find()) {
    locations = classpath.getLocations();
}

By default, the classloaders found in the environment are searched: the context classloader of the calling thread, the classloader of the caller's own class, the system classloader, and their parents, in the order in which they would be asked to load a class. The java.class.path system property and the module system are consulted too.

The classpath elements that a classpath element declares are found as well, and added at the position they are reached from: the jarfiles in its automatic lib dirs, and the entries of its manifest's Class-Path and Bundle-ClassPath attributes. Each of those may declare more, so this is recursive. A jarfile, a jarfile nested inside another jarfile, and an exploded jarfile in a directory all declare their child classpath elements the same way, so a manifest is honoured wherever it is found. A child is resolved against the classpath element that declared it, so a relative Class-Path entry of a jarfile that lives in a non-default FileSystem names a sibling within that same filesystem.

A classpath element that is reached more than once is listed only at the first position it is reached at, which is the position that decides which copy of a duplicated class is loaded. A classpath element that could not be opened, or that is not a jarfile, is still reported -- a classloader may name a jarfile or directory that is not there.

An instance is not thread-safe while it is being configured, but find() may be called any number of times, and returns a new Classpath each time. The configuration methods return this, so they can be chained.

A Classpath is Iterable<ClasspathEntry>, so a for-each loop over it iterates the same entries as getEntries(), in the same order. The modules are a separate list, and iterating a Classpath does not visit them.

toString() returns the classpath elements and then the modules, one per line.

Modules are reported as JDK ModuleReference objects: module.descriptor().name() is the module name, and module.location() is an Optional<URI> naming where it was loaded from.

One element of the classpath: a directory or a jarfile that classes and resources are loaded from.

toString() is the location, followed by the classloader name in square brackets if there is one.

try (Classpath classpath = new ClasspathFinder().find()) {
    Vfs vfs = classpath.getVfs();
    for (ClasspathEntry entry : classpath) {
        for (VfsEntry resource : entry.open(vfs)) {
            System.out.println(resource.getPath());
        }
    }
}

open(Vfs) opens the element in whichever form the classloader named it in, rather than flattening it to location() and parsing that back into an object. That matters for the forms a location cannot round-trip: a Path in a filesystem other than the default one is reached only through its own filesystem, and a URL keeps the scheme it was found with. A remote scheme still has to be allowed with new ClasspathFinder().enableURLScheme("https") before find(), or open throws IOException.

ClasspathEntry is a sealed class, with one subclass per form a classloader can name an element in. Code that needs the object the element was found as can ask for it; code that only wants to read the element does not need to know which subclass it has.

Because the type is sealed, those five are the only possibilities, so a switch over them is checked for exhaustiveness on Java 21 and later:

if (entry instanceof ClasspathEntry.OfURL urlEntry) {
    System.out.println("Served over " + urlEntry.url().getProtocol());
}

Two entries are equal if they were found in the same form, at the same location, from the same classloader, with the same package root prefixes -- so the same jarfile named by a File in one classpath and by a Path in another gives two entries that are not equal. Within a single classpath the question does not arise: an element is listed once, at the first position it is reached at, whichever form it was named in there, since duplicates are recognized by location.

The module system switches the JVM was launched with, read from the runtime's own commandline arguments. This covers only what was named on the commandline -- it does not include the traditional classpath, or the system modules, which the runtime adds by itself.

Each getter returns an unmodifiable, insertion-ordered Set of the switch's values, in the order they were given on the commandline. A switch that was not used gives an empty set, and a switch that was used more than once contributes all of its values to the same set.

getAddExports() and getAddOpens() also include any Add-Exports and Add-Opens entries found in the manifests of jarfiles that were scanned, in the form <source-module>/<package>=ALL-UNNAMED. addExportsEntry(String) and addOpensEntry(String) are what the scanner calls to add those.