8024438: JSR 292 API specification maintenance for JDK 8
Add wildcard to unreflectConstructor, various clarifications and minor edits
Reviewed-by: mchung, darcy, twisti
diff --git a/jdk/src/share/classes/java/lang/invoke/BoundMethodHandle.java b/jdk/src/share/classes/java/lang/invoke/BoundMethodHandle.java
index 9aaafd7..abc3147 100644
--- a/jdk/src/share/classes/java/lang/invoke/BoundMethodHandle.java
+++ b/jdk/src/share/classes/java/lang/invoke/BoundMethodHandle.java
@@ -529,18 +529,18 @@
* A concrete BMH species adheres to the following schema:
*
* <pre>
- * class Species_<<types>> extends BoundMethodHandle {
- * <<fields>>
- * final SpeciesData speciesData() { return SpeciesData.get("<<types>>"); }
+ * class Species_[[types]] extends BoundMethodHandle {
+ * [[fields]]
+ * final SpeciesData speciesData() { return SpeciesData.get("[[types]]"); }
* }
* </pre>
*
- * The {@code <<types>>} signature is precisely the string that is passed to this
+ * The {@code [[types]]} signature is precisely the string that is passed to this
* method.
*
- * The {@code <<fields>>} section consists of one field definition per character in
+ * The {@code [[fields]]} section consists of one field definition per character in
* the type signature, adhering to the naming schema described in the definition of
- * {@link #makeFieldName()}.
+ * {@link #makeFieldName}.
*
* For example, a concrete BMH species for two reference and one integral bound values
* would have the following shape:
@@ -822,7 +822,7 @@
* {@code <init>}. To avoid this, we add an indirection by invoking {@code <init>} through
* {@link MethodHandle#linkToSpecial}.
*
- * The last {@link LambdaForm#Name Name} in the argument's form is expected to be the {@code void}
+ * The last {@link LambdaForm.Name Name} in the argument's form is expected to be the {@code void}
* result of the {@code <init>} invocation. This entry is replaced.
*/
private static MethodHandle linkConstructor(MethodHandle cmh) {
diff --git a/jdk/src/share/classes/java/lang/invoke/CallSite.java b/jdk/src/share/classes/java/lang/invoke/CallSite.java
index e08f1db..1d584d5 100644
--- a/jdk/src/share/classes/java/lang/invoke/CallSite.java
+++ b/jdk/src/share/classes/java/lang/invoke/CallSite.java
@@ -60,7 +60,7 @@
* <p>
* Here is a sample use of call sites and bootstrap methods which links every
* dynamic call site to print its arguments:
-<blockquote><pre><!-- see indy-demo/src/PrintArgsDemo.java -->
+<blockquote><pre>{@code
static void test() throws Throwable {
// THE FOLLOWING LINE IS PSEUDOCODE FOR A JVM INSTRUCTION
InvokeDynamic[#bootstrapDynamic].baz("baz arg", 2, 3.14);
@@ -79,7 +79,7 @@
// ignore caller and name, but match the type:
return new ConstantCallSite(printArgs.asType(type));
}
-</pre></blockquote>
+}</pre></blockquote>
* @author John Rose, JSR 292 EG
*/
abstract
@@ -199,12 +199,12 @@
* which has been linked to this call site.
* <p>
* This method is equivalent to the following code:
- * <blockquote><pre>
+ * <blockquote><pre>{@code
* MethodHandle getTarget, invoker, result;
* getTarget = MethodHandles.publicLookup().bind(this, "getTarget", MethodType.methodType(MethodHandle.class));
* invoker = MethodHandles.exactInvoker(this.type());
* result = MethodHandles.foldArguments(invoker, getTarget)
- * </pre></blockquote>
+ * }</pre></blockquote>
*
* @return a method handle which always invokes this call site's current target
*/
diff --git a/jdk/src/share/classes/java/lang/invoke/InvokerBytecodeGenerator.java b/jdk/src/share/classes/java/lang/invoke/InvokerBytecodeGenerator.java
index 6228c07..7b6b413 100644
--- a/jdk/src/share/classes/java/lang/invoke/InvokerBytecodeGenerator.java
+++ b/jdk/src/share/classes/java/lang/invoke/InvokerBytecodeGenerator.java
@@ -242,9 +242,6 @@
/**
* Extract the MemberName of a newly-defined method.
- *
- * @param classFile
- * @return
*/
private MemberName loadMethod(byte[] classFile) {
Class<?> invokerClass = loadAndInitializeInvokerClass(classFile, cpPatches(classFile));
@@ -253,10 +250,6 @@
/**
* Define a given class as anonymous class in the runtime system.
- *
- * @param classBytes
- * @param patches
- * @return
*/
private static Class<?> loadAndInitializeInvokerClass(byte[] classBytes, Object[] patches) {
Class<?> invokerClass = UNSAFE.defineAnonymousClass(HOST_CLASS, classBytes, patches);
@@ -264,14 +257,6 @@
return invokerClass;
}
- /**
- * TODO
- *
- * @param invokerClass
- * @param name
- * @param type
- * @return
- */
private static MemberName resolveInvokerMember(Class<?> invokerClass, String name, MethodType type) {
MemberName member = new MemberName(invokerClass, name, type, REF_invokeStatic);
//System.out.println("resolveInvokerMember => "+member);
@@ -499,10 +484,6 @@
/**
* Generate customized bytecode for a given LambdaForm.
- *
- * @param form
- * @param invokerType
- * @return
*/
static MemberName generateCustomizedCode(LambdaForm form, MethodType invokerType) {
InvokerBytecodeGenerator g = new InvokerBytecodeGenerator("MH", form, invokerType);
@@ -565,8 +546,6 @@
/**
* Emit an invoke for the given name.
- *
- * @param name
*/
void emitInvoke(Name name) {
if (true) {
@@ -645,8 +624,6 @@
/**
* Emit an invoke for the given name, using the MemberName directly.
- *
- * @param name
*/
void emitStaticInvoke(MemberName member, Name name) {
assert(member.equals(name.function.member()));
@@ -690,9 +667,6 @@
/**
* Check if MemberName is a call to MethodHandleImpl.selectAlternative.
- *
- * @param member
- * @return true if member is a call to MethodHandleImpl.selectAlternative
*/
private boolean isSelectAlternative(MemberName member) {
return member != null &&
@@ -704,14 +678,12 @@
* Emit bytecode for the selectAlternative idiom.
*
* The pattern looks like (Cf. MethodHandleImpl.makeGuardWithTest):
- *
+ * <blockquote><pre>{@code
* Lambda(a0:L,a1:I)=>{
* t2:I=foo.test(a1:I);
* t3:L=MethodHandleImpl.selectAlternative(t2:I,(MethodHandle(int)int),(MethodHandle(int)int));
* t4:I=MethodHandle.invokeBasic(t3:L,a1:I);t4:I}
- *
- * @param selectAlternativeName
- * @param invokeBasicName
+ * }</pre></blockquote>
*/
private void emitSelectAlternative(Name selectAlternativeName, Name invokeBasicName) {
MethodType type = selectAlternativeName.function.methodType();
@@ -750,11 +722,6 @@
mv.visitLabel(L_done);
}
- /**
- *
- * @param name
- * @param paramIndex
- */
private void emitPushArgument(Name name, int paramIndex) {
Object arg = name.arguments[paramIndex];
char ptype = name.function.parameterType(paramIndex);
@@ -923,9 +890,6 @@
/**
* Generate bytecode for a LambdaForm.vmentry which calls interpretWithArguments.
- *
- * @param sig
- * @return
*/
static MemberName generateLambdaFormInterpreterEntryPoint(String sig) {
assert(LambdaForm.isValidSignature(sig));
@@ -993,10 +957,6 @@
/**
* Generate bytecode for a NamedFunction invoker.
- *
- * @param srcType
- * @param dstType
- * @return
*/
static MemberName generateNamedFunctionInvoker(MethodTypeForm typeForm) {
MethodType invokerType = LambdaForm.NamedFunction.INVOKER_METHOD_TYPE;
diff --git a/jdk/src/share/classes/java/lang/invoke/LambdaForm.java b/jdk/src/share/classes/java/lang/invoke/LambdaForm.java
index d83fc47..857cf26 100644
--- a/jdk/src/share/classes/java/lang/invoke/LambdaForm.java
+++ b/jdk/src/share/classes/java/lang/invoke/LambdaForm.java
@@ -50,7 +50,7 @@
* The result of the lambda is defined as one of the names, often the last one.
* <p>
* Here is an approximate grammar:
- * <pre>
+ * <blockquote><pre>{@code
* LambdaForm = "(" ArgName* ")=>{" TempName* Result "}"
* ArgName = "a" N ":" T
* TempName = "t" N ":" T "=" Function "(" Argument* ");"
@@ -60,7 +60,7 @@
* NameRef = "a" N | "t" N
* N = (any whole number)
* T = "L" | "I" | "J" | "F" | "D" | "V"
- * </pre>
+ * }</pre></blockquote>
* Names are numbered consecutively from left to right starting at zero.
* (The letters are merely a taste of syntax sugar.)
* Thus, the first temporary (if any) is always numbered N (where N=arity).
@@ -69,7 +69,7 @@
* A lambda has a void result if and only if its result index is -1.
* If a temporary has the type "V", it cannot be the subject of a NameRef,
* even though possesses a number.
- * Note that all reference types are erased to "L", which stands for {@code Object).
+ * Note that all reference types are erased to "L", which stands for {@code Object}.
* All subword types (boolean, byte, short, char) are erased to "I" which is {@code int}.
* The other types stand for the usual primitive types.
* <p>
@@ -89,7 +89,7 @@
* encoded by using temporary expressions which call type-transformed identity functions.
* <p>
* Examples:
- * <pre>
+ * <blockquote><pre>{@code
* (a0:J)=>{ a0 }
* == identity(long)
* (a0:I)=>{ t1:V = System.out#println(a0); void }
@@ -113,7 +113,7 @@
* (a0:L, a1:L)=>{ t2:L = BoundMethodHandle#argument(a0);
* t3:L = Class#cast(t2,a1); t3 }
* == invoker for identity method handle which performs cast
- * </pre>
+ * }</pre></blockquote>
* <p>
* @author John Rose, JSR 292 EG
*/
@@ -1441,8 +1441,6 @@
* Does this Name precede the given binding node in some canonical order?
* This predicate is used to order data bindings (via insertion sort)
* with some stability.
- * @param binding
- * @return
*/
boolean isSiblingBindingBefore(Name binding) {
assert(!binding.isParam());
diff --git a/jdk/src/share/classes/java/lang/invoke/MethodHandle.java b/jdk/src/share/classes/java/lang/invoke/MethodHandle.java
index 2487f0f..14bc2b4 100644
--- a/jdk/src/share/classes/java/lang/invoke/MethodHandle.java
+++ b/jdk/src/share/classes/java/lang/invoke/MethodHandle.java
@@ -292,7 +292,7 @@
* generates a single invokevirtual instruction with
* the symbolic type descriptor indicated in the following comment.
* In these examples, the helper method {@code assertEquals} is assumed to
- * be a method which calls {@link java.util.Objects#equals(Object,Object) Objects.equals }
+ * be a method which calls {@link java.util.Objects#equals(Object,Object) Objects.equals}
* on its arguments, and asserts that the result is true.
*
* <h1>Exceptions</h1>
@@ -575,10 +575,10 @@
/*non-public*/ static native @PolymorphicSignature Object linkToInterface(Object... args) throws Throwable;
/**
- * Performs a variable arity invocation, passing the arguments in the given array
+ * Performs a variable arity invocation, passing the arguments in the given list
* to the method handle, as if via an inexact {@link #invoke invoke} from a call site
* which mentions only the type {@code Object}, and whose arity is the length
- * of the argument array.
+ * of the argument list.
* <p>
* Specifically, execution proceeds as if by the following steps,
* although the methods are not guaranteed to be called if the JVM
@@ -608,10 +608,10 @@
* or forced to null if the return type is void.
* <p>
* This call is equivalent to the following code:
- * <p><blockquote><pre>
+ * <p><blockquote><pre>{@code
* MethodHandle invoker = MethodHandles.spreadInvoker(this.type(), 0);
* Object result = invoker.invokeExact(this, arguments);
- * </pre></blockquote>
+ * }</pre></blockquote>
* <p>
* Unlike the signature polymorphic methods {@code invokeExact} and {@code invoke},
* {@code invokeWithArguments} can be accessed normally via the Core Reflection API and JNI.
@@ -644,7 +644,7 @@
* <p>
* This method is also equivalent to the following code:
* <p><blockquote><pre>
- * {@link #invokeWithArguments(Object...) invokeWithArguments}(arguments.toArray())
+ * {@link #invokeWithArguments(Object...) invokeWithArguments}{@code(arguments.toArray())}
* </pre></blockquote>
*
* @param arguments the arguments to pass to the target
@@ -1272,9 +1272,9 @@
* starting with the string {@code "MethodHandle"} and
* ending with the string representation of the method handle's type.
* In other words, this method returns a string equal to the value of:
- * <blockquote><pre>
+ * <blockquote><pre>{@code
* "MethodHandle" + type().toString()
- * </pre></blockquote>
+ * }</pre></blockquote>
* <p>
* (<em>Note:</em> Future releases of this API may add further information
* to the string representation.
@@ -1485,7 +1485,6 @@
* Threads may continue running the old form indefinitely,
* but it is likely that the new one will be preferred for new executions.
* Use with discretion.
- * @param newForm
*/
/*non-public*/
void updateForm(LambdaForm newForm) {
diff --git a/jdk/src/share/classes/java/lang/invoke/MethodHandleInfo.java b/jdk/src/share/classes/java/lang/invoke/MethodHandleInfo.java
index 3bab3d2..d63db84 100644
--- a/jdk/src/share/classes/java/lang/invoke/MethodHandleInfo.java
+++ b/jdk/src/share/classes/java/lang/invoke/MethodHandleInfo.java
@@ -32,9 +32,10 @@
import static java.lang.invoke.MethodHandleStatics.*;
/**
- * A symbolic reference obtained by cracking a method handle into its consitutent symbolic parts.
+ * A symbolic reference obtained by cracking a direct method handle
+ * into its consitutent symbolic parts.
* To crack a direct method handle, call {@link Lookup#revealDirect Lookup.revealDirect}.
- * <p>
+ * <h1><a name="directmh"></a>Direct Method Handles</h1>
* A <em>direct method handle</em> represents a method, constructor, or field without
* any intervening argument bindings or other transformations.
* The method, constructor, or field referred to by a direct method handle is called
@@ -56,7 +57,9 @@
* or {@link Lookup#unreflectSetter Lookup.unreflectSetter}
* to convert a {@link Field} into a method handle.
* </ul>
- * In all of these cases, it is possible to crack the resulting direct method handle
+ *
+ * <h1>Restrictions on Cracking</h1>
+ * Given a suitable {@code Lookup} object, it is possible to crack any direct method handle
* to recover a symbolic reference for the underlying method, constructor, or field.
* Cracking must be done via a {@code Lookup} object equivalent to that which created
* the target method handle, or which has enough access permissions to recreate
@@ -202,7 +205,7 @@
* @return the Java language modifiers for underlying member,
* or -1 if the member cannot be accessed
* @see Modifier
- * @see reflectAs
+ * @see #reflectAs
*/
public int getModifiers();
diff --git a/jdk/src/share/classes/java/lang/invoke/MethodHandles.java b/jdk/src/share/classes/java/lang/invoke/MethodHandles.java
index d98bead..369d14b 100644
--- a/jdk/src/share/classes/java/lang/invoke/MethodHandles.java
+++ b/jdk/src/share/classes/java/lang/invoke/MethodHandles.java
@@ -49,7 +49,6 @@
* <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
@@ -66,12 +65,25 @@
//// Method handle creation from ordinary methods.
/**
- * Returns a {@link Lookup lookup object} on the caller,
- * which has the capability to access any method handle that the caller has access to,
- * including direct method handles to private fields and methods.
+ * Returns a {@link Lookup lookup object} with
+ * full capabilities to emulate all supported bytecode behaviors of the caller.
+ * 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() {
@@ -85,9 +97,11 @@
* <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
@@ -101,7 +115,8 @@
}
/**
- * 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}
@@ -154,10 +169,17 @@
* <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>
@@ -233,10 +255,12 @@
* 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:
- * <ul>
+ * class members and bytecode behaviors
+ * 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.
@@ -280,7 +304,8 @@
* 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:
@@ -291,14 +316,23 @@
* </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
- * under which the lookup class could have compiled and resolved a call to {@code M}.
+ * looked up for a method {@code M} are no more restrictive than the conditions
+ * 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
@@ -312,6 +346,12 @@
* (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
@@ -331,6 +371,43 @@
* 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
@@ -343,16 +420,6 @@
* 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.
@@ -365,19 +432,22 @@
* 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
@@ -408,11 +478,32 @@
* 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 {
@@ -639,7 +730,7 @@
* (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
@@ -679,7 +770,7 @@
* 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
@@ -696,7 +787,7 @@
* {@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
@@ -770,10 +861,10 @@
* 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}.
- * This is consistent with the JVM's treatment of constructor type descriptors.)</em>
+ * The requested type must have a return type of {@code void}.
+ * (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
@@ -817,27 +908,26 @@
}
/**
- * Produces an early-bound method handle for a virtual method,
- * as if called from an {@code invokespecial}
- * instruction from {@code caller}.
+ * Produces an early-bound method handle for a virtual method.
+ * It will bypass checks for overriding methods on the receiver,
+ * <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,
- * but will not dispatch on the receiver's type.
- * (This direct invocation action is identical with that performed by an
- * {@code invokespecial} instruction.)
- * <p>
- * If the explicitly specified caller class is not identical with the
- * lookup class, or if this lookup object does not have private access
+ * 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.
- * <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}
@@ -993,7 +1083,7 @@
* 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,
@@ -1008,17 +1098,17 @@
* 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 mh1 = mh0.{@link MethodHandle#bindTo bindTo}(receiver);
+MethodHandle mh0 = lookup().findVirtual(defc, name, type);
+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.
@@ -1034,6 +1124,8 @@
* @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
@@ -1043,7 +1135,8 @@
}
/**
- * 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.
@@ -1090,13 +1183,21 @@
/**
* 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.
@@ -1141,8 +1242,7 @@
* 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;
@@ -1202,7 +1302,8 @@
}
/**
- * 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
@@ -1215,6 +1316,7 @@
* <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) {
@@ -1282,7 +1384,7 @@
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 "<" character. */
void checkMethodName(byte refKind, String name) throws NoSuchMethodException {
if (name.startsWith("<") && refKind != REF_newInvokeSpecial)
throw new NoSuchMethodException("illegal method name: "+name);
@@ -1730,13 +1832,12 @@
* 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>
- * <p>
+ * }</pre></blockquote>
* 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
@@ -1762,9 +1863,7 @@
* 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>
-publicLookup().findVirtual(MethodHandle.class, "invokeExact", type)
- * </pre></blockquote>
+ * {@code publicLookup().findVirtual(MethodHandle.class, "invokeExact", type)}
*
* <p style="font-size:smaller;">
* <em>Discussion:</em>
@@ -1779,7 +1878,7 @@
* 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
@@ -1810,15 +1909,19 @@
* 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>
- * This method is equivalent to the following code (though it may be more efficient):
- * <p><blockquote><pre>
-publicLookup().findVirtual(MethodHandle.class, "invoke", type)
- * </pre></blockquote>
+ * <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>
* This method throws no reflective or security exceptions.
* @param type the desired target type
@@ -2105,7 +2208,7 @@
* 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.*;
...
@@ -2116,11 +2219,11 @@
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
@@ -2163,7 +2266,7 @@
* 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.*;
...
@@ -2178,11 +2281,11 @@
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
@@ -2228,8 +2331,8 @@
* 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><blockquote><pre>
+ * <p><b>Example:</b>
+ * <p><blockquote><pre>{@code
import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
@@ -2244,15 +2347,15 @@
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
@@ -2322,7 +2425,7 @@
* 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.*;
...
@@ -2347,9 +2450,9 @@
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) {
@@ -2370,7 +2473,7 @@
* 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
@@ -2426,8 +2529,8 @@
* 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><blockquote><pre>
+ * <p><b>Example:</b>
+ * <p><blockquote><pre>{@code
import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
@@ -2438,9 +2541,9 @@
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) {
@@ -2461,7 +2564,7 @@
* 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
@@ -2517,8 +2620,8 @@
* 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><blockquote><pre>
+ * <p><b>Example:</b>
+ * <p><blockquote><pre>{@code
import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
@@ -2531,9 +2634,9 @@
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...);
@@ -2548,7 +2651,7 @@
* 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
@@ -2591,7 +2694,7 @@
* 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...);
@@ -2601,7 +2704,7 @@
* 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.
@@ -2653,7 +2756,7 @@
* (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) {
@@ -2663,7 +2766,7 @@
* 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.
diff --git a/jdk/src/share/classes/java/lang/invoke/MethodType.java b/jdk/src/share/classes/java/lang/invoke/MethodType.java
index 5fc1f37..5a73037 100644
--- a/jdk/src/share/classes/java/lang/invoke/MethodType.java
+++ b/jdk/src/share/classes/java/lang/invoke/MethodType.java
@@ -77,7 +77,8 @@
* A method type may be loaded by an {@code ldc} instruction which refers
* to a suitable {@code CONSTANT_MethodType} constant pool entry.
* The entry refers to a {@code CONSTANT_Utf8} spelling for the descriptor string.
- * For more details, see the <a href="package-summary.html#mtcon">package summary</a>.
+ * (For full details on method type constants,
+ * see sections 4.4.8 and 5.4.3.5 of the Java Virtual Machine Specification.)
* <p>
* When the JVM materializes a {@code MethodType} from a descriptor string,
* all classes named in the descriptor must be accessible, and will be loaded.
@@ -940,10 +941,10 @@
* Instead, the return type and parameter type arrays are written directly
* from the {@code writeObject} method, using two calls to {@code s.writeObject}
* as follows:
- * <blockquote><pre>
+ * <blockquote><pre>{@code
s.writeObject(this.returnType());
s.writeObject(this.parameterArray());
- * </pre></blockquote>
+ * }</pre></blockquote>
* <p>
* The deserialized field values are checked as if they were
* provided to the factory method {@link #methodType(Class,Class[]) methodType}.
diff --git a/jdk/src/share/classes/java/lang/invoke/MutableCallSite.java b/jdk/src/share/classes/java/lang/invoke/MutableCallSite.java
index 37bd464..746c8d6 100644
--- a/jdk/src/share/classes/java/lang/invoke/MutableCallSite.java
+++ b/jdk/src/share/classes/java/lang/invoke/MutableCallSite.java
@@ -38,7 +38,7 @@
* Here is an example of a mutable call site which introduces a
* state variable into a method handle chain.
* <!-- JavaDocExamplesTest.testMutableCallSite -->
- * <blockquote><pre>
+ * <blockquote><pre>{@code
MutableCallSite name = new MutableCallSite(MethodType.methodType(String.class));
MethodHandle MH_name = name.dynamicInvoker();
MethodType MT_str1 = MethodType.methodType(String.class);
@@ -50,10 +50,10 @@
name.setTarget(MethodHandles.constant(String.class, "Fred"));
assertEquals("FRED", (String) worker1.invokeExact());
// (mutation can be continued indefinitely)
- * </pre></blockquote>
+ * }</pre></blockquote>
* <p>
* The same call site may be used in several places at once.
- * <blockquote><pre>
+ * <blockquote><pre>{@code
MethodType MT_str2 = MethodType.methodType(String.class, String.class);
MethodHandle MH_cat = lookup().findVirtual(String.class,
"concat", methodType(String.class, String.class));
@@ -63,7 +63,7 @@
name.setTarget(MethodHandles.constant(String.class, "Wilma"));
assertEquals("WILMA", (String) worker1.invokeExact());
assertEquals("Wilma, dear?", (String) worker2.invokeExact());
- * </pre></blockquote>
+ * }</pre></blockquote>
* <p>
* <em>Non-synchronization of target values:</em>
* A write to a mutable call site's target does not force other threads
diff --git a/jdk/src/share/classes/java/lang/invoke/SwitchPoint.java b/jdk/src/share/classes/java/lang/invoke/SwitchPoint.java
index 65fd1da..290f9f0 100644
--- a/jdk/src/share/classes/java/lang/invoke/SwitchPoint.java
+++ b/jdk/src/share/classes/java/lang/invoke/SwitchPoint.java
@@ -55,7 +55,7 @@
* At that point {@code guardWithTest} may ignore {@code T} and return {@code F}.
* <p>
* Here is an example of a switch point in action:
- * <blockquote><pre>
+ * <blockquote><pre>{@code
MethodHandle MH_strcat = MethodHandles.lookup()
.findVirtual(String.class, "concat", MethodType.methodType(String.class, String.class));
SwitchPoint spt = new SwitchPoint();
@@ -68,7 +68,7 @@
SwitchPoint.invalidateAll(new SwitchPoint[]{ spt });
assert(spt.hasBeenInvalidated());
assertEquals("hodmet", (String) worker.invokeExact("met", "hod"));
- * </pre></blockquote>
+ * }</pre></blockquote>
* <p style="font-size:smaller;">
* <em>Discussion:</em>
* Switch points are useful without subclassing. They may also be subclassed.
@@ -82,7 +82,7 @@
* <em>Implementation Note:</em>
* A switch point behaves as if implemented on top of {@link MutableCallSite},
* approximately as follows:
- * <blockquote><pre>
+ * <blockquote><pre>{@code
public class SwitchPoint {
private static final MethodHandle
K_true = MethodHandles.constant(boolean.class, true),
@@ -106,7 +106,7 @@
MutableCallSite.syncAll(mcss.toArray(new MutableCallSite[0]));
}
}
- * </pre></blockquote>
+ * }</pre></blockquote>
* @author Remi Forax, JSR 292 EG
*/
public class SwitchPoint {
diff --git a/jdk/src/share/classes/sun/invoke/WrapperInstance.java b/jdk/src/share/classes/sun/invoke/WrapperInstance.java
index ba918b4..6c545cf 100644
--- a/jdk/src/share/classes/sun/invoke/WrapperInstance.java
+++ b/jdk/src/share/classes/sun/invoke/WrapperInstance.java
@@ -30,7 +30,7 @@
/**
* Private API used inside of java.lang.invoke.MethodHandles.
* Interface implemented by every object which is produced by
- * {@link java.lang.invoke.MethodHandles#asInstance MethodHandles.asInstance}.
+ * {@link java.lang.invoke.MethodHandleProxies#asInterfaceInstance MethodHandleProxies.asInterfaceInstance}.
* The methods of this interface allow a caller to recover the parameters
* to {@code asInstance}.
* This allows applications to repeatedly convert between method handles
diff --git a/jdk/src/share/classes/sun/invoke/util/VerifyAccess.java b/jdk/src/share/classes/sun/invoke/util/VerifyAccess.java
index 5070e97..3b65b58 100644
--- a/jdk/src/share/classes/sun/invoke/util/VerifyAccess.java
+++ b/jdk/src/share/classes/sun/invoke/util/VerifyAccess.java
@@ -172,7 +172,7 @@
* Decide if the given method type, attributed to a member or symbolic
* reference of a given reference class, is really visible to that class.
* @param type the supposed type of a member or symbolic reference of refc
- * @param refc
+ * @param refc the class attempting to make the reference
*/
public static boolean isTypeVisible(Class<?> type, Class<?> refc) {
if (type == refc) return true; // easy check
@@ -197,7 +197,7 @@
* Decide if the given method type, attributed to a member or symbolic
* reference of a given reference class, is really visible to that class.
* @param type the supposed type of a member or symbolic reference of refc
- * @param refc
+ * @param refc the class attempting to make the reference
*/
public static boolean isTypeVisible(java.lang.invoke.MethodType type, Class<?> refc) {
for (int n = -1, max = type.parameterCount(); n < max; n++) {
@@ -210,8 +210,8 @@
/**
* Test if two classes have the same class loader and package qualifier.
- * @param class1
- * @param class2
+ * @param class1 a class
+ * @param class2 another class
* @return whether they are in the same package
*/
public static boolean isSamePackage(Class<?> class1, Class<?> class2) {
@@ -244,8 +244,8 @@
/**
* Test if two classes are defined as part of the same package member (top-level class).
* If this is true, they can share private access with each other.
- * @param class1
- * @param class2
+ * @param class1 a class
+ * @param class2 another class
* @return whether they are identical or nested together
*/
public static boolean isSamePackageMember(Class<?> class1, Class<?> class2) {
@@ -287,8 +287,8 @@
/**
* Is the class loader of parentClass identical to, or an ancestor of,
* the class loader of childClass?
- * @param parentClass
- * @param childClass
+ * @param parentClass a class
+ * @param childClass another class, which may be a descendent of the first class
* @return whether parentClass precedes or equals childClass in class loader order
*/
public static boolean classLoaderIsAncestor(Class<?> parentClass, Class<?> childClass) {
diff --git a/jdk/src/share/classes/sun/invoke/util/VerifyType.java b/jdk/src/share/classes/sun/invoke/util/VerifyType.java
index e755a9e..b0c76ae 100644
--- a/jdk/src/share/classes/sun/invoke/util/VerifyType.java
+++ b/jdk/src/share/classes/sun/invoke/util/VerifyType.java
@@ -41,8 +41,8 @@
* True if a value can be stacked as the source type and unstacked as the
* destination type, without violating the JVM's type consistency.
*
- * @param call the type of a stacked value
- * @param recv the type by which we'd like to treat it
+ * @param src the type of a stacked value
+ * @param dst the type by which we'd like to treat it
* @return whether the retyping can be done without motion or reformatting
*/
public static boolean isNullConversion(Class<?> src, Class<?> dst) {
@@ -67,9 +67,8 @@
/**
* Specialization of isNullConversion to reference types.
-
- * @param call the type of a stacked value
- * @param recv the reference type by which we'd like to treat it
+ * @param src the type of a stacked value
+ * @param dst the reference type by which we'd like to treat it
* @return whether the retyping can be done without a cast
*/
public static boolean isNullReferenceConversion(Class<?> src, Class<?> dst) {
diff --git a/jdk/test/java/lang/invoke/AccessControlTest.java b/jdk/test/java/lang/invoke/AccessControlTest.java
index 0ee0678..0d37ec6 100644
--- a/jdk/test/java/lang/invoke/AccessControlTest.java
+++ b/jdk/test/java/lang/invoke/AccessControlTest.java
@@ -133,7 +133,7 @@
}
/** Simulate all assertions from the spec. for Lookup.in:
- * <hr/>
+ * <hr>
* Creates a lookup on the specified new lookup class.
* [A1] The resulting object will report the specified
* class as its own {@link #lookupClass lookupClass}.
@@ -155,7 +155,7 @@
* </ul>
* Other than the above cases, the new lookup will have the same
* access capabilities as the original. [A8]
- * <hr/>
+ * <hr>
*/
public LookupCase in(Class<?> c2) {
Class<?> c1 = lookupClass();
diff --git a/jdk/test/java/lang/invoke/MethodHandlesTest.java b/jdk/test/java/lang/invoke/MethodHandlesTest.java
index 53eb09c..37da9b0 100644
--- a/jdk/test/java/lang/invoke/MethodHandlesTest.java
+++ b/jdk/test/java/lang/invoke/MethodHandlesTest.java
@@ -496,7 +496,7 @@
return lookup.in(defc);
}
- /** Is findVirtual (etc.) of "<init>" supposed to elicit a NoSuchMethodException? */
+ /** Is findVirtual (etc.) of "<init<" supposed to elicit a NoSuchMethodException? */
final static boolean INIT_REF_CAUSES_NSME = true;
@Test
diff --git a/jdk/test/java/lang/invoke/RevealDirectTest.java b/jdk/test/java/lang/invoke/RevealDirectTest.java
index f05b190..1aa15da8 100644
--- a/jdk/test/java/lang/invoke/RevealDirectTest.java
+++ b/jdk/test/java/lang/invoke/RevealDirectTest.java
@@ -104,6 +104,9 @@
private static Lookup localLookup() { return lookup(); }
private static List<Member> members() { return getMembers(lookup().lookupClass()); };
}
+ static class Nestmate {
+ private static Lookup localLookup() { return lookup(); }
+ }
static boolean VERBOSE = false;
@@ -152,7 +155,10 @@
getMembers(Method.class, "invoke"));
mems = callerSensitive(true, publicOnly(mems));
// CS methods cannot be looked up with publicLookup
- testOnMembersNoLookup("testCallerSensitiveNegative", mems, publicLookup());
+ testOnMembersNoLookup("testCallerSensitiveNegative/1", mems, publicLookup());
+ // CS methods have to be revealed with a matching lookupClass
+ testOnMembersNoReveal("testCallerSensitiveNegative/2", mems, Simple.localLookup(), publicLookup());
+ testOnMembersNoReveal("testCallerSensitiveNegative/3", mems, Simple.localLookup(), Nestmate.localLookup());
}
@Test public void testMethodHandleNatives() throws Throwable {
if (VERBOSE) System.out.println("@Test testMethodHandleNatives");
@@ -703,7 +709,7 @@
try {
info = revLookup.revealDirect(mh);
if (expectEx2) throw new AssertionError("unexpected revelation for negative test");
- } catch (Throwable ex2) {
+ } catch (IllegalArgumentException|SecurityException ex2) {
if (VERBOSE) System.out.println(" "+variation+": "+res+" => "+mh.getClass().getName()+" => (EX2)"+ex2);
if (expectEx2)
continue; // this is OK; we expected the reflect to fail
