Reflection, method handles and VarHandles

Java reflection lets a running program look at its own classes and use them by name: list the fields, methods, constructors and record components of a class, read a field, call a method, create an object. It lives in java.lang.reflect, and test runners, serializers and dependency-injection containers are built on it. Method handles, in java.lang.invoke, are typed references to a method, a constructor or a field that can be called directly. Their access is checked once, when the handle is looked up, instead of on every call. VarHandles are typed references to a variable, a field or an array element, with access modes that plain reflection lacks, such as compareAndSet and getAndAdd. All three trade compile-time checks for run-time flexibility, so mistakes show up only when the code runs, and since JDK 17 strong encapsulation stops them from reaching into the JDK’s own internals. Every session here was recorded on Eclipse Temurin 25.0.4.1, with comparisons on JDK 27.

Inspecting a record at run time

Csv.write turns a list of any record type into CSV without knowing the type in advance: the record’s components give the column names, and each component’s accessor method reads its value:

import java.lang.reflect.RecordComponent;
import java.util.List;
import java.util.StringJoiner;

/** A CSV writer for any record, written once: reflection supplies the column names and reads every value. */
record Ticket(String pnr, String from, String to, int farePaise) {}
record Reading(String sensor, double celsius) {}

public class Csv {
    static <R extends Record> String write(Class<R> type, List<R> rows) throws ReflectiveOperationException {
        RecordComponent[] components = type.getRecordComponents();
        StringJoiner out = new StringJoiner("\n", "", "\n");
        StringJoiner header = new StringJoiner(",");
        for (RecordComponent c : components) header.add(c.getName());
        out.add(header.toString());
        for (R row : rows) {
            StringJoiner line = new StringJoiner(",");
            for (RecordComponent c : components) line.add(field(c.getAccessor().invoke(row)));
            out.add(line.toString());
        }
        return out.toString();
    }

    /** RFC 4180 style: a value with a comma, a quote or a line break goes in quotes, with its quotes doubled. */
    static String field(Object value) {
        String s = String.valueOf(value);
        boolean quote = s.contains(",") || s.contains("\"") || s.contains("\n");
        return quote ? "\"" + s.replace("\"", "\"\"") + "\"" : s;
    }

    public static void main(String[] args) throws ReflectiveOperationException {
        System.out.print(write(Ticket.class, List.of(
                new Ticket("4521837690", "NDLS", "BCT", 2_150_00),
                new Ticket("8812004533", "SBC", "MAS, Chennai", 655_00))));
        System.out.print(write(Reading.class, List.of(new Reading("roof", 31.5))));
        for (RecordComponent c : Ticket.class.getRecordComponents()) {
            System.out.println(c.getName() + ": " + c.getType().getSimpleName() + ", read by " + c.getAccessor().getName() + "()");
        }
        System.out.println("String.class.getRecordComponents(): " + String.class.getRecordComponents());
    }
}

from session import run

# The CSV writer for any record, run on two record types, then what reflection says about one of them.
run("""
javac -d out inspect/Csv.java
java -cp out Csv
""")

# JDK in use: openjdk version "25.0.4.1" LTS
$ javac -d out inspect/Csv.java
$ java -cp out Csv
pnr,from,to,farePaise
4521837690,NDLS,BCT,215000
8812004533,SBC,"MAS, Chennai",65500
sensor,celsius
roof,31.5
pnr: String, read by pnr()
from: String, read by from()
to: String, read by to()
farePaise: int, read by farePaise()
String.class.getRecordComponents(): null

Class.getRecordComponents() returns the components in the order the record declares them, each with its name, its type and its accessor, and it returns null for a class that is not a record, as the last line shows. The writer calls getAccessor().invoke(row) for every value, which is Java reflection at its most typical: one piece of code that works for every record, written without knowing any of them. The price is that a mistake, such as passing the wrong class, is found only at run time.

The same Class object answers many other questions. getDeclaredFields() and getDeclaredMethods() return what the class itself declares, private members included, while getFields() and getMethods() return only public members, inherited ones included. isRecord(), isSealed() and getPermittedSubclasses() describe the newer kinds of class, and Modifier decodes whether a member is static, final or private. None of these arrays comes in a guaranteed order, except the record components.

One method, three ways to call it

Calls calls Fare.withTax directly, through a Method object and through a method handle, then makes the same calls go wrong:

import java.lang.invoke.MethodHandle;
import java.lang.invoke.MethodHandles;
import java.lang.invoke.MethodType;
import java.lang.reflect.Method;

/** One method called directly, through reflection and through a method handle, with right and wrong arguments. */
public class Calls {
    static final class Fare {
        private final int paise;

        Fare(int paise) { this.paise = paise; }

        int withTax(int percent) {
            if (percent < 0) throw new IllegalArgumentException("negative tax rate " + percent);
            return paise + paise * percent / 100;
        }
    }

    public static void main(String[] args) throws Throwable {
        Fare fare = new Fare(10_000);
        System.out.println("direct call:   " + fare.withTax(18));

        Method method = Fare.class.getDeclaredMethod("withTax", int.class);
        System.out.println("reflection:    " + method.invoke(fare, 18));

        MethodHandle handle = MethodHandles.lookup().findVirtual(Fare.class, "withTax", MethodType.methodType(int.class, int.class));
        System.out.println("method handle: " + (int) handle.invokeExact(fare, 18) + ", its type " + handle.type());

        try {
            method.invoke(fare, -1);
        } catch (Exception e) {
            System.out.println("reflection threw " + e.getClass().getSimpleName() + ", cause: " + e.getCause());
        }
        try {
            int ignored = (int) handle.invokeExact(fare, -1);
        } catch (IllegalArgumentException e) {
            System.out.println("method handle threw " + e);
        }
        try {
            method.invoke(fare, "18");
        } catch (IllegalArgumentException e) {
            System.out.println("reflection with a String argument: " + e);
        }
        try {
            long wrong = (long) handle.invokeExact(fare, 18);
        } catch (Throwable e) {
            System.out.println("invokeExact with a long result: " + e);
        }
        System.out.println("invoke adapts the types: " + (long) handle.invoke(fare, Integer.valueOf(18)));
    }
}

from session import run

# One method, three ways to call it, and what each way does with a failing call and with wrong types.
run("""
javac -d out calls/Calls.java
java -cp out Calls
""")

# JDK in use: openjdk version "25.0.4.1" LTS
$ javac -d out calls/Calls.java
$ java -cp out Calls
direct call:   11800
reflection:    11800
method handle: 11800, its type (Fare,int)int
reflection threw InvocationTargetException, cause: java.lang.IllegalArgumentException: negative tax rate -1
method handle threw java.lang.IllegalArgumentException: negative tax rate -1
reflection with a String argument: java.lang.IllegalArgumentException: argument type mismatch
invokeExact with a long result: java.lang.invoke.WrongMethodTypeException: handle's method type (Fare,int)int but found (Fare,int)long
invoke adapts the types: 11800

All three returned 11,800. The failures differ. Method.invoke wrapped the method’s own exception in an InvocationTargetException, and it accepted a String argument until it ran, then refused it as an argument type mismatch. The method handle threw the method’s exception as it is, and invokeExact insisted on the exact type (Fare,int)int: asking for a long result threw WrongMethodTypeException, while invoke converted the boxed argument and the result for us. invokeExact is the strict and cheaper form, because no conversion runs; invoke suits code that only learns the types at run time, at the price of the conversions it adds.

A method handle starts from a Lookup. MethodHandles.lookup() carries the access rights of the class that calls it, so the handles it creates reach exactly what that class could call directly, here a method of a nested class that is not public. A MethodType describes the return type and the parameter types, and findVirtual, findStatic, findConstructor and findGetter turn a class, a name and a type into a handle, or throw at once if no such member is accessible.

Reflection, method handles and VarHandles compared

Java reflection is the tool for finding out what a class has; method handles are the tool for calling something you have already found, many times; VarHandles are the tool for atomic access to a field without a lock. They also combine: Lookup.unreflect turns a Method found by reflection into a method handle. Application code rarely needs any of them, and keeping them at the edges, in the framework or library that maps or injects, leaves the rest of the code checked by the compiler. When the operations are known in advance, an interface or a lambda is the better tool: a Function<Ticket, String> is a typed reference to code that javac checks, and it is called like any other method.

What reflection and method handles cost, measured with JMH Pro: opens with a Pro, Premium or Ultimate pass

What deep reflection may still do: atomic fields, open packages and final fields Pro: opens with a Pro, Premium or Ultimate pass

Key takeaways

• Reflection finds and uses members by name at run time; getRecordComponents() lists a record’s components in order.
• Method.invoke wraps failures in InvocationTargetException and checks argument types only when it runs.
• Method handles check access once, at the lookup, and invokeExact demands the exact type.
• VarHandles give a field atomic and ordered access modes, such as compareAndSet and getAndAdd.