Spec-Zone .ru спецификации, руководства, описания, API

Please note that the specifications and other information contained herein are not final and are subject to change. The information is being made available to you solely for purpose of evaluation.

java.dyn
Class MethodHandles.Lookup

java.lang.Object
  java.dyn.MethodHandles.Lookup

Enclosing class:

MethodHandles

public static final class MethodHandles.Lookup
extends Object

A lookup object is a factory for creating method handles, when the creation requires access checking. Method handles do not perform access checks when they are called, but rather when they are created. (This is a major difference from reflective Method, which performs access checking against every caller, on every call.) Therefore, method handle access restrictions must be enforced when a method handle is created. The caller class against which those restrictions are enforced is known as the lookup class. A lookup object 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.

Access checks only apply to named and reflected methods. Other method handle creation methods, such as MethodHandles.convertArguments, do not require any access checks, and can be done independently of any lookup class.

How access errors are handled

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. This rule is applied even if the Java compiler might have created an wrapper method to access a private method of another class in the same top-level declaration. For example, a lookup object created for a nested class C.D can access private members within other related classes such as C, C.D.E, or C.B.

Method Summary

Modifier and Type	Method and Description
MethodHandle	bind(Object receiver, String name, MethodType type) Produce an early-bound method handle for a non-static method.
MethodHandle	findConstructor(Class<?> refc, MethodType type) Produce a method handle which creates an object and initializes it, using the constructor of the specified type.
MethodHandle	findGetter(Class<?> refc, String name, Class<?> type) PROVISIONAL API, WORK IN PROGRESS: Produce a method handle giving read access to a non-static field.
MethodHandle	findSetter(Class<?> refc, String name, Class<?> type) PROVISIONAL API, WORK IN PROGRESS: Produce a method handle giving write access to a non-static field.
MethodHandle	findSpecial(Class<?> refc, 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<?> refc, String name, MethodType type) Produce a method handle for a static method.
MethodHandle	findStaticGetter(Class<?> refc, String name, Class<?> type) PROVISIONAL API, WORK IN PROGRESS: Produce a method handle giving read access to a static field.
MethodHandle	findStaticSetter(Class<?> refc, String name, Class<?> type) PROVISIONAL API, WORK IN PROGRESS: Produce a method handle giving write access to a static field.
MethodHandle	findVirtual(Class<?> refc, String name, MethodType type) Produce a method handle for a virtual method.
MethodHandles.Lookup	in(Class<?> requestedLookupClass) Create a lookup on the specified new lookup class.
Class<?>	lookupClass() Which class is performing the lookup? It is this class against which checks are performed for visibility and access permissions.
int	lookupModes() Which types of members can this lookup object produce? The result is a bit-mask of the Modifier bits PUBLIC (0x01), PROTECTED (0x02), PRIVATE (0x04), and STATIC (0x08).
String	toString() Display the name of the class.
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 c) 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()

Which class is performing the lookup? It is this class against which checks are performed for visibility and access permissions.

The class implies a maximum level of access permission, but the permissions may be additionally limited by the bitmask lookupModes(), which controls whether non-public members can be accessed.

lookupModes

public int lookupModes()

Which types of members can this lookup object produce? The result is a bit-mask of the Modifier bits PUBLIC (0x01), PROTECTED (0x02), PRIVATE (0x04), and STATIC (0x08). The modifier bit STATIC stands in for the package protection mode, which does not have an explicit modifier bit.

in

public MethodHandles.Lookup in(Class<?> requestedLookupClass)

Create a lookup on the specified new lookup class. The resulting object will report the specified class as its own lookupClass.

However, the resulting Lookup object is guaranteed to have no more access capabilities than the original. In particular:

• If the new lookup class differs from the old one, protected members will not be accessible by virtue of inheritance.
• If the new lookup class is in a different package than the old one, protected and default (package) members will not be accessible.
• If the new lookup class is not within the same package member as the old one, private members will not be accessible.
• In all cases, public members will continue to be accessible.

toString

public String toString()

Display the name of the class. If there are restrictions on the access permitted to this lookup, display those also.

Overrides:

toString in class Object

Returns:

a string representation of the object.

findStatic

public MethodHandle findStatic(Class<?> refc,
                               String name,
                               MethodType type)
                        throws NoAccessException

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:

refc - 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<?> refc,
                                String name,
                                MethodType type)
                         throws NoAccessException

Produce a method handle for a virtual method. The type of the method handle will be that of the method, with the receiver type (usually refc) 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:

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

findConstructor

public MethodHandle findConstructor(Class<?> refc,
                                    MethodType type)
                             throws NoAccessException

Produce a method handle which creates an object and initializes it, using the constructor of the specified type. The parameter types of the method handle will be those of the constructor, while the return type will be a reference to the constructor's class. The constructor and all its argument types must be accessible to the lookup class. If the constructor's class has not yet been initialized, that is done immediately, before the method handle is returned.

Note: The requested type must have a return type of void. This is consistent with the JVM's treatment of constructor signatures.

Parameters:

refc - the class or interface from which the method is accessed

type - the type of the method, with the receiver argument omitted, and a void return type

Returns:

the desired method handle

Throws:

SecurityException - TBD

NoAccessException - if the method does not exist or access checking fails

findSpecial

public MethodHandle findSpecial(Class<?> refc,
                                String name,
                                MethodType type,
                                Class<?> specialCaller)
                         throws NoAccessException

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:

refc - the class or interface from which the method is accessed

name - the name of the method (which must not be "<init>")

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

findGetter

public MethodHandle findGetter(Class<?> refc,
                               String name,
                               Class<?> type)
                        throws NoAccessException

PROVISIONAL API, WORK IN PROGRESS: Produce a method handle giving read access to a non-static field. The type of the method handle will have a return type of the field's value type. The method handle's single argument will be the instance containing the field. Access checking is performed immediately on behalf of the lookup class.

Parameters:

name - the field's name

type - the field's type

Returns:

a method handle which can load values from the field

Throws:

NoAccessException - if access checking fails

findSetter

public MethodHandle findSetter(Class<?> refc,
                               String name,
                               Class<?> type)
                        throws NoAccessException

PROVISIONAL API, WORK IN PROGRESS: Produce a method handle giving write access to a non-static field. The type of the method handle will have a void return type. The method handle will take two arguments, the instance containing the field, and the value to be stored. The second argument will be of the field's value type. Access checking is performed immediately on behalf of the lookup class.

Parameters:

name - the field's name

type - the field's type

Returns:

a method handle which can store values into the field

Throws:

NoAccessException - if access checking fails

findStaticGetter

public MethodHandle findStaticGetter(Class<?> refc,
                                     String name,
                                     Class<?> type)
                              throws NoAccessException

PROVISIONAL API, WORK IN PROGRESS: Produce a method handle giving read access to a static field. The type of the method handle will have a return type of the field's value type. The method handle will take no arguments. Access checking is performed immediately on behalf of the lookup class.

Parameters:

name - the field's name

type - the field's type

Returns:

a method handle which can load values from the field

Throws:

NoAccessException - if access checking fails

findStaticSetter

public MethodHandle findStaticSetter(Class<?> refc,
                                     String name,
                                     Class<?> type)
                              throws NoAccessException

PROVISIONAL API, WORK IN PROGRESS: Produce a method handle giving write access to a static field. The type of the method handle will have a void return type. The method handle will take a single argument, of the field's value type, the value to be stored. Access checking is performed immediately on behalf of the lookup class.

Parameters:

name - the field's name

type - the field's type

Returns:

a method handle which can store values into the field

Throws:

NoAccessException - if access checking fails

bind

public MethodHandle bind(Object receiver,
                         String name,
                         MethodType type)
                  throws NoAccessException

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: insertArguments(findVirtual(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

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

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 a invokespecial instruction from within the specialCaller. The type of the method handle will be that of the method, with the special caller type prepended (and not the receiver of the method). 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

specialCaller - the class nominally calling the method

Returns:

a method handle which can invoke the reflected method

Throws:

NoAccessException - if access checking fails

unreflectConstructor

public MethodHandle unreflectConstructor(Constructor c)
                                  throws NoAccessException

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:

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

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

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