PACKAGE

public static final int PACKAGE

A single-bit mask representing package access (default access), which may contribute to the result of lookupModes. The value is 0x08, which does not correspond meaningfully to any particular modifier bit.

Constant Value: 8 (0x00000008)

PRIVATE

public static final int PRIVATE

A single-bit mask representing private access, which may contribute to the result of lookupModes. The value, 0x02, happens to be the same as the value of the private modifier bit.

Constant Value: 2 (0x00000002)

PROTECTED

public static final int PROTECTED

A single-bit mask representing protected access, which may contribute to the result of lookupModes. The value, 0x04, happens to be the same as the value of the protected modifier bit.

Constant Value: 4 (0x00000004)

PUBLIC

public static final int PUBLIC

A single-bit mask representing public access, which may contribute to the result of lookupModes. The value, 0x01, happens to be the same as the value of the public modifier bit.

Constant Value: 1 (0x00000001)

bind

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

Produces 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 object. 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.

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set and the trailing array argument is not the only argument. (If the trailing array argument is the only argument, the given receiver value will be bound to it.)

This is equivalent to the following code:

import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodHandle mh0 = lookup().findVirtual(defc, name, type);
 MethodHandle mh1 = mh0.bindTo(receiver);
 MethodType mt1 = mh1.type();
 if (mh0.isVarargsCollector())
 mh1 = mh1.asVarargsCollector(mt1.parameterType(mt1.parameterCount()-1));
 return mh1;
 

findConstructor

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

Produces 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 object.

The requested type must have a return type of void. (This is consistent with the JVM's treatment of constructor type descriptors.)

The returned method handle will have variable arity if and only if the constructor's variable arity modifier bit (0x0080) is set.

If the returned method handle is invoked, the constructor's class will be initialized, if it has not already been initialized.

Example:

import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodHandle MH_newArrayList = publicLookup().findConstructor(
 ArrayList.class, methodType(void.class, Collection.class));
 Collection orig = Arrays.asList("x", "y");
 Collection copy = (ArrayList) MH_newArrayList.invokeExact(orig);
 assert(orig != copy);
 assertEquals(orig, copy);
 // a variable-arity constructor:
 MethodHandle MH_newProcessBuilder = publicLookup().findConstructor(
 ProcessBuilder.class, methodType(void.class, String[].class));
 ProcessBuilder pb = (ProcessBuilder)
 MH_newProcessBuilder.invoke("x", "y", "z");
 assertEquals("[x, y, z]", pb.command().toString());
 

findGetter

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

Produces 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.

findSetter

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

Produces 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.

findSpecial

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

Produces an early-bound method handle for a virtual method. It will bypass checks for overriding methods on the receiver, as if called from an invokespecial instruction from within the explicitly specified specialCaller. The type of the method handle will be that of the method, with a suitably restricted receiver type prepended. (The receiver type will be specialCaller or a subtype.) The method and all its argument types must be accessible to the lookup object.

Before method resolution, if the explicitly specified caller class is not identical with the lookup class, or if this lookup object does not have private access privileges, the access fails.

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set.

(Note: JVM internal methods named "<init>" are not visible to this API, even though the invokespecial instruction can refer to them in special circumstances. Use findConstructor to access instance initialization methods in a safe manner.)

Example:

import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 static class Listie extends ArrayList {
 public String toString() { return "[wee Listie]"; }
 static Lookup lookup() { return MethodHandles.lookup(); }
 }
 ...
 // no access to constructor via invokeSpecial:
 MethodHandle MH_newListie = Listie.lookup()
 .findConstructor(Listie.class, methodType(void.class));
 Listie l = (Listie) MH_newListie.invokeExact();
 try { assertEquals("impossible", Listie.lookup().findSpecial(
       Listie.class, "<init>", methodType(void.class), Listie.class));
 } catch (NoSuchMethodException ex) { } // OK
 // access to super and self methods via invokeSpecial:
 MethodHandle MH_super = Listie.lookup().findSpecial(
 ArrayList.class, "toString" , methodType(String.class), Listie.class);
 MethodHandle MH_this = Listie.lookup().findSpecial(
 Listie.class, "toString" , methodType(String.class), Listie.class);
 MethodHandle MH_duper = Listie.lookup().findSpecial(
 Object.class, "toString" , methodType(String.class), Listie.class);
 assertEquals("[]", (String) MH_super.invokeExact(l));
 assertEquals(""+l, (String) MH_this.invokeExact(l));
 assertEquals("[]", (String) MH_duper.invokeExact(l)); // ArrayList method
 try { assertEquals("inaccessible", Listie.lookup().findSpecial(
       String.class, "toString", methodType(String.class), Listie.class));
 } catch (IllegalAccessException ex) { } // OK
 Listie subl = new Listie() { public String toString() { return "[subclass]"; } };
 assertEquals(""+l, (String) MH_this.invokeExact(subl)); // Listie method
 

findStatic

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

Produces 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 or findSpecial.) The method and all its argument types must be accessible to the lookup object.

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set.

If the returned method handle is invoked, the method's class will be initialized, if it has not already been initialized.

Example:

import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodHandle MH_asList = publicLookup().findStatic(Arrays.class,
 "asList", methodType(List.class, Object[].class));
 assertEquals("[x, y]", MH_asList.invoke("x", "y").toString());
 

findStaticGetter

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

Produces 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.

If the returned method handle is invoked, the field's class will be initialized, if it has not already been initialized.

findStaticSetter

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

Produces 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.

If the returned method handle is invoked, the field's class will be initialized, if it has not already been initialized.

findStaticVarHandle

public VarHandle findStaticVarHandle (Class<?> decl, 
                String name, 
                Class<?> type)

Produces a VarHandle giving access to a static field name of type type declared in a class of type decl. The VarHandle's variable type is type and it has no coordinate types.

Access checking is performed immediately on behalf of the lookup class.

If the returned VarHandle is operated on, the declaring class will be initialized, if it has not already been initialized.

Certain access modes of the returned VarHandle are unsupported under the following conditions:

• if the field is declared final, then the write, atomic update, numeric atomic update, and bitwise atomic update access modes are unsupported.
• if the field type is anything other than byte, short, char, int, long, float, or double, then numeric atomic update access modes are unsupported.
• if the field type is anything other than boolean, byte, short, char, int or long then bitwise atomic update access modes are unsupported.

If the field is declared volatile then the returned VarHandle will override access to the field (effectively ignore the volatile declaration) in accordance to its specified access modes.

If the field type is float or double then numeric and atomic update access modes compare values using their bitwise representation (see Float.floatToRawIntBits and Double.doubleToRawLongBits, respectively).

findVarHandle

public VarHandle findVarHandle (Class<?> recv, 
                String name, 
                Class<?> type)

Produces a VarHandle giving access to a non-static field name of type type declared in a class of type recv. The VarHandle's variable type is type and it has one coordinate type, recv.

Access checking is performed immediately on behalf of the lookup class.

Certain access modes of the returned VarHandle are unsupported under the following conditions:

• if the field is declared final, then the write, atomic update, numeric atomic update, and bitwise atomic update access modes are unsupported.
• if the field type is anything other than byte, short, char, int, long, float, or double then numeric atomic update access modes are unsupported.
• if the field type is anything other than boolean, byte, short, char, int or long then bitwise atomic update access modes are unsupported.

If the field is declared volatile then the returned VarHandle will override access to the field (effectively ignore the volatile declaration) in accordance to its specified access modes.

If the field type is float or double then numeric and atomic update access modes compare values using their bitwise representation (see Float.floatToRawIntBits and Double.doubleToRawLongBits, respectively).

findVirtual

public MethodHandle findVirtual (Class<?> refc, 
                String name, 
                MethodType type)

Produces 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 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.)

The first argument will be of type refc if the lookup class has full privileges to access the member. Otherwise the member must be protected and the first argument will be restricted in type to the lookup class.

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set.

Because of the general equivalence between invokevirtual instructions and method handles produced by findVirtual, if the class is MethodHandle and the name string is invokeExact or invoke, the resulting method handle is equivalent to one produced by MethodHandles.exactInvoker or MethodHandles.invoker with the same type argument. Example:

import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodHandle MH_concat = publicLookup().findVirtual(String.class,
 "concat", methodType(String.class, String.class));
 MethodHandle MH_hashCode = publicLookup().findVirtual(Object.class,
 "hashCode", methodType(int.class));
 MethodHandle MH_hashCode_String = publicLookup().findVirtual(String.class,
 "hashCode", methodType(int.class));
 assertEquals("xy", (String) MH_concat.invokeExact("x", "y"));
 assertEquals("xy".hashCode(), (int) MH_hashCode.invokeExact((Object)"xy"));
 assertEquals("xy".hashCode(), (int) MH_hashCode_String.invokeExact("xy"));
 // interface method:
 MethodHandle MH_subSequence = publicLookup().findVirtual(CharSequence.class,
 "subSequence", methodType(CharSequence.class, int.class, int.class));
 assertEquals("def", MH_subSequence.invoke("abcdefghi", 3, 6).toString());
 // constructor "internal method" must be accessed differently:
 MethodType MT_newString = methodType(void.class); //()V for new String()
 try { assertEquals("impossible", lookup()
       .findVirtual(String.class, "<init>", MT_newString));
 } catch (NoSuchMethodException ex) { } // OK
 MethodHandle MH_newString = publicLookup()
 .findConstructor(String.class, MT_newString);
 assertEquals("", (String) MH_newString.invokeExact());
 

in

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

Creates 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, access capabilities can be lost as follows:

• If the new lookup class differs from the old one, protected members will not be accessible by virtue of inheritance. (Protected members may continue to be accessible because of package sharing.)
• 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.
• If the new lookup class is not accessible to the old lookup class, then no members, not even public members, will be accessible. (In all other cases, public members will continue to be accessible.)

lookupClass

public Class<?> lookupClass ()

Tells 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 ()

Tells which access-protection classes of members this lookup object can produce. The result is a bit-mask of the bits PUBLIC (0x01), PRIVATE (0x02), PROTECTED (0x04), and PACKAGE (0x08).

A freshly-created lookup object on the caller's class has all possible bits set, since the caller class can access all its own members. A lookup object on a new lookup class created from a previous lookup object may have some mode bits set to zero. The purpose of this is to restrict access via the new lookup object, so that it can access only names which can be reached by the original lookup object, and also by the new lookup class.

revealDirect

public MethodHandleInfo revealDirect (MethodHandle target)

Cracks a direct method handle created by this lookup object or a similar one. Security and access checks are performed to ensure that this lookup object is capable of reproducing the target method handle. This means that the cracking may fail if target is a direct method handle but was created by an unrelated lookup object. This can happen if the method handle is caller sensitive and was created by a lookup object for a different class.

toString

public String toString ()

Displays the name of the class from which lookups are to be made. (The name is the one reported by Class.getName.) If there are restrictions on the access permitted to this lookup, this is indicated by adding a suffix to the class name, consisting of a slash and a keyword. The keyword represents the strongest allowed access, and is chosen as follows:

• If no access is allowed, the suffix is "/noaccess".
• If only public access is allowed, the suffix is "/public".
• If only public and package access are allowed, the suffix is "/package".
• If only public, package, and private access are allowed, the suffix is "/private".

(It may seem strange that protected access should be stronger than private access. Viewed independently from package access, protected access is the first to be lost, because it requires a direct subclass relationship between caller and callee.)

unreflect

public MethodHandle unreflect (Method m)

Makes 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.

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set.

If m is static, and if the returned method handle is invoked, the method's class will be initialized, if it has not already been initialized.

unreflectConstructor

public MethodHandle unreflectConstructor (Constructor<?> c)

Produces 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.

The returned method handle will have variable arity if and only if the constructor's variable arity modifier bit (0x0080) is set.

If the returned method handle is invoked, the constructor's class will be initialized, if it has not already been initialized.

unreflectGetter

public MethodHandle unreflectGetter (Field f)

Produces 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 field's accessible flag is not set, access checking is performed immediately on behalf of the lookup class.

If the field is static, and if the returned method handle is invoked, the field's class will be initialized, if it has not already been initialized.

unreflectSetter

public MethodHandle unreflectSetter (Field f)

Produces 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 field's accessible flag is not set, access checking is performed immediately on behalf of the lookup class.

If the field is static, and if the returned method handle is invoked, the field's class will be initialized, if it has not already been initialized.

unreflectSpecial

public MethodHandle unreflectSpecial (Method m, 
                Class<?> specialCaller)

Produces a method handle for a reflected method. It will bypass checks for overriding methods on the receiver, as if called from an invokespecial instruction from within the explicitly specified specialCaller. The type of the method handle will be that of the method, with a suitably restricted receiver type prepended. (The receiver type will be specialCaller or a subtype.) 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.

Before method resolution, if the explicitly specified caller class is not identical with the lookup class, or if this lookup object does not have private access privileges, the access fails.

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set.

unreflectVarHandle

public VarHandle unreflectVarHandle (Field f)

Produces a VarHandle giving access to a reflected field f of type T declared in a class of type R. The VarHandle's variable type is T. If the field is non-static the VarHandle has one coordinate type, R. Otherwise, the field is static, and the VarHandle has no coordinate types.

Access checking is performed immediately on behalf of the lookup class, regardless of the value of the field's accessible flag.

If the field is static, and if the returned VarHandle is operated on, the field's declaring class will be initialized, if it has not already been initialized.

Certain access modes of the returned VarHandle are unsupported under the following conditions:

• if the field is declared final, then the write, atomic update, numeric atomic update, and bitwise atomic update access modes are unsupported.
• if the field type is anything other than byte, short, char, int, long, float, or double then numeric atomic update access modes are unsupported.
• if the field type is anything other than boolean, byte, short, char, int or long then bitwise atomic update access modes are unsupported.

If the field is declared volatile then the returned VarHandle will override access to the field (effectively ignore the volatile declaration) in accordance to its specified access modes.

If the field type is float or double then numeric and atomic update access modes compare values using their bitwise representation (see Float.floatToRawIntBits and Double.doubleToRawLongBits, respectively).