Please note that this documentation is not final and is subject to change.

java.dyn
Class MethodHandle

java.lang.Object
  sun.dyn.MethodHandleImpl
      java.dyn.MethodHandle

Direct Known Subclasses:

sun.dyn.BoundMethodHandle

public abstract class MethodHandle
extends sun.dyn.MethodHandleImpl

A method handle is a typed reference to the entry point of a method.

Method handles are strongly typed according to signature. They are not distinguished by method name or enclosing class. A method handle must be invoked under a signature which exactly matches the method handle's own type.

Every method handle confesses its type via the type accessor. The structure of this type is a series of classes, one of which is the return type of the method (or void.class if none).

Every method handle appears as an object containing a method named invoke, whose signature exactly matches the method handle's type. A normal Java method call (using the invokevirtual instruction) can invoke this method from Java source code (if language support is present).

Every call to a method handle specifies an intended method type, which must exactly match the type of the method handle. (The type is specified in the invokevirtual instruction, via a CONSTANT_NameAndType constant pool entry.) The call looks within the receiver object for a method named invoke of the intended method type. The call fails with a WrongMethodTypeException if the method does not exist, even if there is an invoke method of a closely similar signature.

A method handle is an unrestricted capability to call a method. A method handle can be formed on a non-public method by a class that has access to that method; the resulting handle can be used in any place by any caller who receives a reference to it. Thus, access checking is performed when the method handle is created, not (as in reflection) every time it is called. Handles to non-public methods, or in non-public classes, should generally be kept secret. They should not be passed to untrusted code.

Bytecode in an extended JVM can directly call a method handle's invoke from an invokevirtual instruction. The receiver class type must be MethodHandle and the method name must be invoke. The signature of the invocation (after resolving symbolic type names) must exactly match the method type of the target method.

Bytecode in an extended JVM can directly obtain a method handle for any accessible method from a ldc instruction which refers to a CONSTANT_Methodref or CONSTANT_InterfaceMethodref constant pool entry.

All JVMs can also use a reflective API called MethodHandles for creating and calling method handles.

A method reference may refer either to a static or non-static method. In the non-static case, the method handle type includes an explicit receiver argument, prepended before any other arguments. In the method handle's type, the initial receiver argument is typed according to the class under which the method was initially requested. (E.g., if a non-static method handle is obtained via ldc, the type of the receiver is the class named in the constant pool entry.)

When a method handle to a virtual method is invoked, the method is always looked up in the receiver (that is, the first argument).

A non-virtual method handles to a specific virtual method implementation can also be created. These do not perform virtual lookup based on receiver type. Such a method handle simulates the effect of an invokespecial instruction to the same method.

See Also:

MethodType, MethodHandles

Field Summary

Modifier and Type	Field and Description

Fields inherited from class sun.dyn.MethodHandleImpl

vmtarget

Constructor Summary

Modifier	Constructor and Description
protected	MethodHandle(sun.dyn.Access token, MethodType type) The constructor for MethodHandle may only be called by privileged code.

Method Summary

Modifier and Type	Method and Description
MethodType	type() Report the type of this method handle.

Methods inherited from class sun.dyn.MethodHandleImpl

accessArrayElement, accessField, addTypeString, basicToString, bindArgument, bindReceiver, collectArguments, combineArguments, convertArguments, dropArguments, findMethod, getLookup, init, initLookup, initStatics, makeGuardWithTest, spreadArguments, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

MethodHandle

protected MethodHandle(sun.dyn.Access token,
                       MethodType type)

The constructor for MethodHandle may only be called by privileged code. Subclasses may be in other packages, but must possess a token which they obtained from MH with a security check.

Parameters:

token - non-null object which proves access permission

type - type (permanently assigned) of the new method handle

Method Detail

type

public MethodType type()

Report the type of this method handle. Every invocation of this method handle must exactly match this type.

Returns:

the method handle type