301 * access checks when they are called, but rather when they are created.
302 * Therefore, method handle access
303 * restrictions must be enforced when a method handle is created.
304 * The caller class against which those restrictions are enforced
305 * is known as the {@linkplain #lookupClass() lookup class}.
306 * <p>
307 * A lookup class which needs to create method handles will call
308 * {@link MethodHandles#lookup() MethodHandles.lookup} to create a factory for itself.
309 * When the {@code Lookup} factory object is created, the identity of the lookup class is
310 * determined, and securely stored in the {@code Lookup} object.
311 * The lookup class (or its delegates) may then use factory methods
312 * on the {@code Lookup} object to create method handles for access-checked members.
313 * This includes all methods, constructors, and fields which are allowed to the lookup class,
314 * even private ones.
315 *
316 * <h2><a id="lookups"></a>Lookup Factory Methods</h2>
317 * The factory methods on a {@code Lookup} object correspond to all major
318 * use cases for methods, constructors, and fields.
319 * Each method handle created by a factory method is the functional
320 * equivalent of a particular <em>bytecode behavior</em>.
321 * (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.)
322 * Here is a summary of the correspondence between these factory methods and
323 * the behavior of the resulting method handles:
324 * <table class="striped">
325 * <caption style="display:none">lookup method behaviors</caption>
326 * <thead>
327 * <tr>
328 * <th scope="col"><a id="equiv"></a>lookup expression</th>
329 * <th scope="col">member</th>
330 * <th scope="col">bytecode behavior</th>
331 * </tr>
332 * </thead>
333 * <tbody>
334 * <tr>
335 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}</th>
336 * <td>{@code FT f;}</td><td>{@code (T) this.f;}</td>
337 * </tr>
338 * <tr>
339 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}</th>
340 * <td>{@code static}<br>{@code FT f;}</td><td>{@code (FT) C.f;}</td>
341 * </tr>
485 * under which the lookup class could have compiled, verified, and resolved a call to {@code M}.
486 * Where the JVM would raise exceptions like {@code NoSuchMethodError},
487 * a method handle lookup will generally raise a corresponding
488 * checked exception, such as {@code NoSuchMethodException}.
489 * And the effect of invoking the method handle resulting from the lookup
490 * is <a href="MethodHandles.Lookup.html#equiv">exactly equivalent</a>
491 * to executing the compiled, verified, and resolved call to {@code M}.
492 * The same point is true of fields and constructors.
493 * <p style="font-size:smaller;">
494 * <em>Discussion:</em>
495 * Access checks only apply to named and reflected methods,
496 * constructors, and fields.
497 * Other method handle creation methods, such as
498 * {@link MethodHandle#asType MethodHandle.asType},
499 * do not require any access checks, and are used
500 * independently of any {@code Lookup} object.
501 * <p>
502 * If the desired member is {@code protected}, the usual JVM rules apply,
503 * including the requirement that the lookup class must either be in the
504 * same package as the desired member, or must inherit that member.
505 * (See the Java Virtual Machine Specification, sections 4.9.2, 5.4.3.5, and 6.4.)
506 * In addition, if the desired member is a non-static field or method
507 * in a different package, the resulting method handle may only be applied
508 * to objects of the lookup class or one of its subclasses.
509 * This requirement is enforced by narrowing the type of the leading
510 * {@code this} parameter from {@code C}
511 * (which will necessarily be a superclass of the lookup class)
512 * to the lookup class itself.
513 * <p>
514 * The JVM imposes a similar requirement on {@code invokespecial} instruction,
515 * that the receiver argument must match both the resolved method <em>and</em>
516 * the current class. Again, this requirement is enforced by narrowing the
517 * type of the leading parameter to the resulting method handle.
518 * (See the Java Virtual Machine Specification, section 4.10.1.9.)
519 * <p>
520 * The JVM represents constructors and static initializer blocks as internal methods
521 * with special names ({@code "<init>"} and {@code "<clinit>"}).
522 * The internal syntax of invocation instructions allows them to refer to such internal
523 * methods as if they were normal methods, but the JVM bytecode verifier rejects them.
524 * A lookup of such an internal method will produce a {@code NoSuchMethodException}.
525 * <p>
526 * If the relationship between nested types is expressed directly through the
527 * {@code NestHost} and {@code NestMembers} attributes
528 * (see the Java Virtual Machine Specification, sections 4.7.28 and 4.7.29),
529 * then the associated {@code Lookup} object provides direct access to
530 * the lookup class and all of its nestmates
531 * (see {@link java.lang.Class#getNestHost Class.getNestHost}).
532 * Otherwise, access between nested classes is obtained by the Java compiler creating
533 * a wrapper method to access a private method of another class in the same nest.
534 * For example, a nested class {@code C.D}
535 * can access private members within other related classes such as
536 * {@code C}, {@code C.D.E}, or {@code C.B},
537 * but the Java compiler may need to generate wrapper methods in
538 * those related classes. In such cases, a {@code Lookup} object on
539 * {@code C.E} would be unable to access those private members.
540 * A workaround for this limitation is the {@link Lookup#in Lookup.in} method,
541 * which can transform a lookup on {@code C.E} into one on any of those other
542 * classes, without special elevation of privilege.
543 * <p>
544 * The accesses permitted to a given lookup object may be limited,
545 * according to its set of {@link #lookupModes lookupModes},
546 * to a subset of members normally accessible to the lookup class.
547 * For example, the {@link MethodHandles#publicLookup publicLookup}
548 * method produces a lookup object which is only allowed to access
|
301 * access checks when they are called, but rather when they are created.
302 * Therefore, method handle access
303 * restrictions must be enforced when a method handle is created.
304 * The caller class against which those restrictions are enforced
305 * is known as the {@linkplain #lookupClass() lookup class}.
306 * <p>
307 * A lookup class which needs to create method handles will call
308 * {@link MethodHandles#lookup() MethodHandles.lookup} to create a factory for itself.
309 * When the {@code Lookup} factory object is created, the identity of the lookup class is
310 * determined, and securely stored in the {@code Lookup} object.
311 * The lookup class (or its delegates) may then use factory methods
312 * on the {@code Lookup} object to create method handles for access-checked members.
313 * This includes all methods, constructors, and fields which are allowed to the lookup class,
314 * even private ones.
315 *
316 * <h2><a id="lookups"></a>Lookup Factory Methods</h2>
317 * The factory methods on a {@code Lookup} object correspond to all major
318 * use cases for methods, constructors, and fields.
319 * Each method handle created by a factory method is the functional
320 * equivalent of a particular <em>bytecode behavior</em>.
321 * (Bytecode behaviors are described in section {@jvms 5.4.3.5} of the Java Virtual Machine Specification.)
322 * Here is a summary of the correspondence between these factory methods and
323 * the behavior of the resulting method handles:
324 * <table class="striped">
325 * <caption style="display:none">lookup method behaviors</caption>
326 * <thead>
327 * <tr>
328 * <th scope="col"><a id="equiv"></a>lookup expression</th>
329 * <th scope="col">member</th>
330 * <th scope="col">bytecode behavior</th>
331 * </tr>
332 * </thead>
333 * <tbody>
334 * <tr>
335 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}</th>
336 * <td>{@code FT f;}</td><td>{@code (T) this.f;}</td>
337 * </tr>
338 * <tr>
339 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}</th>
340 * <td>{@code static}<br>{@code FT f;}</td><td>{@code (FT) C.f;}</td>
341 * </tr>
485 * under which the lookup class could have compiled, verified, and resolved a call to {@code M}.
486 * Where the JVM would raise exceptions like {@code NoSuchMethodError},
487 * a method handle lookup will generally raise a corresponding
488 * checked exception, such as {@code NoSuchMethodException}.
489 * And the effect of invoking the method handle resulting from the lookup
490 * is <a href="MethodHandles.Lookup.html#equiv">exactly equivalent</a>
491 * to executing the compiled, verified, and resolved call to {@code M}.
492 * The same point is true of fields and constructors.
493 * <p style="font-size:smaller;">
494 * <em>Discussion:</em>
495 * Access checks only apply to named and reflected methods,
496 * constructors, and fields.
497 * Other method handle creation methods, such as
498 * {@link MethodHandle#asType MethodHandle.asType},
499 * do not require any access checks, and are used
500 * independently of any {@code Lookup} object.
501 * <p>
502 * If the desired member is {@code protected}, the usual JVM rules apply,
503 * including the requirement that the lookup class must either be in the
504 * same package as the desired member, or must inherit that member.
505 * (See the Java Virtual Machine Specification, sections {@jvms 4.9.2}, {@jvms 5.4.3.5}, and {@jvms 6.4}.)
506 * In addition, if the desired member is a non-static field or method
507 * in a different package, the resulting method handle may only be applied
508 * to objects of the lookup class or one of its subclasses.
509 * This requirement is enforced by narrowing the type of the leading
510 * {@code this} parameter from {@code C}
511 * (which will necessarily be a superclass of the lookup class)
512 * to the lookup class itself.
513 * <p>
514 * The JVM imposes a similar requirement on {@code invokespecial} instruction,
515 * that the receiver argument must match both the resolved method <em>and</em>
516 * the current class. Again, this requirement is enforced by narrowing the
517 * type of the leading parameter to the resulting method handle.
518 * (See the Java Virtual Machine Specification, section {@jmvs 4.10.1.9}.)
519 * <p>
520 * The JVM represents constructors and static initializer blocks as internal methods
521 * with special names ({@code "<init>"} and {@code "<clinit>"}).
522 * The internal syntax of invocation instructions allows them to refer to such internal
523 * methods as if they were normal methods, but the JVM bytecode verifier rejects them.
524 * A lookup of such an internal method will produce a {@code NoSuchMethodException}.
525 * <p>
526 * If the relationship between nested types is expressed directly through the
527 * {@code NestHost} and {@code NestMembers} attributes
528 * (see the Java Virtual Machine Specification, sections {@jvms 4.7.28} and {@jvms 4.7.29}),
529 * then the associated {@code Lookup} object provides direct access to
530 * the lookup class and all of its nestmates
531 * (see {@link java.lang.Class#getNestHost Class.getNestHost}).
532 * Otherwise, access between nested classes is obtained by the Java compiler creating
533 * a wrapper method to access a private method of another class in the same nest.
534 * For example, a nested class {@code C.D}
535 * can access private members within other related classes such as
536 * {@code C}, {@code C.D.E}, or {@code C.B},
537 * but the Java compiler may need to generate wrapper methods in
538 * those related classes. In such cases, a {@code Lookup} object on
539 * {@code C.E} would be unable to access those private members.
540 * A workaround for this limitation is the {@link Lookup#in Lookup.in} method,
541 * which can transform a lookup on {@code C.E} into one on any of those other
542 * classes, without special elevation of privilege.
543 * <p>
544 * The accesses permitted to a given lookup object may be limited,
545 * according to its set of {@link #lookupModes lookupModes},
546 * to a subset of members normally accessible to the lookup class.
547 * For example, the {@link MethodHandles#publicLookup publicLookup}
548 * method produces a lookup object which is only allowed to access
|