java.dyn
Class MethodHandles.Lookup
java.lang.Object
java.dyn.MethodHandles.Lookup
- Enclosing class:
- MethodHandles
public static final class MethodHandles.Lookup
- extends Object
Disabled: no SafeJ information.
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.
Note that access checks only apply to named and reflected methods.
Other method handle creation methods, such as MethodHandles.convertArguments(java.dyn.MethodHandle, java.dyn.MethodType)
,
do not require any access checks, and can be done independently
of any lookup class.
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.
Method Summary |
MethodHandle |
bind(Object receiver,
String name,
MethodType type)
Produce an early-bound method handle for a non-static method. |
MethodHandle |
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 . |
MethodHandle |
findStatic(Class<?> defc,
String name,
MethodType type)
Produce a method handle for a static method. |
MethodHandle |
findVirtual(Class<?> defc,
String name,
MethodType type)
Produce a method handle for a virtual method. |
MethodHandles.Lookup |
in(Class<?> newLookupClass)
Create a lookup on the specified class. |
Class<?> |
lookupClass()
Which class is performing the lookup? It is this class against
which checks are performed for visibility and access permissions. |
String |
toString()
Returns a string representation of the object. |
MethodHandle |
unreflect(Method m)
PROVISIONAL API, WORK IN PROGRESS:
Make a direct method handle to m, if the lookup class has permission. |
MethodHandle |
unreflectConstructor(Constructor ctor)
PROVISIONAL API, WORK IN PROGRESS:
Produce a method handle for a reflected constructor. |
MethodHandle |
unreflectGetter(Field f)
PROVISIONAL API, WORK IN PROGRESS:
Produce a method handle giving read access to a reflected field. |
MethodHandle |
unreflectSetter(Field f)
PROVISIONAL API, WORK IN PROGRESS:
Produce a method handle giving write access to a reflected field. |
MethodHandle |
unreflectSpecial(Method m,
Class<?> specialCaller)
PROVISIONAL API, WORK IN PROGRESS:
Produce a method handle for a reflected method. |
lookupClass
public Class<?> lookupClass()
- Class is disabled.
- Which class is performing the lookup? It is this class against
which checks are performed for visibility and access permissions.
This value is null if and only if this lookup was produced
by MethodHandles.publicLookup()
.
in
public MethodHandles.Lookup in(Class<?> newLookupClass)
- Class is disabled.
- Create a lookup on the specified class.
The result is guaranteed to have no more access privileges
than the original.
toString
public String toString()
- Suppressed. calls hashCode(), which may be nondeterministic
- Description copied from class:
Object
- 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:
getClass().getName() + '@' + Integer.toHexString(hashCode())
- Overrides:
toString
in class Object
- Returns:
- a string representation of the object.
findStatic
public MethodHandle findStatic(Class<?> defc,
String name,
MethodType type)
throws NoAccessException
- Class is disabled.
- Produce a method handle for a static method.
The type of the method handle will be that of the method.
(Since static methods do not take receivers, there is no
additional receiver argument inserted into the method handle type,
as there would be with findVirtual(java.lang.Class>, java.lang.String, java.dyn.MethodType) or findSpecial(java.lang.Class>, java.lang.String, java.dyn.MethodType, java.lang.Class>).)
The method and all its argument types must be accessible to the lookup class.
If the method's class has not yet been initialized, that is done
immediately, before the method handle is returned.
- Parameters:
defc
- the class from which the method is accessedname
- the name of the methodtype
- the type of the method
- Returns:
- the desired method handle
- Throws:
SecurityException
- TBD
NoAccessException
- if the method does not exist or access checking fails
findVirtual
public MethodHandle findVirtual(Class<?> defc,
String name,
MethodType type)
throws NoAccessException
- Class is disabled.
- 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 accessedname
- the name of the methodtype
- the type of the method, with the receiver argument omitted
- Returns:
- the desired method handle
- Throws:
SecurityException
- TBD
NoAccessException
- if the method does not exist or access checking fails
findSpecial
public MethodHandle findSpecial(Class<?> defc,
String name,
MethodType type,
Class<?> specialCaller)
throws NoAccessException
- Class is disabled.
- 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 accessedname
- the name of the method, or "" for a constructortype
- the type of the method, with the receiver argument omittedspecialCaller
- the proposed calling class to perform the invokespecial
- Returns:
- the desired method handle
- Throws:
SecurityException
- TBD
NoAccessException
- if the method does not exist or access checking fails
bind
public MethodHandle bind(Object receiver,
String name,
MethodType type)
throws NoAccessException
- Class is disabled.
- 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.
This is equivalent to the following expression:
MethodHandles.insertArguments(java.dyn.MethodHandle, int, java.lang.Object...)
(findVirtual(java.lang.Class>, java.lang.String, java.dyn.MethodType)
(defc, name, type), receiver)
where defc
is either receiver.getClass()
or a super
type of that class, in which the requested method is accessible
to the lookup class.
- Parameters:
receiver
- the object from which the method is accessedname
- the name of the methodtype
- the type of the method, with the receiver argument omitted
- Returns:
- the desired method handle
- Throws:
SecurityException
- TBD
NoAccessException
- if the method does not exist or access checking fails
unreflect
public MethodHandle unreflect(Method m)
throws NoAccessException
- Class is disabled.
- 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
- Throws:
NoAccessException
- if access checking fails
unreflectSpecial
public MethodHandle unreflectSpecial(Method m,
Class<?> specialCaller)
throws NoAccessException
- Class is disabled.
- 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
- Throws:
NoAccessException
- if access checking fails
unreflectConstructor
public MethodHandle unreflectConstructor(Constructor ctor)
throws NoAccessException
- Class is disabled.
- 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
- Throws:
NoAccessException
- if access checking fails
unreflectGetter
public MethodHandle unreflectGetter(Field f)
throws NoAccessException
- Class is disabled.
- 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
- Throws:
NoAccessException
- if access checking fails
unreflectSetter
public MethodHandle unreflectSetter(Field f)
throws NoAccessException
- Class is disabled.
- 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
- Throws:
NoAccessException
- if access checking fails