265 * {@link MethodHandles#lookup MethodHandles.lookup} to create a factory for itself.
266 * When the {@code Lookup} factory object is created, the identity of the lookup class is
267 * determined, and securely stored in the {@code Lookup} object.
268 * The lookup class (or its delegates) may then use factory methods
269 * on the {@code Lookup} object to create method handles for access-checked members.
270 * This includes all methods, constructors, and fields which are allowed to the lookup class,
271 * even private ones.
272 *
273 * <h1><a id="lookups"></a>Lookup Factory Methods</h1>
274 * The factory methods on a {@code Lookup} object correspond to all major
275 * use cases for methods, constructors, and fields.
276 * Each method handle created by a factory method is the functional
277 * equivalent of a particular <em>bytecode behavior</em>.
278 * (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.)
279 * Here is a summary of the correspondence between these factory methods and
280 * the behavior of the resulting method handles:
281 * <table class="striped">
282 * <caption style="display:none">lookup method behaviors</caption>
283 * <thead>
284 * <tr>
285 * <th><a id="equiv"></a>lookup expression</th>
286 * <th>member</th>
287 * <th>bytecode behavior</th>
288 * </tr>
289 * </thead>
290 * <tbody>
291 * <tr>
292 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}</td>
293 * <td>{@code FT f;}</td><td>{@code (T) this.f;}</td>
294 * </tr>
295 * <tr>
296 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}</td>
297 * <td>{@code static}<br>{@code FT f;}</td><td>{@code (T) C.f;}</td>
298 * </tr>
299 * <tr>
300 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findSetter lookup.findSetter(C.class,"f",FT.class)}</td>
301 * <td>{@code FT f;}</td><td>{@code this.f = x;}</td>
302 * </tr>
303 * <tr>
304 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStaticSetter lookup.findStaticSetter(C.class,"f",FT.class)}</td>
305 * <td>{@code static}<br>{@code FT f;}</td><td>{@code C.f = arg;}</td>
306 * </tr>
307 * <tr>
308 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findVirtual lookup.findVirtual(C.class,"m",MT)}</td>
309 * <td>{@code T m(A*);}</td><td>{@code (T) this.m(arg*);}</td>
310 * </tr>
311 * <tr>
312 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStatic lookup.findStatic(C.class,"m",MT)}</td>
313 * <td>{@code static}<br>{@code T m(A*);}</td><td>{@code (T) C.m(arg*);}</td>
314 * </tr>
315 * <tr>
316 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findSpecial lookup.findSpecial(C.class,"m",MT,this.class)}</td>
317 * <td>{@code T m(A*);}</td><td>{@code (T) super.m(arg*);}</td>
318 * </tr>
319 * <tr>
320 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findConstructor lookup.findConstructor(C.class,MT)}</td>
321 * <td>{@code C(A*);}</td><td>{@code new C(arg*);}</td>
322 * </tr>
323 * <tr>
324 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectGetter lookup.unreflectGetter(aField)}</td>
325 * <td>({@code static})?<br>{@code FT f;}</td><td>{@code (FT) aField.get(thisOrNull);}</td>
326 * </tr>
327 * <tr>
328 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectSetter lookup.unreflectSetter(aField)}</td>
329 * <td>({@code static})?<br>{@code FT f;}</td><td>{@code aField.set(thisOrNull, arg);}</td>
330 * </tr>
331 * <tr>
332 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
333 * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
334 * </tr>
335 * <tr>
336 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectConstructor lookup.unreflectConstructor(aConstructor)}</td>
337 * <td>{@code C(A*);}</td><td>{@code (C) aConstructor.newInstance(arg*);}</td>
338 * </tr>
339 * <tr>
340 * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
341 * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
342 * </tr>
343 * <tr>
344 * <td>{@link java.lang.invoke.MethodHandles.Lookup#findClass lookup.findClass("C")}</td>
345 * <td>{@code class C { ... }}</td><td>{@code C.class;}</td>
346 * </tr>
347 * </tbody>
348 * </table>
349 *
350 * Here, the type {@code C} is the class or interface being searched for a member,
351 * documented as a parameter named {@code refc} in the lookup methods.
352 * The method type {@code MT} is composed from the return type {@code T}
353 * and the sequence of argument types {@code A*}.
354 * The constructor also has a sequence of argument types {@code A*} and
355 * is deemed to return the newly-created object of type {@code C}.
356 * Both {@code MT} and the field type {@code FT} are documented as a parameter named {@code type}.
357 * The formal parameter {@code this} stands for the self-reference of type {@code C};
358 * if it is present, it is always the leading argument to the method handle invocation.
359 * (In the case of some {@code protected} members, {@code this} may be
360 * restricted in type to the lookup class; see below.)
361 * The name {@code arg} stands for all the other method handle arguments.
362 * In the code examples for the Core Reflection API, the name {@code thisOrNull}
363 * stands for a null reference if the accessed method or field is static,
364 * and {@code this} otherwise.
|
265 * {@link MethodHandles#lookup MethodHandles.lookup} to create a factory for itself.
266 * When the {@code Lookup} factory object is created, the identity of the lookup class is
267 * determined, and securely stored in the {@code Lookup} object.
268 * The lookup class (or its delegates) may then use factory methods
269 * on the {@code Lookup} object to create method handles for access-checked members.
270 * This includes all methods, constructors, and fields which are allowed to the lookup class,
271 * even private ones.
272 *
273 * <h1><a id="lookups"></a>Lookup Factory Methods</h1>
274 * The factory methods on a {@code Lookup} object correspond to all major
275 * use cases for methods, constructors, and fields.
276 * Each method handle created by a factory method is the functional
277 * equivalent of a particular <em>bytecode behavior</em>.
278 * (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.)
279 * Here is a summary of the correspondence between these factory methods and
280 * the behavior of the resulting method handles:
281 * <table class="striped">
282 * <caption style="display:none">lookup method behaviors</caption>
283 * <thead>
284 * <tr>
285 * <th scope="col"><a id="equiv"></a>lookup expression</th>
286 * <th scope="col">member</th>
287 * <th scope="col">bytecode behavior</th>
288 * </tr>
289 * </thead>
290 * <tbody>
291 * <tr>
292 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}</th>
293 * <td>{@code FT f;}</td><td>{@code (T) this.f;}</td>
294 * </tr>
295 * <tr>
296 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}</th>
297 * <td>{@code static}<br>{@code FT f;}</td><td>{@code (T) C.f;}</td>
298 * </tr>
299 * <tr>
300 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findSetter lookup.findSetter(C.class,"f",FT.class)}</th>
301 * <td>{@code FT f;}</td><td>{@code this.f = x;}</td>
302 * </tr>
303 * <tr>
304 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findStaticSetter lookup.findStaticSetter(C.class,"f",FT.class)}</th>
305 * <td>{@code static}<br>{@code FT f;}</td><td>{@code C.f = arg;}</td>
306 * </tr>
307 * <tr>
308 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findVirtual lookup.findVirtual(C.class,"m",MT)}</th>
309 * <td>{@code T m(A*);}</td><td>{@code (T) this.m(arg*);}</td>
310 * </tr>
311 * <tr>
312 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findStatic lookup.findStatic(C.class,"m",MT)}</th>
313 * <td>{@code static}<br>{@code T m(A*);}</td><td>{@code (T) C.m(arg*);}</td>
314 * </tr>
315 * <tr>
316 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findSpecial lookup.findSpecial(C.class,"m",MT,this.class)}</th>
317 * <td>{@code T m(A*);}</td><td>{@code (T) super.m(arg*);}</td>
318 * </tr>
319 * <tr>
320 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findConstructor lookup.findConstructor(C.class,MT)}</th>
321 * <td>{@code C(A*);}</td><td>{@code new C(arg*);}</td>
322 * </tr>
323 * <tr>
324 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#unreflectGetter lookup.unreflectGetter(aField)}</th>
325 * <td>({@code static})?<br>{@code FT f;}</td><td>{@code (FT) aField.get(thisOrNull);}</td>
326 * </tr>
327 * <tr>
328 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#unreflectSetter lookup.unreflectSetter(aField)}</th>
329 * <td>({@code static})?<br>{@code FT f;}</td><td>{@code aField.set(thisOrNull, arg);}</td>
330 * </tr>
331 * <tr>
332 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</th>
333 * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
334 * </tr>
335 * <tr>
336 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#unreflectConstructor lookup.unreflectConstructor(aConstructor)}</th>
337 * <td>{@code C(A*);}</td><td>{@code (C) aConstructor.newInstance(arg*);}</td>
338 * </tr>
339 * <tr>
340 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</th>
341 * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
342 * </tr>
343 * <tr>
344 * <th scope="row">{@link java.lang.invoke.MethodHandles.Lookup#findClass lookup.findClass("C")}</th>
345 * <td>{@code class C { ... }}</td><td>{@code C.class;}</td>
346 * </tr>
347 * </tbody>
348 * </table>
349 *
350 * Here, the type {@code C} is the class or interface being searched for a member,
351 * documented as a parameter named {@code refc} in the lookup methods.
352 * The method type {@code MT} is composed from the return type {@code T}
353 * and the sequence of argument types {@code A*}.
354 * The constructor also has a sequence of argument types {@code A*} and
355 * is deemed to return the newly-created object of type {@code C}.
356 * Both {@code MT} and the field type {@code FT} are documented as a parameter named {@code type}.
357 * The formal parameter {@code this} stands for the self-reference of type {@code C};
358 * if it is present, it is always the leading argument to the method handle invocation.
359 * (In the case of some {@code protected} members, {@code this} may be
360 * restricted in type to the lookup class; see below.)
361 * The name {@code arg} stands for all the other method handle arguments.
362 * In the code examples for the Core Reflection API, the name {@code thisOrNull}
363 * stands for a null reference if the accessed method or field is static,
364 * and {@code this} otherwise.
|