Java Reflection: How It Powers Frameworks, Decouples Code, and Enables FlexibiIity

Have you ever wondered how Java frameworks use annotations, how dependency injection operates, or how to serialize and deserialize objects without a concrete implementation? Did you know that these practices utilize one of the basic JVM APIs? In this blog, we will dig into the concept of the Java Reflection API and look at its usage in software engineering practices.

Core Concepts You Should Know First

Before using the reflection API, we must first have a basic grasp of the Java language and review certain terminologies :

• JVM (Java Virtual Machine): A runtime environment that executes Java bytecode on various platforms by translating it into machine-specific instructions.

• Compile Time: The phase where the Java compiler translates source code (.java files) into bytecode (.class files).

• Run Time: The phase when the JVM executes the compiled bytecode and interacts with the underlying operating system.

• Bytecode: A platform-independent, intermediate representation of Java code executed by the JVM.

• Classpath: The configuration that specifies the locations of classes and libraries required by a Java application during compilation and runtime.

• Annotations: Metadata embedded in Java code that provides additional information for tools and frameworks to process at compile or runtime

• Wildcards: In Java, wildcards (?) are used in generics to represent an unknown type, enabling flexibility in writing methods, classes, or interfaces that can work with different types while maintaining type safety.

How Java Language Works

Java programs revolve around classes (blueprints) and objects (instances of classes). A typical Java program flow begins with the compilation phase into the bytecode and continues with the running phase of the bytecode by converting it to the native machine code.

We can illustrate this flow with a simple diagram below;

Class Loading

Class loading is the process by which Java dynamically loads classes into the JVM during runtime. The JVM uses class loaders to locate, read, and define class files when they are needed.

Reflection and class loading are distinct concepts in Java. Class loading is the process of bringing class definitions into the JVM, typically at runtime, ensuring they are available for use. It involves locating, verifying, and preparing class bytecode using the class loader. While classes can be referenced at compile time, the JVM loads them dynamically when they are first needed, a behavior known as lazy loading. In contrast, reflection operates on already loaded classes, allowing inspection and manipulation of their structure and behavior at runtime using the java.lang.reflect package. While class loading focuses on making classes available, reflection enables dynamic interaction with them.

There are some exception types in Java that are closely related to the class loading process.

ClassNotFoundException: Thrown when an application tries to dynamically load a class (e.g. using Class.forName) and the class cannot be found at runtime.

NoClassDefFoundError: Thrown when the JVM or a class loader tries to load a class that was present at compile time but is missing from the runtime classpath. It typically indicates a configuration or deployment issue.

Both issues arise during runtime, but it's worth noting that ClassNotFoundException is a checked exception, while NoClassDefFoundError is an unchecked error.

What is Reflection

In a concise manner, Java Reflection is a JVM API that enables us to examine and manipulate the classes in the classpath at runtime. It simply means we can make use of the classes (or types) through the reflection API by decoupling them from our code at compile time. This provides us with a significant degree of flexibility, which aids us in maintaining the sustainable growth of our project.

Although the reflection function is one of the core and older features in the Java language, it still holds great value. This is a relatively advanced feature and should be used only by developers who have a strong grasp of the fundamentals of the language.

Working with Reflection (Basics)

All reflection usage starts with getting the Class<?> object — the heart of Java reflection. This object represents a specific class in the classpath. Once we have it, we can inspect and interact with the class at runtime. The use of the wildcard <?> brings flexibility, allowing us to reference any class, regardless of its type.

There are three main ways to obtain a Class<?> object:

• The .getClass() method of any object

• The .class syntax for any class or primitive type

• The Class.forName("...") method, by providing the fully qualified class name as a string

Using any of these methods, we can grab a runtime representation of a class that’s present in the classpath. At this point, our code can start interacting with that class using the Reflection API. This means we are no longer tightly coupled to that specific class — instead, our dependency shifts to the reflection classes themselves. In other words, reflection provides an abstraction layer that decouples our code from the classes it operates on.

Let’s now take a look at how basic reflection works through a simple example. But before that, here are the key classes that make it all possible:

• java.lang.Class — Represents a class or interface at runtime. It provides methods to get metadata such as class name, modifiers, superclass, implemented interfaces, annotations, and more.

• java.lang.reflect.Field — Provides access to the fields (member variables) of a class, both public and private. It allows you to read or modify field values dynamically, even bypassing access checks if necessary.

• java.lang.reflect.Method — Enables dynamic method invocation at runtime. You can inspect method signatures, parameters, return types, and invoke both public and private methods — including inherited ones.

• java.lang.reflect.Constructor — Allows object creation at runtime, even for private constructors. It's used to instantiate objects dynamically when the class type isn’t known at compile time.

The following examples illustrate how to use the Reflection API in its most fundamental form;

Annotation Processing

Java uses annotations to add metadata to classes, methods, fields, and other elements. While this metadata doesn’t affect program logic directly, it becomes incredibly useful when combined with tools like reflection or annotation processors.

Annotations, when used with reflection, enable us to write highly decoupled and configurable code. Instead of hardcoding behavior, we can annotate classes with custom annotations and use that metadata at runtime, making our code far more flexible.

For example, we can tag classes or methods with our own annotations, then scan the classpath at runtime, detect those annotations using reflection, and take action accordingly. This approach is widely used in frameworks like Spring, where annotations such as @Service, @Autowired, and @RequestMapping drive framework behavior without tightly coupling the framework to your business logic.

This pattern is especially valuable in libraries, frameworks, or tools that need to interact with user code without knowing implementation details ahead of time.

A familiar example is JUnit, where annotations like @Test, @BeforeEach, and @AfterAll are used to mark test methods. JUnit uses reflection to detect and invoke these methods automatically during test execution without manual wiring.

Another practical use is in object serialization and deserialization. Libraries like Jackson and Gson use annotations such as @JsonProperty (Jackson) or @SerializedName (Gson) to map JSON fields to Java object fields. Under the hood, reflection is used to dynamically access and populate these fields at runtime — even private ones.

Dynamic Proxy

Dynamic proxies in Java allow you to create proxy objects at runtime. These proxies act as intermediaries that delegate method calls or add behavior dynamically, without modifying the original class. This approach derives it’s power from Reflection API.

They are widely used in aspect-oriented programming to implement cross-cutting concerns like logging and authorization. With dynamic proxies, we can separate these concerns from business logic, making our code more modular.

Dynamic proxies are widely used in popular frameworks:

Spring Framework uses dynamic proxies to power features like @Transactional, @Async, and method-level security. It wraps your beans with proxies that intercept method calls to apply behavior like transaction management or access control.

Hibernate uses dynamic proxies for lazy loading. Instead of immediately loading associated entities, Hibernate returns a proxy that loads the data only when it’s accessed, improving performance and resource usage.

Mockito, a popular testing framework, relies on dynamic proxies to create mock objects at runtime. When you mock a dependency, Mockito generates a proxy that can track method calls, return predefined values, or throw exceptions.

JUnit, while not directly relying on dynamic proxies, is often used together with mocking frameworks like Mockito, which in turn leverage proxies to simulate and test behavior in isolation.

Benefits of Reflection for Loose Coupling

Reflection allows us to instantiate and interact with classes without hardcoding their names. This principle is widely used in dependency injection frameworks like Spring, where objects are injected at runtime based on configuration or annotations, not by explicit new calls. As a result, components can evolve independently, making the system easier to maintain and test.

Reflection also enables dynamic extensibility. In plugin-based systems, for example, we can load external modules or behaviors at runtime without changing existing code. This design makes the application open for extension but closed for modification, aligning well with the Open/Closed Principle.

Sample Practice - Document Parser

We will create a simple DocumentParser class which leverages reflection to strengthen our grasp of the Reflection API.

Assume that we must parse a variety of document formats in our software in order to use them. An individual parser can be developed for each document type. The question is: how do we create a factory pattern for document parsers that will not be impacted by the addition of new parsers or the removal of existing ones?

To achieve such flexible code, we will utilize the Reflection API to isolate our factory pattern code from the actual parser implementations.

Here is a UML diagram that illustrates our code:

We create a standard factory class that serves the parser classes through the getParser() method. We also define one interface named DocumentParser, which abstracts the implementation classes, and one annotation class named CargoDocumentParser, which marks a class as a parser implementation. Then, we create three different parser classes that implement the DocumentParser interface and are also annotated with the CargoDocumentParser annotation.

Our CargoDocumentParserFactory will be designed to scan parser implementations within a given package and load them using the Reflection API. In this way, our code will be capable of detecting new parser classes and using them automatically — with no need for any code changes.

First, we define the interface class named DocumentParser:

We define an annotation class named CargoDocumentParser:

And finally our CargoDocumentParserFactory class;

We add a parser named FlightScheduleXmlParser;

Any parser implementation in our example must meet two conditions to be discovered and used by the CargoDocumentParserFactory:

● It should implement the DocumentParser interface.

● It should be annotated with CargoDocumentParser and provide a parser code.

If these two conditions are fulfilled, our factory detects the parser and includes it automatically.

We should also highlight another important usage in our code in CargoDocumentParserFactory:

We used a utility package to avoid boilerplate code when retrieving classes via reflection:

This utility simplifies obtaining Class<?> objects. Specifically, we're retrieving all classes annotated with CargoDocumentParser in our code. Of course, we could have done this manually.

To achieve it manually, we could use Java's IO functions to get File objects representing the given package. Once we obtain the File object (which corresponds to a directory in the file system), we can access the .class files under that package — since all Java classes are represented as files in the classpath — and load them using the Reflection API. However, to avoid this kind of boilerplate, we used an external utility library called Reflections.

Now, we can use our factory pattern to get a FlightScheduleParser:

And the result is as expected:

After that, we add a new parser implementation named InvoiceHtmlParser and use the same code — just by giving a new parser code to the factory to get an instance.

And here is the result:

As you can see, we didn’t have to make any adjustments to our factory pattern code when adding new parsers or removing existing ones. By using the Reflection API, we were able to isolate our factory logic from the actual implementation classes, making our code more loosely coupled and better supporting its sustainable growth.

Things to Consider Before Using Reflection

While reflection offers flexibility and power, it comes with trade-offs that should not be ignored.

Performance Overhead

Reflection is slower than direct method or field access. Since everything happens at runtime, the JVM can’t optimize reflective calls the same way it does regular code. In performance-critical paths, this can become a bottleneck.

Bypassing Access Control

Reflection allows access to private fields and methods, breaking encapsulation. While this can be useful in some cases, it should be handled with care, as it undermines the safety principles of object-oriented design.

Loss of Compile-time Checks

Normally, the Java compiler ensures type safety, method signatures, and field existence at compile time. When you use reflection, those safety checks are no longer available. You’re responsible for catching all possible exceptions like ClassNotFoundException, NoSuchMethodException, or IllegalAccessException — and if you don’t handle them properly, your app can fail unexpectedly at runtime.

Here is an excerpt taken from Oracle’s official site:

“Reflection is powerful, but should not be used indiscriminately. If it is possible to perform an operation without using reflection, then it is preferable to avoid using it.”

(Source: https://docs.oracle.com/javase/tutorial/reflect/)

Reflection is a powerful feature that brings flexibility, extensibility, and decoupling to Java. But that power comes with responsibility, use it wisely, only when truly needed.