Reflection

What it is and why it exists

Java reflection is a set of runtime APIs for inspecting metadata about classes, interfaces, arrays, primitive types, and their members. The entry point is usually Class<?>; objects such as Constructor, Method, Field, and RecordComponent represent members. Obtaining those objects doesn’t execute the underlying members: lookup, access checking, and execution are separate stages.

Reflection solves the problem of not knowing the concrete type or member when code is compiled. A test runner discovers annotated methods, a serializer reads a data shape, a dependency injection container selects a constructor from configuration, and a plugin boundary may receive only a class name. These systems handle open runtime input that a static call can’t enumerate in source.

You’ll also encounter reflection in diagnostic tools, IDEs, object mappers, and framework startup. It works well when code reads structured metadata and turns it into a validated execution plan. When business code already knows the interface or class, ordinary construction, method calls, and polymorphism are clearer and preserve compiler checks.

Reflection isn’t a universal encapsulation bypass or a security sandbox. Member access remains subject to Java language access rules, module exports and opens, and the identity of the caller. Passing external strings directly to Class.forName() or Method.invoke() also turns class and method selection into an input-validation problem.

Runtime type information isn’t the complete source program either. Type erasure removes some generic information, local variable names are generally unavailable, parameter names are reliable only with the right compiler option, and annotations without RUNTIME retention aren’t visible through runtime reflection. A reflection consumer must define what missing metadata means instead of treating “not observed” as “doesn’t exist.”

A dynamic requirement doesn’t automatically require reflection. Discovery of implementations for a known service interface can use ServiceLoader, behavior can vary through a strategy interface, and builds can generate member-access code. When you choose reflection, you should be able to name the fact available only at runtime and say how failure is exposed to callers.

How it works

The JVM maintains a runtime representation for each loaded type, and Java exposes it through Class. A class literal such as Order.class needs no instance; order.getClass() returns an object’s actual runtime class; Class.forName(name) looks up a binary name and initializes the class by default. To load without initialization, use the overload that accepts an initialize flag and a class loader.

A Class object includes class-loader identity. The same binary name defined by different class loaders produces different runtime types, and casts plus isAssignableFrom() respect that distinction. In a plugin system, “same name but cannot cast” usually indicates a loader boundary rather than random reflection failure.

A reflective operation has five stages: obtain a runtime type, find a member under an explicit rule, validate modifiers and signature, establish access, then execute and convert the result. Keeping these stages in an adapter or startup phase lets business paths use already validated constructors or methods. Rescanning on every request also delays configuration errors until traffic reaches the path.

A reflection object describes a declaration but doesn’t make a string-based call statically type-safe. A misspelled name produces NoSuchMethodException, an incompatible receiver or argument produces IllegalArgumentException, and failed access produces IllegalAccessException. An exception thrown by target code adds another wrapper.

Class and type relationships

Every Java type has a corresponding Class object, including int.class, void.class, and String[].class. Generic code commonly uses Class<?>; when an API must return a known base type, Class<T> can connect a type token to its return type. It still can’t represent the complete parameterized type List<String> because List<String>.class doesn’t exist.

Choose the type test that matches the question. candidate.isInstance(value) is the dynamic counterpart of instanceof; parent.isAssignableFrom(child) asks whether a child value can be assigned to parent. Their argument directions differ, and generated code frequently reverses isAssignableFrom().

getName() returns the JVM’s name form, so an array name may be [Ljava.lang.String;. Human-facing diagnostics usually benefit from getTypeName() or getSimpleName(), but a simple name may be empty and doesn’t uniquely identify a type. A persistent protocol must not depend on display names or compiler-generated names for local and anonymous classes.

Reflection can also expose compiler-generated declarations. Bridge methods, synthetic fields, and helper members for enums and inner classes may appear in scans. A framework should check isBridge(), isSynthetic(), and modifiers according to its contract instead of treating every returned member as user API.

Don’t treat a returned member array as declaration order. If registration, output, or conflict resolution must be stable, sort by an explicit key and define a policy for duplicate signatures or annotations. Tests that depend on reflection order can break when the compiler, build shape, or runtime changes.

Public members and declared members

getMethod() and getMethods() provide a view of public methods and include inherited members according to their rules. getDeclaredMethod() and getDeclaredMethods() look only at members declared directly by the current class but include non-public declarations. Field and constructor APIs use similar names; constructors are never inherited.

Method lookup by name also requires exact parameter types. int.class and Integer.class are different keys, ArrayList.class doesn’t automatically match a parameter declared as List, and null can’t tell the lookup which overload to choose. Reflection lookup doesn’t perform Java source overload resolution for you.

When scanning a hierarchy, don’t mechanically loop over getDeclaredMethods() and take the first matching name. Overrides, bridge methods, interface defaults, and covariant returns all affect the candidates. First decide whether the contract needs the public invocation view or every layer’s declaration view, then implement that algorithm.

If users can select an operation by string, map the string to an allowlist of validated signatures first. A public method isn’t necessarily safe for remote invocation, and a method name isn’t authorization. The allowlist should also fix the receiver type, argument conversion, result handling, and exception policy.

Invocation, conversion, and exceptions

Constructor.newInstance() creates an object, Method.invoke(receiver, arguments...) executes a method, and Field.get() plus Field.set() read and write fields. A static method ignores the receiver argument, while an instance method requires a compatible object. Reflection boxes primitive results and permits specified unboxing and widening conversions, but it doesn’t perform arbitrary narrowing or business string parsing.

For a varargs target, its last reflective parameter is still an array type. Method.invoke() is itself a varargs API, making the two array layers easy to confuse; the caller should build the final array according to the target declaration. Don’t infer an overload or packing policy only from the runtime argument count.

If target code throws normally, invoke() throws an InvocationTargetException , with the original exception in getCause() or getTargetException(). Infrastructure should preserve that original cause and translate it according to its public contract. Catching Exception and logging only the wrapper message often loses the useful exception type and stack.

Examples

These four examples progress through type inspection, exact construction and invocation, module access boundaries, and interface proxies. The output came from local OpenJDK 21.0.12 after compiling with javac --release 21; every API and behavior used is part of Java 25.

Inspect a type and member origins

This example inspects a record’s components, then looks up an inherited public method and a private method declared by the current type. It doesn’t iterate an unordered method array, so its output is stable.

getMethod("auditTag") finds the interface default through the public invocation view, so its declaring type is Auditable. getDeclaredMethod("tax") searches only Order and can therefore obtain the private declaration; obtaining the object doesn’t grant invocation access.

Record components have a dedicated RecordComponent model. Treating a record as an ordinary field bag loses the relationships among component accessors, the canonical constructor, and component annotation locations; when record semantics matter, begin with getRecordComponents().

Construct, invoke, and unwrap precisely

The lookup states the constructor and method parameter types explicitly instead of deriving an overload from argument objects. The second call triggers validation inside the target method, and the caller unwraps the original exception.

import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;

public class InvokeMembers {
    public static final class PriceRule {
        private final String currency;

        public PriceRule(String currency) {
            this.currency = currency;
        }

        public String discount(int cents, int percent) {
            if (percent < 0 || percent > 100) {
                throw new IllegalArgumentException("percent out of range");
            }
            return currency + " " + cents * (100 - percent) / 100;
        }
    }

    public static void main(String[] args) throws Exception {
        Constructor<PriceRule> constructor =
                PriceRule.class.getConstructor(String.class);
        Method discount = PriceRule.class.getMethod(
                "discount", int.class, int.class);

        PriceRule rule = constructor.newInstance("EUR");
        System.out.println(discount.invoke(rule, 2500, 20));

        try {
            discount.invoke(rule, 2500, 120);
        } catch (InvocationTargetException error) {
            Throwable cause = error.getCause();
            System.out.println(cause.getClass().getSimpleName()
                    + ": " + cause.getMessage());
        }
    }
}

EUR 2000
IllegalArgumentException: percent out of range

Constructor<PriceRule> keeps the construction result at its concrete type without a downcast. Method.invoke() still returns Object, so a larger adapter normally validates the return type during startup and centralizes the cast.

Lookup failure, access failure, and target business failure belong to different layers. Wrapping all of them as “reflection failed” prevents callers from distinguishing deployment configuration errors, input signature errors, and an order-rule rejection; preserve causes and use stable domain categories when translating failures.

This price calculation demonstrates invocation semantics only; it doesn’t define currency rounding. Production money code needs an explicit money type and rounding rule rather than a financial contract inferred from this integer example.

Probe accessibility without forcing modules open

trySetAccessible() returns true when Java can suppress language access checks and false otherwise. The example can read a private field in its own nested application class, but by default it can’t open java.lang, a package in java.base that isn’t open to the current module.

import java.lang.reflect.Field;

public class AccessBoundaries {
    private static final class Customer {
        private final String email;

        private Customer(String email) {
            this.email = email;
        }
    }

    public static void main(String[] args) throws Exception {
        Customer customer = new Customer("[email protected]");
        Field email = Customer.class.getDeclaredField("email");
        boolean applicationAccess = email.trySetAccessible();
        System.out.println("application field: " + applicationAccess
                + " -> " + email.get(customer));

        Field stringStorage = String.class.getDeclaredField("value");
        System.out.println("JDK field: " + stringStorage.trySetAccessible());
    }
}

application field: true -> [email protected]
JDK field: false

trySetAccessible() makes access failure an explicit branch; setAccessible(true) throws InaccessibleObjectException in the same situation. Neither API authorizes an operation or proves that reading a sensitive field complies with application policy.

If a framework needs deep reflection, the inspected module should declare its supported runtime contract with opens or open module. Command-line --add-opens can help in a controlled migration or test, but silently adding it to production startup hides the fact that the module owner didn’t promise the access.

Successful private-field access still couples the consumer to internal representation. A field rename, a switch from storage to computation, or a new invariant can break the consumer, so domain objects should prefer stable APIs and serialization boundaries need an explicit version policy.

Build a diagnosable interface proxy

A JDK dynamic proxy creates an object at runtime that implements a supplied interface set and sends calls to an InvocationHandler. In addition to tracing domain calls, this handler treats toString(), hashCode(), and equals() explicitly and unwraps target exceptions.

import java.lang.reflect.*;
import java.util.Arrays;
public class TraceProxy {
    interface Inventory {
        int reserve(String sku, int units);
    }
    static final class Warehouse implements Inventory {
        private int available = 8;
        public int reserve(String sku, int units) {
            if (units > available) throw new IllegalStateException("insufficient stock");
            available -= units;
            return available;
        }
        public String toString() { return "main warehouse"; }
    }
    public static void main(String[] args) {
        Inventory target = new Warehouse();
        Inventory traced = (Inventory) Proxy.newProxyInstance(
                Inventory.class.getClassLoader(),
                new Class<?>[] { Inventory.class },
                (proxy, method, arguments) -> {
                    if (method.getDeclaringClass() == Object.class) {
                        return switch (method.getName()) {
                            case "toString" -> "Trace[" + target + "]";
                            case "hashCode" -> System.identityHashCode(proxy);
                            case "equals" -> proxy == arguments[0];
                            default -> throw new AssertionError(method);
                        };
                    }
                    System.out.println(method.getName() + " " + Arrays.toString(arguments));
                    try {
                        return method.invoke(target, arguments);
                    } catch (InvocationTargetException error) {
                        throw error.getCause();
                    }
                });
        System.out.println(traced);
        System.out.println("remaining: " + traced.reserve("P-7", 3));
    }
}

Trace[main warehouse]
reserve [P-7, 3]
remaining: 5

If the handler concatenates proxy into its log, it re-enters toString() and can recurse. The example gives object methods identity semantics for the proxy itself; a real system must decide whether those semantics should match the target rather than copying a template.

method.invoke(target, arguments) uses reflection again, so it wraps target exceptions. Unwrapping preserves runtime exceptions declared by the interface; checked exceptions are also constrained by the interface’s throws clause, and an undeclared one may surface as UndeclaredThrowableException.

JDK proxies implement interfaces only. Frameworks that proxy a concrete class usually generate a subclass or transform bytecode, which introduces a different set of visibility, final member, and construction rules. Don’t attribute a framework’s class-proxy capability to Proxy.newProxyInstance().

Pitfalls

Guessing a method signature from argument classes

Fix: make the invocation protocol carry explicit parameter types, or map an external operation name to a prevalidated Method. If you truly support overload resolution, implement primitive conversions, varargs, null, and ambiguity rules as a separate algorithm with full tests.

Confusing getMethod() and getDeclaredMethod()

Fix: define whether you need the public invocation view or declaration view first. A hierarchy scan must handle superclasses, interfaces, overrides, and bridge methods explicitly, with a deterministic conflict rule.

Treating setAccessible(true) as a master switch

Fix: prefer public APIs. When a framework needs non-public access, have the package’s owning module declare the contract with a qualified opens, and test InaccessibleObjectException as a deployment error instead of swallowing it and continuing.

Losing the target exception

Fix: distinguish lookup, access, argument conversion, and target execution failures. Unwrap getCause(), then rethrow or translate it according to the boundary contract while retaining the original cause in the exception chain.

Trusting scan order and source shape

Fix: filter members outside the contract, sort by a stable key, and reject ambiguity explicitly. Also verify parameter names, generic signatures, and annotations independently; visibility in an IDE doesn’t prove runtime availability.

Leaking a class loader through a cache

Fix: scope a cache to the framework context or class loader, consider ClassValue, and verify in unload tests that old loaders can be released. Add caching only when measurements justify it, and include the full signature and policy in each key.

Further reading

• Java SE 25 Class API
• Java SE 25 reflection package overview
• Java SE 25 AccessibleObject API
• Java SE 25 Method API
• Java SE 25 Proxy API