changeset 10389:5fa2fd782993

8019646: Clarify javadoc contract of LambdaMetafactory Reviewed-by: briangoetz, rfield Contributed-by: dan.smith@oracle.com
author briangoetz
date Thu, 24 Oct 2013 13:06:05 -0400
parents 808b9ef4f667
children 93e696ba5923
files src/share/classes/java/lang/invoke/AbstractValidatingLambdaMetafactory.java src/share/classes/java/lang/invoke/InnerClassLambdaMetafactory.java src/share/classes/java/lang/invoke/LambdaMetafactory.java
diffstat 3 files changed, 327 insertions(+), 176 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/lang/invoke/AbstractValidatingLambdaMetafactory.java	Thu Oct 24 10:13:39 2013 -0700
+++ b/src/share/classes/java/lang/invoke/AbstractValidatingLambdaMetafactory.java	Thu Oct 24 13:06:05 2013 -0400
@@ -101,7 +101,6 @@
      *                       should implement.
      * @param additionalBridges Method types for additional signatures to be
      *                          bridged to the implementation method
-     * @throws ReflectiveOperationException
      * @throws LambdaConversionException If any of the meta-factory protocol
      * invariants are violated
      */
@@ -114,7 +113,7 @@
                                        boolean isSerializable,
                                        Class<?>[] markerInterfaces,
                                        MethodType[] additionalBridges)
-            throws ReflectiveOperationException, LambdaConversionException {
+            throws LambdaConversionException {
         this.targetClass = caller.lookupClass();
         this.invokedType = invokedType;
 
@@ -160,7 +159,7 @@
      * @throws ReflectiveOperationException
      */
     abstract CallSite buildCallSite()
-            throws ReflectiveOperationException, LambdaConversionException;
+            throws LambdaConversionException;
 
     /**
      * Check the meta-factory arguments for errors
--- a/src/share/classes/java/lang/invoke/InnerClassLambdaMetafactory.java	Thu Oct 24 10:13:39 2013 -0700
+++ b/src/share/classes/java/lang/invoke/InnerClassLambdaMetafactory.java	Thu Oct 24 13:06:05 2013 -0400
@@ -128,7 +128,6 @@
      *                       should implement.
      * @param additionalBridges Method types for additional signatures to be
      *                          bridged to the implementation method
-     * @throws ReflectiveOperationException
      * @throws LambdaConversionException If any of the meta-factory protocol
      * invariants are violated
      */
@@ -141,7 +140,7 @@
                                        boolean isSerializable,
                                        Class<?>[] markerInterfaces,
                                        MethodType[] additionalBridges)
-            throws ReflectiveOperationException, LambdaConversionException {
+            throws LambdaConversionException {
         super(caller, invokedType, samMethodName, samMethodType,
               implMethod, instantiatedMethodType,
               isSerializable, markerInterfaces, additionalBridges);
@@ -179,7 +178,7 @@
      * is not found
      */
     @Override
-    CallSite buildCallSite() throws ReflectiveOperationException, LambdaConversionException {
+    CallSite buildCallSite() throws LambdaConversionException {
         final Class<?> innerClass = spinInnerClass();
         if (invokedType.parameterCount() == 0) {
             final Constructor[] ctrs = AccessController.doPrivileged(
@@ -190,7 +189,7 @@
                 }
             });
             if (ctrs.length != 1) {
-                throw new ReflectiveOperationException("Expected one lambda constructor for "
+                throw new LambdaConversionException("Expected one lambda constructor for "
                         + innerClass.getCanonicalName() + ", got " + ctrs.length);
             }
             // The lambda implementing inner class constructor is private, set
@@ -202,13 +201,23 @@
                     return null;
                 }
             });
-            Object inst = ctrs[0].newInstance();
-            return new ConstantCallSite(MethodHandles.constant(samBase, inst));
+            try {
+                Object inst = ctrs[0].newInstance();
+                return new ConstantCallSite(MethodHandles.constant(samBase, inst));
+            }
+            catch (ReflectiveOperationException e) {
+                throw new LambdaConversionException("Exception instantiating lambda object", e);
+            }
         } else {
-            return new ConstantCallSite(
-                    MethodHandles.Lookup.IMPL_LOOKUP
-                         .findConstructor(innerClass, constructorType)
-                         .asType(constructorType.changeReturnType(samBase)));
+            try {
+                return new ConstantCallSite(
+                        MethodHandles.Lookup.IMPL_LOOKUP
+                             .findConstructor(innerClass, constructorType)
+                             .asType(constructorType.changeReturnType(samBase)));
+            }
+            catch (ReflectiveOperationException e) {
+                throw new LambdaConversionException("Exception finding constructor", e);
+            }
         }
     }
 
--- a/src/share/classes/java/lang/invoke/LambdaMetafactory.java	Thu Oct 24 10:13:39 2013 -0700
+++ b/src/share/classes/java/lang/invoke/LambdaMetafactory.java	Thu Oct 24 13:06:05 2013 -0400
@@ -29,88 +29,128 @@
 import java.util.Arrays;
 
 /**
- * <p>Bootstrap methods for converting lambda expressions and method references to functional interface objects.</p>
+ * <p>Methods to facilitate the creation of simple "function objects" that
+ * implement one or more interfaces by delegation to a provided {@link MethodHandle},
+ * possibly after type adaptation and partial evaluation of arguments.  These
+ * methods are typically used as <em>bootstrap methods</em> for {@code invokedynamic}
+ * call sites, to support the <em>lambda expression</em> and <em>method
+ * reference expression</em> features of the Java Programming Language.
  *
- * <p>For every lambda expressions or method reference in the source code, there is a target type which is a
- * functional interface. Evaluating a lambda expression produces an object of its target type. The mechanism for
- * evaluating lambda expressions is to invoke an invokedynamic call site, which takes arguments describing the sole
- * method of the functional interface and the implementation method, and returns an object (the lambda object) that
- * implements the target type. Methods of the lambda object invoke the implementation method. For method
- * references, the implementation method is simply the referenced method; for lambda expressions, the
- * implementation method is produced by the compiler based on the body of the lambda expression. The methods in
- * this file are the bootstrap methods for those invokedynamic call sites, called lambda factories, and the
- * bootstrap methods responsible for linking the lambda factories are called lambda meta-factories.
+ * <p>Indirect access to the behavior specified by the provided {@code MethodHandle}
+ * proceeds in order through three phases:
+ * <ul>
+ *     <li><em>Linkage</em> occurs when the methods in this class are invoked.
+ *     They take as arguments an interface to be implemented (typically a
+ *     <em>functional interface</em>, one with a single abstract method), a
+ *     name and signature of a method from that interface to be implemented, a
+ *     method handle describing the desired implementation behavior
+ *     for that method, and possibly other additional metadata, and produce a
+ *     {@link CallSite} whose target can be used to create suitable function
+ *     objects.  Linkage may involve dynamically loading a new class that
+ *     implements the target interface. The {@code CallSite} can be considered a
+ *     "factory" for function objects and so these linkage methods are referred
+ *     to as "metafactories".</li>
  *
- * <p>The bootstrap methods in this class take the information about the functional interface, the implementation
- * method, and the static types of the captured lambda arguments, and link a call site which, when invoked,
- * produces the lambda object.
+ *     <li><em>Capture</em> occurs when the {@code CallSite}'s target is
+ *     invoked, typically through an {@code invokedynamic} call site,
+ *     producing a function object.  This may occur many times for
+ *     a single factory {@code CallSite}.  Capture may involve allocation of a
+ *     new function object, or may return an existing function object.  The
+ *     behavior {@code MethodHandle} may have additional parameters beyond those
+ *     of the specified interface method; these are referred to as <em>captured
+ *     parameters</em>, which must be provided as arguments to the
+ *     {@code CallSite} target, and which may be early-bound to the behavior
+ *     {@code MethodHandle}.  The number of captured parameters and their types
+ *     are determined during linkage.</li>
  *
- * <p>When parameterized types are used, the instantiated type of the functional interface method may be different
- * from that in the functional interface. For example, consider
- * {@code interface I<T> { int m(T x); }} if this functional interface type is used in a lambda
- * {@code I<Byte>; v = ...}, we need both the actual functional interface method which has the signature
- * {@code (Object)int} and the erased instantiated type of the functional interface method (or simply
- * <I>instantiated method type</I>), which has signature
- * {@code (Byte)int}.
- *
- * <p>The argument list of the implementation method and the argument list of the functional interface method(s)
- * may differ in several ways.  The implementation methods may have additional arguments to accommodate arguments
- * captured by the lambda expression; there may also be differences resulting from permitted adaptations of
- * arguments, such as casting, boxing, unboxing, and primitive widening. They may also differ because of var-args,
- * but this is expected to be handled by the compiler.
- *
- * <p>Invokedynamic call sites have two argument lists: a static argument list and a dynamic argument list.  The
- * static argument list lives in the constant pool; the dynamic argument list lives on the operand stack at
- * invocation time.  The bootstrap method has access to the entire static argument list (which in this case,
- * contains method handles describing the implementation method and the canonical functional interface method),
- * as well as a method signature describing the number and static types (but not the values) of the dynamic
- * arguments, and the static return type of the invokedynamic site.
- *
- * <p>The implementation method is described with a method handle. In theory, any method handle could be used.
- * Currently supported are method handles representing invocation of virtual, interface, constructor and static
- * methods.
- *
- * <p>Assume:
- * <ul>
- *      <li>the functional interface method has N arguments, of types (U1, U2, ... Un) and return type Ru</li>
- *      <li>then the instantiated method type also has N arguments, of types (T1, T2, ... Tn) and return type Rt</li>
- *      <li>the implementation method has M arguments, of types (A1..Am) and return type Ra,</li>
- *      <li>the dynamic argument list has K arguments of types (D1..Dk), and the invokedynamic return site has
- *          type Rd</li>
- *      <li>the functional interface type is F</li>
+ *     <li><em>Invocation</em> occurs when an implemented interface method
+ *     is invoked on a function object.  This may occur many times for a single
+ *     function object.  The method referenced by the behavior {@code MethodHandle}
+ *     is invoked with the captured arguments and any additional arguments
+ *     provided on invocation, as if by {@link MethodHandle#invoke(Object...)}.</li>
  * </ul>
  *
- * <p>The following signature invariants must hold:
+ * <p>It is sometimes useful to restrict the set of inputs or results permitted
+ * at invocation.  For example, when the generic interface {@code Predicate<T>}
+ * is parameterized as {@code Predicate<String>}, the input must be a
+ * {@code String}, even though the method to implement allows any {@code Object}.
+ * At linkage time, an additional {@link MethodType} parameter describes the
+ * "instantiated" method type; on invocation, the arguments and eventual result
+ * are checked against this {@code MethodType}.
+ *
+ * <p>This class provides two forms of linkage methods: a standard version
+ * ({@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)})
+ * using an optimized protocol, and an alternate version
+ * {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}).
+ * The alternate version is a generalization of the standard version, providing
+ * additional control over the behavior of the generated function objects via
+ * flags and additional arguments.  The alternate version adds the ability to
+ * manage the following attributes of function objects:
+ *
  * <ul>
- *     <li>Rd is a subtype of F</li>
- *     <li>For i=1..N, Ti is a subtype of Ui</li>
- *     <li>Either Rt and Ru are primitive and are the same type, or both are reference types and
- *         Rt is a subtype of Ru</li>
- *     <li>If the implementation method is a static method:
- *     <ul>
- *         <li>K + N = M</li>
- *         <li>For i=1..K, Di = Ai</li>
- *         <li>For i=1..N, Ti is adaptable to Aj, where j=i+k</li>
- *     </ul></li>
- *     <li>If the implementation method is an instance method:
- *     <ul>
- *         <li>K + N = M + 1</li>
- *         <li>D1 must be a subtype of the enclosing class for the implementation method</li>
- *         <li>For i=2..K, Di = Aj, where j=i-1</li>
- *         <li>For i=1..N, Ti is adaptable to Aj, where j=i+k-1</li>
- *     </ul></li>
- *     <li>The return type Rt is void, or the return type Ra is not void and is adaptable to Rt</li>
+ *     <li><em>Bridging.</em>  It is sometimes useful to implement multiple
+ *     variations of the method signature, involving argument or return type
+ *     adaptation.  This occurs when multiple distinct VM signatures for a method
+ *     are logically considered to be the same method by the language.  The
+ *     flag {@code FLAG_BRIDGES} indicates that a list of additional
+ *     {@code MethodType}s will be provided, each of which will be implemented
+ *     by the resulting function object.  These methods will share the same
+ *     name and instantiated type.</li>
+ *
+ *     <li><em>Multiple interfaces.</em>  If needed, more than one interface
+ *     can be implemented by the function object.  (These additional interfaces
+ *     are typically marker interfaces with no methods.)  The flag {@code FLAG_MARKERS}
+ *     indicates that a list of additional interfaces will be provided, each of
+ *     which should be implemented by the resulting function object.</li>
+ *
+ *     <li><em>Serializability.</em>  The generated function objects do not
+ *     generally support serialization.  If desired, {@code FLAG_SERIALIZABLE}
+ *     can be used to indicate that the function objects should be serializable.
+ *     Serializable function objects will use, as their serialized form,
+ *     instances of the class {@code SerializedLambda}, which requires additional
+ *     assistance from the capturing class (the class described by the
+ *     {@link MethodHandles.Lookup} parameter {@code caller}); see
+ *     {@link SerializedLambda} for details.</li>
  * </ul>
  *
- * <p>Note that the potentially parameterized implementation return type provides the value for the SAM. Whereas
- * the completely known instantiated return type is adapted to the implementation arguments. Because the
- * instantiated type of the implementation method is not available, the adaptability of return types cannot be
- * checked as precisely at link-time as the arguments can be checked. Thus a loose version of link-time checking is
- * done on return type, while a strict version is applied to arguments.
+ * <p>Assume the linkage arguments are as follows:
+ * <ul>
+ *      <li>{@code invokedType} (describing the {@code CallSite} signature) has
+ *      K parameters of types (D1..Dk) and return type Rd;</li>
+ *      <li>{@code samMethodType} (describing the implemented method type) has N
+ *      parameters, of types (U1..Un) and return type Ru;</li>
+ *      <li>{@code implMethod} (the {@code MethodHandle} providing the
+ *      implementation has M parameters, of types (A1..Am) and return type Ra
+ *      (if the method describes an instance method, the method type of this
+ *      method handle already includes an extra first argument corresponding to
+ *      the receiver);</li>
+ *      <li>{@code instantiatedMethodType} (allowing restrictions on invocation)
+ *      has N parameters, of types (T1..Tn) and return type Rt.</li>
+ * </ul>
+ *
+ * <p>Then the following linkage invariants must hold:
+ * <ul>
+ *     <li>Rd is an interface</li>
+ *     <li>{@code implMethod} is a <em>direct method handle</em></li>
+ *     <li>{@code samMethodType} and {@code instantiatedMethodType} have the same
+ *     arity N, and for i=1..N, Ti and Ui are the same type, or Ti and Ui are
+ *     both reference types and Ti is a subtype of Ui</li>
+ *     <li>Either Rt and Ru are the same type, or both are reference types and
+ *     Rt is a subtype of Ru</li>
+ *     <li>K + N = M</li>
+ *     <li>For i=1..K, Di = Ai</li>
+ *     <li>For i=1..N, Ti is adaptable to Aj, where j=i+k</li>
+ *     <li>The return type Rt is void, or the return type Ra is not void and is
+ *     adaptable to Rt</li>
+ * </ul>
+ *
+ * <p>Further, at capture time, if {@code implMethod} corresponds to an instance
+ * method, and there are any capture arguments ({@code K > 0}), then the first
+ * capture argument (corresponding to the receiver) must be non-null.
  *
  * <p>A type Q is considered adaptable to S as follows:
  * <table summary="adaptable types">
- *     <tr><th>Q</th><th>S</th><th>Link-time checks</th><th>Capture-time checks</th></tr>
+ *     <tr><th>Q</th><th>S</th><th>Link-time checks</th><th>Invocation-time checks</th></tr>
  *     <tr>
  *         <td>Primitive</td><td>Primitive</td>
  *         <td>Q can be converted to S via a primitive widening conversion</td>
@@ -123,27 +163,59 @@
  *     </tr>
  *     <tr>
  *         <td>Reference</td><td>Primitive</td>
- *         <td>strict: Q is a primitive wrapper and Primitive(Q) can be widened to S
- *         <br>loose: If Q is a primitive wrapper, check that Primitive(Q) can be widened to S</td>
- *         <td>If Q is not a primitive wrapper, cast Q to the base Wrapper(S); for example Number for numeric types</td>
+ *         <td>for parameter types: Q is a primitive wrapper and Primitive(Q)
+ *         can be widened to S
+ *         <br>for return types: If Q is a primitive wrapper, check that
+ *         Primitive(Q) can be widened to S</td>
+ *         <td>If Q is not a primitive wrapper, cast Q to the base Wrapper(S);
+ *         for example Number for numeric types</td>
  *     </tr>
  *     <tr>
  *         <td>Reference</td><td>Reference</td>
- *         <td>strict: S is a supertype of Q
- *         <br>loose: none</td>
+ *         <td>for parameter types: S is a supertype of Q
+ *         <br>for return types: none</td>
  *         <td>Cast from Q to S</td>
  *     </tr>
  * </table>
  *
- * The default bootstrap ({@link #metafactory}) represents the common cases and uses an optimized protocol.
- * Alternate bootstraps (e.g., {@link #altMetafactory}) exist to support uncommon cases such as serialization
- * or additional marker superinterfaces.
+ * @apiNote These linkage methods are designed to support the evaluation
+ * of <em>lambda expressions</em> and <em>method references</em> in the Java
+ * Language.  For every lambda expressions or method reference in the source code,
+ * there is a target type which is a functional interface.  Evaluating a lambda
+ * expression produces an object of its target type. The recommended mechanism
+ * for evaluating lambda expressions is to desugar the lambda body to a method,
+ * invoke an invokedynamic call site whose static argument list describes the
+ * sole method of the functional interface and the desugared implementation
+ * method, and returns an object (the lambda object) that implements the target
+ * type. (For method references, the implementation method is simply the
+ * referenced method; no desugaring is needed.)
  *
+ * <p>The argument list of the implementation method and the argument list of
+ * the interface method(s) may differ in several ways.  The implementation
+ * methods may have additional arguments to accommodate arguments captured by
+ * the lambda expression; there may also be differences resulting from permitted
+ * adaptations of arguments, such as casting, boxing, unboxing, and primitive
+ * widening. (Varargs adaptations are not handled by the metafactories; these are
+ * expected to be handled by the caller.)
+ *
+ * <p>Invokedynamic call sites have two argument lists: a static argument list
+ * and a dynamic argument list.  The static argument list is stored in the
+ * constant pool; the dynamic argument is pushed on the operand stack at capture
+ * time.  The bootstrap method has access to the entire static argument list
+ * (which in this case, includes information describing the implementation method,
+ * the target interface, and the target interface method(s)), as well as a
+ * method signature describing the number and static types (but not the values)
+ * of the dynamic arguments and the static return type of the invokedynamic site.
+ *
+ * @implNote The implementation method is described with a method handle. In
+ * theory, any method handle could be used. Currently supported are direct method
+ * handles representing invocation of virtual, interface, constructor and static
+ * methods.
  */
 public class LambdaMetafactory {
 
-    /** Flag for alternate metafactories indicating the lambda object is
-     * must to be serializable */
+    /** Flag for alternate metafactories indicating the lambda object
+     * must be serializable */
     public static final int FLAG_SERIALIZABLE = 1 << 0;
 
     /**
@@ -163,41 +235,58 @@
     private static final MethodType[] EMPTY_MT_ARRAY = new MethodType[0];
 
     /**
-     * Standard meta-factory for conversion of lambda expressions or method
-     * references to functional interfaces.
+     * Facilitates the creation of simple "function objects" that implement one
+     * or more interfaces by delegation to a provided {@link MethodHandle},
+     * after appropriate type adaptation and partial evaluation of arguments.
+     * Typically used as a <em>bootstrap method</em> for {@code invokedynamic}
+     * call sites, to support the <em>lambda expression</em> and <em>method
+     * reference expression</em> features of the Java Programming Language.
      *
-     * @param caller Stacked automatically by VM; represents a lookup context
-     *                   with the accessibility privileges of the caller.
-     * @param invokedName Stacked automatically by VM; the name of the invoked
-     *                    method as it appears at the call site.
-     *                    Used as the name of the functional interface method
-     *                    to which the lambda or method reference is being
-     *                    converted.
-     * @param invokedType Stacked automatically by VM; the signature of the
-     *                    invoked method, which includes the expected static
-     *                    type of the returned lambda object, and the static
-     *                    types of the captured arguments for the lambda.
+     * <p>This is the standard, streamlined metafactory; additional flexibility
+     * is provided by {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}.
+     * A general description of the behavior of this method is provided
+     * {@link LambdaMetafactory above}.
+     *
+     * <p>When the target of the {@code CallSite} returned from this method is
+     * invoked, the resulting function objects are instances of a class which
+     * implements the interface named by the return type of {@code invokedType},
+     * declares a method with the name given by {@code invokedName} and the
+     * signature given by {@code samMethodType}.  It may also override additional
+     * methods from {@code Object}.
+     *
+     * @param caller Represents a lookup context with the accessibility
+     *               privileges of the caller.  When used with {@code invokedynamic},
+     *               this is stacked automatically by the VM.
+     * @param invokedName The name of the method to implement.  When used with
+     *                    {@code invokedynamic}, this is provided by the
+     *                    {@code NameAndType} of the {@code InvokeDynamic}
+     *                    structure and is stacked automatically by the VM.
+     * @param invokedType The expected signature of the {@code CallSite}.  The
+     *                    parameter types represent the types of capture variables;
+     *                    the return type is the interface to implement.   When
+     *                    used with {@code invokedynamic}, this is provided by
+     *                    the {@code NameAndType} of the {@code InvokeDynamic}
+     *                    structure and is stacked automatically by the VM.
      *                    In the event that the implementation method is an
-     *                    instance method, the first argument in the invocation
-     *                    signature will correspond to the receiver.
-     * @param samMethodType MethodType of the method in the functional interface
-     *                      to which the lambda or method reference is being
-     *                      converted, represented as a MethodType.
+     *                    instance method and this signature has any parameters,
+     *                    the first parameter in the invocation signature must
+     *                    correspond to the receiver.
+     * @param samMethodType Signature and return type of method to be implemented
+     *                      by the function object.
      * @param implMethod A direct method handle describing the implementation
      *                   method which should be called (with suitable adaptation
-     *                   of argument types, return types, and adjustment for
-     *                   captured arguments) when methods of the resulting
-     *                   functional interface instance are invoked.
-     * @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 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
+     *                   of argument types, return types, and with captured
+     *                   arguments prepended to the invocation arguments) at
+     *                   invocation time.
+     * @param instantiatedMethodType The signature and return type that should
+     *                               be enforced dynamically at invocation time.
+     *                               This may be the same as {@code samMethodType},
+     *                               or may be a specialization of it.
+     * @return a CallSite whose target can be used to perform capture, generating
+     *         instances of the interface named by {@code invokedType}
+     * @throws LambdaConversionException If any of the linkage invariants
+     *                                   described {@link LambdaMetafactory above}
+     *                                   are violated
      */
     public static CallSite metafactory(MethodHandles.Lookup caller,
                                        String invokedName,
@@ -205,7 +294,7 @@
                                        MethodType samMethodType,
                                        MethodHandle implMethod,
                                        MethodType instantiatedMethodType)
-                   throws ReflectiveOperationException, LambdaConversionException {
+            throws LambdaConversionException {
         AbstractValidatingLambdaMetafactory mf;
         mf = new InnerClassLambdaMetafactory(caller, invokedType,
                                              invokedName, samMethodType,
@@ -216,11 +305,23 @@
     }
 
     /**
-     * Alternate meta-factory for conversion of lambda expressions or method
-     * references to functional interfaces, which supports serialization and
-     * other uncommon options.
+     * Facilitates the creation of simple "function objects" that implement one
+     * or more interfaces by delegation to a provided {@link MethodHandle},
+     * after appropriate type adaptation and partial evaluation of arguments.
+     * Typically used as a <em>bootstrap method</em> for {@code invokedynamic}
+     * call sites, to support the <em>lambda expression</em> and <em>method
+     * reference expression</em> features of the Java Programming Language.
      *
-     * <p>The declared argument list for this method is:
+     * <p>This is the general, more flexible metafactory; a streamlined version
+     * is provided by {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)}.
+     * A general description of the behavior of this method is provided
+     * {@link LambdaMetafactory above}.
+     *
+     * <p>The argument list for this method includes three fixed parameters,
+     * corresponding to the parameters automatically stacked by the VM for the
+     * bootstrap method in an {@code invokedynamic} invocation, and an {@code Object[]}
+     * parameter that contains additional parameters.  The declared argument
+     * list for this method is:
      *
      * <pre>{@code
      *  CallSite altMetafactory(MethodHandles.Lookup caller,
@@ -229,61 +330,103 @@
      *                          Object... args)
      * }</pre>
      *
-     * <p>but it behaves as if the argument list is as follows, where names that
-     * appear in the argument list for
-     * {@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)}
-     * have the same specification as in that method:
+     * <p>but it behaves as if the argument list is as follows:
      *
      * <pre>{@code
      *  CallSite altMetafactory(MethodHandles.Lookup caller,
      *                          String invokedName,
      *                          MethodType invokedType,
-     *                          MethodType samMethodType
+     *                          MethodType samMethodType,
      *                          MethodHandle implMethod,
      *                          MethodType instantiatedMethodType,
      *                          int flags,
-     *                          int markerInterfaceCount, // IF flags has MARKERS set
-     *                          Class... markerInterfaces // IF flags has MARKERS set
-     *                          int bridgeCount,          // IF flags has BRIDGES set
-     *                          MethodType... bridges     // IF flags has BRIDGES set
+     *                          int markerInterfaceCount,  // IF flags has MARKERS set
+     *                          Class... markerInterfaces, // IF flags has MARKERS set
+     *                          int bridgeCount,           // IF flags has BRIDGES set
+     *                          MethodType... bridges      // IF flags has BRIDGES set
      *                          )
      * }</pre>
      *
-     * <p>If the flags contains {@code FLAG_SERIALIZABLE}, or one of the marker
-     * interfaces extends {@link Serializable}, the metafactory will link the
-     * call site to one that produces a serializable lambda.  In addition to
-     * the lambda instance implementing {@code Serializable}, it will have a
-     * {@code writeReplace} method that returns an appropriate {@link
-     * SerializedLambda}, and an appropriate {@code $deserializeLambda$}
-     * method.
+     * <p>Arguments that appear in the argument list for
+     * {@link #metafactory(MethodHandles.Lookup, String, MethodType, MethodType, MethodHandle, MethodType)}
+     * have the same specification as in that method.  The additional arguments
+     * are interpreted as follows:
+     * <ul>
+     *     <li>{@code flags} indicates additional options; this is a bitwise
+     *     OR of desired flags.  Defined flags are {@link #FLAG_BRIDGES},
+     *     {@link #FLAG_MARKERS}, and {@link #FLAG_SERIALIZABLE}.</li>
+     *     <li>{@code markerInterfaceCount} is the number of additional interfaces
+     *     the function object should implement, and is present if and only if the
+     *     {@code FLAG_MARKERS} flag is set.</li>
+     *     <li>{@code markerInterfaces} is a variable-length list of additional
+     *     interfaces to implement, whose length equals {@code markerInterfaceCount},
+     *     and is present if and only if the {@code FLAG_MARKERS} flag is set.</li>
+     *     <li>{@code bridgeCount} is the number of additional method signatures
+     *     the function object should implement, and is present if and only if
+     *     the {@code FLAG_BRIDGES} flag is set.</li>
+     *     <li>{@code bridges} is a variable-length list of additional
+     *     methods signatures to implement, whose length equals {@code bridgeCount},
+     *     and is present if and only if the {@code FLAG_BRIDGES} flag is set.</li>
+     * </ul>
      *
-     * @param caller Stacked automatically by VM; represents a lookup context
-     *               with the accessibility privileges of the caller.
-     * @param invokedName Stacked automatically by VM; the name of the invoked
-     *                    method as it appears at the call site.
-     *                    Used as the name of the functional interface method
-     *                    to which the lambda or method reference is being
-     *                    converted.
-     * @param invokedType Stacked automatically by VM; the signature of the
-     *                    invoked method, which includes the expected static
-     *                    type of the returned lambda object, and the static
-     *                    types of the captured arguments for the lambda.
+     * <p>Each class named by {@code markerInterfaces} is subject to the same
+     * restrictions as {@code Rd}, the return type of {@code invokedType},
+     * as described {@link LambdaMetafactory above}.  Each {@code MethodType}
+     * named by {@code bridges} is subject to the same restrictions as
+     * {@code samMethodType}, as described {@link LambdaMetafactory above}.
+     *
+     * <p>When FLAG_SERIALIZABLE is set in {@code flags}, the function objects
+     * will implement {@code Serializable}, and will have a {@code writeReplace}
+     * method that returns an appropriate {@link SerializedLambda}.  The
+     * {@code caller} class must have an appropriate {@code $deserializeLambda$}
+     * method, as described in {@link SerializedLambda}.
+     *
+     * <p>When the target of the {@code CallSite} returned from this method is
+     * invoked, the resulting function objects are instances of a class with
+     * the following properties:
+     * <ul>
+     *     <li>The class implements the interface named by the return type
+     *     of {@code invokedType} and any interfaces named by {@code markerInterfaces}</li>
+     *     <li>The class declares methods with the name given by {@code invokedName},
+     *     and the signature given by {@code samMethodType} and additional signatures
+     *     given by {@code bridges}</li>
+     *     <li>The class may override methods from {@code Object}, and may
+     *     implement methods related to serialization.</li>
+     * </ul>
+     *
+     * @param caller Represents a lookup context with the accessibility
+     *               privileges of the caller.  When used with {@code invokedynamic},
+     *               this is stacked automatically by the VM.
+     * @param invokedName The name of the method to implement.  When used with
+     *                    {@code invokedynamic}, this is provided by the
+     *                    {@code NameAndType} of the {@code InvokeDynamic}
+     *                    structure and is stacked automatically by the VM.
+     * @param invokedType The expected signature of the {@code CallSite}.  The
+     *                    parameter types represent the types of capture variables;
+     *                    the return type is the interface to implement.   When
+     *                    used with {@code invokedynamic}, this is provided by
+     *                    the {@code NameAndType} of the {@code InvokeDynamic}
+     *                    structure and is stacked automatically by the VM.
      *                    In the event that the implementation method is an
-     *                    instance method, the first argument in the invocation
-     *                    signature will correspond to the receiver.
-     * @param  args       flags and optional arguments, as described above.
-     * @return a CallSite, which, when invoked, will return an instance of the
-     * functional interface
-     * @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
+     *                    instance method and this signature has any parameters,
+     *                    the first parameter in the invocation signature must
+     *                    correspond to the receiver.
+     * @param  args       An {@code Object[]} array containing the required
+     *                    arguments {@code samMethodType}, {@code implMethod},
+     *                    {@code instantiatedMethodType}, {@code flags}, and any
+     *                    optional arguments, as described
+     *                    {@link #altMetafactory(MethodHandles.Lookup, String, MethodType, Object...)} above}
+     * @return a CallSite whose target can be used to perform capture, generating
+     *         instances of the interface named by {@code invokedType}
+     * @throws LambdaConversionException If any of the linkage invariants
+     *                                   described {@link LambdaMetafactory above}
+     *                                   are violated
      */
     public static CallSite altMetafactory(MethodHandles.Lookup caller,
                                           String invokedName,
                                           MethodType invokedType,
                                           Object... args)
-            throws ReflectiveOperationException, LambdaConversionException {
+            throws LambdaConversionException {
         MethodType samMethodType = (MethodType)args[0];
         MethodHandle implMethod = (MethodHandle)args[1];
         MethodType instantiatedMethodType = (MethodType)args[2];
@@ -308,15 +451,15 @@
         else
             bridges = EMPTY_MT_ARRAY;
 
-        boolean foundSerializableSupertype = Serializable.class.isAssignableFrom(invokedType.returnType());
-        for (Class<?> c : markerInterfaces)
-            foundSerializableSupertype |= Serializable.class.isAssignableFrom(c);
-        boolean isSerializable = ((flags & LambdaMetafactory.FLAG_SERIALIZABLE) != 0)
-                                 || foundSerializableSupertype;
-
-        if (isSerializable && !foundSerializableSupertype) {
-            markerInterfaces = Arrays.copyOf(markerInterfaces, markerInterfaces.length + 1);
-            markerInterfaces[markerInterfaces.length-1] = Serializable.class;
+        boolean isSerializable = ((flags & FLAG_SERIALIZABLE) != 0);
+        if (isSerializable) {
+            boolean foundSerializableSupertype = Serializable.class.isAssignableFrom(invokedType.returnType());
+            for (Class<?> c : markerInterfaces)
+                foundSerializableSupertype |= Serializable.class.isAssignableFrom(c);
+            if (!foundSerializableSupertype) {
+                markerInterfaces = Arrays.copyOf(markerInterfaces, markerInterfaces.length + 1);
+                markerInterfaces[markerInterfaces.length-1] = Serializable.class;
+            }
         }
 
         AbstractValidatingLambdaMetafactory mf