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. Replace X.Y.Z with the latest release number:

<dependency>
    <groupId>io.github.classgraph</groupId>
    <artifactId>classgraph-classpath</artifactId>
    <version>X.Y.Z</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
• Saying what to search
• What is searched
• ClasspathFinder
• Classpath
• ClasspathEntry
• ModulePathInfo

import io.github.classgraph.classpath.*;

try (Classpath classpath = new ClasspathFinder().enableClasspath().enableNonSystemModules().find()) {
    for (ClasspathEntry entry : classpath) {
        System.out.println(entry.getLocation() + " (from " + entry.getClassLoaderName() + ")");
    }
    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().enableClasspath().enableNonSystemModules().find()) {
    locations = classpath.getLocations();
}

Nothing is searched unless it is enabled, so a ClasspathFinder with no enable method called returns an empty Classpath. The methods that say where to search come in pairs. The method with no arguments enables the sources that are found in the current runtime environment; the method that takes varargs enables exactly the sources it is given:

Calling only the varargs method searches only what it names, and nothing from the environment. Calling both searches the environment as well as what you named. A method that searches the environment has no overload that searches only what is named, and a method that searches what is named has no overload that searches the environment.

enableSystemModules() and enableNonSystemModules() say which kinds of module to search for, not where to look for them. They search the module layers that are visible to the caller if you name no layers of your own; name a layer with enableModuleLayers(...), and only the layers you named are searched, unless you call enableDetectedModuleLayers() too.

Each call adds to the end of the list of things to search, so classpath sources are reported in the order the calls were made. Modules always come first, whatever order they were enabled in, since that is the order in which the JVM resolves a class.

enableClasspath() finds every classpath element of every classloader that can be found in the environment. A classloader is found if it is any of the following:

• the context classloader of the calling thread, as returned by Thread.currentThread().getContextClassLoader();
• the classloader that loaded ClassGraph itself;
• the system classloader, as returned by ClassLoader.getSystemClassLoader() -- this is the application classloader, unless the JVM was launched with -Djava.system.class.loader;
• the classloader of the class in any frame of the current call stack, so that the classloader of the code that called ClassGraph is searched even when it is none of the above; or
• an ancestor of any of those, reached through ClassLoader#getParent().

Every classpath element that every one of those classloaders loads classes from is found, whether or not the classloader exposes it publicly -- see Classpath specification mechanisms for how each supported classloader is read. Elements are reported in the order in which the classloaders that declared them would be asked to load a class. The application classloader is normally one of the classloaders found, so the entries that the java.class.path system property lists are searched too, at the position the application classloader takes in that order.

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 honored 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. Class-Path entries are separated by any whitespace, and follow the JVM's rules for URLs: a jarfile in a filesystem can name another element by a file: URL, but by no other URL; a nested jarfile, or one fetched from a URL, can name no URL; and a jarfile fetched from a URL can only name paths below its own directory, by a relative URL with no .. in it. Allowing a URL scheme does not change this.

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. Whether two elements are the same one is decided by their location, and a location that names a file or directory is canonical, so the same jarfile reached through a symbolic link and reached directly is one element rather than two.

A classloader, or a jarfile's manifest, may name a file or directory that is not there, or that cannot be read. Such an element is logged and left out of the classpath rather than listed, since it can contribute no class. An element that is there but cannot be opened -- a file with a .jar name that is not a zipfile, say -- is still listed, because whether it can be opened is only found out when it is opened.

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.

No configuration method calls another configuration method: every method changes exactly the one setting it names, so each option you rely on has to be called for by name. An option that is only read by another option -- the three module layer methods above, which say where to look for modules but not which kind to look for, ignoreParentClassLoaders() and registerClassLoaderHandler(...), which need a classloader to be searched, filterClasspathEntries(...), which needs a classpath source, and enableRealtimeLogging(), which needs a log -- is refused by find() with an IllegalArgumentException naming both methods, rather than being silently ignored.

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().enableClasspath().enableNonSystemModules().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 getLocation() and parsing that back into an object. That matters for the forms a location does not reliably round-trip: a Path in a filesystem other than the default one is read through that filesystem, whether or not its toUri() form resolves back to it and whatever URL schemes are denied, and a URL keeps the scheme it was found with. A network scheme still has to be allowed with new ClasspathFinder().enableClasspath().allowURLScheme("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:

String form = switch (entry) {
    case ClasspathEntry.OfPathString s -> "string";
    case ClasspathEntry.OfFile f -> "File " + f.getFile();
    case ClasspathEntry.OfPath p -> "Path in " + p.getPath().getFileSystem();
    case ClasspathEntry.OfURL u -> "URL served over " + u.getURL().getProtocol();
    case ClasspathEntry.OfURI u -> "URI " + u.getURI();
};

A switch with type patterns needs Java 21 or newer. On Java 17, test for each subclass with instanceof instead:

String form;
if (entry instanceof ClasspathEntry.OfFile f) {
    form = "File " + f.getFile();
} else if (entry instanceof ClasspathEntry.OfPath p) {
    form = "Path in " + p.getPath().getFileSystem();
} else if (entry instanceof ClasspathEntry.OfURL u) {
    form = "URL served over " + u.getURL().getProtocol();
} else if (entry instanceof ClasspathEntry.OfURI u) {
    form = "URI " + u.getURI();
} else {
    form = "string";
}

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 and lib dir 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. A switch that was used more than once contributes all of its values to the same set, except --module-path, for which only the last occurrence is reported, since that is the only one the JVM uses.

The commandline cannot change while the JVM runs, so there is one instance for the whole JVM, returned by ModulePathInfo.current(). Classpath#getModulePathInfo(), ClassGraph#getModulePathInfo() and ScanResult#getModulePathInfo() return the same object.

The values are read from the commandline only, so the manifest attributes of jarfiles found later do not change them.