The new reflection - Basics

The basic reflection facility of Java historically amounts to using a Class object to acquire Method, Constructor, and/or Field objects. These objects are used primarily for invocation of a method or constructor (in the former two cases) or read/write access to a field (in the latter case). The mechanism is simple: each reflective object accepts an Object or array of Object and yields void or an Object with the result (depending on the operation).

Because primitives in Java are not Object instances, in order to pass or return values of primitive type, we rely on so-called "box objects", which are object classes whose purpose is to represent a primitive value as an Object.

These APIs are fairly useful for a number of use cases (including non-access cases like examining annotations), but come with several limitations:

In Java 7, a new class was introduced which was intended to overcome these limitations, called `MethodHandle` . This class, and its related classes in `java.lang.invoke` , are all designed to support a new and more efficient means of indirect access to class members. The initial motivating use case included support for the new invokedynamic JVM instruction as part of JSR 292 .

This efficiency is primarily achieved through a few specific mechanisms:

In addition to acting as a replacement for a large number of reflection use cases, method handles are also the basis of lambdas and the Foreign Function & Memory (FFM) API , among other things.

int result = (int) mh.invokeExact(123, "Hello world!", Object.class);

mh.invokeExact(123, "Hello world!", Object.class);

var _ = (int) mh.invokeExact(123, "Hello world!", Object.class);

long result = (int) mh.invokeExact(123, "Hello world!", Object.class);

String result = (String) (CharSequence) mh.invokeExact();

Every MethodHandle instance has a method type, represented by instances of `MethodType` and accessible using the `MethodHandle#type()` accessor method. This class encodes the argument types and return type (as Class instances) of a method, which suffices to identify the type of any given call site. Every call site has an implied MethodType which goes along with it.

A MethodHandle may be transformed to have a different type by using the `MethodHandle#asType()` method. This method returns a new version of the given MethodHandle, but where each argument and the return type are based on those of the given MethodType. The number of arguments in the new type must equal the number of arguments in the old type, and the conversion must be valid. For example, if you have a method handle whose return type is String, and you try to convert it to one which returns an int, an exception is thrown. However, converting a method handle which returns String to one which returns CharSequence is perfectly valid.

A method handle may be invoked exactly or inexactly. Invoking a method handle exactly is done via the MethodHandle.invokeExact(...) method. When performing an exact invocation, the call site's implied type and the type of the MethodHandle must be exactly identical (even the return type), or an exception will be thrown at run time.

Inexact invocation via the MethodHandle.invoke(...) method is much more flexible. Rather than requiring the method handle's type to exactly match, an inexact invocation works on any method handle which can be reasonably converted to the call site type (as if by calling MethodHandle.asType(callSiteType) with the exact type of the call site). However, this flexibility comes at a cost, since the argument types have to be checked at run time; this may be unnecessary in many cases for exact invocations.

If a method handle is only going to be used once, then an inexact call via invoke(...) is usually going to be fine. Otherwise, it is usually preferable to use invokeExact(...). One common strategy is to adapt an original MethodHandle to the expected call site type using asType(), and store the result in some place where it can be reused thereafter.

Unfortunately, the invocation methods on MethodHandle are declared to throw Throwable. This is because a MethodHandle can refer to anything in the JVM that can be called, and those things in turn can be declared to throw any kind or number of exceptions.

To cope with this, you may be tempted to wrap the Throwable with some kind of RuntimeException subclass and rethrow it unconditionally. Do not do this !

Instead, use this pattern always:

private void invokeIt(MethodHandle handle, int foo, String bar) {
    try {
        int ignored = (int) handle.invokeExact(foo, bar);
    } catch (RuntimeException | Error e) {
        throw e;
    } catch (Throwable t) {
        throw new UndeclaredThrowableException(t);
    }
}

If the method handle in question has some specific checked exceptions that can be thrown, add those to the list:

private void invokeIt(MethodHandle handle, int foo, String bar) throws SpecificException {
    try {
        int ignored = (int) handle.invokeExact(foo, bar);
    } catch (RuntimeException | Error | SpecificException e) {
        throw e;
    } catch (Throwable t) {
        throw new UndeclaredThrowableException(t);
    }
}

A MethodHandle is not useful unless you can somehow acquire one. In order to acquire a MethodHandle, you need an instance of `MethodHandles.Lookup` .

A Lookup instance provides factory methods which can create method handles representing:

A Lookup functions as an access key to a given lookup class, which is the class that is associated with the Lookup instance. The lookup class can be returned by calling the lookupClass() getter method on a Lookup instance.

The access power of the Lookup depends not only on the lookup class, but also on its _lookup mode_ . The lookup mode determines which access levels are accessible by the Lookup. For example, a Lookup with PRIVATE access may be used to access any private member that is accessible from the lookup class. However a Lookup which lacks PRIVATE access may not access any private members, even those which would otherwise be accessible from the lookup class. A lookup with reduced lookup modes may be created by calling the `dropLookupMode(int)` method with the specific mode to drop.

There are several possible ways to acquire a Lookup. The best strategy to use depends on use case.

In the next post in this series, I will cover some more intermediate-level cases and talk a bit out proper API design around method handles.