--- a/jdk/src/share/classes/java/lang/invoke/LambdaConversionException.java Thu Jun 27 14:40:21 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/LambdaConversionException.java Thu Jun 27 19:02:02 2013 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -29,21 +29,45 @@
* LambdaConversionException
*/
public class LambdaConversionException extends Exception {
+ /**
+ * Constructs a {@code LambdaConversionException}.
+ */
public LambdaConversionException() {
}
+ /**
+ * Constructs a {@code LambdaConversionException} with a message.
+ * @param message the detail message
+ */
public LambdaConversionException(String message) {
super(message);
}
+ /**
+ * Constructs a {@code LambdaConversionException} with a message and cause.
+ * @param message the detail message
+ * @param cause the cause
+ */
public LambdaConversionException(String message, Throwable cause) {
super(message, cause);
}
+ /**
+ * Constructs a {@code LambdaConversionException} with a cause.
+ * @param cause the cause
+ */
public LambdaConversionException(Throwable cause) {
super(cause);
}
+ /**
+ * Constructs a {@code LambdaConversionException} with a message,
+ * cause, and other settings.
+ * @param message the detail message
+ * @param cause the cause
+ * @param enableSuppression whether or not suppressed exceptions are enabled
+ * @param writableStackTrace whether or not the stack trace is writable
+ */
public LambdaConversionException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
super(message, cause, enableSuppression, writableStackTrace);
}
--- a/jdk/src/share/classes/java/lang/invoke/LambdaMetafactory.java Thu Jun 27 14:40:21 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/LambdaMetafactory.java Thu Jun 27 19:02:02 2013 -0700
@@ -111,7 +111,7 @@
* done on return type, while a strict version is applied to arguments.
*
* <p>A type Q is considered adaptable to S as follows:
- * <table>
+ * <table summary="adaptable types">
* <tr><th>Q</th><th>S</th><th>Link-time checks</th><th>Capture-time checks</th></tr>
* <tr>
* <td>Primitive</td><td>Primitive</td>
@@ -155,7 +155,7 @@
private static final Class<?>[] EMPTY_CLASS_ARRAY = new Class<?>[0];
-/**
+ /**
* Standard meta-factory for conversion of lambda expressions or method references to functional interfaces.
*
* @param caller Stacked automatically by VM; represents a lookup context with the accessibility privileges
@@ -174,7 +174,7 @@
* @param instantiatedMethodType The signature of the primary functional interface method after type variables
* are substituted with their instantiation from the capture site
* @return a CallSite, which, when invoked, will return an instance of the functional interface
- * @throws ReflectiveOperationException
+ * @throws ReflectiveOperationException if the caller is not able to reconstruct one of the method handles
* @throws LambdaConversionException If any of the meta-factory protocol invariants are violated
*/
public static CallSite metaFactory(MethodHandles.Lookup caller,
@@ -226,7 +226,7 @@
* the first argument in the invocation signature will correspond to the receiver.
* @param args argument to pass, flags, marker interface count, and marker interfaces as described above
* @return a CallSite, which, when invoked, will return an instance of the functional interface
- * @throws ReflectiveOperationException
+ * @throws ReflectiveOperationException if the caller is not able to reconstruct one of the method handles
* @throws LambdaConversionException If any of the meta-factory protocol invariants are violated
*/
public static CallSite altMetaFactory(MethodHandles.Lookup caller,
--- a/jdk/src/share/classes/java/lang/invoke/MethodHandle.java Thu Jun 27 14:40:21 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/MethodHandle.java Thu Jun 27 19:02:02 2013 -0700
@@ -44,7 +44,7 @@
* {@linkplain java.lang.invoke.MethodHandles#dropArguments deletion},
* and {@linkplain java.lang.invoke.MethodHandles#filterArguments substitution}.
*
- * <h3>Method handle contents</h3>
+ * <h1>Method handle contents</h1>
* Method handles are dynamically and strongly typed according to their parameter and return types.
* They are not distinguished by the name or the defining class of their underlying methods.
* A method handle must be invoked using a symbolic type descriptor which matches
@@ -81,7 +81,7 @@
* from its specific class, as the method handle class hierarchy (if any)
* may change from time to time or across implementations from different vendors.
*
- * <h3>Method handle compilation</h3>
+ * <h1>Method handle compilation</h1>
* A Java method call expression naming {@code invokeExact} or {@code invoke}
* can invoke a method handle from Java source code.
* From the viewpoint of source code, these methods can take any arguments
@@ -111,7 +111,7 @@
* The ambiguity with the type {@code Void} is harmless, since there are no references of type
* {@code Void} except the null reference.
*
- * <h3>Method handle invocation</h3>
+ * <h1>Method handle invocation</h1>
* The first time a {@code invokevirtual} instruction is executed
* it is linked, by symbolically resolving the names in the instruction
* and verifying that the method call is statically legal.
@@ -154,7 +154,7 @@
* (<em>Note:</em> The adjusted method handle {@code M2} is not directly observable,
* and implementations are therefore not required to materialize it.)
*
- * <h3>Invocation checking</h3>
+ * <h1>Invocation checking</h1>
* In typical programs, method handle type matching will usually succeed.
* But if a match fails, the JVM will throw a {@link WrongMethodTypeException},
* either directly (in the case of {@code invokeExact}) or indirectly as if
@@ -195,7 +195,7 @@
* They should not be passed to untrusted code unless their use from
* the untrusted code would be harmless.
*
- * <h3>Method handle creation</h3>
+ * <h1>Method handle creation</h1>
* Java code can create a method handle that directly accesses
* any method, constructor, or field that is accessible to that code.
* This is done via a reflective, capability-based API called
@@ -249,7 +249,7 @@
* receiver type. Such a method handle simulates the effect of
* an {@code invokespecial} instruction to the same method.
*
- * <h3>Usage examples</h3>
+ * <h1>Usage examples</h1>
* Here are some examples of usage:
* <p><blockquote><pre>{@code
Object x, y; String s; int i;
@@ -295,7 +295,7 @@
* be a method which calls {@link java.util.Objects#equals(Object,Object) Objects.equals }
* on its arguments, and asserts that the result is true.
*
- * <h3>Exceptions</h3>
+ * <h1>Exceptions</h1>
* The methods {@code invokeExact} and {@code invoke} are declared
* to throw {@link java.lang.Throwable Throwable},
* which is to say that there is no static restriction on what a method handle
@@ -308,7 +308,7 @@
* throwables locally, rethrowing only those which are legal in the context,
* and wrapping ones which are illegal.
*
- * <h3><a name="sigpoly"></a>Signature polymorphism</h3>
+ * <h1><a name="sigpoly"></a>Signature polymorphism</h1>
* The unusual compilation and linkage behavior of
* {@code invokeExact} and plain {@code invoke}
* is referenced by the term <em>signature polymorphism</em>.
@@ -333,7 +333,7 @@
* Tools which determine symbolic linkage are required to accept such
* untransformed descriptors, without reporting linkage errors.
*
- * <h3>Interoperation between method handles and the Core Reflection API</h3>
+ * <h1>Interoperation between method handles and the Core Reflection API</h1>
* Using factory methods in the {@link java.lang.invoke.MethodHandles.Lookup Lookup} API,
* any class member represented by a Core Reflection API object
* can be converted to a behaviorally equivalent method handle.
@@ -375,7 +375,7 @@
* to call {@code invokeExact} or plain {@code invoke},
* for any specified type descriptor .
*
- * <h3>Interoperation between method handles and Java generics</h3>
+ * <h1>Interoperation between method handles and Java generics</h1>
* A method handle can be obtained on a method, constructor, or field
* which is declared with Java generic types.
* As with the Core Reflection API, the type of the method handle
@@ -457,6 +457,8 @@
* {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}, via JNI,
* or indirectly via {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect},
* it will throw an {@code UnsupportedOperationException}.
+ * @param args the signature-polymorphic parameter list, statically represented using varargs
+ * @return the signature-polymorphic result, statically represented using {@code Object}
* @throws WrongMethodTypeException if the target's type is not identical with the caller's symbolic type descriptor
* @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
*/
@@ -491,6 +493,8 @@
* {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke}, via JNI,
* or indirectly via {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect},
* it will throw an {@code UnsupportedOperationException}.
+ * @param args the signature-polymorphic parameter list, statically represented using varargs
+ * @return the signature-polymorphic result, statically represented using {@code Object}
* @throws WrongMethodTypeException if the target's type cannot be adjusted to the caller's symbolic type descriptor
* @throws ClassCastException if the target's type can be adjusted to the caller, but a reference cast fails
* @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
@@ -511,15 +515,26 @@
* operations on outgoing argument values.)
* The caller can assume that the incoming result value is part of the range
* of the callee's return type.
+ * @param args the signature-polymorphic parameter list, statically represented using varargs
+ * @return the signature-polymorphic result, statically represented using {@code Object}
*/
/*non-public*/ final native @PolymorphicSignature Object invokeBasic(Object... args) throws Throwable;
+ /**
+ * Private method for trusted invocation of a MemberName of kind {@code REF_invokeVirtual}.
+ * The caller signature is restricted to basic types as with {@code invokeBasic}.
+ * The trailing (not leading) argument must be a MemberName.
+ * @param args the signature-polymorphic parameter list, statically represented using varargs
+ * @return the signature-polymorphic result, statically represented using {@code Object}
+ */
/*non-public*/ static native @PolymorphicSignature Object linkToVirtual(Object... args) throws Throwable;
/**
* Private method for trusted invocation of a MemberName of kind {@code REF_invokeStatic}.
* The caller signature is restricted to basic types as with {@code invokeBasic}.
* The trailing (not leading) argument must be a MemberName.
+ * @param args the signature-polymorphic parameter list, statically represented using varargs
+ * @return the signature-polymorphic result, statically represented using {@code Object}
*/
/*non-public*/ static native @PolymorphicSignature Object linkToStatic(Object... args) throws Throwable;
@@ -527,6 +542,8 @@
* Private method for trusted invocation of a MemberName of kind {@code REF_invokeSpecial}.
* The caller signature is restricted to basic types as with {@code invokeBasic}.
* The trailing (not leading) argument must be a MemberName.
+ * @param args the signature-polymorphic parameter list, statically represented using varargs
+ * @return the signature-polymorphic result, statically represented using {@code Object}
*/
/*non-public*/ static native @PolymorphicSignature Object linkToSpecial(Object... args) throws Throwable;
@@ -534,6 +551,8 @@
* Private method for trusted invocation of a MemberName of kind {@code REF_invokeInterface}.
* The caller signature is restricted to basic types as with {@code invokeBasic}.
* The trailing (not leading) argument must be a MemberName.
+ * @param args the signature-polymorphic parameter list, statically represented using varargs
+ * @return the signature-polymorphic result, statically represented using {@code Object}
*/
/*non-public*/ static native @PolymorphicSignature Object linkToInterface(Object... args) throws Throwable;
--- a/jdk/src/share/classes/java/lang/invoke/MethodHandleProxies.java Thu Jun 27 14:40:21 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/MethodHandleProxies.java Thu Jun 27 19:02:02 2013 -0700
@@ -108,8 +108,9 @@
* Future versions of this API may also equip wrapper instances
* with one or more additional public "marker" interfaces.
*
+ * @param <T> the desired type of the wrapper, a single-method interface
+ * @param intfc a class object representing {@code T}
* @param target the method handle to invoke from the wrapper
- * @param intfc the desired type of the wrapper, a single-method interface
* @return a correctly-typed wrapper for the given target
* @throws NullPointerException if either argument is null
* @throws IllegalArgumentException if the {@code intfc} is not a
--- a/jdk/src/share/classes/java/lang/invoke/MethodHandles.java Thu Jun 27 14:40:21 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/MethodHandles.java Thu Jun 27 19:02:02 2013 -0700
@@ -70,6 +70,7 @@
* including direct method handles to 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
*/
@CallerSensitive
public static Lookup lookup() {
@@ -88,6 +89,7 @@
* {@linkplain Lookup#in <code>publicLookup().in(C.class)</code>}.
* Since all classes have equal access to public names,
* such a change would confer no new access rights.
+ * @return a lookup object which is trusted minimally
*/
public static Lookup publicLookup() {
return Lookup.PUBLIC_LOOKUP;
@@ -111,72 +113,74 @@
* on the {@code Lookup} object to create method handles for access-checked members.
* This includes all methods, constructors, and fields which are allowed to the lookup class,
* even private ones.
- * <p>
+ *
+ * <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.
* Here is a summary of the correspondence between these factory methods and
* the behavior the resulting method handles:
- * <code>
* <table border=1 cellpadding=5 summary="lookup method behaviors">
* <tr><th>lookup expression</th><th>member</th><th>behavior</th></tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}</td>
- * <td>FT f;</td><td>(T) this.f;</td>
+ * <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>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}</td>
- * <td>static<br>FT f;</td><td>(T) C.f;</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}</td>
+ * <td>{@code static}<br>{@code FT f;}</td><td>{@code (T) C.f;}</td>
* </tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findSetter lookup.findSetter(C.class,"f",FT.class)}</td>
- * <td>FT f;</td><td>this.f = x;</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#findSetter lookup.findSetter(C.class,"f",FT.class)}</td>
+ * <td>{@code FT f;}</td><td>{@code this.f = x;}</td>
* </tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findStaticSetter lookup.findStaticSetter(C.class,"f",FT.class)}</td>
- * <td>static<br>FT f;</td><td>C.f = arg;</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStaticSetter lookup.findStaticSetter(C.class,"f",FT.class)}</td>
+ * <td>{@code static}<br>{@code FT f;}</td><td>{@code C.f = arg;}</td>
* </tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findVirtual lookup.findVirtual(C.class,"m",MT)}</td>
- * <td>T m(A*);</td><td>(T) this.m(arg*);</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#findVirtual lookup.findVirtual(C.class,"m",MT)}</td>
+ * <td>{@code T m(A*);}</td><td>{@code (T) this.m(arg*);}</td>
* </tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findStatic lookup.findStatic(C.class,"m",MT)}</td>
- * <td>static<br>T m(A*);</td><td>(T) C.m(arg*);</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#findStatic lookup.findStatic(C.class,"m",MT)}</td>
+ * <td>{@code static}<br>{@code T m(A*);}</td><td>{@code (T) C.m(arg*);}</td>
* </tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findSpecial lookup.findSpecial(C.class,"m",MT,this.class)}</td>
- * <td>T m(A*);</td><td>(T) super.m(arg*);</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#findSpecial lookup.findSpecial(C.class,"m",MT,this.class)}</td>
+ * <td>{@code T m(A*);}</td><td>{@code (T) super.m(arg*);}</td>
* </tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#findConstructor lookup.findConstructor(C.class,MT)}</td>
- * <td>C(A*);</td><td>(T) new C(arg*);</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#findConstructor lookup.findConstructor(C.class,MT)}</td>
+ * <td>{@code C(A*);}</td><td>{@code new C(arg*);}</td>
* </tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#unreflectGetter lookup.unreflectGetter(aField)}</td>
- * <td>(static)?<br>FT f;</td><td>(FT) aField.get(thisOrNull);</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectGetter lookup.unreflectGetter(aField)}</td>
+ * <td>({@code static})?<br>{@code FT f;}</td><td>{@code (FT) aField.get(thisOrNull);}</td>
* </tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#unreflectSetter lookup.unreflectSetter(aField)}</td>
- * <td>(static)?<br>FT f;</td><td>aField.set(thisOrNull, arg);</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectSetter lookup.unreflectSetter(aField)}</td>
+ * <td>({@code static})?<br>{@code FT f;}</td><td>{@code aField.set(thisOrNull, arg);}</td>
+ * </tr>
+ * <tr>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
+ * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
* </tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
- * <td>(static)?<br>T m(A*);</td><td>(T) aMethod.invoke(thisOrNull, arg*);</td>
- * </tr>
- * <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#unreflectConstructor lookup.unreflectConstructor(aConstructor)}</td>
- * <td>C(A*);</td><td>(C) aConstructor.newInstance(arg*);</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflectConstructor lookup.unreflectConstructor(aConstructor)}</td>
+ * <td>{@code C(A*);}</td><td>{@code (C) aConstructor.newInstance(arg*);}</td>
* </tr>
* <tr>
- * <td>{@linkplain java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
- * <td>(static)?<br>T m(A*);</td><td>(T) aMethod.invoke(thisOrNull, arg*);</td>
+ * <td>{@link java.lang.invoke.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}</td>
+ * <td>({@code static})?<br>{@code T m(A*);}</td><td>{@code (T) aMethod.invoke(thisOrNull, arg*);}</td>
* </tr>
* </table>
- * </code>
+ *
* Here, the type {@code C} is the class or interface being searched for a member,
* documented as a parameter named {@code refc} in the lookup methods.
- * The method or constructor type {@code MT} is composed from the return type {@code T}
+ * The method type {@code MT} is composed from the return type {@code T}
* and the sequence of argument types {@code A*}.
+ * The constructor also has a sequence of argument types {@code A*} and
+ * is deemed to return the newly-created object of type {@code C}.
* Both {@code MT} and the field type {@code FT} are documented as a parameter named {@code type}.
* The formal parameter {@code this} stands for the self-reference of type {@code C};
* if it is present, it is always the leading argument to the method handle invocation.
@@ -210,7 +214,7 @@
* security manager checks.
* </ul>
*
- * <h3><a name="access"></a>Access checking</h3>
+ * <h1><a name="access"></a>Access checking</h1>
* Access checks are applied in the factory methods of {@code Lookup},
* when a method handle is created.
* This is a key difference from the Core Reflection API, since
@@ -297,7 +301,7 @@
* with static methods of {@link MethodHandles},
* independently of any {@code Lookup} object.
*
- * <h3>Security manager interactions</h3>
+ * <h1>Security manager interactions</h1>
* <a name="secmgr"></a>
* If a security manager is present, member lookups are subject to
* additional checks.
@@ -388,6 +392,7 @@
* but the permissions may be additionally limited by the bitmask
* {@link #lookupModes lookupModes}, which controls whether non-public members
* can be accessed.
+ * @return the lookup class, on behalf of which this lookup object finds members
*/
public Class<?> lookupClass() {
return lookupClass;
@@ -414,6 +419,7 @@
* The purpose of this is to restrict access via the new lookup object,
* so that it can access only names which can be reached by the original
* lookup object, and also by the new lookup class.
+ * @return the lookup modes, which limit the kinds of access performed by this lookup object
*/
public int lookupModes() {
return allowedModes & ALL_MODES;
@@ -1352,6 +1358,7 @@
* The type of the method handle will have a void return type.
* Its last argument will be the array's element type.
* The first and second arguments will be the array type and int.
+ * @param arrayClass the class of an array
* @return a method handle which can store values into the array type
* @throws NullPointerException if the argument is null
* @throws IllegalArgumentException if arrayClass is not an array type
@@ -1580,12 +1587,12 @@
...
MethodType intfn1 = methodType(int.class, int.class);
MethodType intfn2 = methodType(int.class, int.class, int.class);
-MethodHandle sub = ... {int x, int y => x-y} ...;
+MethodHandle sub = ... (int x, int y) -> (x-y) ...;
assert(sub.type().equals(intfn2));
MethodHandle sub1 = permuteArguments(sub, intfn2, 0, 1);
MethodHandle rsub = permuteArguments(sub, intfn2, 1, 0);
assert((int)rsub.invokeExact(1, 100) == 99);
-MethodHandle add = ... {int x, int y => x+y} ...;
+MethodHandle add = ... (int x, int y) -> (x+y) ...;
assert(add.type().equals(intfn2));
MethodHandle twice = permuteArguments(add, intfn1, 0, 0);
assert(twice.type().equals(intfn1));
@@ -2261,6 +2268,8 @@
* The method type will nominally specify a return of {@code returnType}.
* The return type may be anything convenient: It doesn't matter to the
* method handle's behavior, since it will never return normally.
+ * @param returnType the return type of the desired method handle
+ * @param exType the parameter type of the desired method handle
* @return method handle which can throw the given exceptions
* @throws NullPointerException if either argument is null
*/
--- a/jdk/src/share/classes/java/lang/invoke/MethodType.java Thu Jun 27 14:40:21 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/MethodType.java Thu Jun 27 19:02:02 2013 -0700
@@ -194,6 +194,8 @@
/**
* Finds or creates a method type with the given components.
* Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
+ * @param rtype the return type
+ * @param ptypes the parameter types
* @return a method type with the given components
* @throws NullPointerException if {@code rtype} or {@code ptypes} or any element of {@code ptypes} is null
* @throws IllegalArgumentException if any element of {@code ptypes} is {@code void.class}
@@ -214,6 +216,9 @@
* Finds or creates a method type with the given components.
* Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
* The leading parameter type is prepended to the remaining array.
+ * @param rtype the return type
+ * @param ptype0 the first parameter type
+ * @param ptypes the remaining parameter types
* @return a method type with the given components
* @throws NullPointerException if {@code rtype} or {@code ptype0} or {@code ptypes} or any element of {@code ptypes} is null
* @throws IllegalArgumentException if {@code ptype0} or {@code ptypes} or any element of {@code ptypes} is {@code void.class}
@@ -230,6 +235,7 @@
* Finds or creates a method type with the given components.
* Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
* The resulting method has no parameter types.
+ * @param rtype the return type
* @return a method type with the given return value
* @throws NullPointerException if {@code rtype} is null
*/
@@ -242,6 +248,8 @@
* Finds or creates a method type with the given components.
* Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
* The resulting method has the single given parameter type.
+ * @param rtype the return type
+ * @param ptype0 the parameter type
* @return a method type with the given return value and parameter type
* @throws NullPointerException if {@code rtype} or {@code ptype0} is null
* @throws IllegalArgumentException if {@code ptype0} is {@code void.class}
@@ -256,6 +264,9 @@
* Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
* The resulting method has the same parameter types as {@code ptypes},
* and the specified return type.
+ * @param rtype the return type
+ * @param ptypes the method type which supplies the parameter types
+ * @return a method type with the given components
* @throws NullPointerException if {@code rtype} or {@code ptypes} is null
*/
public static
@@ -938,7 +949,8 @@
* provided to the factory method {@link #methodType(Class,Class[]) methodType}.
* For example, null values, or {@code void} parameter types,
* will lead to exceptions during deserialization.
- * @param the stream to write the object to
+ * @param s the stream to write the object to
+ * @throws java.io.IOException if there is a problem writing the object
*/
private void writeObject(java.io.ObjectOutputStream s) throws java.io.IOException {
s.defaultWriteObject(); // requires serialPersistentFields to be an empty array
@@ -953,7 +965,9 @@
* It provides the parameters to the factory method called by
* {@link #readResolve readResolve}.
* After that call it is discarded.
- * @param the stream to read the object from
+ * @param s the stream to read the object from
+ * @throws java.io.IOException if there is a problem reading the object
+ * @throws ClassNotFoundException if one of the component classes cannot be resolved
* @see #MethodType()
* @see #readResolve
* @see #writeObject
--- a/jdk/src/share/classes/java/lang/invoke/MutableCallSite.java Thu Jun 27 14:40:21 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/MutableCallSite.java Thu Jun 27 19:02:02 2013 -0700
@@ -195,7 +195,7 @@
* processed before the method returns abnormally.
* Which elements these are (if any) is implementation-dependent.
*
- * <h3>Java Memory Model details</h3>
+ * <h1>Java Memory Model details</h1>
* In terms of the Java Memory Model, this operation performs a synchronization
* action which is comparable in effect to the writing of a volatile variable
* by the current thread, and an eventual volatile read by every other thread
--- a/jdk/src/share/classes/java/lang/invoke/SerializedLambda.java Thu Jun 27 14:40:21 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/SerializedLambda.java Thu Jun 27 19:02:02 2013 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -97,66 +97,113 @@
this.capturedArgs = Objects.requireNonNull(capturedArgs).clone();
}
- /** Get the name of the class that captured this lambda */
+ /**
+ * Get the name of the class that captured this lambda.
+ * @return the name of the class that captured this lambda
+ */
public String getCapturingClass() {
return capturingClass.getName().replace('.', '/');
}
- /** Get the name of the functional interface class to which this lambda has been converted */
+ /**
+ * Get the name of the functional interface class to which this
+ * lambda has been converted
+ * @return the name of the functional interface this lambda has
+ * been converted to
+ */
public String getFunctionalInterfaceClass() {
return functionalInterfaceClass;
}
- /** Get the name of the primary method for the functional interface to which this lambda has been converted */
+ /**
+ * Get the name of the primary method for the functional interface
+ * to which this lambda has been converted.
+ * @return the name of the primary methods of the functional interface
+ */
public String getFunctionalInterfaceMethodName() {
return functionalInterfaceMethodName;
}
- /** Get the signature of the primary method for the functional interface to which this lambda has been converted */
+ /**
+ * Get the signature of the primary method for the functional
+ * interface to which this lambda has been converted.
+ * @return the signature of the primary method of the functional
+ * interface
+ */
public String getFunctionalInterfaceMethodSignature() {
return functionalInterfaceMethodSignature;
}
- /** Get the method handle kind (see {@link MethodHandleInfo}) of the primary method for the functional interface
- * to which this lambda has been converted */
+ /**
+ * Get the method handle kind (see {@link MethodHandleInfo}) of
+ * the primary method for the functional interface to which this
+ * lambda has been converted
+ * @return the method handle kind of the primary method of
+ * functional interface
+ */
public int getFunctionalInterfaceMethodKind() {
return functionalInterfaceMethodKind;
}
- /** Get the name of the class containing the implementation method */
+ /**
+ * Get the name of the class containing the implementation
+ * method.
+ * @return the name of the class containing the implementation
+ * method
+ */
public String getImplClass() {
return implClass;
}
- /** Get the name of the implementation method */
+ /**
+ * Get the name of the implementation method.
+ * @return the name of the implementation method
+ */
public String getImplMethodName() {
return implMethodName;
}
- /** Get the signature of the implementation method */
+ /**
+ * Get the signature of the implementation method.
+ * @return the signature of the implementation method
+ */
public String getImplMethodSignature() {
return implMethodSignature;
}
- /** Get the method handle kind (see {@link MethodHandleInfo}) of the implementation method */
+ /**
+ * Get the method handle kind (see {@link MethodHandleInfo}) of
+ * the implementation method.
+ * @return the method handle kind of the implementation method
+ */
public int getImplMethodKind() {
return implMethodKind;
}
/**
- * Get the signature of the primary functional interface method after type variables are substituted with
- * their instantiation from the capture site
+ * Get the signature of the primary functional interface method
+ * after type variables are substituted with their instantiation
+ * from the capture site.
+ * @return the signature of the primary functional interface method
+ * after type variable processing
*/
public final String getInstantiatedMethodType() {
return instantiatedMethodType;
}
- /** Get the count of dynamic arguments to the lambda capture site */
+ /**
+ * Get the count of dynamic arguments to the lambda capture site.
+ * @return the count of dynamic arguments to the lambda capture site
+ */
public int getCapturedArgCount() {
return capturedArgs.length;
}
- /** Get a dynamic argument to the lambda capture site */
+ /**
+ * Get a dynamic argument to the lambda capture site.
+ * @param i the argument to capture
+ * @return a dynamic argument to the lambda capture site
+ */
public Object getCapturedArg(int i) {
return capturedArgs[i];
}
--- a/jdk/src/share/classes/java/lang/invoke/package-info.java Thu Jun 27 14:40:21 2013 -0700
+++ b/jdk/src/share/classes/java/lang/invoke/package-info.java Thu Jun 27 19:02:02 2013 -0700
@@ -43,13 +43,13 @@
* </li>
* </ul>
*
- * <h2><a name="jvm_mods"></a>Summary of relevant Java Virtual Machine changes</h2>
+ * <h1><a name="jvm_mods"></a>Summary of relevant Java Virtual Machine changes</h1>
* The following low-level information summarizes relevant parts of the
* Java Virtual Machine specification. For full details, please see the
* current version of that specification.
*
* Each occurrence of an {@code invokedynamic} instruction is called a <em>dynamic call site</em>.
- * <h3><a name="indyinsn"></a>{@code invokedynamic} instructions</h3>
+ * <h2><a name="indyinsn"></a>{@code invokedynamic} instructions</h2>
* A dynamic call site is originally in an unlinked state. In this state, there is
* no target method for the call site to invoke.
* <p>
@@ -97,7 +97,7 @@
* If this happens, the same error will the thrown for all subsequent
* attempts to execute the dynamic call site.
*
- * <h3>timing of linkage</h3>
+ * <h2>timing of linkage</h2>
* A dynamic call site is linked just before its first execution.
* The bootstrap method call implementing the linkage occurs within
* a thread that is attempting a first execution.
@@ -131,7 +131,7 @@
* just before its first invocation.
* There is no way to undo the effect of a completed bootstrap method call.
*
- * <h3>types of bootstrap methods</h3>
+ * <h2>types of bootstrap methods</h2>
* As long as each bootstrap method can be correctly invoked
* by {@code MethodHandle.invoke}, its detailed type is arbitrary.
* For example, the first argument could be {@code Object}