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.

Methods inherited from class java.lang.Object

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

Method Detail

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 accessed

name - the name of the method

type - 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 accessed

name - the name of the method

type - 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 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

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 accessed

name - the name of the method

type - 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