jdk-sandbox: comparison jdk/src/share/classes/java/lang/invoke/MethodHandles.java

equal deleted inserted replaced

-:da86f7904e6d
+:cc85c8626435
 * method handles. They fall into several categories:
 * <ul>
 * <li>Lookup methods which help create method handles for methods and fields.
 * <li>Combinator methods, which combine or transform pre-existing method handles into new ones.
 * <li>Other factory methods to create method handles that emulate other common JVM operations or control flow patterns.
-* <li>Wrapper methods which can convert between method handles and interface types.
 * </ul>
 * <p>
 * @author John Rose, JSR 292 EG
 * @since 1.7
 */
 // See IMPL_LOOKUP below.
 //// Method handle creation from ordinary methods.
 /**
-* Returns a {@link Lookup lookup object} on the caller,
+* Returns a {@link Lookup lookup object} with
-* which has the capability to access any method handle that the caller has access to,
+* full capabilities to emulate all supported bytecode behaviors of the caller.
-* including direct method handles to private fields and methods.
+* These capabilities include <a href="MethodHandles.Lookup.html#privacc">private access</a> to the caller.
+* Factory methods on the lookup object can create
+* <a href="MethodHandleInfo.html#directmh">direct method handles</a>
+* for any member that the caller has access to via bytecodes,
+* including protected and private fields and methods.
 * This lookup object is a <em>capability</em> which may be delegated to trusted agents.
 * Do not store it in place where untrusted code can access it.
-* @return a lookup object for the caller of this method
+* <p>
+* This method is caller sensitive, which means that it may return different
+* values to different callers.
+* <p>
+* For any given caller class {@code C}, the lookup object returned by this call
+* has equivalent capabilities to any lookup object
+* supplied by the JVM to the bootstrap method of an
+* <a href="package-summary.html#indyinsn">invokedynamic instruction</a>
+* executing in the same caller class {@code C}.
+* @return a lookup object for the caller of this method, with private access
 */
 @CallerSensitive
 public static Lookup lookup() {
 return new Lookup(Reflection.getCallerClass());
 }
 * It can only be used to create method handles to
 * publicly accessible fields and methods.
 * <p>
 * As a matter of pure convention, the {@linkplain Lookup#lookupClass lookup class}
 * of this lookup object will be {@link java.lang.Object}.
-* <p>
+*
+* <p style="font-size:smaller;">
+* <em>Discussion:</em>
 * The lookup class can be changed to any other class {@code C} using an expression of the form
-* {@linkplain Lookup#in <code>publicLookup().in(C.class)</code>}.
+* {@link Lookup#in publicLookup().in(C.class)}.
 * Since all classes have equal access to public names,
 * such a change would confer no new access rights.
 * A public lookup object is always subject to
 * <a href="MethodHandles.Lookup.html#secmgr">security manager checks</a>.
 * Also, it cannot access
 public static Lookup publicLookup() {
 return Lookup.PUBLIC_LOOKUP;
 }
 /**
-* Performs an unchecked "crack" of a direct method handle.
+* Performs an unchecked "crack" of a
+* <a href="MethodHandleInfo.html#directmh">direct method handle</a>.
 * The result is as if the user had obtained a lookup object capable enough
 * to crack the target method handle, called
 * {@link java.lang.invoke.MethodHandles.Lookup#revealDirect Lookup.revealDirect}
 * on the target to obtain its symbolic reference, and then called
 * {@link java.lang.invoke.MethodHandleInfo#reflectAs MethodHandleInfo.reflectAs}
 * even private ones.
 *
 * <h1><a name="lookups"></a>Lookup Factory Methods</h1>
 * The factory methods on a {@code Lookup} object correspond to all major
 * use cases for methods, constructors, and fields.
+* Each method handle created by a factory method is the functional
+* equivalent of a particular <em>bytecode behavior</em>.
+* (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.)
 * Here is a summary of the correspondence between these factory methods and
 * the behavior the resulting method handles:
 * <table border=1 cellpadding=5 summary="lookup method behaviors">
-* <tr><th>lookup expression</th><th>member</th><th>behavior</th></tr>
+* <tr>
+*     <th><a name="equiv"></a>lookup expression</th>
+*     <th>member</th>
+*     <th>bytecode behavior</th>
+* </tr>
 * <tr>
 *     <td>{@link java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}</td>
 *     <td>{@code FT f;}</td><td>{@code (T) this.f;}</td>
 * </tr>
 * <tr>
 * for reflective objects corresponding to the given members.
 * <p>
 * In cases where the given member is of variable arity (i.e., a method or constructor)
 * the returned method handle will also be of {@linkplain MethodHandle#asVarargsCollector variable arity}.
 * In all other cases, the returned method handle will be of fixed arity.
-* <p>
+* <p style="font-size:smaller;">
+* <em>Discussion:</em>
 * The equivalence between looked-up method handles and underlying
-* class members can break down in a few ways:
+* class members and bytecode behaviors
-* <ul>
+* can break down in a few ways:
+* <ul style="font-size:smaller;">
 * <li>If {@code C} is not symbolically accessible from the lookup class's loader,
 * the lookup can still succeed, even when there is no equivalent
 * Java expression or bytecoded constant.
 * <li>Likewise, if {@code T} or {@code MT}
 * is not symbolically accessible from the lookup class's loader,
 * original lookup class.
 * <p>
 * A lookup can fail, because
 * the containing class is not accessible to the lookup class, or
 * because the desired class member is missing, or because the
-* desired class member is not accessible to the lookup class.
+* desired class member is not accessible to the lookup class, or
+* because the lookup object is not trusted enough to access the member.
 * In any of these cases, a {@code ReflectiveOperationException} will be
 * thrown from the attempted lookup.  The exact class will be one of
 * the following:
 * <ul>
 * <li>NoSuchMethodException &mdash; if a method is requested but does not exist
 * <li>NoSuchFieldException &mdash; if a field is requested but does not exist
 * <li>IllegalAccessException &mdash; if the member exists but an access check fails
 * </ul>
 * <p>
 * In general, the conditions under which a method handle may be
-* looked up for a method {@code M} are exactly equivalent to the conditions
+* looked up for a method {@code M} are no more restrictive than the conditions
-* under which the lookup class could have compiled and resolved a call to {@code M}.
+* under which the lookup class could have compiled, verified, and resolved a call to {@code M}.
 * Where the JVM would raise exceptions like {@code NoSuchMethodError},
 * a method handle lookup will generally raise a corresponding
 * checked exception, such as {@code NoSuchMethodException}.
 * And the effect of invoking the method handle resulting from the lookup
-* is exactly equivalent to executing the compiled and resolved call to {@code M}.
+* is <a href="MethodHandles.Lookup.html#equiv">exactly equivalent</a>
+* to executing the compiled, verified, and resolved call to {@code M}.
 * The same point is true of fields and constructors.
+* <p style="font-size:smaller;">
+* <em>Discussion:</em>
+* Access checks only apply to named and reflected methods,
+* constructors, and fields.
+* Other method handle creation methods, such as
+* {@link MethodHandle#asType MethodHandle.asType},
+* do not require any access checks, and are used
+* independently of any {@code Lookup} object.
 * <p>
 * If the desired member is {@code protected}, the usual JVM rules apply,
 * including the requirement that the lookup class must be either be in the
 * same package as the desired member, or must inherit that member.
 * (See the Java Virtual Machine Specification, sections 4.9.2, 5.4.3.5, and 6.4.)
 * to objects of the lookup class or one of its subclasses.
 * This requirement is enforced by narrowing the type of the leading
 * {@code this} parameter from {@code C}
 * (which will necessarily be a superclass of the lookup class)
 * to the lookup class itself.
+* <p>
+* The JVM imposes a similar requirement on {@code invokespecial} instruction,
+* that the receiver argument must match both the resolved method <em>and</em>
+* the current class.  Again, this requirement is enforced by narrowing the
+* type of the leading parameter to the resulting method handle.
+* (See the Java Virtual Machine Specification, section 4.10.1.9.)
 * <p>
 * The JVM represents constructors and static initializer blocks as internal methods
 * with special names ({@code "<init>"} and {@code "<clinit>"}).
 * The internal syntax of invocation instructions allows them to refer to such internal
 * methods as if they were normal methods, but the JVM bytecode verifier rejects them.
 * {@code C.E} would be unable to those private members.
 * A workaround for this limitation is the {@link Lookup#in Lookup.in} method,
 * which can transform a lookup on {@code C.E} into one on any of those other
 * classes, without special elevation of privilege.
 * <p>
+* The accesses permitted to a given lookup object may be limited,
+* according to its set of {@link #lookupModes lookupModes},
+* to a subset of members normally accessible to the lookup class.
+* For example, the {@link MethodHandles#publicLookup publicLookup}
+* method produces a lookup object which is only allowed to access
+* public members in public classes.
+* The caller sensitive method {@link MethodHandles#lookup lookup}
+* produces a lookup object with full capabilities relative to
+* its caller class, to emulate all supported bytecode behaviors.
+* Also, the {@link Lookup#in Lookup.in} method may produce a lookup object
+* with fewer access modes than the original lookup object.
+*
+* <p style="font-size:smaller;">
+* <a name="privacc"></a>
+* <em>Discussion of private access:</em>
+* We say that a lookup has <em>private access</em>
+* if its {@linkplain #lookupModes lookup modes}
+* include the possibility of accessing {@code private} members.
+* As documented in the relevant methods elsewhere,
+* only lookups with private access possess the following capabilities:
+* <ul style="font-size:smaller;">
+* <li>access private fields, methods, and constructors of the lookup class
+* <li>create method handles which invoke <a href="MethodHandles.Lookup.html#callsens">caller sensitive</a> methods,
+*     such as {@code Class.forName}
+* <li>create method handles which {@link Lookup#findSpecial emulate invokespecial} instructions
+* <li>avoid <a href="MethodHandles.Lookup.html#secmgr">package access checks</a>
+*     for classes accessible to the lookup class
+* <li>create {@link Lookup#in delegated lookup objects} which have private access to other classes
+*     within the same package member
+* </ul>
+* <p style="font-size:smaller;">
+* Each of these permissions is a consequence of the fact that a lookup object
+* with private access can be securely traced back to an originating class,
+* whose <a href="MethodHandles.Lookup.html#equiv">bytecode behaviors</a> and Java language access permissions
+* can be reliably determined and emulated by method handles.
+*
+* <h1><a name="secmgr"></a>Security manager interactions</h1>
 * Although bytecode instructions can only refer to classes in
 * a related class loader, this API can search for methods in any
 * class, as long as a reference to its {@code Class} object is
 * available.  Such cross-loader references are also possible with the
 * Core Reflection API, and are impossible to bytecode instructions
 * to allow applications to check such cross-loader references.
 * These checks apply to both the {@code MethodHandles.Lookup} API
 * and the Core Reflection API
 * (as found on {@link java.lang.Class Class}).
 * <p>
-* Access checks only apply to named and reflected methods,
-* constructors, and fields.
-* Other method handle creation methods, such as
-* {@link MethodHandle#asType MethodHandle.asType},
-* do not require any access checks, and are done
-* with static methods of {@link MethodHandles},
-* independently of any {@code Lookup} object.
-*
-* <h1>Security manager interactions</h1>
-* <a name="secmgr"></a>
 * If a security manager is present, member lookups are subject to
 * additional checks.
 * From one to three calls are made to the security manager.
 * Any of these calls can refuse access by throwing a
 * {@link java.lang.SecurityException SecurityException}.
 * {@code refc} as the containing class in which the member
 * is being sought, and {@code defc} as the class in which the
 * member is actually defined.
 * The value {@code lookc} is defined as <em>not present</em>
 * if the current lookup object does not have
-* {@linkplain java.lang.invoke.MethodHandles.Lookup#PRIVATE private access}.
+* <a href="MethodHandles.Lookup.html#privacc">private access</a>.
 * The calls are made according to the following rules:
 * <ul>
-* <li>If {@code lookc} is not present, or if its class loader is not
+* <li><b>Step 1:</b>
+*     If {@code lookc} is not present, or if its class loader is not
 *     the same as or an ancestor of the class loader of {@code refc},
 *     then {@link SecurityManager#checkPackageAccess
 *     smgr.checkPackageAccess(refcPkg)} is called,
 *     where {@code refcPkg} is the package of {@code refc}.
-* <li>If the retrieved member is not public and
+* <li><b>Step 2:</b>
+*     If the retrieved member is not public and
 *     {@code lookc} is not present, then
 *     {@link SecurityManager#checkPermission smgr.checkPermission}
 *     with {@code RuntimePermission("accessDeclaredMembers")} is called.
-* <li>If the retrieved member is not public,
+* <li><b>Step 3:</b>
+*     If the retrieved member is not public,
 *     and if {@code lookc} is not present,
 *     and if {@code defc} and {@code refc} are different,
 *     then {@link SecurityManager#checkPackageAccess
 *     smgr.checkPackageAccess(defcPkg)} is called,
 *     where {@code defcPkg} is the package of {@code defc}.
 * differently behaving method handles.
 * <p>
 * In cases where the lookup object is
 * {@link MethodHandles#publicLookup() publicLookup()},
 * or some other lookup object without
-* {@linkplain java.lang.invoke.MethodHandles.Lookup#PRIVATE private access},
+* <a href="MethodHandles.Lookup.html#privacc">private access</a>,
 * the lookup class is disregarded.
 * In such cases, no caller-sensitive method handle can be created,
 * access is forbidden, and the lookup fails with an
 * {@code IllegalAccessException}.
+* <p style="font-size:smaller;">
+* <em>Discussion:</em>
+* For example, the caller-sensitive method
+* {@link java.lang.Class#forName(String) Class.forName(x)}
+* can return varying classes or throw varying exceptions,
+* depending on the class loader of the class that calls it.
+* A public lookup of {@code Class.forName} will fail, because
+* there is no reasonable way to determine its bytecode behavior.
+* <p style="font-size:smaller;">
+* If an application caches method handles for broad sharing,
+* it should use {@code publicLookup()} to create them.
+* If there is a lookup of {@code Class.forName}, it will fail,
+* and the application must take appropriate action in that case.
+* It may be that a later lookup, perhaps during the invocation of a
+* bootstrap method, can incorporate the specific identity
+* of the caller, making the method accessible.
+* <p style="font-size:smaller;">
+* The function {@code MethodHandles.lookup} is caller sensitive
+* so that there can be a secure foundation for lookups.
+* Nearly all other methods in the JSR 292 API rely on lookup
+* objects to check access requests.
 */
 public static final
 class Lookup {
 /** The class on behalf of whom the lookup is being performed. */
 private final Class<?> lookupClass;
 * Produces a method handle for a static method.
 * The type of the method handle will be that of the method.
 * (Since static methods do not take receivers, there is no
 * additional receiver argument inserted into the method handle type,
 * as there would be with {@link #findVirtual findVirtual} or {@link #findSpecial findSpecial}.)
-* The method and all its argument types must be accessible to the lookup class.
+* The method and all its argument types must be accessible to the lookup object.
 * <p>
 * The returned method handle will have
 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
 * the method's variable arity modifier bit ({@code 0x0080}) is set.
 * <p>
 /**
 * Produces a method handle for a virtual method.
 * The type of the method handle will be that of the method,
 * with the receiver type (usually {@code refc}) prepended.
-* The method and all its argument types must be accessible to the lookup class.
+* The method and all its argument types must be accessible to the lookup object.
 * <p>
 * When called, the handle will treat the first argument as a receiver
 * and dispatch on the receiver's type to determine which method
 * implementation to enter.
 * (The dispatching action is identical with that performed by an
 * <p>
 * The returned method handle will have
 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
 * the method's variable arity modifier bit ({@code 0x0080}) is set.
 * <p>
-* Because of the general equivalence between {@code invokevirtual}
+* Because of the general <a href="MethodHandles.Lookup.html#equiv">equivalence</a> between {@code invokevirtual}
 * instructions and method handles produced by {@code findVirtual},
 * if the class is {@code MethodHandle} and the name string is
 * {@code invokeExact} or {@code invoke}, the resulting
 * method handle is equivalent to one produced by
 * {@link java.lang.invoke.MethodHandles#exactInvoker MethodHandles.exactInvoker} or
 /**
 * Produces a method handle which creates an object and initializes it, using
 * the constructor of the specified type.
 * The parameter types of the method handle will be those of the constructor,
 * while the return type will be a reference to the constructor's class.
-* The constructor and all its argument types must be accessible to the lookup class.
+* The constructor and all its argument types must be accessible to the lookup object.
 * <p>
-* <em>(Note:  The requested type must have a return type of {@code void}.
+* The requested type must have a return type of {@code void}.
-* This is consistent with the JVM's treatment of constructor type descriptors.)</em>
+* (This is consistent with the JVM's treatment of constructor type descriptors.)
 * <p>
 * The returned method handle will have
 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
 * the constructor's variable arity modifier bit ({@code 0x0080}) is set.
 * <p>
 MemberName ctor = resolveOrFail(REF_newInvokeSpecial, refc, name, type);
 return getDirectConstructor(refc, ctor);
 }
 /**
-* Produces an early-bound method handle for a virtual method,
+* Produces an early-bound method handle for a virtual method.
-* as if called from an {@code invokespecial}
+* It will bypass checks for overriding methods on the receiver,
-* instruction from {@code caller}.
+* <a href="MethodHandles.Lookup.html#equiv">as if called</a> from an {@code invokespecial}
+* instruction from within the explicitly specified {@code specialCaller}.
 * The type of the method handle will be that of the method,
-* with a suitably restricted receiver type (such as {@code caller}) prepended.
+* with a suitably restricted receiver type prepended.
+* (The receiver type will be {@code specialCaller} or a subtype.)
 * The method and all its argument types must be accessible
-* to the caller.
+* to the lookup object.
 * <p>
-* When called, the handle will treat the first argument as a receiver,
+* Before method resolution,
-* but will not dispatch on the receiver's type.
+* if the explicitly specified caller class is not identical with the
-* (This direct invocation action is identical with that performed by an
+* lookup class, or if this lookup object does not have
-* {@code invokespecial} instruction.)
+* <a href="MethodHandles.Lookup.html#privacc">private access</a>
-* <p>
-* If the explicitly specified caller class is not identical with the
-* lookup class, or if this lookup object does not have private access
 * privileges, the access fails.
 * <p>
 * The returned method handle will have
 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
 * the method's variable arity modifier bit ({@code 0x0080}) is set.
-* <p>
+* <p style="font-size:smaller;">
 * <em>(Note:  JVM internal methods named {@code "<init>"} are not visible to this API,
 * even though the {@code invokespecial} instruction can refer to them
 * in special circumstances.  Use {@link #findConstructor findConstructor}
 * to access instance initialization methods in a safe manner.)</em>
 * <p><b>Example:</b>
 /**
 * Produces an early-bound method handle for a non-static method.
 * The receiver must have a supertype {@code defc} in which a method
 * of the given name and type is accessible to the lookup class.
-* The method and all its argument types must be accessible to the lookup class.
+* The method and all its argument types must be accessible to the lookup object.
 * The type of the method handle will be that of the method,
 * without any insertion of an additional receiver parameter.
 * The given receiver will be bound into the method handle,
 * so that every call to the method handle will invoke the
 * requested method on the given receiver.
 * <em>and</em> the trailing array argument is not the only argument.
 * (If the trailing array argument is the only argument,
 * the given receiver value will be bound to it.)
 * <p>
 * This is equivalent to the following code:
-* <blockquote><pre>
+* <blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
-MethodHandle mh0 = lookup().{@link #findVirtual findVirtual}(defc, name, type);
+MethodHandle mh0 = lookup().findVirtual(defc, name, type);
-MethodHandle mh1 = mh0.{@link MethodHandle#bindTo bindTo}(receiver);
+MethodHandle mh1 = mh0.bindTo(receiver);
 MethodType mt1 = mh1.type();
 if (mh0.isVarargsCollector())
 mh1 = mh1.asVarargsCollector(mt1.parameterType(mt1.parameterCount()-1));
 return mh1;
-* </pre></blockquote>
+* }</pre></blockquote>
 * where {@code defc} is either {@code receiver.getClass()} or a super
 * type of that class, in which the requested method is accessible
 * to the lookup class.
 * (Note that {@code bindTo} does not preserve variable arity.)
 * @param receiver the object from which the method is accessed
 *                                or if the method's variable arity modifier bit
 *                                is set and {@code asVarargsCollector} fails
 * @exception SecurityException if a security manager is present and it
 *                              <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
 * @throws NullPointerException if any argument is null
+* @see MethodHandle#bindTo
+* @see #findVirtual
 */
 public MethodHandle bind(Object receiver, String name, MethodType type) throws NoSuchMethodException, IllegalAccessException {
 Class<? extends Object> refc = receiver.getClass(); // may get NPE
 MemberName method = resolveOrFail(REF_invokeSpecial, refc, name, type);
 MethodHandle mh = getDirectMethodNoRestrict(REF_invokeSpecial, refc, method, findBoundCallerClass(method));
 return mh.bindReceiver(receiver).setVarargs(method);
 }
 /**
-* Makes a direct method handle to <i>m</i>, if the lookup class has permission.
+* Makes a <a href="MethodHandleInfo.html#directmh">direct method handle</a>
+* to <i>m</i>, if the lookup class has permission.
 * If <i>m</i> is non-static, the receiver argument is treated as an initial argument.
 * If <i>m</i> is virtual, overriding is respected on every call.
 * Unlike the Core Reflection API, exceptions are <em>not</em> wrapped.
 * The type of the method handle will be that of the method,
 * with the receiver type prepended (but only if it is non-static).
 }
 /**
 * Produces a method handle for a reflected method.
 * It will bypass checks for overriding methods on the receiver,
-* as if by a {@code invokespecial} instruction from within the {@code specialCaller}.
+* <a href="MethodHandles.Lookup.html#equiv">as if called</a> from an {@code invokespecial}
+* instruction from within the explicitly specified {@code specialCaller}.
 * The type of the method handle will be that of the method,
-* with the special caller type prepended (and <em>not</em> the receiver of the method).
+* with a suitably restricted receiver type prepended.
+* (The receiver type will be {@code specialCaller} or a subtype.)
 * If the method's {@code accessible} flag is not set,
 * access checking is performed immediately on behalf of the lookup class,
 * as if {@code invokespecial} instruction were being linked.
+* <p>
+* Before method resolution,
+* if the explicitly specified caller class is not identical with the
+* lookup class, or if this lookup object does not have
+* <a href="MethodHandles.Lookup.html#privacc">private access</a>
+* privileges, the access fails.
 * <p>
 * The returned method handle will have
 * {@linkplain MethodHandle#asVarargsCollector variable arity} if and only if
 * the method's variable arity modifier bit ({@code 0x0080}) is set.
 * @param m the reflected method
 * @throws IllegalAccessException if access checking fails
 *                                or if the method's variable arity modifier bit
 *                                is set and {@code asVarargsCollector} fails
 * @throws NullPointerException if the argument is null
 */
-@SuppressWarnings("rawtypes")  // Will be Constructor<?> after JSR 292 MR
+public MethodHandle unreflectConstructor(Constructor<?> c) throws IllegalAccessException {
-public MethodHandle unreflectConstructor(Constructor c) throws IllegalAccessException {
 MemberName ctor = new MemberName(c);
 assert(ctor.isConstructor());
 Lookup lookup = c.isAccessible() ? IMPL_LOOKUP : this;
 return lookup.getDirectConstructorNoSecurityManager(ctor.getDeclaringClass(), ctor);
 }
 public MethodHandle unreflectSetter(Field f) throws IllegalAccessException {
 return unreflectField(f, true);
 }
 /**
-* Cracks a direct method handle created by this lookup object or a similar one.
+* Cracks a <a href="MethodHandleInfo.html#directmh">direct method handle</a>
+* created by this lookup object or a similar one.
 * Security and access checks are performed to ensure that this lookup object
 * is capable of reproducing the target method handle.
 * This means that the cracking may fail if target is a direct method handle
 * but was created by an unrelated lookup object.
 * This can happen if the method handle is <a href="MethodHandles.Lookup.html#callsens">caller sensitive</a>
 * @return a symbolic reference which can be used to reconstruct this method handle from this lookup object
 * @exception SecurityException if a security manager is present and it
 *                              <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
 * @throws IllegalArgumentException if the target is not a direct method handle or if access checking fails
 * @exception NullPointerException if the target is {@code null}
+* @see MethodHandleInfo
 * @since 1.8
 */
 public MethodHandleInfo revealDirect(MethodHandle target) {
 MemberName member = target.internalMemberName();
 if (member == null || (!member.isResolved() && !member.isMethodHandleInvoke()))
 Class<?> caller = lookupClassOrNull();
 if (caller != null && !VerifyAccess.isClassAccessible(refc, caller, allowedModes))
 throw new MemberName(refc).makeAccessException("symbolic reference class is not public", this);
 }
-/** Check name for an illegal leading "<" character. */
+/** Check name for an illegal leading "&lt;" character. */
 void checkMethodName(byte refKind, String name) throws NoSuchMethodException {
 if (name.startsWith("<") && refKind != REF_newInvokeSpecial)
 throw new NoSuchMethodException("illegal method name: "+name);
 }
 * If, when the invoker is called, the supplied array argument does
 * not have the correct number of elements, the invoker will throw
 * an {@link IllegalArgumentException} instead of invoking the target.
 * <p>
 * This method is equivalent to the following code (though it may be more efficient):
-* <p><blockquote><pre>
+* <blockquote><pre>{@code
 MethodHandle invoker = MethodHandles.invoker(type);
 int spreadArgCount = type.parameterCount() - leadingArgCount;
 invoker = invoker.asSpreader(Object[].class, spreadArgCount);
 return invoker;
-* </pre></blockquote>
+* }</pre></blockquote>
-* <p>
 * This method throws no reflective or security exceptions.
 * @param type the desired target type
 * @param leadingArgCount number of fixed arguments, to be passed unchanged to the target
 * @return a method handle suitable for invoking any method handle of the given type
 * @throws NullPointerException if {@code type} is null
 * The resulting invoker will have a type which is
 * exactly equal to the desired type, except that it will accept
 * an additional leading argument of type {@code MethodHandle}.
 * <p>
 * This method is equivalent to the following code (though it may be more efficient):
-* <p><blockquote><pre>
+* {@code publicLookup().findVirtual(MethodHandle.class, "invokeExact", type)}
-publicLookup().findVirtual(MethodHandle.class, "invokeExact", type)
-* </pre></blockquote>
 *
 * <p style="font-size:smaller;">
 * <em>Discussion:</em>
 * Invoker method handles can be useful when working with variable method handles
 * of unknown types.
 * (It would not work to call {@code X.invokeExact}, since the type {@code T}
 * is unknown.)
 * If spreading, collecting, or other argument transformations are required,
 * they can be applied once to the invoker {@code X} and reused on many {@code M}
 * method handle values, as long as they are compatible with the type of {@code X}.
-* <p>
+* <p style="font-size:smaller;">
 * <em>(Note:  The invoker method is not available via the Core Reflection API.
 * An attempt to call {@linkplain java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}
 * on the declared {@code invokeExact} or {@code invoke} method will raise an
 * {@link java.lang.UnsupportedOperationException UnsupportedOperationException}.)</em>
 * <p>
 * necessary and box, unbox, or widen primitive values, as if by {@link MethodHandle#asType asType}.
 * Similarly, the return value will be converted as necessary.
 * If the target is a {@linkplain MethodHandle#asVarargsCollector variable arity method handle},
 * the required arity conversion will be made, again as if by {@link MethodHandle#asType asType}.
 * <p>
-* A {@linkplain MethodType#genericMethodType general method type},
+* This method is equivalent to the following code (though it may be more efficient):
+* {@code publicLookup().findVirtual(MethodHandle.class, "invoke", type)}
+* <p style="font-size:smaller;">
+* <em>Discussion:</em>
+* A {@linkplain MethodType#genericMethodType general method type} is one which
 * mentions only {@code Object} arguments and return values.
 * An invoker for such a type is capable of calling any method handle
 * of the same arity as the general type.
-* <p>
+* <p style="font-size:smaller;">
-* This method is equivalent to the following code (though it may be more efficient):
+* <em>(Note:  The invoker method is not available via the Core Reflection API.
-* <p><blockquote><pre>
+* An attempt to call {@linkplain java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}
-publicLookup().findVirtual(MethodHandle.class, "invoke", type)
+* on the declared {@code invokeExact} or {@code invoke} method will raise an
-* </pre></blockquote>
+* {@link java.lang.UnsupportedOperationException UnsupportedOperationException}.)</em>
 * <p>
 * This method throws no reflective or security exceptions.
 * @param type the desired target type
 * @return a method handle suitable for invoking any method handle convertible to the given type
 * @throws IllegalArgumentException if the resulting method handle's type would have
 * If {@code pos} is zero, the dummy arguments will precede
 * the target's real arguments; if {@code pos} is <i>N</i>
 * they will come after.
 * <p>
 * <b>Example:</b>
-* <p><blockquote><pre>
+* <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodHandle cat = lookup().findVirtual(String.class,
 "concat", methodType(String.class, String.class));
 assertEquals("xy", (String) cat.invokeExact("x", "y"));
 MethodType bigType = cat.type().insertParameterTypes(0, int.class, String.class);
 MethodHandle d0 = dropArguments(cat, 0, bigType.parameterList().subList(0,2));
 assertEquals(bigType, d0.type());
 assertEquals("yz", (String) d0.invokeExact(123, "x", "y", "z"));
-* </pre></blockquote>
+* }</pre></blockquote>
 * <p>
 * This method is also equivalent to the following code:
 * <p><blockquote><pre>
-* {@link #dropArguments(MethodHandle,int,Class...) dropArguments}(target, pos, valueTypes.toArray(new Class[0]))
+* {@link #dropArguments(MethodHandle,int,Class...) dropArguments}{@code (target, pos, valueTypes.toArray(new Class[0]))}
 * </pre></blockquote>
 * @param target the method handle to invoke after the arguments are dropped
 * @param valueTypes the type(s) of the argument(s) to drop
 * @param pos position of first argument to drop (zero for the leftmost)
 * @return a method handle which drops arguments of the given types,
 * If {@code pos} is zero, the dummy arguments will precede
 * the target's real arguments; if {@code pos} is <i>N</i>
 * they will come after.
 * <p>
 * <b>Example:</b>
-* <p><blockquote><pre>
+* <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodHandle cat = lookup().findVirtual(String.class,
 "concat", methodType(String.class, String.class));
 assertEquals("xz", (String) d1.invokeExact("x", "y", "z"));
 MethodHandle d2 = dropArguments(cat, 2, String.class);
 assertEquals("xy", (String) d2.invokeExact("x", "y", "z"));
 MethodHandle d12 = dropArguments(cat, 1, int.class, boolean.class);
 assertEquals("xz", (String) d12.invokeExact("x", 12, true, "z"));
-* </pre></blockquote>
+* }</pre></blockquote>
 * <p>
 * This method is also equivalent to the following code:
 * <p><blockquote><pre>
-* {@link #dropArguments(MethodHandle,int,List) dropArguments}(target, pos, Arrays.asList(valueTypes))
+* {@link #dropArguments(MethodHandle,int,List) dropArguments}{@code (target, pos, Arrays.asList(valueTypes))}
 * </pre></blockquote>
 * @param target the method handle to invoke after the arguments are dropped
 * @param valueTypes the type(s) of the argument(s) to drop
 * @param pos position of first argument to drop (zero for the leftmost)
 * @return a method handle which drops arguments of the given types,
 * parameter type of the target.
 * <p>
 * It is an error if there are elements of {@code filters}
 * (null or not)
 * which do not correspond to argument positions in the target.
-* <b>Example:</b>
+* <p><b>Example:</b>
-* <p><blockquote><pre>
+* <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodHandle cat = lookup().findVirtual(String.class,
 "concat", methodType(String.class, String.class));
 assertEquals("Xy", (String) f0.invokeExact("x", "y")); // Xy
 MethodHandle f1 = filterArguments(cat, 1, upcase);
 assertEquals("xY", (String) f1.invokeExact("x", "y")); // xY
 MethodHandle f2 = filterArguments(cat, 0, upcase, upcase);
 assertEquals("XY", (String) f2.invokeExact("x", "y")); // XY
-* </pre></blockquote>
+* }</pre></blockquote>
 * <p> Here is pseudocode for the resulting adapter:
-* <blockquote><pre>
+* <blockquote><pre>{@code
 * V target(P... p, A[i]... a[i], B... b);
 * A[i] filter[i](V[i]);
 * T adapter(P... p, V[i]... v[i], B... b) {
 *   return target(p..., f[i](v[i])..., b...);
 * }
-* </pre></blockquote>
+* }</pre></blockquote>
 *
 * @param target the method handle to invoke after arguments are filtered
 * @param pos the position of the first argument to filter
 * @param filters method handles to call initially on filtered arguments
 * @return method handle which incorporates the specified argument filtering logic
 * is supplied by the return value of the filter.
 * <p>
 * In all cases, {@code pos} must be greater than or equal to zero, and
 * {@code pos} must also be less than or equal to the target's arity.
 * <p><b>Example:</b>
-* <p><blockquote><pre>
+* <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodHandle deepToString = publicLookup()
 .findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));
 (String) ts3_ts2_ts1.invokeExact("top", "up", "down", "strange"));
 MethodHandle ts3_ts2_ts3 = collectArguments(ts3_ts2, 1, ts3);
 assertEquals("[top, [[up, down, strange], charm], bottom]",
 (String) ts3_ts2_ts3.invokeExact("top", "up", "down", "strange", "charm", "bottom"));
-* </pre></blockquote>
+* }</pre></blockquote>
 * <p> Here is pseudocode for the resulting adapter:
-* <blockquote><pre>
+* <blockquote><pre>{@code
 * T target(A...,V,C...);
 * V filter(B...);
 * T adapter(A... a,B... b,C... c) {
 *   V v = filter(b...);
 *   return target(a...,v,c...);
 * void filter3(B...);
 * void adapter3(A... a,B... b,C... c) {
 *   filter3(b...);
 *   return target3(a...,c...);
 * }
-* </pre></blockquote>
+* }</pre></blockquote>
 * <p>
 * A collection adapter {@code collectArguments(mh, 0, coll)} is equivalent to
 * one which first "folds" the affected arguments, and then drops them, in separate
 * steps as follows:
 * <blockquote><pre>{@code
 * The return type of the filter
 * replaces the return type of the target
 * in the resulting adapted method handle.
 * The argument type of the filter (if any) must be identical to the
 * return type of the target.
-* <b>Example:</b>
+* <p><b>Example:</b>
-* <p><blockquote><pre>
+* <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodHandle cat = lookup().findVirtual(String.class,
 "concat", methodType(String.class, String.class));
 MethodHandle length = lookup().findVirtual(String.class,
 "length", methodType(int.class));
 System.out.println((String) cat.invokeExact("x", "y")); // xy
 MethodHandle f0 = filterReturnValue(cat, length);
 System.out.println((int) f0.invokeExact("x", "y")); // 2
-* </pre></blockquote>
+* }</pre></blockquote>
 * <p> Here is pseudocode for the resulting adapter:
-* <blockquote><pre>
+* <blockquote><pre>{@code
 * V target(A...);
 * T filter(V);
 * T adapter(A... a) {
 *   V v = target(a...);
 *   return filter(v);
 * void filter3(V);
 * void adapter3(A... a) {
 *   V v = target3(a...);
 *   filter3(v);
 * }
-* </pre></blockquote>
+* }</pre></blockquote>
 * @param target the method handle to invoke before filtering the return value
 * @param filter method handle to call on the return value
 * @return method handle which incorporates the specified return value filtering logic
 * @throws NullPointerException if either argument is null
 * @throws IllegalArgumentException if the argument list of {@code filter}
 * that either the combiner or the target does not wish to receive.
 * If some of the incoming arguments are destined only for the combiner,
 * consider using {@link MethodHandle#asCollector asCollector} instead, since those
 * arguments will not need to be live on the stack on entry to the
 * target.)
-* <b>Example:</b>
+* <p><b>Example:</b>
-* <p><blockquote><pre>
+* <p><blockquote><pre>{@code
 import static java.lang.invoke.MethodHandles.*;
 import static java.lang.invoke.MethodType.*;
 ...
 MethodHandle trace = publicLookup().findVirtual(java.io.PrintStream.class,
 "println", methodType(void.class, String.class))
 "concat", methodType(String.class, String.class));
 assertEquals("boojum", (String) cat.invokeExact("boo", "jum"));
 MethodHandle catTrace = foldArguments(cat, trace);
 // also prints "boo":
 assertEquals("boojum", (String) catTrace.invokeExact("boo", "jum"));
-* </pre></blockquote>
+* }</pre></blockquote>
 * <p> Here is pseudocode for the resulting adapter:
-* <blockquote><pre>
+* <blockquote><pre>{@code
 * // there are N arguments in A...
 * T target(V, A[N]..., B...);
 * V combiner(A...);
 * T adapter(A... a, B... b) {
 *   V v = combiner(a...);
 * void combiner2(A...);
 * T adapter2(A... a, B... b) {
 *   combiner2(a...);
 *   return target2(a..., b...);
 * }
-* </pre></blockquote>
+* }</pre></blockquote>
 * @param target the method handle to invoke after arguments are combined
 * @param combiner method handle to call initially on the incoming arguments
 * @return method handle which incorporates the specified argument folding logic
 * @throws NullPointerException if either argument is null
 * @throws IllegalArgumentException if {@code combiner}'s return type
 * All three method handles must have the same corresponding
 * argument and return types, except that the return type
 * of the test must be boolean, and the test is allowed
 * to have fewer arguments than the other two method handles.
 * <p> Here is pseudocode for the resulting adapter:
-* <blockquote><pre>
+* <blockquote><pre>{@code
 * boolean test(A...);
 * T target(A...,B...);
 * T fallback(A...,B...);
 * T adapter(A... a,B... b) {
 *   if (test(a...))
 *     return target(a..., b...);
 *   else
 *     return fallback(a..., b...);
 * }
-* </pre></blockquote>
+* }</pre></blockquote>
 * Note that the test arguments ({@code a...} in the pseudocode) cannot
 * be modified by execution of the test, and so are passed unchanged
 * from the caller to the target or fallback as appropriate.
 * @param test method handle used for test, must return boolean
 * @param target method handle to call if test passes
 * The target and handler must have the same corresponding
 * argument and return types, except that handler may omit trailing arguments
 * (similarly to the predicate in {@link #guardWithTest guardWithTest}).
 * Also, the handler must have an extra leading parameter of {@code exType} or a supertype.
 * <p> Here is pseudocode for the resulting adapter:
-* <blockquote><pre>
+* <blockquote><pre>{@code
 * T target(A..., B...);
 * T handler(ExType, A...);
 * T adapter(A... a, B... b) {
 *   try {
 *     return target(a..., b...);
 *   } catch (ExType ex) {
 *     return handler(ex, a...);
 *   }
 * }
-* </pre></blockquote>
+* }</pre></blockquote>
 * Note that the saved arguments ({@code a...} in the pseudocode) cannot
 * be modified by execution of the target, and so are passed unchanged
 * from the caller to the handler, if the handler is invoked.
 * <p>
 * The target and handler must return the same type, even if the handler

changeset 20535	cc85c8626435
parent 20534	da86f7904e6d
child 20853	505b28fe2b98