Finding All Classes in a Java Package

1. Overview

Sometimes, we want to get information about the runtime behavior of our application, such as finding all classes available at runtime.

In this tutorial, we'll explore several examples of how to find all classes in a Java package at runtime.

2. Class Loaders

First, we'll start our discussion with the Java class loaders. The Java class loader is part of the Java Runtime Environment (JRE) that dynamically loads Java classes into the Java Virtual Machine (JVM). The Java class loader decouples the JRE from knowing about files and file systems. Not all classes are loaded by a single class loader.

Let's understand the available class loaders in Java through pictorial representation:

Java 9 introduced some major changes to the class loaders. With the introduction of modules, we have the option to provide the module path alongside the classpath. The system class loader loads the classes that are present on the module path.

Class loaders are dynamic. They are not required to tell the JVM which classes it can provide at runtime. Hence, finding classes in a package is essentially a file system operation rather than one done by using Java Reflection.

However, we can write our own class loaders or examine the classpath to find classes inside a package.

3. Finding Classes in a Java Package

For our illustration, let's create a package com.baeldung.reflection.access.packages.search.

Now, let's define an example class:

public class ClassExample {
    class NestedClass {
    }
}

Next, let's define an interface:

public interface InterfaceExample {
}

In the next section, we'll look at how to find classes using the system class loader and some third-party libraries.

3.1. System Class Loader

First, we'll use the built-in system class loader. The system class loader loads all the classes found in the classpath. This happens during the early initialization of the JVM:

public class AccessingAllClassesInPackage {
    public Set<Class> findAllClassesUsingClassLoader(String packageName) {
        InputStream stream = ClassLoader.getSystemClassLoader()
          .getResourceAsStream(packageName.replaceAll("[.]", "/"));
        BufferedReader reader = new BufferedReader(new InputStreamReader(stream));
        return reader.lines()
          .filter(line -> line.endsWith(".class"))
          .map(line -> getClass(line, packageName))
          .collect(Collectors.toSet());
    }
 
    private Class getClass(String className, String packageName) {
        try {
            return Class.forName(packageName + "."
              + className.substring(0, className.lastIndexOf('.')));
        } catch (ClassNotFoundException e) {
            // handle the exception
        }
        return null;
    }
}

In our example above, we're loading the system class loader using the static getSystemClassLoader() method.

Next, we'll find the resources in the given package. We'll read the resources as a stream of URLs using the getResourceAsStream method. To fetch the resources under a package, we need to convert the package name to a URL string. So, we have to replace all the dots (.) with a path separator (“/”).

After that, we're going to input our stream to a BufferedReader and filter all the URLs with the .class extension. After getting the required resources, we'll construct the class and collect all the results into a Set. Since Java doesn't allow lambda to throw an exception, we have to handle it in the getClass method.

Let's now test this method:

@Test
public void when_findAllClassesUsingClassLoader_thenSuccess() {
    AccessingAllClassesInPackage instance = new AccessingAllClassesInPackage();
 
    Set<Class> classes = instance.findAllClassesUsingClassLoader(
      "com.baeldung.reflection.access.packages.search");
 
    Assertions.assertEquals(3, classes.size());
}

There are just two Java files in the package. However, we have three classes declared — including the nested class, NestedExample. As a result, our test resulted in three classes.

Note that the search package is different from the current working package.

3.2. Reflections Library

Reflections is a popular library that scans the current classpath and allows us to query it at runtime.

Let's start by adding the reflections dependency to our Maven project:

<dependency>
    <groupId>org.reflections</groupId>
    <artifactId>reflections</artifactId> 
    <version>0.9.12</version>
</dependency>

Now, let's dive into the code sample:

public Set<Class> findAllClassesUsingReflectionsLibrary(String packageName) {
    Reflections reflections = new Reflections(packageName, new SubTypesScanner(false));
    return reflections.getSubTypesOf(Object.class)
      .stream()
      .collect(Collectors.toSet());
}

In this method, we're initiating the SubTypesScanner class and fetching all subtypes of the Object class. Through this approach, we get more granularity when fetching the classes.

Again, let's test it out:

@Test
public void when_findAllClassesUsingReflectionsLibrary_thenSuccess() {
    AccessingAllClassesInPackage instance = new AccessingAllClassesInPackage();
 
    Set<Class> classes = instance.findAllClassesUsingReflectionsLibrary(
      "com.baeldung.reflection.access.packages.search");
 
    Assertions.assertEquals(3, classes.size());
}

Similar to our previous test, this test finds the classes declared in the given package.

Now, let's move on to our next example.

3.3. Google Guava Library

In this section, we'll see how to find classes using the Google Guava library. Google Guava provides a ClassPath utility class that scans the source of the class loader and finds all loadable classes and resources.

First, let's add the guava dependency to our project:

<dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>30.1.1-jre</version>
</dependency>

Let's dive into the code:

public Set<Class> findAllClassesUsingGoogleGuice(String packageName) throws IOException {
    return ClassPath.from(ClassLoader.getSystemClassLoader())
      .getAllClasses()
      .stream()
      .filter(clazz -> clazz.getPackageName()
        .equalsIgnoreCase(packageName))
      .map(clazz -> clazz.load())
      .collect(Collectors.toSet());
}

In the above method, we're providing the system class loader as input to the ClassPath#from method. All the classes scanned by ClassPath are filtered based on the package name. The filtered classes are then loaded (but not linked or initialized) and collected into a Set.

Let's now test this method:

@Test
public void when_findAllClassesUsingGoogleGuice_thenSuccess() throws IOException {
    AccessingAllClassesInPackage instance = new AccessingAllClassesInPackage();
 
    Set<Class> classes = instance.findAllClassesUsingGoogleGuice(
      "com.baeldung.reflection.access.packages.search");
 
    Assertions.assertEquals(3, classes.size());
}

In addition, the Google Guava library provides getTopLevelClasses() and getTopLevelClassesRecursive() methods.

It's important to note that in all the above examples, package-info is included in the list of available classes if present under the package and annotated with one or more package-level annotations.

The next section will discuss how to find classes in a Modular Application.

4. Finding Classes in a Modular Application

The Java Platform Module System (JPMS) introduced us to a new level of access control through modules. Each package has to be explicitly exported to be accessed outside the module.

In a modular application, each module can be one of named, unnamed, or automatic modules.

For the named and automatic modules, the built-in system class loader will have no classpath. The system class loader will search for classes and resources using the application module path.

For an unnamed module, it will set the classpath to the current working directory.

4.1. Within a Module

All packages in a module have visibility to other packages in the module. The code inside the module enjoys reflective access to all types and all their members.

4.2. Outside a Module

Since Java enforces the most restrictive access, we have to explicitly declare packages using the export or open module declaration to get reflective access to the classes inside the module.

For a normal module, the reflective access for exported packages (but not open ones) only provides access to public and protected types and all their members of the declared package.

We can construct a module that exports the package that needs to be searched:

module my.module {
    exports com.baeldung.reflection.access.packages.search;
}

For a normal module, the reflective access for open packages provides access to all types and their members of the declared package:

module my.module {
    opens com.baeldung.reflection.access.packages.search;
}

Likewise, an open module grants reflective access to all types and their members as if all packages had been opened. Let's now open our entire module for reflective access:

open module my.module{
}

Finally, after ensuring that the proper modular descriptions for accessing packages are provided for the module, any of the methods from the previous section can be used to find all available classes inside a package.

5. Conclusion

In conclusion, we learned about class loaders and the different ways to find all classes in a package. Also, we discussed accessing packages in a modular application.

As usual, all the code is available over on GitHub.