jaroslav@1692: /* jaroslav@1692: * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved. jaroslav@1692: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jaroslav@1692: * jaroslav@1692: * This code is free software; you can redistribute it and/or modify it jaroslav@1692: * under the terms of the GNU General Public License version 2 only, as jaroslav@1692: * published by the Free Software Foundation. Oracle designates this jaroslav@1692: * particular file as subject to the "Classpath" exception as provided jaroslav@1692: * by Oracle in the LICENSE file that accompanied this code. jaroslav@1692: * jaroslav@1692: * This code is distributed in the hope that it will be useful, but WITHOUT jaroslav@1692: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jaroslav@1692: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jaroslav@1692: * version 2 for more details (a copy is included in the LICENSE file that jaroslav@1692: * accompanied this code). jaroslav@1692: * jaroslav@1692: * You should have received a copy of the GNU General Public License version jaroslav@1692: * 2 along with this work; if not, write to the Free Software Foundation, jaroslav@1692: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jaroslav@1692: * jaroslav@1692: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jaroslav@1692: * or visit www.oracle.com if you need additional information or have any jaroslav@1692: * questions. jaroslav@1692: */ jaroslav@1692: jaroslav@1692: package java.lang.invoke; jaroslav@1692: jaroslav@1692: import java.lang.reflect.*; jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * This class consists exclusively of static methods that operate on or return jaroslav@1692: * method handles. They fall into several categories: jaroslav@1692: * jaroslav@1692: *

jaroslav@1692: * @author John Rose, JSR 292 EG jaroslav@1692: * @since 1.7 jaroslav@1692: */ jaroslav@1692: public class MethodHandles { jaroslav@1692: jaroslav@1692: private MethodHandles() { } // do not instantiate jaroslav@1692: jaroslav@1692: //// Method handle creation from ordinary methods. jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Returns a {@link Lookup lookup object} with jaroslav@1692: * full capabilities to emulate all supported bytecode behaviors of the caller. jaroslav@1692: * These capabilities include private access to the caller. jaroslav@1692: * Factory methods on the lookup object can create jaroslav@1692: * direct method handles jaroslav@1692: * for any member that the caller has access to via bytecodes, jaroslav@1692: * including protected and private fields and methods. jaroslav@1692: * This lookup object is a capability which may be delegated to trusted agents. jaroslav@1692: * Do not store it in place where untrusted code can access it. jaroslav@1692: *

jaroslav@1692: * This method is caller sensitive, which means that it may return different jaroslav@1692: * values to different callers. jaroslav@1692: *

jaroslav@1692: * For any given caller class {@code C}, the lookup object returned by this call jaroslav@1692: * has equivalent capabilities to any lookup object jaroslav@1692: * supplied by the JVM to the bootstrap method of an jaroslav@1692: * invokedynamic instruction jaroslav@1692: * executing in the same caller class {@code C}. jaroslav@1692: * @return a lookup object for the caller of this method, with private access jaroslav@1692: */ jaroslav@1692: // @CallerSensitive jaroslav@1692: public static Lookup lookup() { jaroslav@1692: throw new IllegalStateException("Implement me!"); jaroslav@1692: // return new Lookup(Reflection.getCallerClass()); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Returns a {@link Lookup lookup object} which is trusted minimally. jaroslav@1692: * It can only be used to create method handles to jaroslav@1692: * publicly accessible fields and methods. jaroslav@1692: *

jaroslav@1692: * As a matter of pure convention, the {@linkplain Lookup#lookupClass lookup class} jaroslav@1692: * of this lookup object will be {@link java.lang.Object}. jaroslav@1692: * jaroslav@1692: *

jaroslav@1692: * Discussion: jaroslav@1692: * The lookup class can be changed to any other class {@code C} using an expression of the form jaroslav@1692: * {@link Lookup#in publicLookup().in(C.class)}. jaroslav@1692: * Since all classes have equal access to public names, jaroslav@1692: * such a change would confer no new access rights. jaroslav@1692: * A public lookup object is always subject to jaroslav@1692: * security manager checks. jaroslav@1692: * Also, it cannot access jaroslav@1692: * caller sensitive methods. jaroslav@1692: * @return a lookup object which is trusted minimally jaroslav@1692: */ jaroslav@1692: public static Lookup publicLookup() { jaroslav@1692: return Lookup.PUBLIC_LOOKUP; jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Performs an unchecked "crack" of a jaroslav@1692: * direct method handle. jaroslav@1692: * The result is as if the user had obtained a lookup object capable enough jaroslav@1692: * to crack the target method handle, called jaroslav@1692: * {@link java.lang.invoke.MethodHandles.Lookup#revealDirect Lookup.revealDirect} jaroslav@1692: * on the target to obtain its symbolic reference, and then called jaroslav@1692: * {@link java.lang.invoke.MethodHandleInfo#reflectAs MethodHandleInfo.reflectAs} jaroslav@1692: * to resolve the symbolic reference to a member. jaroslav@1692: *

jaroslav@1692: * If there is a security manager, its {@code checkPermission} method jaroslav@1692: * is called with a {@code ReflectPermission("suppressAccessChecks")} permission. jaroslav@1692: * @param the desired type of the result, either {@link Member} or a subtype jaroslav@1692: * @param target a direct method handle to crack into symbolic reference components jaroslav@1692: * @param expected a class object representing the desired result type {@code T} jaroslav@1692: * @return a reference to the method, constructor, or field object jaroslav@1692: * @exception SecurityException if the caller is not privileged to call {@code setAccessible} jaroslav@1692: * @exception NullPointerException if either argument is {@code null} jaroslav@1692: * @exception IllegalArgumentException if the target is not a direct method handle jaroslav@1692: * @exception ClassCastException if the member is not of the expected type jaroslav@1692: * @since 1.8 jaroslav@1692: */ jaroslav@1692: public static T jaroslav@1692: reflectAs(Class expected, MethodHandle target) { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: // Copied from AccessibleObject, as used by Method.setAccessible, etc.: jaroslav@1692: // static final private java.security.Permission ACCESS_PERMISSION = jaroslav@1692: // new ReflectPermission("suppressAccessChecks"); jaroslav@1692: jaroslav@1692: static Lookup findFor(Class clazz) { jaroslav@1692: Object o = clazz; jaroslav@1692: if (o instanceof Class) { jaroslav@1692: return new Lookup(clazz, Lookup.ALL_MODES); jaroslav@1692: } jaroslav@1692: throw new IllegalArgumentException("Expecting class: " + o); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * A lookup object is a factory for creating method handles, jaroslav@1692: * when the creation requires access checking. jaroslav@1692: * Method handles do not perform jaroslav@1692: * access checks when they are called, but rather when they are created. jaroslav@1692: * Therefore, method handle access jaroslav@1692: * restrictions must be enforced when a method handle is created. jaroslav@1692: * The caller class against which those restrictions are enforced jaroslav@1692: * is known as the {@linkplain #lookupClass lookup class}. jaroslav@1692: *

jaroslav@1692: * A lookup class which needs to create method handles will call jaroslav@1692: * {@link MethodHandles#lookup MethodHandles.lookup} to create a factory for itself. jaroslav@1692: * When the {@code Lookup} factory object is created, the identity of the lookup class is jaroslav@1692: * determined, and securely stored in the {@code Lookup} object. jaroslav@1692: * The lookup class (or its delegates) may then use factory methods jaroslav@1692: * on the {@code Lookup} object to create method handles for access-checked members. jaroslav@1692: * This includes all methods, constructors, and fields which are allowed to the lookup class, jaroslav@1692: * even private ones. jaroslav@1692: * jaroslav@1692: *

Lookup Factory Methods

jaroslav@1692: * The factory methods on a {@code Lookup} object correspond to all major jaroslav@1692: * use cases for methods, constructors, and fields. jaroslav@1692: * Each method handle created by a factory method is the functional jaroslav@1692: * equivalent of a particular bytecode behavior. jaroslav@1692: * (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.) jaroslav@1692: * Here is a summary of the correspondence between these factory methods and jaroslav@1692: * the behavior the resulting method handles: jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: * jaroslav@1692: *
lookup expressionmemberbytecode behavior
{@link java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}{@code FT f;}{@code (T) this.f;}
{@link java.lang.invoke.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}{@code static}
{@code FT f;}		{@code (T) C.f;}
{@link java.lang.invoke.MethodHandles.Lookup#findSetter lookup.findSetter(C.class,"f",FT.class)}{@code FT f;}{@code this.f = x;}
{@link java.lang.invoke.MethodHandles.Lookup#findStaticSetter lookup.findStaticSetter(C.class,"f",FT.class)}{@code static}
{@code FT f;}		{@code C.f = arg;}
{@link java.lang.invoke.MethodHandles.Lookup#findVirtual lookup.findVirtual(C.class,"m",MT)}{@code T m(A*);}{@code (T) this.m(arg*);}
{@link java.lang.invoke.MethodHandles.Lookup#findStatic lookup.findStatic(C.class,"m",MT)}{@code static}
{@code T m(A*);}		{@code (T) C.m(arg*);}
{@link java.lang.invoke.MethodHandles.Lookup#findSpecial lookup.findSpecial(C.class,"m",MT,this.class)}{@code T m(A*);}{@code (T) super.m(arg*);}
{@link java.lang.invoke.MethodHandles.Lookup#findConstructor lookup.findConstructor(C.class,MT)}{@code C(A*);}{@code new C(arg*);}
{@link java.lang.invoke.MethodHandles.Lookup#unreflectGetter lookup.unreflectGetter(aField)}({@code static})?
{@code FT f;}		{@code (FT) aField.get(thisOrNull);}
{@link java.lang.invoke.MethodHandles.Lookup#unreflectSetter lookup.unreflectSetter(aField)}({@code static})?
{@code FT f;}		{@code aField.set(thisOrNull, arg);}
{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}({@code static})?
{@code T m(A*);}		{@code (T) aMethod.invoke(thisOrNull, arg*);}
{@link java.lang.invoke.MethodHandles.Lookup#unreflectConstructor lookup.unreflectConstructor(aConstructor)}{@code C(A*);}{@code (C) aConstructor.newInstance(arg*);}
{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}({@code static})?
{@code T m(A*);}		{@code (T) aMethod.invoke(thisOrNull, arg*);}
jaroslav@1692: * jaroslav@1692: * Here, the type {@code C} is the class or interface being searched for a member, jaroslav@1692: * documented as a parameter named {@code refc} in the lookup methods. jaroslav@1692: * The method type {@code MT} is composed from the return type {@code T} jaroslav@1692: * and the sequence of argument types {@code A*}. jaroslav@1692: * The constructor also has a sequence of argument types {@code A*} and jaroslav@1692: * is deemed to return the newly-created object of type {@code C}. jaroslav@1692: * Both {@code MT} and the field type {@code FT} are documented as a parameter named {@code type}. jaroslav@1692: * The formal parameter {@code this} stands for the self-reference of type {@code C}; jaroslav@1692: * if it is present, it is always the leading argument to the method handle invocation. jaroslav@1692: * (In the case of some {@code protected} members, {@code this} may be jaroslav@1692: * restricted in type to the lookup class; see below.) jaroslav@1692: * The name {@code arg} stands for all the other method handle arguments. jaroslav@1692: * In the code examples for the Core Reflection API, the name {@code thisOrNull} jaroslav@1692: * stands for a null reference if the accessed method or field is static, jaroslav@1692: * and {@code this} otherwise. jaroslav@1692: * The names {@code aMethod}, {@code aField}, and {@code aConstructor} stand jaroslav@1692: * for reflective objects corresponding to the given members. jaroslav@1692: *

jaroslav@1692: * In cases where the given member is of variable arity (i.e., a method or constructor) jaroslav@1692: * the returned method handle will also be of {@linkplain MethodHandle#asVarargsCollector variable arity}. jaroslav@1692: * In all other cases, the returned method handle will be of fixed arity. jaroslav@1692: *

jaroslav@1692: * Discussion: jaroslav@1692: * The equivalence between looked-up method handles and underlying jaroslav@1692: * class members and bytecode behaviors jaroslav@1692: * can break down in a few ways: jaroslav@1692: *

jaroslav@1692: * jaroslav@1692: *

Access checking

jaroslav@1692: * Access checks are applied in the factory methods of {@code Lookup}, jaroslav@1692: * when a method handle is created. jaroslav@1692: * This is a key difference from the Core Reflection API, since jaroslav@1692: * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke} jaroslav@1692: * performs access checking against every caller, on every call. jaroslav@1692: *

jaroslav@1692: * All access checks start from a {@code Lookup} object, which jaroslav@1692: * compares its recorded lookup class against all requests to jaroslav@1692: * create method handles. jaroslav@1692: * A single {@code Lookup} object can be used to create any number jaroslav@1692: * of access-checked method handles, all checked against a single jaroslav@1692: * lookup class. jaroslav@1692: *

jaroslav@1692: * A {@code Lookup} object can be shared with other trusted code, jaroslav@1692: * such as a metaobject protocol. jaroslav@1692: * A shared {@code Lookup} object delegates the capability jaroslav@1692: * to create method handles on private members of the lookup class. jaroslav@1692: * Even if privileged code uses the {@code Lookup} object, jaroslav@1692: * the access checking is confined to the privileges of the jaroslav@1692: * original lookup class. jaroslav@1692: *

jaroslav@1692: * A lookup can fail, because jaroslav@1692: * the containing class is not accessible to the lookup class, or jaroslav@1692: * because the desired class member is missing, or because the jaroslav@1692: * desired class member is not accessible to the lookup class, or jaroslav@1692: * because the lookup object is not trusted enough to access the member. jaroslav@1692: * In any of these cases, a {@code ReflectiveOperationException} will be jaroslav@1692: * thrown from the attempted lookup. The exact class will be one of jaroslav@1692: * the following: jaroslav@1692: *

jaroslav@1692: *

jaroslav@1692: * In general, the conditions under which a method handle may be jaroslav@1692: * looked up for a method {@code M} are no more restrictive than the conditions jaroslav@1692: * under which the lookup class could have compiled, verified, and resolved a call to {@code M}. jaroslav@1692: * Where the JVM would raise exceptions like {@code NoSuchMethodError}, jaroslav@1692: * a method handle lookup will generally raise a corresponding jaroslav@1692: * checked exception, such as {@code NoSuchMethodException}. jaroslav@1692: * And the effect of invoking the method handle resulting from the lookup jaroslav@1692: * is exactly equivalent jaroslav@1692: * to executing the compiled, verified, and resolved call to {@code M}. jaroslav@1692: * The same point is true of fields and constructors. jaroslav@1692: *

jaroslav@1692: * Discussion: jaroslav@1692: * Access checks only apply to named and reflected methods, jaroslav@1692: * constructors, and fields. jaroslav@1692: * Other method handle creation methods, such as jaroslav@1692: * {@link MethodHandle#asType MethodHandle.asType}, jaroslav@1692: * do not require any access checks, and are used jaroslav@1692: * independently of any {@code Lookup} object. jaroslav@1692: *

jaroslav@1692: * If the desired member is {@code protected}, the usual JVM rules apply, jaroslav@1692: * including the requirement that the lookup class must be either be in the jaroslav@1692: * same package as the desired member, or must inherit that member. jaroslav@1692: * (See the Java Virtual Machine Specification, sections 4.9.2, 5.4.3.5, and 6.4.) jaroslav@1692: * In addition, if the desired member is a non-static field or method jaroslav@1692: * in a different package, the resulting method handle may only be applied jaroslav@1692: * to objects of the lookup class or one of its subclasses. jaroslav@1692: * This requirement is enforced by narrowing the type of the leading jaroslav@1692: * {@code this} parameter from {@code C} jaroslav@1692: * (which will necessarily be a superclass of the lookup class) jaroslav@1692: * to the lookup class itself. jaroslav@1692: *

jaroslav@1692: * The JVM imposes a similar requirement on {@code invokespecial} instruction, jaroslav@1692: * that the receiver argument must match both the resolved method and jaroslav@1692: * the current class. Again, this requirement is enforced by narrowing the jaroslav@1692: * type of the leading parameter to the resulting method handle. jaroslav@1692: * (See the Java Virtual Machine Specification, section 4.10.1.9.) jaroslav@1692: *

jaroslav@1692: * The JVM represents constructors and static initializer blocks as internal methods jaroslav@1692: * with special names ({@code ""} and {@code ""}). jaroslav@1692: * The internal syntax of invocation instructions allows them to refer to such internal jaroslav@1692: * methods as if they were normal methods, but the JVM bytecode verifier rejects them. jaroslav@1692: * A lookup of such an internal method will produce a {@code NoSuchMethodException}. jaroslav@1692: *

jaroslav@1692: * In some cases, access between nested classes is obtained by the Java compiler by creating jaroslav@1692: * an wrapper method to access a private method of another class jaroslav@1692: * in the same top-level declaration. jaroslav@1692: * For example, a nested class {@code C.D} jaroslav@1692: * can access private members within other related classes such as jaroslav@1692: * {@code C}, {@code C.D.E}, or {@code C.B}, jaroslav@1692: * but the Java compiler may need to generate wrapper methods in jaroslav@1692: * those related classes. In such cases, a {@code Lookup} object on jaroslav@1692: * {@code C.E} would be unable to those private members. jaroslav@1692: * A workaround for this limitation is the {@link Lookup#in Lookup.in} method, jaroslav@1692: * which can transform a lookup on {@code C.E} into one on any of those other jaroslav@1692: * classes, without special elevation of privilege. jaroslav@1692: *

jaroslav@1692: * The accesses permitted to a given lookup object may be limited, jaroslav@1692: * according to its set of {@link #lookupModes lookupModes}, jaroslav@1692: * to a subset of members normally accessible to the lookup class. jaroslav@1692: * For example, the {@link MethodHandles#publicLookup publicLookup} jaroslav@1692: * method produces a lookup object which is only allowed to access jaroslav@1692: * public members in public classes. jaroslav@1692: * The caller sensitive method {@link MethodHandles#lookup lookup} jaroslav@1692: * produces a lookup object with full capabilities relative to jaroslav@1692: * its caller class, to emulate all supported bytecode behaviors. jaroslav@1692: * Also, the {@link Lookup#in Lookup.in} method may produce a lookup object jaroslav@1692: * with fewer access modes than the original lookup object. jaroslav@1692: * jaroslav@1692: *

jaroslav@1692: * jaroslav@1692: * Discussion of private access: jaroslav@1692: * We say that a lookup has private access jaroslav@1692: * if its {@linkplain #lookupModes lookup modes} jaroslav@1692: * include the possibility of accessing {@code private} members. jaroslav@1692: * As documented in the relevant methods elsewhere, jaroslav@1692: * only lookups with private access possess the following capabilities: jaroslav@1692: *

jaroslav@1692: *

jaroslav@1692: * Each of these permissions is a consequence of the fact that a lookup object jaroslav@1692: * with private access can be securely traced back to an originating class, jaroslav@1692: * whose bytecode behaviors and Java language access permissions jaroslav@1692: * can be reliably determined and emulated by method handles. jaroslav@1692: * jaroslav@1692: *

Security manager interactions

jaroslav@1692: * Although bytecode instructions can only refer to classes in jaroslav@1692: * a related class loader, this API can search for methods in any jaroslav@1692: * class, as long as a reference to its {@code Class} object is jaroslav@1692: * available. Such cross-loader references are also possible with the jaroslav@1692: * Core Reflection API, and are impossible to bytecode instructions jaroslav@1692: * such as {@code invokestatic} or {@code getfield}. jaroslav@1692: * There is a {@linkplain java.lang.SecurityManager security manager API} jaroslav@1692: * to allow applications to check such cross-loader references. jaroslav@1692: * These checks apply to both the {@code MethodHandles.Lookup} API jaroslav@1692: * and the Core Reflection API jaroslav@1692: * (as found on {@link java.lang.Class Class}). jaroslav@1692: *

jaroslav@1692: * If a security manager is present, member lookups are subject to jaroslav@1692: * additional checks. jaroslav@1692: * From one to three calls are made to the security manager. jaroslav@1692: * Any of these calls can refuse access by throwing a jaroslav@1692: * {@link java.lang.SecurityException SecurityException}. jaroslav@1692: * Define {@code smgr} as the security manager, jaroslav@1692: * {@code lookc} as the lookup class of the current lookup object, jaroslav@1692: * {@code refc} as the containing class in which the member jaroslav@1692: * is being sought, and {@code defc} as the class in which the jaroslav@1692: * member is actually defined. jaroslav@1692: * The value {@code lookc} is defined as not present jaroslav@1692: * if the current lookup object does not have jaroslav@1692: * private access. jaroslav@1692: * The calls are made according to the following rules: jaroslav@1692: *

jaroslav@1692: * Security checks are performed after other access checks have passed. jaroslav@1692: * Therefore, the above rules presuppose a member that is public, jaroslav@1692: * or else that is being accessed from a lookup class that has jaroslav@1692: * rights to access the member. jaroslav@1692: * jaroslav@1692: *

Caller sensitive methods

jaroslav@1692: * A small number of Java methods have a special property called caller sensitivity. jaroslav@1692: * A caller-sensitive method can behave differently depending on the jaroslav@1692: * identity of its immediate caller. jaroslav@1692: *

jaroslav@1692: * If a method handle for a caller-sensitive method is requested, jaroslav@1692: * the general rules for bytecode behaviors apply, jaroslav@1692: * but they take account of the lookup class in a special way. jaroslav@1692: * The resulting method handle behaves as if it were called jaroslav@1692: * from an instruction contained in the lookup class, jaroslav@1692: * so that the caller-sensitive method detects the lookup class. jaroslav@1692: * (By contrast, the invoker of the method handle is disregarded.) jaroslav@1692: * Thus, in the case of caller-sensitive methods, jaroslav@1692: * different lookup classes may give rise to jaroslav@1692: * differently behaving method handles. jaroslav@1692: *

jaroslav@1692: * In cases where the lookup object is jaroslav@1692: * {@link MethodHandles#publicLookup() publicLookup()}, jaroslav@1692: * or some other lookup object without jaroslav@1692: * private access, jaroslav@1692: * the lookup class is disregarded. jaroslav@1692: * In such cases, no caller-sensitive method handle can be created, jaroslav@1692: * access is forbidden, and the lookup fails with an jaroslav@1692: * {@code IllegalAccessException}. jaroslav@1692: *

jaroslav@1692: * Discussion: jaroslav@1692: * For example, the caller-sensitive method jaroslav@1692: * {@link java.lang.Class#forName(String) Class.forName(x)} jaroslav@1692: * can return varying classes or throw varying exceptions, jaroslav@1692: * depending on the class loader of the class that calls it. jaroslav@1692: * A public lookup of {@code Class.forName} will fail, because jaroslav@1692: * there is no reasonable way to determine its bytecode behavior. jaroslav@1692: *

jaroslav@1692: * If an application caches method handles for broad sharing, jaroslav@1692: * it should use {@code publicLookup()} to create them. jaroslav@1692: * If there is a lookup of {@code Class.forName}, it will fail, jaroslav@1692: * and the application must take appropriate action in that case. jaroslav@1692: * It may be that a later lookup, perhaps during the invocation of a jaroslav@1692: * bootstrap method, can incorporate the specific identity jaroslav@1692: * of the caller, making the method accessible. jaroslav@1692: *

jaroslav@1692: * The function {@code MethodHandles.lookup} is caller sensitive jaroslav@1692: * so that there can be a secure foundation for lookups. jaroslav@1692: * Nearly all other methods in the JSR 292 API rely on lookup jaroslav@1692: * objects to check access requests. jaroslav@1692: */ jaroslav@1692: public static final jaroslav@1692: class Lookup { jaroslav@1692: /** The class on behalf of whom the lookup is being performed. */ jaroslav@1692: private final Class lookupClass; jaroslav@1692: jaroslav@1692: /** The allowed sorts of members which may be looked up (PUBLIC, etc.). */ jaroslav@1692: private final int allowedModes; jaroslav@1692: jaroslav@1692: /** A single-bit mask representing {@code public} access, jaroslav@1692: * which may contribute to the result of {@link #lookupModes lookupModes}. jaroslav@1692: * The value, {@code 0x01}, happens to be the same as the value of the jaroslav@1692: * {@code public} {@linkplain java.lang.reflect.Modifier#PUBLIC modifier bit}. jaroslav@1692: */ jaroslav@1692: public static final int PUBLIC = Modifier.PUBLIC; jaroslav@1692: jaroslav@1692: /** A single-bit mask representing {@code private} access, jaroslav@1692: * which may contribute to the result of {@link #lookupModes lookupModes}. jaroslav@1692: * The value, {@code 0x02}, happens to be the same as the value of the jaroslav@1692: * {@code private} {@linkplain java.lang.reflect.Modifier#PRIVATE modifier bit}. jaroslav@1692: */ jaroslav@1692: public static final int PRIVATE = Modifier.PRIVATE; jaroslav@1692: jaroslav@1692: /** A single-bit mask representing {@code protected} access, jaroslav@1692: * which may contribute to the result of {@link #lookupModes lookupModes}. jaroslav@1692: * The value, {@code 0x04}, happens to be the same as the value of the jaroslav@1692: * {@code protected} {@linkplain java.lang.reflect.Modifier#PROTECTED modifier bit}. jaroslav@1692: */ jaroslav@1692: public static final int PROTECTED = Modifier.PROTECTED; jaroslav@1692: jaroslav@1692: /** A single-bit mask representing {@code package} access (default access), jaroslav@1692: * which may contribute to the result of {@link #lookupModes lookupModes}. jaroslav@1692: * The value is {@code 0x08}, which does not correspond meaningfully to jaroslav@1692: * any particular {@linkplain java.lang.reflect.Modifier modifier bit}. jaroslav@1692: */ jaroslav@1692: public static final int PACKAGE = Modifier.STATIC; jaroslav@1692: jaroslav@1692: private static final int ALL_MODES = (PUBLIC | PRIVATE | PROTECTED | PACKAGE); jaroslav@1692: private static final int TRUSTED = -1; jaroslav@1692: jaroslav@1692: private static int fixmods(int mods) { jaroslav@1692: mods &= (ALL_MODES - PACKAGE); jaroslav@1692: return (mods != 0) ? mods : PACKAGE; jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** Tells which class is performing the lookup. It is this class against jaroslav@1692: * which checks are performed for visibility and access permissions. jaroslav@1692: *

jaroslav@1692: * The class implies a maximum level of access permission, jaroslav@1692: * but the permissions may be additionally limited by the bitmask jaroslav@1692: * {@link #lookupModes lookupModes}, which controls whether non-public members jaroslav@1692: * can be accessed. jaroslav@1692: * @return the lookup class, on behalf of which this lookup object finds members jaroslav@1692: */ jaroslav@1692: public Class lookupClass() { jaroslav@1692: return lookupClass; jaroslav@1692: } jaroslav@1692: jaroslav@1692: // This is just for calling out to MethodHandleImpl. jaroslav@1692: private Class lookupClassOrNull() { jaroslav@1692: return (allowedModes == TRUSTED) ? null : lookupClass; jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** Tells which access-protection classes of members this lookup object can produce. jaroslav@1692: * The result is a bit-mask of the bits jaroslav@1692: * {@linkplain #PUBLIC PUBLIC (0x01)}, jaroslav@1692: * {@linkplain #PRIVATE PRIVATE (0x02)}, jaroslav@1692: * {@linkplain #PROTECTED PROTECTED (0x04)}, jaroslav@1692: * and {@linkplain #PACKAGE PACKAGE (0x08)}. jaroslav@1692: *

jaroslav@1692: * A freshly-created lookup object jaroslav@1692: * on the {@linkplain java.lang.invoke.MethodHandles#lookup() caller's class} jaroslav@1692: * has all possible bits set, since the caller class can access all its own members. jaroslav@1692: * A lookup object on a new lookup class jaroslav@1692: * {@linkplain java.lang.invoke.MethodHandles.Lookup#in created from a previous lookup object} jaroslav@1692: * may have some mode bits set to zero. jaroslav@1692: * The purpose of this is to restrict access via the new lookup object, jaroslav@1692: * so that it can access only names which can be reached by the original jaroslav@1692: * lookup object, and also by the new lookup class. jaroslav@1692: * @return the lookup modes, which limit the kinds of access performed by this lookup object jaroslav@1692: */ jaroslav@1692: public int lookupModes() { jaroslav@1692: return allowedModes & ALL_MODES; jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** Embody the current class (the lookupClass) as a lookup class jaroslav@1692: * for method handle creation. jaroslav@1692: * Must be called by from a method in this package, jaroslav@1692: * which in turn is called by a method not in this package. jaroslav@1692: */ jaroslav@1692: Lookup(Class lookupClass) { jaroslav@1692: this(lookupClass, ALL_MODES); jaroslav@1692: // make sure we haven't accidentally picked up a privileged class: jaroslav@1692: } jaroslav@1692: jaroslav@1692: private Lookup(Class lookupClass, int allowedModes) { jaroslav@1692: this.lookupClass = lookupClass; jaroslav@1692: this.allowedModes = allowedModes; jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Creates a lookup on the specified new lookup class. jaroslav@1692: * The resulting object will report the specified jaroslav@1692: * class as its own {@link #lookupClass lookupClass}. jaroslav@1692: *

jaroslav@1692: * However, the resulting {@code Lookup} object is guaranteed jaroslav@1692: * to have no more access capabilities than the original. jaroslav@1692: * In particular, access capabilities can be lost as follows:

jaroslav@1692: * jaroslav@1692: * @param requestedLookupClass the desired lookup class for the new lookup object jaroslav@1692: * @return a lookup object which reports the desired lookup class jaroslav@1692: * @throws NullPointerException if the argument is null jaroslav@1692: */ jaroslav@1692: public Lookup in(Class requestedLookupClass) { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** Version of lookup which is trusted minimally. jaroslav@1692: * It can only be used to create method handles to jaroslav@1692: * publicly accessible members. jaroslav@1692: */ jaroslav@1692: static final Lookup PUBLIC_LOOKUP = new Lookup(Object.class, PUBLIC); jaroslav@1692: jaroslav@1692: /** Package-private version of lookup which is trusted. */ jaroslav@1692: static final Lookup IMPL_LOOKUP = new Lookup(Object.class, TRUSTED); jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Displays the name of the class from which lookups are to be made. jaroslav@1692: * (The name is the one reported by {@link java.lang.Class#getName() Class.getName}.) jaroslav@1692: * If there are restrictions on the access permitted to this lookup, jaroslav@1692: * this is indicated by adding a suffix to the class name, consisting jaroslav@1692: * of a slash and a keyword. The keyword represents the strongest jaroslav@1692: * allowed access, and is chosen as follows: jaroslav@1692: * jaroslav@1692: * If none of the above cases apply, it is the case that full jaroslav@1692: * access (public, package, private, and protected) is allowed. jaroslav@1692: * In this case, no suffix is added. jaroslav@1692: * This is true only of an object obtained originally from jaroslav@1692: * {@link java.lang.invoke.MethodHandles#lookup MethodHandles.lookup}. jaroslav@1692: * Objects created by {@link java.lang.invoke.MethodHandles.Lookup#in Lookup.in} jaroslav@1692: * always have restricted access, and will display a suffix. jaroslav@1692: *

jaroslav@1692: * (It may seem strange that protected access should be jaroslav@1692: * stronger than private access. Viewed independently from jaroslav@1692: * package access, protected access is the first to be lost, jaroslav@1692: * because it requires a direct subclass relationship between jaroslav@1692: * caller and callee.) jaroslav@1692: * @see #in jaroslav@1692: */ jaroslav@1692: @Override jaroslav@1692: public String toString() { jaroslav@1692: String cname = lookupClass.getName(); jaroslav@1692: switch (allowedModes) { jaroslav@1692: case 0: // no privileges jaroslav@1692: return cname + "/noaccess"; jaroslav@1692: case PUBLIC: jaroslav@1692: return cname + "/public"; jaroslav@1692: case PUBLIC|PACKAGE: jaroslav@1692: return cname + "/package"; jaroslav@1692: case ALL_MODES & ~PROTECTED: jaroslav@1692: return cname + "/private"; jaroslav@1692: case ALL_MODES: jaroslav@1692: return cname; jaroslav@1692: case TRUSTED: jaroslav@1692: return "/trusted"; // internal only; not exported jaroslav@1692: default: // Should not happen, but it's a bitfield... jaroslav@1692: cname = cname + "/" + Integer.toHexString(allowedModes); jaroslav@1692: assert(false) : cname; jaroslav@1692: return cname; jaroslav@1692: } jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle for a static method. jaroslav@1692: * The type of the method handle will be that of the method. jaroslav@1692: * (Since static methods do not take receivers, there is no jaroslav@1692: * additional receiver argument inserted into the method handle type, jaroslav@1692: * as there would be with {@link #findVirtual findVirtual} or {@link #findSpecial findSpecial}.) jaroslav@1692: * The method and all its argument types must be accessible to the lookup object. jaroslav@1692: *

jaroslav@1692: * The returned method handle will have jaroslav@1692: * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if jaroslav@1692: * the method's variable arity modifier bit ({@code 0x0080}) is set. jaroslav@1692: *

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

Example: jaroslav@1692: * 

{@code
jaroslav@1692: import static java.lang.invoke.MethodHandles.*;
jaroslav@1692: import static java.lang.invoke.MethodType.*;
jaroslav@1692: ...
jaroslav@1692: MethodHandle MH_asList = publicLookup().findStatic(Arrays.class,
jaroslav@1692:   "asList", methodType(List.class, Object[].class));
jaroslav@1692: assertEquals("[x, y]", MH_asList.invoke("x", "y").toString());
jaroslav@1692:          * }
jaroslav@1692: * @param refc the class from which the method is accessed jaroslav@1692: * @param name the name of the method jaroslav@1692: * @param type the type of the method jaroslav@1692: * @return the desired method handle jaroslav@1692: * @throws NoSuchMethodException if the method does not exist jaroslav@1692: * @throws IllegalAccessException if access checking fails, jaroslav@1692: * or if the method is not {@code static}, jaroslav@1692: * or if the method's variable arity modifier bit jaroslav@1692: * is set and {@code asVarargsCollector} fails jaroslav@1692: * @exception SecurityException if a security manager is present and it jaroslav@1692: * refuses access jaroslav@1692: * @throws NullPointerException if any argument is null jaroslav@1692: */ jaroslav@1692: public jaroslav@1692: MethodHandle findStatic(Class refc, String name, MethodType type) throws NoSuchMethodException, IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle for a virtual method. jaroslav@1692: * The type of the method handle will be that of the method, jaroslav@1692: * with the receiver type (usually {@code refc}) prepended. jaroslav@1692: * The method and all its argument types must be accessible to the lookup object. jaroslav@1692: *

jaroslav@1692: * When called, the handle will treat the first argument as a receiver jaroslav@1692: * and dispatch on the receiver's type to determine which method jaroslav@1692: * implementation to enter. jaroslav@1692: * (The dispatching action is identical with that performed by an jaroslav@1692: * {@code invokevirtual} or {@code invokeinterface} instruction.) jaroslav@1692: *

jaroslav@1692: * The first argument will be of type {@code refc} if the lookup jaroslav@1692: * class has full privileges to access the member. Otherwise jaroslav@1692: * the member must be {@code protected} and the first argument jaroslav@1692: * will be restricted in type to the lookup class. jaroslav@1692: *

jaroslav@1692: * The returned method handle will have jaroslav@1692: * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if jaroslav@1692: * the method's variable arity modifier bit ({@code 0x0080}) is set. jaroslav@1692: *

jaroslav@1692: * Because of the general equivalence between {@code invokevirtual} jaroslav@1692: * instructions and method handles produced by {@code findVirtual}, jaroslav@1692: * if the class is {@code MethodHandle} and the name string is jaroslav@1692: * {@code invokeExact} or {@code invoke}, the resulting jaroslav@1692: * method handle is equivalent to one produced by jaroslav@1692: * {@link java.lang.invoke.MethodHandles#exactInvoker MethodHandles.exactInvoker} or jaroslav@1692: * {@link java.lang.invoke.MethodHandles#invoker MethodHandles.invoker} jaroslav@1692: * with the same {@code type} argument. jaroslav@1692: * jaroslav@1692: * Example: jaroslav@1692: * 

{@code
jaroslav@1692: import static java.lang.invoke.MethodHandles.*;
jaroslav@1692: import static java.lang.invoke.MethodType.*;
jaroslav@1692: ...
jaroslav@1692: MethodHandle MH_concat = publicLookup().findVirtual(String.class,
jaroslav@1692:   "concat", methodType(String.class, String.class));
jaroslav@1692: MethodHandle MH_hashCode = publicLookup().findVirtual(Object.class,
jaroslav@1692:   "hashCode", methodType(int.class));
jaroslav@1692: MethodHandle MH_hashCode_String = publicLookup().findVirtual(String.class,
jaroslav@1692:   "hashCode", methodType(int.class));
jaroslav@1692: assertEquals("xy", (String) MH_concat.invokeExact("x", "y"));
jaroslav@1692: assertEquals("xy".hashCode(), (int) MH_hashCode.invokeExact((Object)"xy"));
jaroslav@1692: assertEquals("xy".hashCode(), (int) MH_hashCode_String.invokeExact("xy"));
jaroslav@1692: // interface method:
jaroslav@1692: MethodHandle MH_subSequence = publicLookup().findVirtual(CharSequence.class,
jaroslav@1692:   "subSequence", methodType(CharSequence.class, int.class, int.class));
jaroslav@1692: assertEquals("def", MH_subSequence.invoke("abcdefghi", 3, 6).toString());
jaroslav@1692: // constructor "internal method" must be accessed differently:
jaroslav@1692: MethodType MT_newString = methodType(void.class); //()V for new String()
jaroslav@1692: try { assertEquals("impossible", lookup()
jaroslav@1692:         .findVirtual(String.class, "", MT_newString));
jaroslav@1692:  } catch (NoSuchMethodException ex) { } // OK
jaroslav@1692: MethodHandle MH_newString = publicLookup()
jaroslav@1692:   .findConstructor(String.class, MT_newString);
jaroslav@1692: assertEquals("", (String) MH_newString.invokeExact());
jaroslav@1692:          * }
jaroslav@1692: * jaroslav@1692: * @param refc the class or interface from which the method is accessed jaroslav@1692: * @param name the name of the method jaroslav@1692: * @param type the type of the method, with the receiver argument omitted jaroslav@1692: * @return the desired method handle jaroslav@1692: * @throws NoSuchMethodException if the method does not exist jaroslav@1692: * @throws IllegalAccessException if access checking fails, jaroslav@1692: * or if the method is {@code static} jaroslav@1692: * or if the method's variable arity modifier bit jaroslav@1692: * is set and {@code asVarargsCollector} fails jaroslav@1692: * @exception SecurityException if a security manager is present and it jaroslav@1692: * refuses access jaroslav@1692: * @throws NullPointerException if any argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle findVirtual(Class refc, String name, MethodType type) throws NoSuchMethodException, IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle which creates an object and initializes it, using jaroslav@1692: * the constructor of the specified type. jaroslav@1692: * The parameter types of the method handle will be those of the constructor, jaroslav@1692: * while the return type will be a reference to the constructor's class. jaroslav@1692: * The constructor and all its argument types must be accessible to the lookup object. jaroslav@1692: *

jaroslav@1692: * The requested type must have a return type of {@code void}. jaroslav@1692: * (This is consistent with the JVM's treatment of constructor type descriptors.) jaroslav@1692: *

jaroslav@1692: * The returned method handle will have jaroslav@1692: * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if jaroslav@1692: * the constructor's variable arity modifier bit ({@code 0x0080}) is set. jaroslav@1692: *

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

Example: jaroslav@1692: * 

{@code
jaroslav@1692: import static java.lang.invoke.MethodHandles.*;
jaroslav@1692: import static java.lang.invoke.MethodType.*;
jaroslav@1692: ...
jaroslav@1692: MethodHandle MH_newArrayList = publicLookup().findConstructor(
jaroslav@1692:   ArrayList.class, methodType(void.class, Collection.class));
jaroslav@1692: Collection orig = Arrays.asList("x", "y");
jaroslav@1692: Collection copy = (ArrayList) MH_newArrayList.invokeExact(orig);
jaroslav@1692: assert(orig != copy);
jaroslav@1692: assertEquals(orig, copy);
jaroslav@1692: // a variable-arity constructor:
jaroslav@1692: MethodHandle MH_newProcessBuilder = publicLookup().findConstructor(
jaroslav@1692:   ProcessBuilder.class, methodType(void.class, String[].class));
jaroslav@1692: ProcessBuilder pb = (ProcessBuilder)
jaroslav@1692:   MH_newProcessBuilder.invoke("x", "y", "z");
jaroslav@1692: assertEquals("[x, y, z]", pb.command().toString());
jaroslav@1692:          * }
jaroslav@1692: * @param refc the class or interface from which the method is accessed jaroslav@1692: * @param type the type of the method, with the receiver argument omitted, and a void return type jaroslav@1692: * @return the desired method handle jaroslav@1692: * @throws NoSuchMethodException if the constructor does not exist jaroslav@1692: * @throws IllegalAccessException if access checking fails jaroslav@1692: * or if the method's variable arity modifier bit jaroslav@1692: * is set and {@code asVarargsCollector} fails jaroslav@1692: * @exception SecurityException if a security manager is present and it jaroslav@1692: * refuses access jaroslav@1692: * @throws NullPointerException if any argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle findConstructor(Class refc, MethodType type) throws NoSuchMethodException, IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces an early-bound method handle for a virtual method. jaroslav@1692: * It will bypass checks for overriding methods on the receiver, jaroslav@1692: * as if called from an {@code invokespecial} jaroslav@1692: * instruction from within the explicitly specified {@code specialCaller}. jaroslav@1692: * The type of the method handle will be that of the method, jaroslav@1692: * with a suitably restricted receiver type prepended. jaroslav@1692: * (The receiver type will be {@code specialCaller} or a subtype.) jaroslav@1692: * The method and all its argument types must be accessible jaroslav@1692: * to the lookup object. jaroslav@1692: *

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

jaroslav@1692: * The returned method handle will have jaroslav@1692: * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if jaroslav@1692: * the method's variable arity modifier bit ({@code 0x0080}) is set. jaroslav@1692: *

jaroslav@1692: * (Note: JVM internal methods named {@code ""} are not visible to this API, jaroslav@1692: * even though the {@code invokespecial} instruction can refer to them jaroslav@1692: * in special circumstances. Use {@link #findConstructor findConstructor} jaroslav@1692: * to access instance initialization methods in a safe manner.) jaroslav@1692: *

Example: jaroslav@1692: * 

{@code
jaroslav@1692: import static java.lang.invoke.MethodHandles.*;
jaroslav@1692: import static java.lang.invoke.MethodType.*;
jaroslav@1692: ...
jaroslav@1692: static class Listie extends ArrayList {
jaroslav@1692:   public String toString() { return "[wee Listie]"; }
jaroslav@1692:   static Lookup lookup() { return MethodHandles.lookup(); }
jaroslav@1692: }
jaroslav@1692: ...
jaroslav@1692: // no access to constructor via invokeSpecial:
jaroslav@1692: MethodHandle MH_newListie = Listie.lookup()
jaroslav@1692:   .findConstructor(Listie.class, methodType(void.class));
jaroslav@1692: Listie l = (Listie) MH_newListie.invokeExact();
jaroslav@1692: try { assertEquals("impossible", Listie.lookup().findSpecial(
jaroslav@1692:         Listie.class, "", methodType(void.class), Listie.class));
jaroslav@1692:  } catch (NoSuchMethodException ex) { } // OK
jaroslav@1692: // access to super and self methods via invokeSpecial:
jaroslav@1692: MethodHandle MH_super = Listie.lookup().findSpecial(
jaroslav@1692:   ArrayList.class, "toString" , methodType(String.class), Listie.class);
jaroslav@1692: MethodHandle MH_this = Listie.lookup().findSpecial(
jaroslav@1692:   Listie.class, "toString" , methodType(String.class), Listie.class);
jaroslav@1692: MethodHandle MH_duper = Listie.lookup().findSpecial(
jaroslav@1692:   Object.class, "toString" , methodType(String.class), Listie.class);
jaroslav@1692: assertEquals("[]", (String) MH_super.invokeExact(l));
jaroslav@1692: assertEquals(""+l, (String) MH_this.invokeExact(l));
jaroslav@1692: assertEquals("[]", (String) MH_duper.invokeExact(l)); // ArrayList method
jaroslav@1692: try { assertEquals("inaccessible", Listie.lookup().findSpecial(
jaroslav@1692:         String.class, "toString", methodType(String.class), Listie.class));
jaroslav@1692:  } catch (IllegalAccessException ex) { } // OK
jaroslav@1692: Listie subl = new Listie() { public String toString() { return "[subclass]"; } };
jaroslav@1692: assertEquals(""+l, (String) MH_this.invokeExact(subl)); // Listie method
jaroslav@1692:          * }
jaroslav@1692: * jaroslav@1692: * @param refc the class or interface from which the method is accessed jaroslav@1692: * @param name the name of the method (which must not be "<init>") jaroslav@1692: * @param type the type of the method, with the receiver argument omitted jaroslav@1692: * @param specialCaller the proposed calling class to perform the {@code invokespecial} jaroslav@1692: * @return the desired method handle jaroslav@1692: * @throws NoSuchMethodException if the method does not exist jaroslav@1692: * @throws IllegalAccessException if access checking fails jaroslav@1692: * or if the method's variable arity modifier bit jaroslav@1692: * is set and {@code asVarargsCollector} fails jaroslav@1692: * @exception SecurityException if a security manager is present and it jaroslav@1692: * refuses access jaroslav@1692: * @throws NullPointerException if any argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle findSpecial(Class refc, String name, MethodType type, jaroslav@1692: Class specialCaller) throws NoSuchMethodException, IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle giving read access to a non-static field. jaroslav@1692: * The type of the method handle will have a return type of the field's jaroslav@1692: * value type. jaroslav@1692: * The method handle's single argument will be the instance containing jaroslav@1692: * the field. jaroslav@1692: * Access checking is performed immediately on behalf of the lookup class. jaroslav@1692: * @param refc the class or interface from which the method is accessed jaroslav@1692: * @param name the field's name jaroslav@1692: * @param type the field's type jaroslav@1692: * @return a method handle which can load values from the field jaroslav@1692: * @throws NoSuchFieldException if the field does not exist jaroslav@1692: * @throws IllegalAccessException if access checking fails, or if the field is {@code static} jaroslav@1692: * @exception SecurityException if a security manager is present and it jaroslav@1692: * refuses access jaroslav@1692: * @throws NullPointerException if any argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle findGetter(Class refc, String name, Class type) throws IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle giving write access to a non-static field. jaroslav@1692: * The type of the method handle will have a void return type. jaroslav@1692: * The method handle will take two arguments, the instance containing jaroslav@1692: * the field, and the value to be stored. jaroslav@1692: * The second argument will be of the field's value type. jaroslav@1692: * Access checking is performed immediately on behalf of the lookup class. jaroslav@1692: * @param refc the class or interface from which the method is accessed jaroslav@1692: * @param name the field's name jaroslav@1692: * @param type the field's type jaroslav@1692: * @return a method handle which can store values into the field jaroslav@1692: * @throws NoSuchFieldException if the field does not exist jaroslav@1692: * @throws IllegalAccessException if access checking fails, or if the field is {@code static} jaroslav@1692: * @exception SecurityException if a security manager is present and it jaroslav@1692: * refuses access jaroslav@1692: * @throws NullPointerException if any argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle findSetter(Class refc, String name, Class type) throws IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle giving read access to a static field. jaroslav@1692: * The type of the method handle will have a return type of the field's jaroslav@1692: * value type. jaroslav@1692: * The method handle will take no arguments. jaroslav@1692: * Access checking is performed immediately on behalf of the lookup class. jaroslav@1692: *

jaroslav@1692: * If the returned method handle is invoked, the field's class will jaroslav@1692: * be initialized, if it has not already been initialized. jaroslav@1692: * @param refc the class or interface from which the method is accessed jaroslav@1692: * @param name the field's name jaroslav@1692: * @param type the field's type jaroslav@1692: * @return a method handle which can load values from the field jaroslav@1692: * @throws NoSuchFieldException if the field does not exist jaroslav@1692: * @throws IllegalAccessException if access checking fails, or if the field is not {@code static} jaroslav@1692: * @exception SecurityException if a security manager is present and it jaroslav@1692: * refuses access jaroslav@1692: * @throws NullPointerException if any argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle findStaticGetter(Class refc, String name, Class type) throws IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle giving write access to a static field. jaroslav@1692: * The type of the method handle will have a void return type. jaroslav@1692: * The method handle will take a single jaroslav@1692: * argument, of the field's value type, the value to be stored. jaroslav@1692: * Access checking is performed immediately on behalf of the lookup class. jaroslav@1692: *

jaroslav@1692: * If the returned method handle is invoked, the field's class will jaroslav@1692: * be initialized, if it has not already been initialized. jaroslav@1692: * @param refc the class or interface from which the method is accessed jaroslav@1692: * @param name the field's name jaroslav@1692: * @param type the field's type jaroslav@1692: * @return a method handle which can store values into the field jaroslav@1692: * @throws NoSuchFieldException if the field does not exist jaroslav@1692: * @throws IllegalAccessException if access checking fails, or if the field is not {@code static} jaroslav@1692: * @exception SecurityException if a security manager is present and it jaroslav@1692: * refuses access jaroslav@1692: * @throws NullPointerException if any argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle findStaticSetter(Class refc, String name, Class type) throws IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces an early-bound method handle for a non-static method. jaroslav@1692: * The receiver must have a supertype {@code defc} in which a method jaroslav@1692: * of the given name and type is accessible to the lookup class. jaroslav@1692: * The method and all its argument types must be accessible to the lookup object. jaroslav@1692: * The type of the method handle will be that of the method, jaroslav@1692: * without any insertion of an additional receiver parameter. jaroslav@1692: * The given receiver will be bound into the method handle, jaroslav@1692: * so that every call to the method handle will invoke the jaroslav@1692: * requested method on the given receiver. jaroslav@1692: *

jaroslav@1692: * The returned method handle will have jaroslav@1692: * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if jaroslav@1692: * the method's variable arity modifier bit ({@code 0x0080}) is set jaroslav@1692: * and the trailing array argument is not the only argument. jaroslav@1692: * (If the trailing array argument is the only argument, jaroslav@1692: * the given receiver value will be bound to it.) jaroslav@1692: *

jaroslav@1692: * This is equivalent to the following code: jaroslav@1692: * 

{@code
jaroslav@1692: import static java.lang.invoke.MethodHandles.*;
jaroslav@1692: import static java.lang.invoke.MethodType.*;
jaroslav@1692: ...
jaroslav@1692: MethodHandle mh0 = lookup().findVirtual(defc, name, type);
jaroslav@1692: MethodHandle mh1 = mh0.bindTo(receiver);
jaroslav@1692: MethodType mt1 = mh1.type();
jaroslav@1692: if (mh0.isVarargsCollector())
jaroslav@1692:   mh1 = mh1.asVarargsCollector(mt1.parameterType(mt1.parameterCount()-1));
jaroslav@1692: return mh1;
jaroslav@1692:          * }
jaroslav@1692: * where {@code defc} is either {@code receiver.getClass()} or a super jaroslav@1692: * type of that class, in which the requested method is accessible jaroslav@1692: * to the lookup class. jaroslav@1692: * (Note that {@code bindTo} does not preserve variable arity.) jaroslav@1692: * @param receiver the object from which the method is accessed jaroslav@1692: * @param name the name of the method jaroslav@1692: * @param type the type of the method, with the receiver argument omitted jaroslav@1692: * @return the desired method handle jaroslav@1692: * @throws NoSuchMethodException if the method does not exist jaroslav@1692: * @throws IllegalAccessException if access checking fails jaroslav@1692: * or if the method's variable arity modifier bit jaroslav@1692: * is set and {@code asVarargsCollector} fails jaroslav@1692: * @exception SecurityException if a security manager is present and it jaroslav@1692: * refuses access jaroslav@1692: * @throws NullPointerException if any argument is null jaroslav@1692: * @see MethodHandle#bindTo jaroslav@1692: * @see #findVirtual jaroslav@1692: */ jaroslav@1692: public MethodHandle bind(Object receiver, String name, MethodType type) throws NoSuchMethodException, IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Makes a direct method handle jaroslav@1692: * to m, if the lookup class has permission. jaroslav@1692: * If m is non-static, the receiver argument is treated as an initial argument. jaroslav@1692: * If m is virtual, overriding is respected on every call. jaroslav@1692: * Unlike the Core Reflection API, exceptions are not wrapped. jaroslav@1692: * The type of the method handle will be that of the method, jaroslav@1692: * with the receiver type prepended (but only if it is non-static). jaroslav@1692: * If the method's {@code accessible} flag is not set, jaroslav@1692: * access checking is performed immediately on behalf of the lookup class. jaroslav@1692: * If m is not public, do not share the resulting handle with untrusted parties. jaroslav@1692: *

jaroslav@1692: * The returned method handle will have jaroslav@1692: * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if jaroslav@1692: * the method's variable arity modifier bit ({@code 0x0080}) is set. jaroslav@1692: *

jaroslav@1692: * If m is static, and jaroslav@1692: * if the returned method handle is invoked, the method's class will jaroslav@1692: * be initialized, if it has not already been initialized. jaroslav@1692: * @param m the reflected method jaroslav@1692: * @return a method handle which can invoke the reflected method jaroslav@1692: * @throws IllegalAccessException if access checking fails jaroslav@1692: * or if the method's variable arity modifier bit jaroslav@1692: * is set and {@code asVarargsCollector} fails jaroslav@1692: * @throws NullPointerException if the argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle unreflect(Method m) throws IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle for a reflected method. jaroslav@1692: * It will bypass checks for overriding methods on the receiver, jaroslav@1692: * as if called from an {@code invokespecial} jaroslav@1692: * instruction from within the explicitly specified {@code specialCaller}. jaroslav@1692: * The type of the method handle will be that of the method, jaroslav@1692: * with a suitably restricted receiver type prepended. jaroslav@1692: * (The receiver type will be {@code specialCaller} or a subtype.) jaroslav@1692: * If the method's {@code accessible} flag is not set, jaroslav@1692: * access checking is performed immediately on behalf of the lookup class, jaroslav@1692: * as if {@code invokespecial} instruction were being linked. jaroslav@1692: *

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

jaroslav@1692: * The returned method handle will have jaroslav@1692: * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if jaroslav@1692: * the method's variable arity modifier bit ({@code 0x0080}) is set. jaroslav@1692: * @param m the reflected method jaroslav@1692: * @param specialCaller the class nominally calling the method jaroslav@1692: * @return a method handle which can invoke the reflected method jaroslav@1692: * @throws IllegalAccessException if access checking fails jaroslav@1692: * or if the method's variable arity modifier bit jaroslav@1692: * is set and {@code asVarargsCollector} fails jaroslav@1692: * @throws NullPointerException if any argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle unreflectSpecial(Method m, Class specialCaller) throws IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle for a reflected constructor. jaroslav@1692: * The type of the method handle will be that of the constructor, jaroslav@1692: * with the return type changed to the declaring class. jaroslav@1692: * The method handle will perform a {@code newInstance} operation, jaroslav@1692: * creating a new instance of the constructor's class on the jaroslav@1692: * arguments passed to the method handle. jaroslav@1692: *

jaroslav@1692: * If the constructor's {@code accessible} flag is not set, jaroslav@1692: * access checking is performed immediately on behalf of the lookup class. jaroslav@1692: *

jaroslav@1692: * The returned method handle will have jaroslav@1692: * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if jaroslav@1692: * the constructor's variable arity modifier bit ({@code 0x0080}) is set. jaroslav@1692: *

jaroslav@1692: * If the returned method handle is invoked, the constructor's class will jaroslav@1692: * be initialized, if it has not already been initialized. jaroslav@1692: * @param c the reflected constructor jaroslav@1692: * @return a method handle which can invoke the reflected constructor jaroslav@1692: * @throws IllegalAccessException if access checking fails jaroslav@1692: * or if the method's variable arity modifier bit jaroslav@1692: * is set and {@code asVarargsCollector} fails jaroslav@1692: * @throws NullPointerException if the argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle unreflectConstructor(Constructor c) throws IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle giving read access to a reflected field. jaroslav@1692: * The type of the method handle will have a return type of the field's jaroslav@1692: * value type. jaroslav@1692: * If the field is static, the method handle will take no arguments. jaroslav@1692: * Otherwise, its single argument will be the instance containing jaroslav@1692: * the field. jaroslav@1692: * If the field's {@code accessible} flag is not set, jaroslav@1692: * access checking is performed immediately on behalf of the lookup class. jaroslav@1692: *

jaroslav@1692: * If the field is static, and jaroslav@1692: * if the returned method handle is invoked, the field's class will jaroslav@1692: * be initialized, if it has not already been initialized. jaroslav@1692: * @param f the reflected field jaroslav@1692: * @return a method handle which can load values from the reflected field jaroslav@1692: * @throws IllegalAccessException if access checking fails jaroslav@1692: * @throws NullPointerException if the argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle unreflectGetter(Field f) throws IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Produces a method handle giving write access to a reflected field. jaroslav@1692: * The type of the method handle will have a void return type. jaroslav@1692: * If the field is static, the method handle will take a single jaroslav@1692: * argument, of the field's value type, the value to be stored. jaroslav@1692: * Otherwise, the two arguments will be the instance containing jaroslav@1692: * the field, and the value to be stored. jaroslav@1692: * If the field's {@code accessible} flag is not set, jaroslav@1692: * access checking is performed immediately on behalf of the lookup class. jaroslav@1692: *

jaroslav@1692: * If the field is static, and jaroslav@1692: * if the returned method handle is invoked, the field's class will jaroslav@1692: * be initialized, if it has not already been initialized. jaroslav@1692: * @param f the reflected field jaroslav@1692: * @return a method handle which can store values into the reflected field jaroslav@1692: * @throws IllegalAccessException if access checking fails jaroslav@1692: * @throws NullPointerException if the argument is null jaroslav@1692: */ jaroslav@1692: public MethodHandle unreflectSetter(Field f) throws IllegalAccessException { jaroslav@1692: throw new IllegalStateException(); jaroslav@1692: } jaroslav@1692: jaroslav@1692: /** jaroslav@1692: * Cracks a direct method handle jaroslav@1692: * created by this lookup object or a similar one. jaroslav@1692: * Security and access checks are performed to ensure that this lookup object jaroslav@1692: * is capable of reproducing the target method handle. jaroslav@1692: * This means that the cracking may fail if target is a direct method handle jaroslav@1692: * but was created by an unrelated lookup object. jaroslav@1692: * This can happen if the method handle is caller sensitive jaroslav@1692: * and was created by a lookup object for a different class. jaroslav@1692: * @param target a direct method handle to crack into symbolic reference components jaroslav@1692: * @return a symbolic reference which can be used to reconstruct this method handle from this lookup object jaroslav@1692: * @exception SecurityException if a security manager is present and it jaroslav@1692: * refuses access jaroslav@1692: * @throws IllegalArgumentException if the target is not a direct method handle or if access checking fails jaroslav@1692: * @exception NullPointerException if the target is {@code null} jaroslav@1692: * @see MethodHandleInfo jaroslav@1692: * @since 1.8 jaroslav@1692: */ jaroslav@1692: // public MethodHandleInfo revealDirect(MethodHandle target) { jaroslav@1692: // throw new IllegalStateException(); jaroslav@1692: // } jaroslav@1692: } jaroslav@1692: jaroslav@1692: }