248 * The caller class against which those restrictions are enforced
249 * is known as the {@linkplain #lookupClass lookup class}.
250 * <p>
251 * A lookup class which needs to create method handles will call
252 * {@link MethodHandles#lookup MethodHandles.lookup} to create a factory for itself.
253 * When the {@code Lookup} factory object is created, the identity of the lookup class is
254 * determined, and securely stored in the {@code Lookup} object.
255 * The lookup class (or its delegates) may then use factory methods
256 * on the {@code Lookup} object to create method handles for access-checked members.
257 * This includes all methods, constructors, and fields which are allowed to the lookup class,
258 * even private ones.
259 *
260 * <h1><a id="lookups"></a>Lookup Factory Methods</h1>
261 * The factory methods on a {@code Lookup} object correspond to all major
262 * use cases for methods, constructors, and fields.
263 * Each method handle created by a factory method is the functional
264 * equivalent of a particular <em>bytecode behavior</em>.
265 * (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.)
266 * Here is a summary of the correspondence between these factory methods and
267 * the behavior of the resulting method handles:
268 * <table border=1 cellpadding=5 summary="lookup method behaviors">
269 * <tr>
270 * <th><a id="equiv"></a>lookup expression</th>
271 * <th>member</th>
272 * <th>bytecode behavior</th>
273 * </tr>
274 * <tr>
275 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}</td>
276 * <td>{@code FT f;}</td><td>{@code (T) this.f;}</td>
277 * </tr>
278 * <tr>
279 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}</td>
280 * <td>{@code static}<br>{@code FT f;}</td><td>{@code (T) C.f;}</td>
281 * </tr>
282 * <tr>
283 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findSetter lookup.findSetter(C.class,"f",FT.class)}</td>
284 * <td>{@code FT f;}</td><td>{@code this.f = x;}</td>
285 * </tr>
286 * <tr>
287 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStaticSetter lookup.findStaticSetter(C.class,"f",FT.class)}</td>
288 * <td>{@code static}<br>{@code FT f;}</td><td>{@code C.f = arg;}</td>
289 * </tr>
290 * <tr>
291 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findVirtual lookup.findVirtual(C.class,"m",MT)}</td>
292 * <td>{@code T m(A*);}</td><td>{@code (T) this.m(arg*);}</td>
293 * </tr>
310 * <tr>
311 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectSetter lookup.unreflectSetter(aField)}</td>
312 * <td>({@code static})?<br>{@code FT f;}</td><td>{@code aField.set(thisOrNull, arg);}</td>
313 * </tr>
314 * <tr>
315 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
316 * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
317 * </tr>
318 * <tr>
319 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectConstructor lookup.unreflectConstructor(aConstructor)}</td>
320 * <td>{@code C(A*);}</td><td>{@code (C) aConstructor.newInstance(arg*);}</td>
321 * </tr>
322 * <tr>
323 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
324 * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
325 * </tr>
326 * <tr>
327 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findClass lookup.findClass("C")}</td>
328 * <td>{@code class C { ... }}</td><td>{@code C.class;}</td>
329 * </tr>
330 * </table>
331 *
332 * Here, the type {@code C} is the class or interface being searched for a member,
333 * documented as a parameter named {@code refc} in the lookup methods.
334 * The method type {@code MT} is composed from the return type {@code T}
335 * and the sequence of argument types {@code A*}.
336 * The constructor also has a sequence of argument types {@code A*} and
337 * is deemed to return the newly-created object of type {@code C}.
338 * Both {@code MT} and the field type {@code FT} are documented as a parameter named {@code type}.
339 * The formal parameter {@code this} stands for the self-reference of type {@code C};
340 * if it is present, it is always the leading argument to the method handle invocation.
341 * (In the case of some {@code protected} members, {@code this} may be
342 * restricted in type to the lookup class; see below.)
343 * The name {@code arg} stands for all the other method handle arguments.
344 * In the code examples for the Core Reflection API, the name {@code thisOrNull}
345 * stands for a null reference if the accessed method or field is static,
346 * and {@code this} otherwise.
347 * The names {@code aMethod}, {@code aField}, and {@code aConstructor} stand
348 * for reflective objects corresponding to the given members.
349 * <p>
|
248 * The caller class against which those restrictions are enforced
249 * is known as the {@linkplain #lookupClass lookup class}.
250 * <p>
251 * A lookup class which needs to create method handles will call
252 * {@link MethodHandles#lookup MethodHandles.lookup} to create a factory for itself.
253 * When the {@code Lookup} factory object is created, the identity of the lookup class is
254 * determined, and securely stored in the {@code Lookup} object.
255 * The lookup class (or its delegates) may then use factory methods
256 * on the {@code Lookup} object to create method handles for access-checked members.
257 * This includes all methods, constructors, and fields which are allowed to the lookup class,
258 * even private ones.
259 *
260 * <h1><a id="lookups"></a>Lookup Factory Methods</h1>
261 * The factory methods on a {@code Lookup} object correspond to all major
262 * use cases for methods, constructors, and fields.
263 * Each method handle created by a factory method is the functional
264 * equivalent of a particular <em>bytecode behavior</em>.
265 * (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.)
266 * Here is a summary of the correspondence between these factory methods and
267 * the behavior of the resulting method handles:
268 * <table class="altrows">
269 * <caption style="display:none">lookup method behaviors</caption>
270 * <thead>
271 * <tr>
272 * <th><a id="equiv"></a>lookup expression</th>
273 * <th>member</th>
274 * <th>bytecode behavior</th>
275 * </tr>
276 * </thead>
277 * <tbody>
278 * <tr>
279 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}</td>
280 * <td>{@code FT f;}</td><td>{@code (T) this.f;}</td>
281 * </tr>
282 * <tr>
283 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}</td>
284 * <td>{@code static}<br>{@code FT f;}</td><td>{@code (T) C.f;}</td>
285 * </tr>
286 * <tr>
287 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findSetter lookup.findSetter(C.class,"f",FT.class)}</td>
288 * <td>{@code FT f;}</td><td>{@code this.f = x;}</td>
289 * </tr>
290 * <tr>
291 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStaticSetter lookup.findStaticSetter(C.class,"f",FT.class)}</td>
292 * <td>{@code static}<br>{@code FT f;}</td><td>{@code C.f = arg;}</td>
293 * </tr>
294 * <tr>
295 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findVirtual lookup.findVirtual(C.class,"m",MT)}</td>
296 * <td>{@code T m(A*);}</td><td>{@code (T) this.m(arg*);}</td>
297 * </tr>
314 * <tr>
315 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectSetter lookup.unreflectSetter(aField)}</td>
316 * <td>({@code static})?<br>{@code FT f;}</td><td>{@code aField.set(thisOrNull, arg);}</td>
317 * </tr>
318 * <tr>
319 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
320 * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
321 * </tr>
322 * <tr>
323 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectConstructor lookup.unreflectConstructor(aConstructor)}</td>
324 * <td>{@code C(A*);}</td><td>{@code (C) aConstructor.newInstance(arg*);}</td>
325 * </tr>
326 * <tr>
327 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
328 * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
329 * </tr>
330 * <tr>
331 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findClass lookup.findClass("C")}</td>
332 * <td>{@code class C { ... }}</td><td>{@code C.class;}</td>
333 * </tr>
334 * </tbody>
335 * </table>
336 *
337 * Here, the type {@code C} is the class or interface being searched for a member,
338 * documented as a parameter named {@code refc} in the lookup methods.
339 * The method type {@code MT} is composed from the return type {@code T}
340 * and the sequence of argument types {@code A*}.
341 * The constructor also has a sequence of argument types {@code A*} and
342 * is deemed to return the newly-created object of type {@code C}.
343 * Both {@code MT} and the field type {@code FT} are documented as a parameter named {@code type}.
344 * The formal parameter {@code this} stands for the self-reference of type {@code C};
345 * if it is present, it is always the leading argument to the method handle invocation.
346 * (In the case of some {@code protected} members, {@code this} may be
347 * restricted in type to the lookup class; see below.)
348 * The name {@code arg} stands for all the other method handle arguments.
349 * In the code examples for the Core Reflection API, the name {@code thisOrNull}
350 * stands for a null reference if the accessed method or field is static,
351 * and {@code this} otherwise.
352 * The names {@code aMethod}, {@code aField}, and {@code aConstructor} stand
353 * for reflective objects corresponding to the given members.
354 * <p>
|