public static final class MethodHandles.Lookup
extends Object
A factory object for creating method handles, when the creation
requires access checking. Method handles do not perform
access checks when they are called; this is a major difference
from reflective Method, which performs access checking
against every caller, on every call. Method handle access
restrictions are enforced when a method handle is created.
The caller class against which those restrictions are enforced
is known as the "lookup class". MethodHandles.Lookup embodies an
authenticated lookup class, and can be used to create any number
of access-checked method handles, all checked against a single
lookup class.
A class which needs to create method handles will call
MethodHandles.lookup() to create a factory for itself.
It may then use this factory to create method handles on
all of its methods, including private ones.
It may also delegate the lookup (e.g., to a metaobject protocol)
by passing the Lookup object to other code.
If this other code creates method handles, they will be access
checked against the original lookup class, and not with any higher
privileges.
A note about error conditions: A lookup can fail, because
the containing class is not accessible to the lookup class, or
because the desired class member is missing, or because the
desired class member is not accessible to the lookup class.
It can also fail if a security manager is installed and refuses
access. In any of these cases, an exception will be
thrown from the attempted lookup.
In general, the conditions under which a method handle may be
created for a method M are exactly as restrictive as the conditions
under which the lookup class could have compiled a call to M.
At least some of these error conditions are likely to be
represented by checked exceptions in the final version of this API.
findSpecial(Class<?> defc,
String name,
MethodType type,
Class<?> specialCaller)
Produce an early-bound method handle for a virtual method,
as if called from an invokespecial
instruction from caller.
Returns a string representation of the object. In general, the
toString method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
Produce a method handle for a virtual method.
The type of the method handle will be that of the method,
with the receiver type (defc) prepended.
The method and all its argument types must be accessible to the lookup class.
(BUG NOTE: The type Object may be prepended instead
of the receiver type, if the receiver type is not on the boot class path.
This is due to a temporary JVM limitation, in which MethodHandle
claims to be unable to access such classes. To work around this
bug, use convertArguments to normalize the type of the leading
argument to a type on the boot class path, such as Object.)
When called, the handle will treat the first argument as a receiver
and dispatch on the receiver's type to determine which method
implementation to enter.
(The dispatching action is identical with that performed by an
invokevirtual or invokeinterface instruction.)
Parameters:
defc - the class or interface from which the method is accessed
name - the name of the method
type - the type of the method, with the receiver argument omitted
Produce an early-bound method handle for a virtual method,
as if called from an invokespecial
instruction from caller.
The type of the method handle will be that of the method,
with a suitably restricted receiver type (such as caller) prepended.
The method and all its argument types must be accessible
to the caller.
When called, the handle will treat the first argument as a receiver,
but will not dispatch on the receiver's type.
(This direct invocation action is identical with that performed by an
invokespecial instruction.)
If the explicitly specified caller class is not identical with the
lookup class, a security check TBD is performed.
Parameters:
defc - the class or interface from which the method is accessed
name - the name of the method, or "" for a constructor
type - the type of the method, with the receiver argument omitted
specialCaller - the proposed calling class to perform the invokespecial
Produce an early-bound method handle for a non-static method.
The receiver must have a supertype defc in which a method
of the given name and type is accessible to the lookup class.
The method and all its argument types must be accessible to the lookup class.
The type of the method handle will be that of the method,
without any insertion of an additional receiver parameter.
The given receiver will be bound into the method handle,
so that every call to the method handle will invoke the
requested method on the given receiver.
PROVISIONAL API, WORK IN PROGRESS:
Make a direct method handle to m, if the lookup class has permission.
If m is non-static, the receiver argument is treated as an initial argument.
If m is virtual, overriding is respected on every call.
Unlike the Core Reflection API, exceptions are not wrapped.
The type of the method handle will be that of the method,
with the receiver type prepended (but only if it is non-static).
If the method's accessible flag is not set,
access checking is performed immediately on behalf of the lookup class.
If m is not public, do not share the resulting handle with untrusted parties.
Parameters:
m - the reflected method
Returns:
a method handle which can invoke the reflected method
PROVISIONAL API, WORK IN PROGRESS:
Produce a method handle for a reflected method.
It will bypass checks for overriding methods on the receiver,
as if by the invokespecial instruction.
The type of the method handle will be that of the method,
with the receiver type prepended.
If the method's accessible flag is not set,
access checking is performed immediately on behalf of the lookup class,
as if invokespecial instruction were being linked.
Parameters:
m - the reflected method
Returns:
a method handle which can invoke the reflected method
PROVISIONAL API, WORK IN PROGRESS:
Produce a method handle for a reflected constructor.
The type of the method handle will be that of the constructor,
with the return type changed to the declaring class.
The method handle will perform a newInstance operation,
creating a new instance of the constructor's class on the
arguments passed to the method handle.
If the constructor's accessible flag is not set,
access checking is performed immediately on behalf of the lookup class.
Parameters:
ctor - the reflected constructor
Returns:
a method handle which can invoke the reflected constructor
PROVISIONAL API, WORK IN PROGRESS:
Produce a method handle giving read access to a reflected field.
The type of the method handle will have a return type of the field's
value type.
If the field is static, the method handle will take no arguments.
Otherwise, its single argument will be the instance containing
the field.
If the method's accessible flag is not set,
access checking is performed immediately on behalf of the lookup class.
Parameters:
f - the reflected field
Returns:
a method handle which can load values from the reflected field
PROVISIONAL API, WORK IN PROGRESS:
Produce a method handle giving write access to a reflected field.
The type of the method handle will have a void return type.
If the field is static, the method handle will take a single
argument, of the field's value type, the value to be stored.
Otherwise, the two arguments will be the instance containing
the field, and the value to be stored.
If the method's accessible flag is not set,
access checking is performed immediately on behalf of the lookup class.
Parameters:
f - the reflected field
Returns:
a method handle which can store values into the reflected field
java.dyn.MethodHandles.Lookup