java.lang.invoke

Class MethodHandles

java.lang.Object

java.lang.invoke.MethodHandles

public class MethodHandles
extends Object

This class consists exclusively of static methods that operate on or return method handles. They fall into several categories:

• Lookup methods which help create method handles for methods and fields.
• Combinator methods, which combine or transform pre-existing method handles into new ones.
• Other factory methods to create method handles that emulate other common JVM operations or control flow patterns.

Since:

1.7

Author:

John Rose, JSR 292 EG

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MethodHandles.Lookup A lookup object is a factory for creating method handles, when the creation requires access checking.

Method Summary

Methods

Modifier and Type	Method and Description
static MethodHandles.Lookup	lookup() Returns a lookup object with full capabilities to emulate all supported bytecode behaviors of the caller.
static MethodHandles.Lookup	publicLookup() Returns a lookup object which is trusted minimally.
static <T extends Member> T	reflectAs(Class<T> expected, MethodHandle target) Performs an unchecked "crack" of a direct method handle.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

lookup

public static MethodHandles.Lookup lookup()

Returns a lookup object with full capabilities to emulate all supported bytecode behaviors of the caller. These capabilities include private access to the caller. Factory methods on the lookup object can create direct method handles for any member that the caller has access to via bytecodes, including protected and private fields and methods. This lookup object is a capability which may be delegated to trusted agents. Do not store it in place where untrusted code can access it.

This method is caller sensitive, which means that it may return different values to different callers.

For any given caller class C, the lookup object returned by this call has equivalent capabilities to any lookup object supplied by the JVM to the bootstrap method of an invokedynamic instruction executing in the same caller class C.

Returns:

a lookup object for the caller of this method, with private access

publicLookup

public static MethodHandles.Lookup publicLookup()

Returns a lookup object which is trusted minimally. It can only be used to create method handles to publicly accessible fields and methods.

As a matter of pure convention, the lookup class of this lookup object will be Object.

Discussion: The lookup class can be changed to any other class C using an expression of the form publicLookup().in(C.class). Since all classes have equal access to public names, such a change would confer no new access rights. A public lookup object is always subject to security manager checks. Also, it cannot access caller sensitive methods.

Returns:

a lookup object which is trusted minimally

reflectAs

public static <T extends Member> T reflectAs(Class<T> expected,
                             MethodHandle target)

Performs an unchecked "crack" of a direct method handle. The result is as if the user had obtained a lookup object capable enough to crack the target method handle, called Lookup.revealDirect on the target to obtain its symbolic reference, and then called MethodHandleInfo.reflectAs to resolve the symbolic reference to a member.

If there is a security manager, its checkPermission method is called with a ReflectPermission("suppressAccessChecks") permission.

Type Parameters:

T - the desired type of the result, either Member or a subtype

Parameters:

target - a direct method handle to crack into symbolic reference components

expected - a class object representing the desired result type T

Returns:

a reference to the method, constructor, or field object

Throws:

SecurityException - if the caller is not privileged to call setAccessible

NullPointerException - if either argument is null

IllegalArgumentException - if the target is not a direct method handle

ClassCastException - if the member is not of the expected type

Since:

1.8