Adding necessary fake classes to allow Javac to compile lamda expressions against our emulation library.
2 * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
26 package java.lang.invoke;
28 import java.lang.reflect.*;
31 * This class consists exclusively of static methods that operate on or return
32 * method handles. They fall into several categories:
34 * <li>Lookup methods which help create method handles for methods and fields.
35 * <li>Combinator methods, which combine or transform pre-existing method handles into new ones.
36 * <li>Other factory methods to create method handles that emulate other common JVM operations or control flow patterns.
39 * @author John Rose, JSR 292 EG
42 public class MethodHandles {
44 private MethodHandles() { } // do not instantiate
46 //// Method handle creation from ordinary methods.
49 * Returns a {@link Lookup lookup object} with
50 * full capabilities to emulate all supported bytecode behaviors of the caller.
51 * These capabilities include <a href="MethodHandles.Lookup.html#privacc">private access</a> to the caller.
52 * Factory methods on the lookup object can create
53 * <a href="MethodHandleInfo.html#directmh">direct method handles</a>
54 * for any member that the caller has access to via bytecodes,
55 * including protected and private fields and methods.
56 * This lookup object is a <em>capability</em> which may be delegated to trusted agents.
57 * Do not store it in place where untrusted code can access it.
59 * This method is caller sensitive, which means that it may return different
60 * values to different callers.
62 * For any given caller class {@code C}, the lookup object returned by this call
63 * has equivalent capabilities to any lookup object
64 * supplied by the JVM to the bootstrap method of an
65 * <a href="package-summary.html#indyinsn">invokedynamic instruction</a>
66 * executing in the same caller class {@code C}.
67 * @return a lookup object for the caller of this method, with private access
70 public static Lookup lookup() {
71 throw new IllegalStateException("Implement me!");
72 // return new Lookup(Reflection.getCallerClass());
76 * Returns a {@link Lookup lookup object} which is trusted minimally.
77 * It can only be used to create method handles to
78 * publicly accessible fields and methods.
80 * As a matter of pure convention, the {@linkplain Lookup#lookupClass lookup class}
81 * of this lookup object will be {@link java.lang.Object}.
83 * <p style="font-size:smaller;">
84 * <em>Discussion:</em>
85 * The lookup class can be changed to any other class {@code C} using an expression of the form
86 * {@link Lookup#in publicLookup().in(C.class)}.
87 * Since all classes have equal access to public names,
88 * such a change would confer no new access rights.
89 * A public lookup object is always subject to
90 * <a href="MethodHandles.Lookup.html#secmgr">security manager checks</a>.
91 * Also, it cannot access
92 * <a href="MethodHandles.Lookup.html#callsens">caller sensitive methods</a>.
93 * @return a lookup object which is trusted minimally
95 public static Lookup publicLookup() {
96 return Lookup.PUBLIC_LOOKUP;
100 * Performs an unchecked "crack" of a
101 * <a href="MethodHandleInfo.html#directmh">direct method handle</a>.
102 * The result is as if the user had obtained a lookup object capable enough
103 * to crack the target method handle, called
104 * {@link java.lang.invoke.MethodHandles.Lookup#revealDirect Lookup.revealDirect}
105 * on the target to obtain its symbolic reference, and then called
106 * {@link java.lang.invoke.MethodHandleInfo#reflectAs MethodHandleInfo.reflectAs}
107 * to resolve the symbolic reference to a member.
109 * If there is a security manager, its {@code checkPermission} method
110 * is called with a {@code ReflectPermission("suppressAccessChecks")} permission.
111 * @param <T> the desired type of the result, either {@link Member} or a subtype
112 * @param target a direct method handle to crack into symbolic reference components
113 * @param expected a class object representing the desired result type {@code T}
114 * @return a reference to the method, constructor, or field object
115 * @exception SecurityException if the caller is not privileged to call {@code setAccessible}
116 * @exception NullPointerException if either argument is {@code null}
117 * @exception IllegalArgumentException if the target is not a direct method handle
118 * @exception ClassCastException if the member is not of the expected type
121 public static <T extends Member> T
122 reflectAs(Class<T> expected, MethodHandle target) {
123 throw new IllegalStateException();
125 // Copied from AccessibleObject, as used by Method.setAccessible, etc.:
126 // static final private java.security.Permission ACCESS_PERMISSION =
127 // new ReflectPermission("suppressAccessChecks");
129 static Lookup findFor(Class<?> clazz) {
131 if (o instanceof Class) {
132 return new Lookup(clazz, Lookup.ALL_MODES);
134 throw new IllegalArgumentException("Expecting class: " + o);
138 * A <em>lookup object</em> is a factory for creating method handles,
139 * when the creation requires access checking.
140 * Method handles do not perform
141 * access checks when they are called, but rather when they are created.
142 * Therefore, method handle access
143 * restrictions must be enforced when a method handle is created.
144 * The caller class against which those restrictions are enforced
145 * is known as the {@linkplain #lookupClass lookup class}.
147 * A lookup class which needs to create method handles will call
148 * {@link MethodHandles#lookup MethodHandles.lookup} to create a factory for itself.
149 * When the {@code Lookup} factory object is created, the identity of the lookup class is
150 * determined, and securely stored in the {@code Lookup} object.
151 * The lookup class (or its delegates) may then use factory methods
152 * on the {@code Lookup} object to create method handles for access-checked members.
153 * This includes all methods, constructors, and fields which are allowed to the lookup class,
156 * <h1><a name="lookups"></a>Lookup Factory Methods</h1>
157 * The factory methods on a {@code Lookup} object correspond to all major
158 * use cases for methods, constructors, and fields.
159 * Each method handle created by a factory method is the functional
160 * equivalent of a particular <em>bytecode behavior</em>.
161 * (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.)
162 * Here is a summary of the correspondence between these factory methods and
163 * the behavior the resulting method handles:
164 * <table border=1 cellpadding=5 summary="lookup method behaviors">
166 * <th><a name="equiv"></a>lookup expression</th>
168 * <th>bytecode behavior</th>
171 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}</td>
172 * <td>{@code FT f;}</td><td>{@code (T) this.f;}</td>
175 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}</td>
176 * <td>{@code static}<br>{@code FT f;}</td><td>{@code (T) C.f;}</td>
179 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findSetter lookup.findSetter(C.class,"f",FT.class)}</td>
180 * <td>{@code FT f;}</td><td>{@code this.f = x;}</td>
183 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStaticSetter lookup.findStaticSetter(C.class,"f",FT.class)}</td>
184 * <td>{@code static}<br>{@code FT f;}</td><td>{@code C.f = arg;}</td>
187 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findVirtual lookup.findVirtual(C.class,"m",MT)}</td>
188 * <td>{@code T m(A*);}</td><td>{@code (T) this.m(arg*);}</td>
191 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStatic lookup.findStatic(C.class,"m",MT)}</td>
192 * <td>{@code static}<br>{@code T m(A*);}</td><td>{@code (T) C.m(arg*);}</td>
195 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findSpecial lookup.findSpecial(C.class,"m",MT,this.class)}</td>
196 * <td>{@code T m(A*);}</td><td>{@code (T) super.m(arg*);}</td>
199 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findConstructor lookup.findConstructor(C.class,MT)}</td>
200 * <td>{@code C(A*);}</td><td>{@code new C(arg*);}</td>
203 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectGetter lookup.unreflectGetter(aField)}</td>
204 * <td>({@code static})?<br>{@code FT f;}</td><td>{@code (FT) aField.get(thisOrNull);}</td>
207 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectSetter lookup.unreflectSetter(aField)}</td>
208 * <td>({@code static})?<br>{@code FT f;}</td><td>{@code aField.set(thisOrNull, arg);}</td>
211 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
212 * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
215 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectConstructor lookup.unreflectConstructor(aConstructor)}</td>
216 * <td>{@code C(A*);}</td><td>{@code (C) aConstructor.newInstance(arg*);}</td>
219 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
220 * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
224 * Here, the type {@code C} is the class or interface being searched for a member,
225 * documented as a parameter named {@code refc} in the lookup methods.
226 * The method type {@code MT} is composed from the return type {@code T}
227 * and the sequence of argument types {@code A*}.
228 * The constructor also has a sequence of argument types {@code A*} and
229 * is deemed to return the newly-created object of type {@code C}.
230 * Both {@code MT} and the field type {@code FT} are documented as a parameter named {@code type}.
231 * The formal parameter {@code this} stands for the self-reference of type {@code C};
232 * if it is present, it is always the leading argument to the method handle invocation.
233 * (In the case of some {@code protected} members, {@code this} may be
234 * restricted in type to the lookup class; see below.)
235 * The name {@code arg} stands for all the other method handle arguments.
236 * In the code examples for the Core Reflection API, the name {@code thisOrNull}
237 * stands for a null reference if the accessed method or field is static,
238 * and {@code this} otherwise.
239 * The names {@code aMethod}, {@code aField}, and {@code aConstructor} stand
240 * for reflective objects corresponding to the given members.
242 * In cases where the given member is of variable arity (i.e., a method or constructor)
243 * the returned method handle will also be of {@linkplain MethodHandle#asVarargsCollector variable arity}.
244 * In all other cases, the returned method handle will be of fixed arity.
245 * <p style="font-size:smaller;">
246 * <em>Discussion:</em>
247 * The equivalence between looked-up method handles and underlying
248 * class members and bytecode behaviors
249 * can break down in a few ways:
250 * <ul style="font-size:smaller;">
251 * <li>If {@code C} is not symbolically accessible from the lookup class's loader,
252 * the lookup can still succeed, even when there is no equivalent
253 * Java expression or bytecoded constant.
254 * <li>Likewise, if {@code T} or {@code MT}
255 * is not symbolically accessible from the lookup class's loader,
256 * the lookup can still succeed.
257 * For example, lookups for {@code MethodHandle.invokeExact} and
258 * {@code MethodHandle.invoke} will always succeed, regardless of requested type.
259 * <li>If there is a security manager installed, it can forbid the lookup
260 * on various grounds (<a href="MethodHandles.Lookup.html#secmgr">see below</a>).
261 * By contrast, the {@code ldc} instruction on a {@code CONSTANT_MethodHandle}
262 * constant is not subject to security manager checks.
263 * <li>If the looked-up method has a
264 * <a href="MethodHandle.html#maxarity">very large arity</a>,
265 * the method handle creation may fail, due to the method handle
266 * type having too many parameters.
269 * <h1><a name="access"></a>Access checking</h1>
270 * Access checks are applied in the factory methods of {@code Lookup},
271 * when a method handle is created.
272 * This is a key difference from the Core Reflection API, since
273 * {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}
274 * performs access checking against every caller, on every call.
276 * All access checks start from a {@code Lookup} object, which
277 * compares its recorded lookup class against all requests to
278 * create method handles.
279 * A single {@code Lookup} object can be used to create any number
280 * of access-checked method handles, all checked against a single
283 * A {@code Lookup} object can be shared with other trusted code,
284 * such as a metaobject protocol.
285 * A shared {@code Lookup} object delegates the capability
286 * to create method handles on private members of the lookup class.
287 * Even if privileged code uses the {@code Lookup} object,
288 * the access checking is confined to the privileges of the
289 * original lookup class.
291 * A lookup can fail, because
292 * the containing class is not accessible to the lookup class, or
293 * because the desired class member is missing, or because the
294 * desired class member is not accessible to the lookup class, or
295 * because the lookup object is not trusted enough to access the member.
296 * In any of these cases, a {@code ReflectiveOperationException} will be
297 * thrown from the attempted lookup. The exact class will be one of
300 * <li>NoSuchMethodException — if a method is requested but does not exist
301 * <li>NoSuchFieldException — if a field is requested but does not exist
302 * <li>IllegalAccessException — if the member exists but an access check fails
305 * In general, the conditions under which a method handle may be
306 * looked up for a method {@code M} are no more restrictive than the conditions
307 * under which the lookup class could have compiled, verified, and resolved a call to {@code M}.
308 * Where the JVM would raise exceptions like {@code NoSuchMethodError},
309 * a method handle lookup will generally raise a corresponding
310 * checked exception, such as {@code NoSuchMethodException}.
311 * And the effect of invoking the method handle resulting from the lookup
312 * is <a href="MethodHandles.Lookup.html#equiv">exactly equivalent</a>
313 * to executing the compiled, verified, and resolved call to {@code M}.
314 * The same point is true of fields and constructors.
315 * <p style="font-size:smaller;">
316 * <em>Discussion:</em>
317 * Access checks only apply to named and reflected methods,
318 * constructors, and fields.
319 * Other method handle creation methods, such as
320 * {@link MethodHandle#asType MethodHandle.asType},
321 * do not require any access checks, and are used
322 * independently of any {@code Lookup} object.
324 * If the desired member is {@code protected}, the usual JVM rules apply,
325 * including the requirement that the lookup class must be either be in the
326 * same package as the desired member, or must inherit that member.
327 * (See the Java Virtual Machine Specification, sections 4.9.2, 5.4.3.5, and 6.4.)
328 * In addition, if the desired member is a non-static field or method
329 * in a different package, the resulting method handle may only be applied
330 * to objects of the lookup class or one of its subclasses.
331 * This requirement is enforced by narrowing the type of the leading
332 * {@code this} parameter from {@code C}
333 * (which will necessarily be a superclass of the lookup class)
334 * to the lookup class itself.
336 * The JVM imposes a similar requirement on {@code invokespecial} instruction,
337 * that the receiver argument must match both the resolved method <em>and</em>
338 * the current class. Again, this requirement is enforced by narrowing the
339 * type of the leading parameter to the resulting method handle.
340 * (See the Java Virtual Machine Specification, section 4.10.1.9.)
342 * The JVM represents constructors and static initializer blocks as internal methods
343 * with special names ({@code "<init>"} and {@code "<clinit>"}).
344 * The internal syntax of invocation instructions allows them to refer to such internal
345 * methods as if they were normal methods, but the JVM bytecode verifier rejects them.
346 * A lookup of such an internal method will produce a {@code NoSuchMethodException}.
348 * In some cases, access between nested classes is obtained by the Java compiler by creating
349 * an wrapper method to access a private method of another class
350 * in the same top-level declaration.
351 * For example, a nested class {@code C.D}
352 * can access private members within other related classes such as
353 * {@code C}, {@code C.D.E}, or {@code C.B},
354 * but the Java compiler may need to generate wrapper methods in
355 * those related classes. In such cases, a {@code Lookup} object on
356 * {@code C.E} would be unable to those private members.
357 * A workaround for this limitation is the {@link Lookup#in Lookup.in} method,
358 * which can transform a lookup on {@code C.E} into one on any of those other
359 * classes, without special elevation of privilege.
361 * The accesses permitted to a given lookup object may be limited,
362 * according to its set of {@link #lookupModes lookupModes},
363 * to a subset of members normally accessible to the lookup class.
364 * For example, the {@link MethodHandles#publicLookup publicLookup}
365 * method produces a lookup object which is only allowed to access
366 * public members in public classes.
367 * The caller sensitive method {@link MethodHandles#lookup lookup}
368 * produces a lookup object with full capabilities relative to
369 * its caller class, to emulate all supported bytecode behaviors.
370 * Also, the {@link Lookup#in Lookup.in} method may produce a lookup object
371 * with fewer access modes than the original lookup object.
373 * <p style="font-size:smaller;">
374 * <a name="privacc"></a>
375 * <em>Discussion of private access:</em>
376 * We say that a lookup has <em>private access</em>
377 * if its {@linkplain #lookupModes lookup modes}
378 * include the possibility of accessing {@code private} members.
379 * As documented in the relevant methods elsewhere,
380 * only lookups with private access possess the following capabilities:
381 * <ul style="font-size:smaller;">
382 * <li>access private fields, methods, and constructors of the lookup class
383 * <li>create method handles which invoke <a href="MethodHandles.Lookup.html#callsens">caller sensitive</a> methods,
384 * such as {@code Class.forName}
385 * <li>create method handles which {@link Lookup#findSpecial emulate invokespecial} instructions
386 * <li>avoid <a href="MethodHandles.Lookup.html#secmgr">package access checks</a>
387 * for classes accessible to the lookup class
388 * <li>create {@link Lookup#in delegated lookup objects} which have private access to other classes
389 * within the same package member
391 * <p style="font-size:smaller;">
392 * Each of these permissions is a consequence of the fact that a lookup object
393 * with private access can be securely traced back to an originating class,
394 * whose <a href="MethodHandles.Lookup.html#equiv">bytecode behaviors</a> and Java language access permissions
395 * can be reliably determined and emulated by method handles.
397 * <h1><a name="secmgr"></a>Security manager interactions</h1>
398 * Although bytecode instructions can only refer to classes in
399 * a related class loader, this API can search for methods in any
400 * class, as long as a reference to its {@code Class} object is
401 * available. Such cross-loader references are also possible with the
402 * Core Reflection API, and are impossible to bytecode instructions
403 * such as {@code invokestatic} or {@code getfield}.
404 * There is a {@linkplain java.lang.SecurityManager security manager API}
405 * to allow applications to check such cross-loader references.
406 * These checks apply to both the {@code MethodHandles.Lookup} API
407 * and the Core Reflection API
408 * (as found on {@link java.lang.Class Class}).
410 * If a security manager is present, member lookups are subject to
412 * From one to three calls are made to the security manager.
413 * Any of these calls can refuse access by throwing a
414 * {@link java.lang.SecurityException SecurityException}.
415 * Define {@code smgr} as the security manager,
416 * {@code lookc} as the lookup class of the current lookup object,
417 * {@code refc} as the containing class in which the member
418 * is being sought, and {@code defc} as the class in which the
419 * member is actually defined.
420 * The value {@code lookc} is defined as <em>not present</em>
421 * if the current lookup object does not have
422 * <a href="MethodHandles.Lookup.html#privacc">private access</a>.
423 * The calls are made according to the following rules:
426 * If {@code lookc} is not present, or if its class loader is not
427 * the same as or an ancestor of the class loader of {@code refc},
428 * then {@link SecurityManager#checkPackageAccess
429 * smgr.checkPackageAccess(refcPkg)} is called,
430 * where {@code refcPkg} is the package of {@code refc}.
432 * If the retrieved member is not public and
433 * {@code lookc} is not present, then
434 * {@link SecurityManager#checkPermission smgr.checkPermission}
435 * with {@code RuntimePermission("accessDeclaredMembers")} is called.
437 * If the retrieved member is not public,
438 * and if {@code lookc} is not present,
439 * and if {@code defc} and {@code refc} are different,
440 * then {@link SecurityManager#checkPackageAccess
441 * smgr.checkPackageAccess(defcPkg)} is called,
442 * where {@code defcPkg} is the package of {@code defc}.
444 * Security checks are performed after other access checks have passed.
445 * Therefore, the above rules presuppose a member that is public,
446 * or else that is being accessed from a lookup class that has
447 * rights to access the member.
449 * <h1><a name="callsens"></a>Caller sensitive methods</h1>
450 * A small number of Java methods have a special property called caller sensitivity.
451 * A <em>caller-sensitive</em> method can behave differently depending on the
452 * identity of its immediate caller.
454 * If a method handle for a caller-sensitive method is requested,
455 * the general rules for <a href="MethodHandles.Lookup.html#equiv">bytecode behaviors</a> apply,
456 * but they take account of the lookup class in a special way.
457 * The resulting method handle behaves as if it were called
458 * from an instruction contained in the lookup class,
459 * so that the caller-sensitive method detects the lookup class.
460 * (By contrast, the invoker of the method handle is disregarded.)
461 * Thus, in the case of caller-sensitive methods,
462 * different lookup classes may give rise to
463 * differently behaving method handles.
465 * In cases where the lookup object is
466 * {@link MethodHandles#publicLookup() publicLookup()},
467 * or some other lookup object without
468 * <a href="MethodHandles.Lookup.html#privacc">private access</a>,
469 * the lookup class is disregarded.
470 * In such cases, no caller-sensitive method handle can be created,
471 * access is forbidden, and the lookup fails with an
472 * {@code IllegalAccessException}.
473 * <p style="font-size:smaller;">
474 * <em>Discussion:</em>
475 * For example, the caller-sensitive method
476 * {@link java.lang.Class#forName(String) Class.forName(x)}
477 * can return varying classes or throw varying exceptions,
478 * depending on the class loader of the class that calls it.
479 * A public lookup of {@code Class.forName} will fail, because
480 * there is no reasonable way to determine its bytecode behavior.
481 * <p style="font-size:smaller;">
482 * If an application caches method handles for broad sharing,
483 * it should use {@code publicLookup()} to create them.
484 * If there is a lookup of {@code Class.forName}, it will fail,
485 * and the application must take appropriate action in that case.
486 * It may be that a later lookup, perhaps during the invocation of a
487 * bootstrap method, can incorporate the specific identity
488 * of the caller, making the method accessible.
489 * <p style="font-size:smaller;">
490 * The function {@code MethodHandles.lookup} is caller sensitive
491 * so that there can be a secure foundation for lookups.
492 * Nearly all other methods in the JSR 292 API rely on lookup
493 * objects to check access requests.
497 /** The class on behalf of whom the lookup is being performed. */
498 private final Class<?> lookupClass;
500 /** The allowed sorts of members which may be looked up (PUBLIC, etc.). */
501 private final int allowedModes;
503 /** A single-bit mask representing {@code public} access,
504 * which may contribute to the result of {@link #lookupModes lookupModes}.
505 * The value, {@code 0x01}, happens to be the same as the value of the
506 * {@code public} {@linkplain java.lang.reflect.Modifier#PUBLIC modifier bit}.
508 public static final int PUBLIC = Modifier.PUBLIC;
510 /** A single-bit mask representing {@code private} access,
511 * which may contribute to the result of {@link #lookupModes lookupModes}.
512 * The value, {@code 0x02}, happens to be the same as the value of the
513 * {@code private} {@linkplain java.lang.reflect.Modifier#PRIVATE modifier bit}.
515 public static final int PRIVATE = Modifier.PRIVATE;
517 /** A single-bit mask representing {@code protected} access,
518 * which may contribute to the result of {@link #lookupModes lookupModes}.
519 * The value, {@code 0x04}, happens to be the same as the value of the
520 * {@code protected} {@linkplain java.lang.reflect.Modifier#PROTECTED modifier bit}.
522 public static final int PROTECTED = Modifier.PROTECTED;
524 /** A single-bit mask representing {@code package} access (default access),
525 * which may contribute to the result of {@link #lookupModes lookupModes}.
526 * The value is {@code 0x08}, which does not correspond meaningfully to
527 * any particular {@linkplain java.lang.reflect.Modifier modifier bit}.
529 public static final int PACKAGE = Modifier.STATIC;
531 private static final int ALL_MODES = (PUBLIC | PRIVATE | PROTECTED | PACKAGE);
532 private static final int TRUSTED = -1;
534 private static int fixmods(int mods) {
535 mods &= (ALL_MODES - PACKAGE);
536 return (mods != 0) ? mods : PACKAGE;
539 /** Tells which class is performing the lookup. It is this class against
540 * which checks are performed for visibility and access permissions.
542 * The class implies a maximum level of access permission,
543 * but the permissions may be additionally limited by the bitmask
544 * {@link #lookupModes lookupModes}, which controls whether non-public members
546 * @return the lookup class, on behalf of which this lookup object finds members
548 public Class<?> lookupClass() {
552 // This is just for calling out to MethodHandleImpl.
553 private Class<?> lookupClassOrNull() {
554 return (allowedModes == TRUSTED) ? null : lookupClass;
557 /** Tells which access-protection classes of members this lookup object can produce.
558 * The result is a bit-mask of the bits
559 * {@linkplain #PUBLIC PUBLIC (0x01)},
560 * {@linkplain #PRIVATE PRIVATE (0x02)},
561 * {@linkplain #PROTECTED PROTECTED (0x04)},
562 * and {@linkplain #PACKAGE PACKAGE (0x08)}.
564 * A freshly-created lookup object
565 * on the {@linkplain java.lang.invoke.MethodHandles#lookup() caller's class}
566 * has all possible bits set, since the caller class can access all its own members.
567 * A lookup object on a new lookup class
568 * {@linkplain java.lang.invoke.MethodHandles.Lookup#in created from a previous lookup object}
569 * may have some mode bits set to zero.
570 * The purpose of this is to restrict access via the new lookup object,
571 * so that it can access only names which can be reached by the original
572 * lookup object, and also by the new lookup class.
573 * @return the lookup modes, which limit the kinds of access performed by this lookup object
575 public int lookupModes() {
576 return allowedModes & ALL_MODES;
579 /** Embody the current class (the lookupClass) as a lookup class
580 * for method handle creation.
581 * Must be called by from a method in this package,
582 * which in turn is called by a method not in this package.
584 Lookup(Class<?> lookupClass) {
585 this(lookupClass, ALL_MODES);
586 // make sure we haven't accidentally picked up a privileged class:
589 private Lookup(Class<?> lookupClass, int allowedModes) {
590 this.lookupClass = lookupClass;
591 this.allowedModes = allowedModes;
595 * Creates a lookup on the specified new lookup class.
596 * The resulting object will report the specified
597 * class as its own {@link #lookupClass lookupClass}.
599 * However, the resulting {@code Lookup} object is guaranteed
600 * to have no more access capabilities than the original.
601 * In particular, access capabilities can be lost as follows:<ul>
602 * <li>If the new lookup class differs from the old one,
603 * protected members will not be accessible by virtue of inheritance.
604 * (Protected members may continue to be accessible because of package sharing.)
605 * <li>If the new lookup class is in a different package
606 * than the old one, protected and default (package) members will not be accessible.
607 * <li>If the new lookup class is not within the same package member
608 * as the old one, private members will not be accessible.
609 * <li>If the new lookup class is not accessible to the old lookup class,
610 * then no members, not even public members, will be accessible.
611 * (In all other cases, public members will continue to be accessible.)
614 * @param requestedLookupClass the desired lookup class for the new lookup object
615 * @return a lookup object which reports the desired lookup class
616 * @throws NullPointerException if the argument is null
618 public Lookup in(Class<?> requestedLookupClass) {
619 throw new IllegalStateException();
622 /** Version of lookup which is trusted minimally.
623 * It can only be used to create method handles to
624 * publicly accessible members.
626 static final Lookup PUBLIC_LOOKUP = new Lookup(Object.class, PUBLIC);
628 /** Package-private version of lookup which is trusted. */
629 static final Lookup IMPL_LOOKUP = new Lookup(Object.class, TRUSTED);
632 * Displays the name of the class from which lookups are to be made.
633 * (The name is the one reported by {@link java.lang.Class#getName() Class.getName}.)
634 * If there are restrictions on the access permitted to this lookup,
635 * this is indicated by adding a suffix to the class name, consisting
636 * of a slash and a keyword. The keyword represents the strongest
637 * allowed access, and is chosen as follows:
639 * <li>If no access is allowed, the suffix is "/noaccess".
640 * <li>If only public access is allowed, the suffix is "/public".
641 * <li>If only public and package access are allowed, the suffix is "/package".
642 * <li>If only public, package, and private access are allowed, the suffix is "/private".
644 * If none of the above cases apply, it is the case that full
645 * access (public, package, private, and protected) is allowed.
646 * In this case, no suffix is added.
647 * This is true only of an object obtained originally from
648 * {@link java.lang.invoke.MethodHandles#lookup MethodHandles.lookup}.
649 * Objects created by {@link java.lang.invoke.MethodHandles.Lookup#in Lookup.in}
650 * always have restricted access, and will display a suffix.
652 * (It may seem strange that protected access should be
653 * stronger than private access. Viewed independently from
654 * package access, protected access is the first to be lost,
655 * because it requires a direct subclass relationship between
656 * caller and callee.)
660 public String toString() {
661 String cname = lookupClass.getName();
662 switch (allowedModes) {
663 case 0: // no privileges
664 return cname + "/noaccess";
666 return cname + "/public";
668 return cname + "/package";
669 case ALL_MODES & ~PROTECTED:
670 return cname + "/private";
674 return "/trusted"; // internal only; not exported
675 default: // Should not happen, but it's a bitfield...
676 cname = cname + "/" + Integer.toHexString(allowedModes);
677 assert(false) : cname;
683 * Produces a method handle for a static method.
684 * The type of the method handle will be that of the method.
685 * (Since static methods do not take receivers, there is no
686 * additional receiver argument inserted into the method handle type,
687 * as there would be with {@link #findVirtual findVirtual} or {@link #findSpecial findSpecial}.)
688 * The method and all its argument types must be accessible to the lookup object.
690 * The returned method handle will have
691 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
692 * the method's variable arity modifier bit ({@code 0x0080}) is set.
694 * If the returned method handle is invoked, the method's class will
695 * be initialized, if it has not already been initialized.
697 * <blockquote><pre>{@code
698 import static java.lang.invoke.MethodHandles.*;
699 import static java.lang.invoke.MethodType.*;
701 MethodHandle MH_asList = publicLookup().findStatic(Arrays.class,
702 "asList", methodType(List.class, Object[].class));
703 assertEquals("[x, y]", MH_asList.invoke("x", "y").toString());
704 * }</pre></blockquote>
705 * @param refc the class from which the method is accessed
706 * @param name the name of the method
707 * @param type the type of the method
708 * @return the desired method handle
709 * @throws NoSuchMethodException if the method does not exist
710 * @throws IllegalAccessException if access checking fails,
711 * or if the method is not {@code static},
712 * or if the method's variable arity modifier bit
713 * is set and {@code asVarargsCollector} fails
714 * @exception SecurityException if a security manager is present and it
715 * <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
716 * @throws NullPointerException if any argument is null
719 MethodHandle findStatic(Class<?> refc, String name, MethodType type) throws NoSuchMethodException, IllegalAccessException {
720 throw new IllegalStateException();
724 * Produces a method handle for a virtual method.
725 * The type of the method handle will be that of the method,
726 * with the receiver type (usually {@code refc}) prepended.
727 * The method and all its argument types must be accessible to the lookup object.
729 * When called, the handle will treat the first argument as a receiver
730 * and dispatch on the receiver's type to determine which method
731 * implementation to enter.
732 * (The dispatching action is identical with that performed by an
733 * {@code invokevirtual} or {@code invokeinterface} instruction.)
735 * The first argument will be of type {@code refc} if the lookup
736 * class has full privileges to access the member. Otherwise
737 * the member must be {@code protected} and the first argument
738 * will be restricted in type to the lookup class.
740 * The returned method handle will have
741 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
742 * the method's variable arity modifier bit ({@code 0x0080}) is set.
744 * Because of the general <a href="MethodHandles.Lookup.html#equiv">equivalence</a> between {@code invokevirtual}
745 * instructions and method handles produced by {@code findVirtual},
746 * if the class is {@code MethodHandle} and the name string is
747 * {@code invokeExact} or {@code invoke}, the resulting
748 * method handle is equivalent to one produced by
749 * {@link java.lang.invoke.MethodHandles#exactInvoker MethodHandles.exactInvoker} or
750 * {@link java.lang.invoke.MethodHandles#invoker MethodHandles.invoker}
751 * with the same {@code type} argument.
754 * <blockquote><pre>{@code
755 import static java.lang.invoke.MethodHandles.*;
756 import static java.lang.invoke.MethodType.*;
758 MethodHandle MH_concat = publicLookup().findVirtual(String.class,
759 "concat", methodType(String.class, String.class));
760 MethodHandle MH_hashCode = publicLookup().findVirtual(Object.class,
761 "hashCode", methodType(int.class));
762 MethodHandle MH_hashCode_String = publicLookup().findVirtual(String.class,
763 "hashCode", methodType(int.class));
764 assertEquals("xy", (String) MH_concat.invokeExact("x", "y"));
765 assertEquals("xy".hashCode(), (int) MH_hashCode.invokeExact((Object)"xy"));
766 assertEquals("xy".hashCode(), (int) MH_hashCode_String.invokeExact("xy"));
768 MethodHandle MH_subSequence = publicLookup().findVirtual(CharSequence.class,
769 "subSequence", methodType(CharSequence.class, int.class, int.class));
770 assertEquals("def", MH_subSequence.invoke("abcdefghi", 3, 6).toString());
771 // constructor "internal method" must be accessed differently:
772 MethodType MT_newString = methodType(void.class); //()V for new String()
773 try { assertEquals("impossible", lookup()
774 .findVirtual(String.class, "<init>", MT_newString));
775 } catch (NoSuchMethodException ex) { } // OK
776 MethodHandle MH_newString = publicLookup()
777 .findConstructor(String.class, MT_newString);
778 assertEquals("", (String) MH_newString.invokeExact());
779 * }</pre></blockquote>
781 * @param refc the class or interface from which the method is accessed
782 * @param name the name of the method
783 * @param type the type of the method, with the receiver argument omitted
784 * @return the desired method handle
785 * @throws NoSuchMethodException if the method does not exist
786 * @throws IllegalAccessException if access checking fails,
787 * or if the method is {@code static}
788 * or if the method's variable arity modifier bit
789 * is set and {@code asVarargsCollector} fails
790 * @exception SecurityException if a security manager is present and it
791 * <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
792 * @throws NullPointerException if any argument is null
794 public MethodHandle findVirtual(Class<?> refc, String name, MethodType type) throws NoSuchMethodException, IllegalAccessException {
795 throw new IllegalStateException();
799 * Produces a method handle which creates an object and initializes it, using
800 * the constructor of the specified type.
801 * The parameter types of the method handle will be those of the constructor,
802 * while the return type will be a reference to the constructor's class.
803 * The constructor and all its argument types must be accessible to the lookup object.
805 * The requested type must have a return type of {@code void}.
806 * (This is consistent with the JVM's treatment of constructor type descriptors.)
808 * The returned method handle will have
809 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
810 * the constructor's variable arity modifier bit ({@code 0x0080}) is set.
812 * If the returned method handle is invoked, the constructor's class will
813 * be initialized, if it has not already been initialized.
815 * <blockquote><pre>{@code
816 import static java.lang.invoke.MethodHandles.*;
817 import static java.lang.invoke.MethodType.*;
819 MethodHandle MH_newArrayList = publicLookup().findConstructor(
820 ArrayList.class, methodType(void.class, Collection.class));
821 Collection orig = Arrays.asList("x", "y");
822 Collection copy = (ArrayList) MH_newArrayList.invokeExact(orig);
823 assert(orig != copy);
824 assertEquals(orig, copy);
825 // a variable-arity constructor:
826 MethodHandle MH_newProcessBuilder = publicLookup().findConstructor(
827 ProcessBuilder.class, methodType(void.class, String[].class));
828 ProcessBuilder pb = (ProcessBuilder)
829 MH_newProcessBuilder.invoke("x", "y", "z");
830 assertEquals("[x, y, z]", pb.command().toString());
831 * }</pre></blockquote>
832 * @param refc the class or interface from which the method is accessed
833 * @param type the type of the method, with the receiver argument omitted, and a void return type
834 * @return the desired method handle
835 * @throws NoSuchMethodException if the constructor does not exist
836 * @throws IllegalAccessException if access checking fails
837 * or if the method's variable arity modifier bit
838 * is set and {@code asVarargsCollector} fails
839 * @exception SecurityException if a security manager is present and it
840 * <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
841 * @throws NullPointerException if any argument is null
843 public MethodHandle findConstructor(Class<?> refc, MethodType type) throws NoSuchMethodException, IllegalAccessException {
844 throw new IllegalStateException();
848 * Produces an early-bound method handle for a virtual method.
849 * It will bypass checks for overriding methods on the receiver,
850 * <a href="MethodHandles.Lookup.html#equiv">as if called</a> from an {@code invokespecial}
851 * instruction from within the explicitly specified {@code specialCaller}.
852 * The type of the method handle will be that of the method,
853 * with a suitably restricted receiver type prepended.
854 * (The receiver type will be {@code specialCaller} or a subtype.)
855 * The method and all its argument types must be accessible
856 * to the lookup object.
858 * Before method resolution,
859 * if the explicitly specified caller class is not identical with the
860 * lookup class, or if this lookup object does not have
861 * <a href="MethodHandles.Lookup.html#privacc">private access</a>
862 * privileges, the access fails.
864 * The returned method handle will have
865 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
866 * the method's variable arity modifier bit ({@code 0x0080}) is set.
867 * <p style="font-size:smaller;">
868 * <em>(Note: JVM internal methods named {@code "<init>"} are not visible to this API,
869 * even though the {@code invokespecial} instruction can refer to them
870 * in special circumstances. Use {@link #findConstructor findConstructor}
871 * to access instance initialization methods in a safe manner.)</em>
873 * <blockquote><pre>{@code
874 import static java.lang.invoke.MethodHandles.*;
875 import static java.lang.invoke.MethodType.*;
877 static class Listie extends ArrayList {
878 public String toString() { return "[wee Listie]"; }
879 static Lookup lookup() { return MethodHandles.lookup(); }
882 // no access to constructor via invokeSpecial:
883 MethodHandle MH_newListie = Listie.lookup()
884 .findConstructor(Listie.class, methodType(void.class));
885 Listie l = (Listie) MH_newListie.invokeExact();
886 try { assertEquals("impossible", Listie.lookup().findSpecial(
887 Listie.class, "<init>", methodType(void.class), Listie.class));
888 } catch (NoSuchMethodException ex) { } // OK
889 // access to super and self methods via invokeSpecial:
890 MethodHandle MH_super = Listie.lookup().findSpecial(
891 ArrayList.class, "toString" , methodType(String.class), Listie.class);
892 MethodHandle MH_this = Listie.lookup().findSpecial(
893 Listie.class, "toString" , methodType(String.class), Listie.class);
894 MethodHandle MH_duper = Listie.lookup().findSpecial(
895 Object.class, "toString" , methodType(String.class), Listie.class);
896 assertEquals("[]", (String) MH_super.invokeExact(l));
897 assertEquals(""+l, (String) MH_this.invokeExact(l));
898 assertEquals("[]", (String) MH_duper.invokeExact(l)); // ArrayList method
899 try { assertEquals("inaccessible", Listie.lookup().findSpecial(
900 String.class, "toString", methodType(String.class), Listie.class));
901 } catch (IllegalAccessException ex) { } // OK
902 Listie subl = new Listie() { public String toString() { return "[subclass]"; } };
903 assertEquals(""+l, (String) MH_this.invokeExact(subl)); // Listie method
904 * }</pre></blockquote>
906 * @param refc the class or interface from which the method is accessed
907 * @param name the name of the method (which must not be "<init>")
908 * @param type the type of the method, with the receiver argument omitted
909 * @param specialCaller the proposed calling class to perform the {@code invokespecial}
910 * @return the desired method handle
911 * @throws NoSuchMethodException if the method does not exist
912 * @throws IllegalAccessException if access checking fails
913 * or if the method's variable arity modifier bit
914 * is set and {@code asVarargsCollector} fails
915 * @exception SecurityException if a security manager is present and it
916 * <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
917 * @throws NullPointerException if any argument is null
919 public MethodHandle findSpecial(Class<?> refc, String name, MethodType type,
920 Class<?> specialCaller) throws NoSuchMethodException, IllegalAccessException {
921 throw new IllegalStateException();
925 * Produces a method handle giving read access to a non-static field.
926 * The type of the method handle will have a return type of the field's
928 * The method handle's single argument will be the instance containing
930 * Access checking is performed immediately on behalf of the lookup class.
931 * @param refc the class or interface from which the method is accessed
932 * @param name the field's name
933 * @param type the field's type
934 * @return a method handle which can load values from the field
935 * @throws NoSuchFieldException if the field does not exist
936 * @throws IllegalAccessException if access checking fails, or if the field is {@code static}
937 * @exception SecurityException if a security manager is present and it
938 * <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
939 * @throws NullPointerException if any argument is null
941 public MethodHandle findGetter(Class<?> refc, String name, Class<?> type) throws IllegalAccessException {
942 throw new IllegalStateException();
946 * Produces a method handle giving write access to a non-static field.
947 * The type of the method handle will have a void return type.
948 * The method handle will take two arguments, the instance containing
949 * the field, and the value to be stored.
950 * The second argument will be of the field's value type.
951 * Access checking is performed immediately on behalf of the lookup class.
952 * @param refc the class or interface from which the method is accessed
953 * @param name the field's name
954 * @param type the field's type
955 * @return a method handle which can store values into the field
956 * @throws NoSuchFieldException if the field does not exist
957 * @throws IllegalAccessException if access checking fails, or if the field is {@code static}
958 * @exception SecurityException if a security manager is present and it
959 * <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
960 * @throws NullPointerException if any argument is null
962 public MethodHandle findSetter(Class<?> refc, String name, Class<?> type) throws IllegalAccessException {
963 throw new IllegalStateException();
967 * Produces a method handle giving read access to a static field.
968 * The type of the method handle will have a return type of the field's
970 * The method handle will take no arguments.
971 * Access checking is performed immediately on behalf of the lookup class.
973 * If the returned method handle is invoked, the field's class will
974 * be initialized, if it has not already been initialized.
975 * @param refc the class or interface from which the method is accessed
976 * @param name the field's name
977 * @param type the field's type
978 * @return a method handle which can load values from the field
979 * @throws NoSuchFieldException if the field does not exist
980 * @throws IllegalAccessException if access checking fails, or if the field is not {@code static}
981 * @exception SecurityException if a security manager is present and it
982 * <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
983 * @throws NullPointerException if any argument is null
985 public MethodHandle findStaticGetter(Class<?> refc, String name, Class<?> type) throws IllegalAccessException {
986 throw new IllegalStateException();
990 * Produces a method handle giving write access to a static field.
991 * The type of the method handle will have a void return type.
992 * The method handle will take a single
993 * argument, of the field's value type, the value to be stored.
994 * Access checking is performed immediately on behalf of the lookup class.
996 * If the returned method handle is invoked, the field's class will
997 * be initialized, if it has not already been initialized.
998 * @param refc the class or interface from which the method is accessed
999 * @param name the field's name
1000 * @param type the field's type
1001 * @return a method handle which can store values into the field
1002 * @throws NoSuchFieldException if the field does not exist
1003 * @throws IllegalAccessException if access checking fails, or if the field is not {@code static}
1004 * @exception SecurityException if a security manager is present and it
1005 * <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
1006 * @throws NullPointerException if any argument is null
1008 public MethodHandle findStaticSetter(Class<?> refc, String name, Class<?> type) throws IllegalAccessException {
1009 throw new IllegalStateException();
1013 * Produces an early-bound method handle for a non-static method.
1014 * The receiver must have a supertype {@code defc} in which a method
1015 * of the given name and type is accessible to the lookup class.
1016 * The method and all its argument types must be accessible to the lookup object.
1017 * The type of the method handle will be that of the method,
1018 * without any insertion of an additional receiver parameter.
1019 * The given receiver will be bound into the method handle,
1020 * so that every call to the method handle will invoke the
1021 * requested method on the given receiver.
1023 * The returned method handle will have
1024 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
1025 * the method's variable arity modifier bit ({@code 0x0080}) is set
1026 * <em>and</em> the trailing array argument is not the only argument.
1027 * (If the trailing array argument is the only argument,
1028 * the given receiver value will be bound to it.)
1030 * This is equivalent to the following code:
1031 * <blockquote><pre>{@code
1032 import static java.lang.invoke.MethodHandles.*;
1033 import static java.lang.invoke.MethodType.*;
1035 MethodHandle mh0 = lookup().findVirtual(defc, name, type);
1036 MethodHandle mh1 = mh0.bindTo(receiver);
1037 MethodType mt1 = mh1.type();
1038 if (mh0.isVarargsCollector())
1039 mh1 = mh1.asVarargsCollector(mt1.parameterType(mt1.parameterCount()-1));
1041 * }</pre></blockquote>
1042 * where {@code defc} is either {@code receiver.getClass()} or a super
1043 * type of that class, in which the requested method is accessible
1044 * to the lookup class.
1045 * (Note that {@code bindTo} does not preserve variable arity.)
1046 * @param receiver the object from which the method is accessed
1047 * @param name the name of the method
1048 * @param type the type of the method, with the receiver argument omitted
1049 * @return the desired method handle
1050 * @throws NoSuchMethodException if the method does not exist
1051 * @throws IllegalAccessException if access checking fails
1052 * or if the method's variable arity modifier bit
1053 * is set and {@code asVarargsCollector} fails
1054 * @exception SecurityException if a security manager is present and it
1055 * <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
1056 * @throws NullPointerException if any argument is null
1057 * @see MethodHandle#bindTo
1060 public MethodHandle bind(Object receiver, String name, MethodType type) throws NoSuchMethodException, IllegalAccessException {
1061 throw new IllegalStateException();
1065 * Makes a <a href="MethodHandleInfo.html#directmh">direct method handle</a>
1066 * to <i>m</i>, if the lookup class has permission.
1067 * If <i>m</i> is non-static, the receiver argument is treated as an initial argument.
1068 * If <i>m</i> is virtual, overriding is respected on every call.
1069 * Unlike the Core Reflection API, exceptions are <em>not</em> wrapped.
1070 * The type of the method handle will be that of the method,
1071 * with the receiver type prepended (but only if it is non-static).
1072 * If the method's {@code accessible} flag is not set,
1073 * access checking is performed immediately on behalf of the lookup class.
1074 * If <i>m</i> is not public, do not share the resulting handle with untrusted parties.
1076 * The returned method handle will have
1077 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
1078 * the method's variable arity modifier bit ({@code 0x0080}) is set.
1080 * If <i>m</i> is static, and
1081 * if the returned method handle is invoked, the method's class will
1082 * be initialized, if it has not already been initialized.
1083 * @param m the reflected method
1084 * @return a method handle which can invoke the reflected method
1085 * @throws IllegalAccessException if access checking fails
1086 * or if the method's variable arity modifier bit
1087 * is set and {@code asVarargsCollector} fails
1088 * @throws NullPointerException if the argument is null
1090 public MethodHandle unreflect(Method m) throws IllegalAccessException {
1091 throw new IllegalStateException();
1095 * Produces a method handle for a reflected method.
1096 * It will bypass checks for overriding methods on the receiver,
1097 * <a href="MethodHandles.Lookup.html#equiv">as if called</a> from an {@code invokespecial}
1098 * instruction from within the explicitly specified {@code specialCaller}.
1099 * The type of the method handle will be that of the method,
1100 * with a suitably restricted receiver type prepended.
1101 * (The receiver type will be {@code specialCaller} or a subtype.)
1102 * If the method's {@code accessible} flag is not set,
1103 * access checking is performed immediately on behalf of the lookup class,
1104 * as if {@code invokespecial} instruction were being linked.
1106 * Before method resolution,
1107 * if the explicitly specified caller class is not identical with the
1108 * lookup class, or if this lookup object does not have
1109 * <a href="MethodHandles.Lookup.html#privacc">private access</a>
1110 * privileges, the access fails.
1112 * The returned method handle will have
1113 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
1114 * the method's variable arity modifier bit ({@code 0x0080}) is set.
1115 * @param m the reflected method
1116 * @param specialCaller the class nominally calling the method
1117 * @return a method handle which can invoke the reflected method
1118 * @throws IllegalAccessException if access checking fails
1119 * or if the method's variable arity modifier bit
1120 * is set and {@code asVarargsCollector} fails
1121 * @throws NullPointerException if any argument is null
1123 public MethodHandle unreflectSpecial(Method m, Class<?> specialCaller) throws IllegalAccessException {
1124 throw new IllegalStateException();
1128 * Produces a method handle for a reflected constructor.
1129 * The type of the method handle will be that of the constructor,
1130 * with the return type changed to the declaring class.
1131 * The method handle will perform a {@code newInstance} operation,
1132 * creating a new instance of the constructor's class on the
1133 * arguments passed to the method handle.
1135 * If the constructor's {@code accessible} flag is not set,
1136 * access checking is performed immediately on behalf of the lookup class.
1138 * The returned method handle will have
1139 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
1140 * the constructor's variable arity modifier bit ({@code 0x0080}) is set.
1142 * If the returned method handle is invoked, the constructor's class will
1143 * be initialized, if it has not already been initialized.
1144 * @param c the reflected constructor
1145 * @return a method handle which can invoke the reflected constructor
1146 * @throws IllegalAccessException if access checking fails
1147 * or if the method's variable arity modifier bit
1148 * is set and {@code asVarargsCollector} fails
1149 * @throws NullPointerException if the argument is null
1151 public MethodHandle unreflectConstructor(Constructor<?> c) throws IllegalAccessException {
1152 throw new IllegalStateException();
1156 * Produces a method handle giving read access to a reflected field.
1157 * The type of the method handle will have a return type of the field's
1159 * If the field is static, the method handle will take no arguments.
1160 * Otherwise, its single argument will be the instance containing
1162 * If the field's {@code accessible} flag is not set,
1163 * access checking is performed immediately on behalf of the lookup class.
1165 * If the field is static, and
1166 * if the returned method handle is invoked, the field's class will
1167 * be initialized, if it has not already been initialized.
1168 * @param f the reflected field
1169 * @return a method handle which can load values from the reflected field
1170 * @throws IllegalAccessException if access checking fails
1171 * @throws NullPointerException if the argument is null
1173 public MethodHandle unreflectGetter(Field f) throws IllegalAccessException {
1174 throw new IllegalStateException();
1178 * Produces a method handle giving write access to a reflected field.
1179 * The type of the method handle will have a void return type.
1180 * If the field is static, the method handle will take a single
1181 * argument, of the field's value type, the value to be stored.
1182 * Otherwise, the two arguments will be the instance containing
1183 * the field, and the value to be stored.
1184 * If the field's {@code accessible} flag is not set,
1185 * access checking is performed immediately on behalf of the lookup class.
1187 * If the field is static, and
1188 * if the returned method handle is invoked, the field's class will
1189 * be initialized, if it has not already been initialized.
1190 * @param f the reflected field
1191 * @return a method handle which can store values into the reflected field
1192 * @throws IllegalAccessException if access checking fails
1193 * @throws NullPointerException if the argument is null
1195 public MethodHandle unreflectSetter(Field f) throws IllegalAccessException {
1196 throw new IllegalStateException();
1200 * Cracks a <a href="MethodHandleInfo.html#directmh">direct method handle</a>
1201 * created by this lookup object or a similar one.
1202 * Security and access checks are performed to ensure that this lookup object
1203 * is capable of reproducing the target method handle.
1204 * This means that the cracking may fail if target is a direct method handle
1205 * but was created by an unrelated lookup object.
1206 * This can happen if the method handle is <a href="MethodHandles.Lookup.html#callsens">caller sensitive</a>
1207 * and was created by a lookup object for a different class.
1208 * @param target a direct method handle to crack into symbolic reference components
1209 * @return a symbolic reference which can be used to reconstruct this method handle from this lookup object
1210 * @exception SecurityException if a security manager is present and it
1211 * <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
1212 * @throws IllegalArgumentException if the target is not a direct method handle or if access checking fails
1213 * @exception NullPointerException if the target is {@code null}
1214 * @see MethodHandleInfo
1217 // public MethodHandleInfo revealDirect(MethodHandle target) {
1218 // throw new IllegalStateException();