# HG changeset patch # User jrose # Date 1297416388 28800 # Node ID 3b891698c4eca2940491db090eb69ecfb5d2a1b3 # Parent 9e2483e6cfabbdd0fd0797d293fd9bf985d5ced8 7012650: implement JSR 292 EG adjustments through January 2010 Summary: misc. EG changes and polishes (excluding 7013417) Reviewed-by: twisti diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/CallSite.java --- a/jdk/src/share/classes/java/dyn/CallSite.java Fri Feb 11 01:26:24 2011 -0800 +++ b/jdk/src/share/classes/java/dyn/CallSite.java Fri Feb 11 01:26:28 2011 -0800 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2008, 2011, 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 @@ -78,7 +78,7 @@ } private static CallSite bootstrapDynamic(MethodHandles.Lookup caller, String name, MethodType type) { // ignore caller and name, but match the type: - return new ConstantCallSite(MethodHandles.collectArguments(printArgs, type)); + return new ConstantCallSite(printArgs.asType(type)); } * @author John Rose, JSR 292 EG @@ -86,6 +86,7 @@ abstract public class CallSite { private static final Access IMPL_TOKEN = Access.getToken(); + static { MethodHandleImpl.initStatics(); } // Fields used only by the JVM. Do not use or change. private MemberName vmmethod; // supplied by the JVM (ref. to calling method) @@ -125,8 +126,8 @@ } /** - * Report the type of this call site's target. - * Although targets may change, the call site's type can never change. + * Returns the type of this call site's target. + * Although targets may change, any call site's type is permanent, and can never change to an unequal type. * The {@code setTarget} method enforces this invariant by refusing any new target that does * not have the previous target's type. * @return the type of the current target, which is also the type of any future target @@ -154,73 +155,40 @@ } /** - * Report the current linkage state of the call site, a value which may change over time. - *

- * If a {@code CallSite} object is returned - * from the bootstrap method of the {@code invokedynamic} instruction, - * the {@code CallSite} is permanently bound to that instruction. - * When the {@code invokedynamic} instruction is executed, the target method - * of its associated call site object is invoked directly. - * It is as if the instruction calls {@code getTarget} and then - * calls {@link MethodHandle#invokeExact invokeExact} on the result. - *

- * Unless specified differently by a subclass, - * the interactions of {@code getTarget} with memory are the same - * as of a read from an ordinary variable, such as an array element or a - * non-volatile, non-final field. - *

- * In particular, the current thread may choose to reuse the result - * of a previous read of the target from memory, and may fail to see - * a recent update to the target by another thread. - *

- * In a {@linkplain ConstantCallSite constant call site}, the {@code getTarget} method behaves - * like a read from a {@code final} field of the {@code CallSite}. - *

- * In a {@linkplain VolatileCallSite volatile call site}, the {@code getTarget} method behaves - * like a read from a {@code volatile} field of the {@code CallSite}. - *

- * This method may not be overridden by application code. + * Returns the target method of the call site, according to the + * behavior defined by this call site's specific class. + * The immediate subclasses of {@code CallSite} document the + * class-specific behaviors of this method. + * * @return the current linkage state of the call site, its target method handle * @see ConstantCallSite * @see VolatileCallSite * @see #setTarget + * @see ConstantCallSite#getTarget + * @see MutableCallSite#getTarget + * @see VolatileCallSite#getTarget */ - public final MethodHandle getTarget() { - return getTarget0(); - } + public abstract MethodHandle getTarget(); /** - * Privileged implementations can override this to force final or volatile semantics on getTarget. - */ - /*package-private*/ - MethodHandle getTarget0() { - return target; - } - - /** - * Set the target method of this call site. + * Updates the target method of this call site, according to the + * behavior defined by this call site's specific class. + * The immediate subclasses of {@code CallSite} document the + * class-specific behaviors of this method. *

- * Unless a subclass of CallSite documents otherwise, - * the interactions of {@code setTarget} with memory are the same - * as of a write to an ordinary variable, such as an array element or a - * non-volatile, non-final field. - *

- * In particular, unrelated threads may fail to see the updated target - * until they perform a read from memory. - * Stronger guarantees can be created by putting appropriate operations - * into the bootstrap method and/or the target methods used - * at any given call site. + * The type of the new target must be {@linkplain MethodType#equals equal to} + * the type of the old target. + * * @param newTarget the new target * @throws NullPointerException if the proposed new target is null * @throws WrongMethodTypeException if the proposed new target * has a method type that differs from the previous target - * @throws UnsupportedOperationException if the call site is - * in fact a {@link ConstantCallSite} + * @see CallSite#getTarget + * @see ConstantCallSite#setTarget + * @see MutableCallSite#setTarget + * @see VolatileCallSite#setTarget */ - public void setTarget(MethodHandle newTarget) { - checkTargetChange(this.target, newTarget); - setTargetNormal(newTarget); - } + public abstract void setTarget(MethodHandle newTarget); void checkTargetChange(MethodHandle oldTarget, MethodHandle newTarget) { MethodType oldType = oldTarget.type(); @@ -236,25 +204,25 @@ /** * Produce a method handle equivalent to an invokedynamic instruction * which has been linked to this call site. - *

If this call site is a {@linkplain ConstantCallSite constant call site}, - * this method simply returns the call site's target, since that will never change. - *

Otherwise, this method is equivalent to the following code: - * 

+     * 

+     * This method is equivalent to the following code:
+     * 
      * MethodHandle getTarget, invoker, result;
-     * getTarget = MethodHandles.lookup().bind(this, "getTarget", MethodType.methodType(MethodHandle.class));
+     * getTarget = MethodHandles.publicLookup().bind(this, "getTarget", MethodType.methodType(MethodHandle.class));
      * invoker = MethodHandles.exactInvoker(this.type());
      * result = MethodHandles.foldArguments(invoker, getTarget)
      * 

+     *
      * @return a method handle which always invokes this call site's current target
      */
-    public final MethodHandle dynamicInvoker() {
-        if (this instanceof ConstantCallSite) {
-            return getTarget0();  // will not change dynamically
-        }
+    public abstract MethodHandle dynamicInvoker();
+
+    /*non-public*/ MethodHandle makeDynamicInvoker() {
         MethodHandle getTarget = MethodHandleImpl.bindReceiver(IMPL_TOKEN, GET_TARGET, this);
         MethodHandle invoker = MethodHandles.exactInvoker(this.type());
         return MethodHandles.foldArguments(invoker, getTarget);
     }
+
     private static final MethodHandle GET_TARGET;
     static {
         try {
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/ClassValue.java
--- a/jdk/src/share/classes/java/dyn/ClassValue.java	Fri Feb 11 01:26:24 2011 -0800
+++ b/jdk/src/share/classes/java/dyn/ClassValue.java	Fri Feb 11 01:26:28 2011 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2011, 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
@@ -31,10 +31,14 @@
 import java.lang.reflect.UndeclaredThrowableException;
 
 /**
- * Lazily associate a computed value with (potentially) every class.
+ * Lazily associate a computed value with (potentially) every type.
+ * For example, if a dynamic language needs to construct a message dispatch
+ * table for each class encountered at a message send call site,
+ * it can use a {@code ClassValue} to cache information needed to
+ * perform the message send quickly, for each class encountered.
  * @author John Rose, JSR 292 EG
  */
-public class ClassValue {
+public abstract class ClassValue {
     /**
      * Compute the given class's derived value for this {@code ClassValue}.
      * 

@@ -45,61 +49,41 @@
      * but it may be invoked again if there has been a call to
      * {@link #remove remove}.
      * 

-     * If there is no override from a subclass, this method returns
-     * the result of applying the {@code ClassValue}'s {@code computeValue}
-     * method handle, which was supplied at construction time.
+     * If this method throws an exception, the corresponding call to {@code get}
+     * will terminate abnormally with that exception, and no class value will be recorded.
      *
+     * @param type the type whose class value must be computed
      * @return the newly computed value associated with this {@code ClassValue}, for the given class or interface
-     * @throws UndeclaredThrowableException if the {@code computeValue} method handle invocation throws something other than a {@code RuntimeException} or {@code Error}
-     * @throws UnsupportedOperationException if the {@code computeValue} method handle is null (subclasses must override)
+     * @see #get
+     * @see #remove
      */
-    protected T computeValue(Class type) {
-        if (computeValue == null)
-            return null;
-        try {
-            return (T) (Object) computeValue.invokeGeneric(type);
-        } catch (Throwable ex) {
-            if (ex instanceof Error)             throw (Error) ex;
-            if (ex instanceof RuntimeException)  throw (RuntimeException) ex;
-            throw new UndeclaredThrowableException(ex);
-        }
-    }
-
-    private final MethodHandle computeValue;
-
-    /**
-     * Creates a new class value.
-     * Subclasses which use this constructor must override
-     * the {@link #computeValue computeValue} method,
-     * since the default {@code computeValue} method requires a method handle,
-     * which this constructor does not provide.
-     */
-    protected ClassValue() {
-        this.computeValue = null;
-    }
-
-    /**
-     * Creates a new class value, whose {@link #computeValue computeValue} method
-     * will return the result of {@code computeValue.invokeGeneric(type)}.
-     * @throws NullPointerException  if the method handle parameter is null
-     */
-    public ClassValue(MethodHandle computeValue) {
-        computeValue.getClass();  // trigger NPE if null
-        this.computeValue = computeValue;
-    }
+    protected abstract T computeValue(Class type);
 
     /**
      * Returns the value for the given class.
      * If no value has yet been computed, it is obtained by
-     * by an invocation of the {@link #computeValue computeValue} method.
+     * an invocation of the {@link #computeValue computeValue} method.
      * 

      * The actual installation of the value on the class
      * is performed atomically.
-     * At that point, if racing threads have
+     * At that point, if several racing threads have
      * computed values, one is chosen, and returned to
      * all the racing threads.
+     * 

+     * The {@code type} parameter is typically a class, but it may be any type,
+     * such as an interface, a primitive type (like {@code int.class}), or {@code void.class}.
+     * 

+     * In the absence of {@code remove} calls, a class value has a simple
+     * state diagram:  uninitialized and initialized.
+     * When {@code remove} calls are made,
+     * the rules for value observation are more complex.
+     * See the documentation for {@link #remove remove} for more information.
      *
+     * @param type the type whose class value must be computed or retrieved
      * @return the current value associated with this {@code ClassValue}, for the given class or interface
+     * @throws NullPointerException if the argument is null
+     * @see #remove
+     * @see #computeValue
      */
     public T get(Class type) {
         ClassValueMap map = getMap(type);
@@ -119,12 +103,51 @@
      * This may result in an additional invocation of the
      * {@code computeValue computeValue} method for the given class.
      * 

-     * If racing threads perform a combination of {@code get} and {@code remove} calls,
-     * the calls are serialized.
-     * A value produced by a call to {@code computeValue} will be discarded, if
-     * the corresponding {@code get} call was followed by a {@code remove} call
-     * before the {@code computeValue} could complete.
-     * In such a case, the {@code get} call will re-invoke {@code computeValue}.
+     * In order to explain the interaction between {@code get} and {@code remove} calls,
+     * we must model the state transitions of a class value to take into account
+     * the alternation between uninitialized and initialized states.
+     * To do this, number these states sequentially from zero, and note that
+     * uninitialized (or removed) states are numbered with even numbers,
+     * while initialized (or re-initialized) states have odd numbers.
+     * 

+     * When a thread {@code T} removes a class value in state {@code 2N},
+     * nothing happens, since the class value is already uninitialized.
+     * Otherwise, the state is advanced atomically to {@code 2N+1}.
+     * 

+     * When a thread {@code T} queries a class value in state {@code 2N},
+     * the thread first attempts to initialize the class value to state {@code 2N+1}
+     * by invoking {@code computeValue} and installing the resulting value.
+     * 

+     * When {@code T} attempts to install the newly computed value,
+     * if the state is still at {@code 2N}, the class value will be initialized
+     * with the computed value, advancing it to state {@code 2N+1}.
+     * 

+     * Otherwise, whether the new state is even or odd,
+     * {@code T} will discard the newly computed value
+     * and retry the {@code get} operation.
+     * 

+     * Discarding and retrying is an important proviso,
+     * since otherwise {@code T} could potentially install
+     * a disastrously stale value.  For example:
+     * 
    
+     * 
  • {@code T} calls {@code CV.get(C)} and sees state {@code 2N}
+     * 
  • {@code T} quickly computes a time-dependent value {@code V0} and gets ready to install it
+     * 
  • {@code T} is hit by an unlucky paging or scheduling event, and goes to sleep for a long time
+     * 
  • ...meanwhile, {@code T2} also calls {@code CV.get(C)} and sees state {@code 2N}
+     * 
  • {@code T2} quickly computes a similar time-dependent value {@code V1} and installs it on {@code CV.get(C)}
+     * 
  • {@code T2} (or a third thread) then calls {@code CV.remove(C)}, undoing {@code T2}'s work
+     * 
  •  the previous actions of {@code T2} are repeated several times
+     * 
  •  also, the relevant computed values change over time: {@code V1}, {@code V2}, ...
+     * 
  • ...meanwhile, {@code T} wakes up and attempts to install {@code V0}; this must fail
+     * 

+     * We can assume in the above scenario that {@code CV.computeValue} uses locks to properly
+     * observe the time-dependent states as it computes {@code V1}, etc.
+     * This does not remove the threat of a stale value, since there is a window of time
+     * between the return of {@code computeValue} in {@code T} and the installation
+     * of the the new value.  No user synchronization is possible during this time.
+     *
+     * @param type the type whose class value must be removed
+     * @throws NullPointerException if the argument is null
      */
     public void remove(Class type) {
         ClassValueMap map = getMap(type);
@@ -137,9 +160,9 @@
 
     /// Implementation...
 
-    /** The hash code for this type is based on the identity of the object,
-     *  and is well-dispersed for power-of-two tables.
-     */
+    // The hash code for this type is based on the identity of the object,
+    // and is well-dispersed for power-of-two tables.
+    /** @deprecated This override, which is implementation-specific, will be removed for PFD. */
     public final int hashCode() { return hashCode; }
     private final int hashCode = HASH_CODES.getAndAdd(0x61c88647);
     private static final AtomicInteger HASH_CODES = new AtomicInteger();
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/ConstantCallSite.java
--- a/jdk/src/share/classes/java/dyn/ConstantCallSite.java	Fri Feb 11 01:26:24 2011 -0800
+++ b/jdk/src/share/classes/java/dyn/ConstantCallSite.java	Fri Feb 11 01:26:28 2011 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2011, 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
@@ -32,16 +32,46 @@
  * @author John Rose, JSR 292 EG
  */
 public class ConstantCallSite extends CallSite {
-    /** Create a call site with a permanent target.
+    /**
+     * Creates a call site with a permanent target.
+     * @param target the target to be permanently associated with this call site
      * @throws NullPointerException if the proposed target is null
      */
     public ConstantCallSite(MethodHandle target) {
         super(target);
     }
+
     /**
-     * Throw an {@link UnsupportedOperationException}, because this kind of call site cannot change its target.
+     * Returns the target method of the call site, which behaves
+     * like a {@code final} field of the {@code ConstantCallSite}.
+     * That is, the the target is always the original value passed
+     * to the constructor call which created this instance.
+     *
+     * @return the immutable linkage state of this call site, a constant method handle
+     * @throws UnsupportedOperationException because this kind of call site cannot change its target
+     */
+    @Override public final MethodHandle getTarget() {
+        return target;
+    }
+
+    /**
+     * Always throws an {@link UnsupportedOperationException}.
+     * This kind of call site cannot change its target.
+     * @param ignore a new target proposed for the call site, which is ignored
+     * @throws UnsupportedOperationException because this kind of call site cannot change its target
      */
     @Override public final void setTarget(MethodHandle ignore) {
         throw new UnsupportedOperationException("ConstantCallSite");
     }
+
+    /**
+     * Returns this call site's permanent target.
+     * Since that target will never change, this is a correct implementation
+     * of {@link CallSite#dynamicInvoker CallSite.dynamicInvoker}.
+     * @return the immutable linkage state of this call site, a constant method handle
+     */
+    @Override
+    public final MethodHandle dynamicInvoker() {
+        return getTarget();
+    }
 }
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/InvokeDynamicBootstrapError.java
--- a/jdk/src/share/classes/java/dyn/InvokeDynamicBootstrapError.java	Fri Feb 11 01:26:24 2011 -0800
+++ b/jdk/src/share/classes/java/dyn/InvokeDynamicBootstrapError.java	Fri Feb 11 01:26:28 2011 -0800
@@ -31,8 +31,8 @@
  * {@linkplain BootstrapMethod bootstrap method},
  * or the bootstrap method has
  * failed to provide a
- * {@linkplain CallSite} call site with a non-null {@linkplain MethodHandle target}
- * of the correct {@linkplain MethodType method type}.
+ * {@linkplain CallSite call site} with a {@linkplain CallSite#getTarget target}
+ * of the correct {@linkplain MethodHandle#type method type}.
  *
  * @author John Rose, JSR 292 EG
  * @since 1.7
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/Linkage.java
--- a/jdk/src/share/classes/java/dyn/Linkage.java	Fri Feb 11 01:26:24 2011 -0800
+++ b/jdk/src/share/classes/java/dyn/Linkage.java	Fri Feb 11 01:26:28 2011 -0800
@@ -101,8 +101,9 @@
     /**
      * METHOD WILL BE REMOVED FOR PFD:
      * Invalidate all invokedynamic call sites everywhere.
-     * @deprecated Use {@linkplain CallSite#setTarget call site target setting}
-     * and {@link VolatileCallSite#invalidateAll call site invalidation} instead.
+     * @deprecated Use {@linkplain MutableCallSite#setTarget call site target setting},
+     * {@link MutableCallSite#syncAll call site update pushing},
+     * and {@link SwitchPoint#guardWithTest target switching} instead.
      */
     public static
     Object invalidateAll() {
@@ -113,8 +114,9 @@
      * METHOD WILL BE REMOVED FOR PFD:
      * Invalidate all {@code invokedynamic} call sites in the bytecodes
      * of any methods of the given class.
-     * @deprecated Use {@linkplain CallSite#setTarget call site target setting}
-     * and {@link VolatileCallSite#invalidateAll call site invalidation} instead.
+     * @deprecated Use {@linkplain MutableCallSite#setTarget call site target setting},
+     * {@link MutableCallSite#syncAll call site update pushing},
+     * and {@link SwitchPoint#guardWithTest target switching} instead.
      */
     public static
     Object invalidateCallerClass(Class callerClass) {
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/MethodHandle.java
--- a/jdk/src/share/classes/java/dyn/MethodHandle.java	Fri Feb 11 01:26:24 2011 -0800
+++ b/jdk/src/share/classes/java/dyn/MethodHandle.java	Fri Feb 11 01:26:28 2011 -0800
@@ -34,7 +34,7 @@
 import static sun.dyn.MemberName.newIllegalArgumentException;  // utility
 
 /**
- * A method handle is a typed, directly executable reference to a method,
+ * A method handle is a typed, directly executable reference to an underlying method,
  * constructor, field, or similar low-level operation, with optional
  * transformations of arguments or return values.
  * These transformations are quite general, and include such patterns as
@@ -48,105 +48,183 @@
  *     will be removed before the Proposed Final Draft.
  *     Also, the final version will not include any public or
  *     protected constructors.
- * 

- * Method handles are strongly typed according to signature.
- * They are not distinguished by method name or enclosing class.
- * A method handle must be invoked under a signature which matches
- * the method handle's own {@linkplain MethodType method type}.
+ *
+ * 
Method handle contents

+ * Method handles are dynamically and strongly typed according to type descriptor.
+ * They are not distinguished by the name or defining class of their underlying methods.
+ * A method handle must be invoked using type descriptor which matches
+ * the method handle's own {@linkplain #type method type}.
  * 

  * Every method handle reports its type via the {@link #type type} accessor.
- * The structure of this type is a series of classes, one of which is
+ * This type descriptor is a {@link java.dyn.MethodType MethodType} object,
+ * whose structure is a series of classes, one of which is
  * the return type of the method (or {@code void.class} if none).
  * 

- * Every method handle appears as an object containing a method named
- * {@link #invokeExact invokeExact}, whose signature exactly matches
- * the method handle's type.
- * A Java method call expression, which compiles to an
- * {@code invokevirtual} instruction,
- * can invoke this method from Java source code.
+ * A method handle's type controls the types of invocations it accepts,
+ * and the kinds of transformations that apply to it.
+ * 

+ * A method handle contains a pair of special invoker methods
+ * called {@link #invokeExact invokeExact} and {@link #invokeGeneric invokeGeneric}.
+ * Both invoker methods provide direct access to the method handle's
+ * underlying method, constructor, field, or other operation,
+ * as modified by transformations of arguments and return values.
+ * Both invokers accept calls which exactly match the method handle's own type.
+ * The {@code invokeGeneric} invoker also accepts a range of other call types.
+ * 

+ * Method handles are immutable and have no visible state.
+ * Of course, they can be bound to underlying methods or data which exhibit state.
+ * With respect to the Java Memory Model, any method handle will behave
+ * as if all of its (internal) fields are final variables.  This means that any method
+ * handle made visible to the application will always be fully formed.
+ * This is true even if the method handle is published through a shared
+ * variable in a data race.
+ * 

+ * Method handles cannot be subclassed by the user.
+ * Implementations may (or may not) create internal subclasses of {@code MethodHandle}
+ * which may be visible via the {@link java.lang.Object#getClass Object.getClass}
+ * operation.  The programmer should not draw conclusions about a method handle
+ * from its specific class, as the method handle class hierarchy (if any)
+ * may change from time to time or across implementations from different vendors.
+ *
+ * 
Method handle compilation

+ * A Java method call expression naming {@code invokeExact} or {@code invokeGeneric}
+ * can invoke a method handle from Java source code.
+ * From the viewpoint of source code, these methods can take any arguments
+ * and their result can be cast to any return type.
+ * Formally this is accomplished by giving the invoker methods
+ * {@code Object} return types and variable-arity {@code Object} arguments,
+ * but they have an additional quality called "signature polymorphism"
+ * which connects this freedom of invocation directly to the JVM execution stack.
  * 

- * Every call to a method handle specifies an intended method type,
- * which must exactly match the type of the method handle.
- * (The type is specified in the {@code invokevirtual} instruction,
- * via a {@code CONSTANT_NameAndType} constant pool entry.)
- * The call looks within the receiver object for a method
- * named {@code invokeExact} of the intended method type.
- * The call fails with a {@link WrongMethodTypeException}
- * if the method does not exist, even if there is an {@code invokeExact}
- * method of a closely similar signature.
- * As with other kinds
- * of methods in the JVM, signature matching during method linkage
- * is exact, and does not allow for language-level implicit conversions
- * such as {@code String} to {@code Object} or {@code short} to {@code int}.
+ * As is usual with virtual methods, source-level calls to {@code invokeExact}
+ * and {@code invokeGeneric} compile to an {@code invokevirtual} instruction.
+ * More unusually, the compiler must record the actual argument types,
+ * and may not perform method invocation conversions on the arguments.
+ * Instead, it must push them on the stack according to their own unconverted types.
+ * The method handle object itself is pushed on the stack before the arguments.
+ * The compiler then calls the method handle with a type descriptor which
+ * describes the argument and return types.
+ * 

+ * To issue a complete type descriptor, the compiler must also determine
+ * the return type.  This is based on a cast on the method invocation expression,
+ * if there is one, or else {@code Object} if the invocation is an expression
+ * or else {@code void} if the invocation is a statement.
+ * The cast may be to a primitive type (but not {@code void}).
  * 

- * Each individual method handle also contains a method named
- * {@link #invokeGeneric invokeGeneric}, whose type is the same
- * as {@code invokeExact}, and is therefore also reported by
- * the {@link #type type} accessor.
+ * As a corner case, an uncasted {@code null} argument is given
+ * a type descriptor of {@code java.lang.Void}.
+ * The ambiguity with the type {@code Void} is harmless, since there are no references of type
+ * {@code Void} except the null reference.
+ *
+ * 
Method handle invocation

+ * 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.
+ * This is true of calls to {@code invokeExact} and {@code invokeGeneric}.
+ * In this case, the type descriptor emitted by the compiler is checked for
+ * correct syntax and names it contains are resolved.
+ * Thus, an {@code invokevirtual} instruction which invokes
+ * a method handle will always link, as long
+ * as the type descriptor is syntactically well-formed
+ * and the types exist.
+ * 

+ * When the {@code invokevirtual} is executed after linking,
+ * the receiving method handle's type is first checked by the JVM
+ * to ensure that it matches the descriptor.
+ * If the type match fails, it means that the method which the
+ * caller is invoking is not present on the individual
+ * method handle being invoked.
+ * 

+ * In the case of {@code invokeExact}, the type descriptor of the invocation
+ * (after resolving symbolic type names) must exactly match the method type
+ * of the receiving method handle.
+ * In the case of {@code invokeGeneric}, the resolved type descriptor
+ * must be a valid argument to the receiver's {@link #asType asType} method.
+ * Thus, {@code invokeGeneric} is more permissive than {@code invokeExact}.
+ * 

+ * After type matching, a call to {@code invokeExact} directly
+ * and immediately invoke the method handle's underlying method
+ * (or other behavior, as the case may be).
+ * 

  * A call to {@code invokeGeneric} works the same as a call to
- * {@code invokeExact}, if the signature specified by the caller
+ * {@code invokeExact}, if the type descriptor specified by the caller
  * exactly matches the method handle's own type.
  * If there is a type mismatch, {@code invokeGeneric} attempts
- * to adjust the type of the target method handle
- * (as if by a call to {@link #asType asType})
- * to obtain an exactly invokable target.
+ * to adjust the type of the receiving method handle,
+ * as if by a call to {@link #asType asType},
+ * to obtain an exactly invokable method handle {@code M2}.
  * This allows a more powerful negotiation of method type
  * between caller and callee.
  * 

- * A method handle is an unrestricted capability to call a method.
- * A method handle can be formed on a non-public method by a class
- * that has access to that method; the resulting handle can be used
- * in any place by any caller who receives a reference to it.  Thus, access
- * checking is performed when the method handle is created, not
- * (as in reflection) every time it is called.  Handles to non-public
- * methods, or in non-public classes, should generally be kept secret.
+ * (Note: The adjusted method handle {@code M2} is not directly observable,
+ * and implementations are therefore not required to materialize it.)
+ *
+ * 
Invocation checking

+ * 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
+ * by a failed call to {@code asType} (in the case of {@code invokeGeneric}).
+ * 

+ * Thus, a method type mismatch which might show up as a linkage error
+ * in a statically typed program can show up as
+ * a dynamic {@code WrongMethodTypeException}
+ * in a program which uses method handles.
+ * 

+ * Because method types contain "live" {@code Class} objects,
+ * method type matching takes into account both types names and class loaders.
+ * Thus, even if a method handle {@code M} is created in one
+ * class loader {@code L1} and used in another {@code L2},
+ * method handle calls are type-safe, because the caller's type
+ * descriptor, as resolved in {@code L2},
+ * is matched against the original callee method's type descriptor,
+ * as resolved in {@code L1}.
+ * The resolution in {@code L1} happens when {@code M} is created
+ * and its type is assigned, while the resolution in {@code L2} happens
+ * when the {@code invokevirtual} instruction is linked.
+ * 

+ * Apart from the checking of type descriptors,
+ * a method handle's capability to call its underlying method is unrestricted.
+ * If a method handle is formed on a non-public method by a class
+ * that has access to that method, the resulting handle can be used
+ * in any place by any caller who receives a reference to it.
+ * 

+ * Unlike with the Core Reflection API, where access is checked every time
+ * a reflective method is invoked,
+ * method handle access checking is performed
+ * when the method handle is created.
+ * In the case of {@code ldc} (see below), access checking is performed as part of linking
+ * the constant pool entry underlying the constant method handle.
+ * 

+ * Thus, handles to non-public methods, or to methods in non-public classes,
+ * should generally be kept secret.
  * They should not be passed to untrusted code unless their use from
  * the untrusted code would be harmless.
- * 

- * Bytecode in the JVM can directly call a method handle's
- * {@code invokeExact} method from an {@code invokevirtual} instruction.
- * The receiver class type must be {@code MethodHandle} and the method name
- * must be {@code invokeExact}.  The signature of the invocation
- * (after resolving symbolic type names) must exactly match the method type
- * of the target method.
- * Similarly, bytecode can directly call a method handle's {@code invokeGeneric}
- * method.  The signature of the invocation (after resolving symbolic type names)
- * must either exactly match the method type or be a valid argument to
- * the target's {@link #asType asType} method.
+ *
+ * 
Method handle creation

+ * 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
+ * {@link java.dyn.MethodHandles.Lookup MethodHandles.Lookup}
+ * For example, a static method handle can be obtained
+ * from {@link java.dyn.MethodHandles.Lookup#findStatic Lookup.findStatic}.
+ * There are also conversion methods from Core Reflection API objects,
+ * such as {@link java.dyn.MethodHandles.Lookup#unreflect Lookup.unreflect}.
  * 

- * Every {@code invokeExact} and {@code invokeGeneric} method always
- * throws {@link java.lang.Throwable Throwable},
- * which is to say that there is no static restriction on what a method handle
- * can throw.  Since the JVM does not distinguish between checked
- * and unchecked exceptions (other than by their class, of course),
- * there is no particular effect on bytecode shape from ascribing
- * checked exceptions to method handle invocations.  But in Java source
- * code, methods which perform method handle calls must either explicitly
- * throw {@code java.lang.Throwable Throwable}, or else must catch all
- * throwables locally, rethrowing only those which are legal in the context,
- * and wrapping ones which are illegal.
- * 

- * Bytecode in the JVM can directly obtain a method handle
- * for any accessible method from a {@code ldc} instruction
- * which refers to a {@code CONSTANT_MethodHandle} constant pool entry.
- * (Each such entry refers directly to a {@code CONSTANT_Methodref},
+ * Like classes and strings, method handles that correspond to accessible
+ * fields, methods, and constructors can also be represented directly
+ * in a class file's constant pool as constants to be loaded by {@code ldc} bytecodes.
+ * A new type of constant pool entry, {@code CONSTANT_MethodHandle},
+ * refers directly to an associated {@code CONSTANT_Methodref},
  * {@code CONSTANT_InterfaceMethodref}, or {@code CONSTANT_Fieldref}
  * constant pool entry.
- * For more details, see the package summary.)
+ * (For more details on method handle constants,
+ * see the package summary.)
  * 

  * Method handles produced by lookups or constant loads from methods or
  * constructors with the variable arity modifier bit ({@code 0x0080})
  * have a corresponding variable arity, as if they were defined with
  * the help of {@link #asVarargsCollector asVarargsCollector}.
  * 

- * Java code can also use a reflective API called
- * {@link java.dyn.MethodHandles.Lookup MethodHandles.Lookup}
- * for creating and calling method handles.
- * For example, a static method handle can be obtained
- * from {@link java.dyn.MethodHandles.Lookup#findStatic Lookup.findStatic}.
- * There are also bridge methods from Core Reflection API objects,
- * such as {@link java.dyn.MethodHandles.Lookup#unreflect Lookup.ureflect}.
- * 

  * A method reference may refer either to a static or non-static method.
  * In the non-static case, the method handle type includes an explicit
  * receiver argument, prepended before any other arguments.
@@ -158,64 +236,141 @@
  * When a method handle to a virtual method is invoked, the method is
  * always looked up in the receiver (that is, the first argument).
  * 

- * A non-virtual method handles to a specific virtual method implementation
+ * A non-virtual method handle to a specific virtual method implementation
  * can also be created.  These do not perform virtual lookup based on
  * receiver type.  Such a method handle simulates the effect of
  * an {@code invokespecial} instruction to the same method.
- * 

+ *
+ * 
Usage examples

  * Here are some examples of usage:
  * 
 Object x, y; String s; int i;
 MethodType mt; MethodHandle mh;
 MethodHandles.Lookup lookup = MethodHandles.lookup();
-// mt is {(char,char) => String}
+// mt is (char,char)String
 mt = MethodType.methodType(String.class, char.class, char.class);
 mh = lookup.findVirtual(String.class, "replace", mt);
-// (Ljava/lang/String;CC)Ljava/lang/String;
 s = (String) mh.invokeExact("daddy",'d','n');
+// invokeExact(Ljava/lang/String;CC)Ljava/lang/String;
 assert(s.equals("nanny"));
 // weakly typed invocation (using MHs.invoke)
 s = (String) mh.invokeWithArguments("sappy", 'p', 'v');
 assert(s.equals("savvy"));
-// mt is {Object[] => List}
+// mt is (Object[])List
 mt = MethodType.methodType(java.util.List.class, Object[].class);
 mh = lookup.findStatic(java.util.Arrays.class, "asList", mt);
 assert(mh.isVarargsCollector());
 x = mh.invokeGeneric("one", "two");
+// invokeGeneric(Ljava/lang/String;Ljava/lang/String;)Ljava/lang/Object;
 assert(x.equals(java.util.Arrays.asList("one","two")));
-// mt is {(Object,Object,Object) => Object}
+// mt is (Object,Object,Object)Object
 mt = MethodType.genericMethodType(3);
-mh = MethodHandles.collectArguments(mh, mt);
-// mt is {(Object,Object,Object) => Object}
-// (Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;
+mh = mh.asType(mt);
 x = mh.invokeExact((Object)1, (Object)2, (Object)3);
+// invokeExact(Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object;
 assert(x.equals(java.util.Arrays.asList(1,2,3)));
 // mt is { => int}
 mt = MethodType.methodType(int.class);
 mh = lookup.findVirtual(java.util.List.class, "size", mt);
-// (Ljava/util/List;)I
 i = (int) mh.invokeExact(java.util.Arrays.asList(1,2,3));
+// invokeExact(Ljava/util/List;)I
 assert(i == 3);
 mt = MethodType.methodType(void.class, String.class);
 mh = lookup.findVirtual(java.io.PrintStream.class, "println", mt);
 mh.invokeExact(System.out, "Hello, world.");
-// (Ljava/io/PrintStream;Ljava/lang/String;)V
+// invokeExact(Ljava/io/PrintStream;Ljava/lang/String;)V
  * 

- * Each of the above calls generates a single invokevirtual instruction
- * with the name {@code invoke} and the type descriptors indicated in the comments.
- * The argument types are taken directly from the actual arguments,
- * while the return type is taken from the cast immediately applied to the call.
- * This cast may be to a primitive.
- * If it is missing, the type defaults to {@code Object} if the call
- * occurs in a context which uses the return value.
- * If the call occurs as a statement, a cast is impossible,
- * and there is no return type; the call is {@code void}.
+ * Each of the above calls to {@code invokeExact} or {@code invokeGeneric}
+ * generates a single invokevirtual instruction with
+ * the type descriptor indicated in the following comment.
+ *
+ * 
Exceptions

+ * The methods {@code invokeExact} and {@code invokeGeneric} are declared
+ * to throw {@link java.lang.Throwable Throwable},
+ * which is to say that there is no static restriction on what a method handle
+ * can throw.  Since the JVM does not distinguish between checked
+ * and unchecked exceptions (other than by their class, of course),
+ * there is no particular effect on bytecode shape from ascribing
+ * checked exceptions to method handle invocations.  But in Java source
+ * code, methods which perform method handle calls must either explicitly
+ * throw {@code java.lang.Throwable Throwable}, or else must catch all
+ * throwables locally, rethrowing only those which are legal in the context,
+ * and wrapping ones which are illegal.
+ *
+ * 
Signature polymorphism

+ * The unusual compilation and linkage behavior of
+ * {@code invokeExact} and {@code invokeGeneric}
+ * is referenced by the term signature polymorphism.
+ * A signature polymorphic method is one which can operate with
+ * any of a wide range of call signatures and return types.
+ * In order to make this work, both the Java compiler and the JVM must
+ * give special treatment to signature polymorphic methods.
+ * 

+ * In source code, a call to a signature polymorphic method will
+ * compile, regardless of the requested type descriptor.
+ * As usual, the Java compiler emits an {@code invokevirtual}
+ * instruction with the given type descriptor against the named method.
+ * The unusual part is that the type descriptor is derived from
+ * the actual argument and return types, not from the method declaration.
+ * 

+ * When the JVM processes bytecode containing signature polymorphic calls,
+ * it will successfully link any such call, regardless of its type descriptor.
+ * (In order to retain type safety, the JVM will guard such calls with suitable
+ * dynamic type checks, as described elsewhere.)
  * 

- * A note on generic typing:  Method handles do not represent
- * their function types in terms of Java parameterized (generic) types,
- * because there are three mismatches between function types and parameterized
+ * Bytecode generators, including the compiler back end, are required to emit
+ * untransformed type descriptors for these methods.
+ * Tools which determine symbolic linkage are required to accept such
+ * untransformed descriptors, without reporting linkage errors.
+ *
+ * 
Interoperation between method handles and the Core Reflection API

+ * Using factory methods in the {@link java.dyn.MethodHandles.Lookup Lookup} API,
+ * any class member represented by a Core Reflection API object
+ * can be converted to a behaviorally equivalent method handle.
+ * For example, a reflective {@link java.lang.reflect.Method Method} can
+ * be converted to a method handle using
+ * {@link java.dyn.MethodHandles.Lookup#unreflect Lookup.unreflect}.
+ * The resulting method handles generally provide more direct and efficient
+ * access to the underlying class members.
+ * 

+ * As a special case,
+ * when the Core Reflection API is used to view the signature polymorphic
+ * methods {@code invokeExact} or {@code invokeGeneric} in this class,
+ * they appear as single, non-polymorphic native methods.
+ * Calls to these native methods do not result in method handle invocations.
+ * Since {@code invokevirtual} instructions can natively
+ * invoke method handles under any type descriptor, this reflective view conflicts
+ * with the normal presentation via bytecodes.
+ * Thus, these two native methods, as viewed by
+ * {@link java.lang.Class#getDeclaredMethod Class.getDeclaredMethod},
+ * are placeholders only.
+ * If invoked via {@link java.lang.reflect.Method#invoke Method.invoke},
+ * they will throw {@code UnsupportedOperationException}.
+ * 

+ * In order to obtain an invoker method for a particular type descriptor,
+ * use {@link java.dyn.MethodHandles#exactInvoker MethodHandles.exactInvoker},
+ * or {@link java.dyn.MethodHandles#genericInvoker MethodHandles.genericInvoker}.
+ * The {@link java.dyn.MethodHandles.Lookup#findVirtual Lookup.findVirtual}
+ * API is also able to return a method handle
+ * to call {@code invokeExact} or {@code invokeGeneric},
+ * for any specified type descriptor .
+ *
+ * 
Interoperation between method handles and Java generics

+ * 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
+ * will constructed from the erasure of the source-level type.
+ * When a method handle is invoked, the types of its arguments
+ * or the return value cast type may be generic types or type instances.
+ * If this occurs, the compiler will replace those
+ * types by their erasures when when it constructs the type descriptor
+ * for the {@code invokevirtual} instruction.
+ * 

+ * Method handles do not represent
+ * their function-like types in terms of Java parameterized (generic) types,
+ * because there are three mismatches between function-like types and parameterized
  * Java types.
- * 
    
+ * 
      
  * 
    • Method types range over all possible arities,
  * from no arguments to up to 255 of arguments (a limit imposed by the JVM).
  * Generics are not variadic, and so cannot represent this.
      • 
@@ -225,29 +380,7 @@
  * often generic across a wide range of function types, including
  * those of multiple arities.  It is impossible to represent such
  * genericity with a Java type parameter.
- * 

- * Signature polymorphic methods in this class appear to be documented
- * as having type parameters for return types and a parameter, but that is
- * merely a documentation convention.  These type parameters do
- * not play a role in type-checking method handle invocations.
- * 

- * Like classes and strings, method handles that correspond to accessible
- * fields, methods, and constructors can be represented directly
- * in a class file's constant pool as constants to be loaded by {@code ldc} bytecodes.
- * Loading such a constant causes the component classes of its type to be loaded as necessary.
- * 

- * Method handles cannot be subclassed by the user.
- * Implementations may (or may not) create internal subclasses of {@code MethodHandle}
- * which may be visible via the {@code java.lang.Object#getClass Object.getClass}
- * operation.  The programmer should not draw conclusions about a method handle
- * from its specific class, as the method handle class hierarchy (if any)
- * may change from time to time or across implementations from different vendors.
- * 

- * With respect to the Java Memory Model, any method handle will behave
- * as if all of its fields are final variables.  This means that any method
- * handle made visible to the application will always be fully formed.
- * This is true even if the method handle is published through a shared
- * variables in a data race.
+ * 
  *
  * @see MethodType
  * @see MethodHandles
@@ -259,6 +392,7 @@
         extends MethodHandleImpl
 {
     private static Access IMPL_TOKEN = Access.getToken();
+    static { MethodHandleImpl.initStatics(); }
 
     // interface MethodHandle
     // { MethodType type(); public R invokeExact(A...) throws X; }
@@ -278,7 +412,7 @@
      * Every invocation of this method handle via {@code invokeExact} must exactly match this type.
      * @return the method handle type
      */
-    public final MethodType type() {
+    public MethodType type() {
         return type;
     }
 
@@ -315,20 +449,27 @@
     }
 
     /**
-     * Invoke the method handle, allowing any caller signature, but requiring an exact signature match.
-     * The signature at the call site of {@code invokeExact} must
+     * Invoke the method handle, allowing any caller type descriptor, but requiring an exact type match.
+     * The type descriptor at the call site of {@code invokeExact} must
      * exactly match this method handle's {@link #type type}.
      * No conversions are allowed on arguments or return values.
-     * @throws WrongMethodTypeException if the target's type is not identical with the caller's type signature
+     * 

+     * When this method is observed via the Core Reflection API,
+     * it will appear as a single native method, taking an object array and returning an object.
+     * If this native method is invoked directly via
+     * {@link java.lang.reflect.Method#invoke Method.invoke}, via JNI,
+     * or indirectly via {@link java.dyn.MethodHandles.Lookup#unreflect Lookup.unreflect},
+     * it will throw an {@code UnsupportedOperationException}.
+     * @throws WrongMethodTypeException if the target's type is not identical with the caller's type descriptor
      * @throws Throwable anything thrown by the underlying method propagates unchanged through the method handle call
      */
     public final native @PolymorphicSignature Object invokeExact(Object... args) throws Throwable;
 
     /**
-     * Invoke the method handle, allowing any caller signature,
+     * Invoke the method handle, allowing any caller type descriptor,
      * and optionally performing conversions on arguments and return values.
      * 

-     * If the call site signature exactly matches this method handle's {@link #type type},
+     * If the call site type descriptor exactly matches this method handle's {@link #type type},
      * the call proceeds as if by {@link #invokeExact invokeExact}.
      * 

      * Otherwise, the call proceeds as if this method handle were first
@@ -341,12 +482,19 @@
      * adaptations directly on the caller's arguments,
      * and call the target method handle according to its own exact type.
      * 

-     * The signature at the call site of {@code invokeGeneric} must
+     * The type descriptor at the call site of {@code invokeGeneric} must
      * be a valid argument to the receivers {@code asType} method.
      * In particular, the caller must specify the same argument arity
      * as the callee's type,
      * if the callee is not a {@linkplain #asVarargsCollector variable arity collector}.
-     * @throws WrongMethodTypeException if the target's type cannot be adjusted to the caller's type signature
+     * 

+     * When this method is observed via the Core Reflection API,
+     * it will appear as a single native method, taking an object array and returning an object.
+     * If this native method is invoked directly via
+     * {@link java.lang.reflect.Method#invoke Method.invoke}, via JNI,
+     * or indirectly via {@link java.dyn.MethodHandles.Lookup#unreflect Lookup.unreflect},
+     * it will throw an {@code UnsupportedOperationException}.
+     * @throws WrongMethodTypeException if the target's type cannot be adjusted to the caller's 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
      */
@@ -390,13 +538,19 @@
      * MethodHandle invoker = MethodHandles.spreadInvoker(this.type(), 0);
      * Object result = invoker.invokeExact(this, arguments);
      *
+ *

+ * Unlike the signature polymorphic methods {@code invokeExact} and {@code invokeGeneric}, + * {@code invokeWithArguments} can be accessed normally via the Core Reflection API and JNI. + * It can therefore be used as a bridge between native or reflective code and method handles. + * * @param arguments the arguments to pass to the target * @return the result returned by the target - * @throws WrongMethodTypeException if the target's type cannot be adjusted to take the arguments + * @throws ClassCastException if an argument cannot be converted by reference casting + * @throws WrongMethodTypeException if the target's type cannot be adjusted to take the given number of {@code Object} arguments * @throws Throwable anything thrown by the target method invocation * @see MethodHandles#spreadInvoker */ - public final Object invokeWithArguments(Object... arguments) throws Throwable { + public Object invokeWithArguments(Object... arguments) throws Throwable { int argc = arguments == null ? 0 : arguments.length; MethodType type = type(); if (type.parameterCount() != argc) { @@ -404,7 +558,7 @@ return asType(MethodType.genericMethodType(argc)).invokeWithArguments(arguments); } if (argc <= 10) { - MethodHandle invoker = MethodHandles.invokers(type).genericInvoker(); + MethodHandle invoker = invokers(type).genericInvoker(); switch (argc) { case 0: return invoker.invokeExact(this); case 1: return invoker.invokeExact(this, @@ -447,15 +601,7 @@ return invoker.invokeExact(this, arguments); } /** Equivalent to {@code invokeWithArguments(arguments.toArray())}. */ - public final Object invokeWithArguments(java.util.List arguments) throws Throwable { - return invokeWithArguments(arguments.toArray()); - } - @Deprecated - public final Object invokeVarargs(Object... arguments) throws Throwable { - return invokeWithArguments(arguments); - } - @Deprecated - public final Object invokeVarargs(java.util.List arguments) throws Throwable { + public Object invokeWithArguments(java.util.List arguments) throws Throwable { return invokeWithArguments(arguments.toArray()); } @@ -524,7 +670,7 @@ * @throws WrongMethodTypeException if the implied {@code asType} call fails * @see #asCollector */ - public final MethodHandle asSpreader(Class arrayType, int arrayLength) { + public MethodHandle asSpreader(Class arrayType, int arrayLength) { Class arrayElement = arrayType.getComponentType(); if (arrayElement == null) throw newIllegalArgumentException("not an array type"); MethodType oldType = type(); @@ -575,7 +721,7 @@ * @see #asSpreader * @see #asVarargsCollector */ - public final MethodHandle asCollector(Class arrayType, int arrayLength) { + public MethodHandle asCollector(Class arrayType, int arrayLength) { Class arrayElement = arrayType.getComponentType(); if (arrayElement == null) throw newIllegalArgumentException("not an array type"); MethodType oldType = type(); @@ -699,6 +845,7 @@ assertEquals("[three, thee, tee]", Arrays.toString((Object[])ls.get(0))); * *

+ * Discussion: * These rules are designed as a dynamically-typed variation * of the Java rules for variable arity methods. * In both cases, callers to a variable arity method or method handle @@ -710,7 +857,7 @@ * array or a single element of an array to be collected. * Note that the dynamic type of the trailing argument has no * effect on this decision, only a comparison between the static - * type signature of the call site and the type of the method handle.) + * type descriptor of the call site and the type of the method handle.) *

* As a result of the previously stated rules, the variable arity behavior * of a method handle may be suppressed, by binding it to the exact invoker @@ -719,9 +866,7 @@ MethodHandle vamh = publicLookup() .findStatic(Arrays.class, "asList", methodType(List.class, Object[].class)) .asVarargsCollector(Object[].class); -MethodHandle invokeExact = publicLookup() - .findVirtual(MethodHandle.class, "invokeExact", vamh.type()); -MethodHandle mh = invokeExact.bindTo(vamh); +MethodHandle mh = MethodHandles.exactInvoker(vamh.type()).bindTo(vamh); assert(vamh.type().equals(mh.type())); assertEquals("[1, 2, 3]", vamh.invokeGeneric(1,2,3).toString()); boolean failed = false; @@ -731,12 +876,14 @@ * * This transformation has no behavioral effect if the method handle is * not of variable arity. + * * @param arrayType often {@code Object[]}, the type of the array argument which will collect the arguments * @return a new method handle which can collect any number of trailing arguments * into an array, before calling the original method handle * @throws IllegalArgumentException if {@code arrayType} is not an array type * or {@code arrayType} is not assignable to this method handle's trailing parameter type * @see #asCollector + * @see #isVarargsCollector */ public MethodHandle asVarargsCollector(Class arrayType) { Class arrayElement = arrayType.getComponentType(); @@ -756,6 +903,7 @@ * which resolves to a variable arity Java method or constructor * * @return true if this method handle accepts more than one arity of {@code invokeGeneric} calls + * @see #asVarargsCollector */ public boolean isVarargsCollector() { return false; @@ -785,7 +933,7 @@ * to the leading parameter type of the target * @see MethodHandles#insertArguments */ - public final MethodHandle bindTo(Object x) { + public MethodHandle bindTo(Object x) { return MethodHandles.insertArguments(this, 0, x); } diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/MethodHandles.java --- a/jdk/src/share/classes/java/dyn/MethodHandles.java Fri Feb 11 01:26:24 2011 -0800 +++ b/jdk/src/share/classes/java/dyn/MethodHandles.java Fri Feb 11 01:26:28 2011 -0800 @@ -29,6 +29,7 @@ import sun.dyn.Access; import sun.dyn.MemberName; import sun.dyn.MethodHandleImpl; +import sun.dyn.WrapperInstance; import sun.dyn.util.ValueConversions; import sun.dyn.util.VerifyAccess; import sun.dyn.util.Wrapper; @@ -45,10 +46,10 @@ * This class consists exclusively of static methods that operate on or return * method handles. They fall into several categories: *

*

* @author John Rose, JSR 292 EG @@ -97,34 +98,130 @@ * when the creation requires access checking. * Method handles do not perform * access checks when they are called, but rather when they are created. - * (This is a major difference - * from reflective {@link Method}, which performs access checking - * against every caller, on every call.) * Therefore, method handle access * restrictions must be enforced when a method handle is created. * The caller class against which those restrictions are enforced * is known as the {@linkplain #lookupClass lookup class}. - * A lookup object embodies an - * authenticated lookup class, and can be used to create any number + *

+ * A lookup class which needs to create method handles will call + * {@link MethodHandles#lookup MethodHandles.lookup} to create a factory for itself. + * When the {@code Lookup} factory object is created, the identity of the lookup class is + * determined, and securely stored in the {@code Lookup} object. + * The lookup class (or its delegates) may then use factory methods + * 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. + *

+ * 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: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
lookup expressionmemberbehavior
{@linkplain java.dyn.MethodHandles.Lookup#findGetter lookup.findGetter(C.class,"f",FT.class)}FT f;(T) this.f;
{@linkplain java.dyn.MethodHandles.Lookup#findStaticGetter lookup.findStaticGetter(C.class,"f",FT.class)}static
FT f;		(T) C.f;
{@linkplain java.dyn.MethodHandles.Lookup#findSetter lookup.findSetter(C.class,"f",FT.class)}FT f;this.f = x;
{@linkplain java.dyn.MethodHandles.Lookup#findStaticSetter lookup.findStaticSetter(C.class,"f",FT.class)}static
FT f;		C.f = arg;
{@linkplain java.dyn.MethodHandles.Lookup#findVirtual lookup.findVirtual(C.class,"m",MT)}T m(A*);(T) this.m(arg*);
{@linkplain java.dyn.MethodHandles.Lookup#findStatic lookup.findStatic(C.class,"m",MT)}static
T m(A*);		(T) C.m(arg*);
{@linkplain java.dyn.MethodHandles.Lookup#findSpecial lookup.findSpecial(C.class,"m",MT,this.class)}T m(A*);(T) super.m(arg*);
{@linkplain java.dyn.MethodHandles.Lookup#findConstructor lookup.findConstructor(C.class,MT)}C(A*);(T) new C(arg*);
{@linkplain java.dyn.MethodHandles.Lookup#unreflectGetter lookup.unreflectGetter(aField)}(static)?
FT f;		(FT) aField.get(thisOrNull);
{@linkplain java.dyn.MethodHandles.Lookup#unreflectSetter lookup.unreflectSetter(aField)}(static)?
FT f;		aField.set(thisOrNull, arg);
{@linkplain java.dyn.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}(static)?
T m(A*);		(T) aMethod.invoke(thisOrNull, arg*);
{@linkplain java.dyn.MethodHandles.Lookup#unreflectConstructor lookup.unreflectConstructor(aConstructor)}C(A*);(C) aConstructor.newInstance(arg*);
{@linkplain java.dyn.MethodHandles.Lookup#unreflect lookup.unreflect(aMethod)}(static)?
T m(A*);		(T) aMethod.invoke(thisOrNull, arg*);
+ * + * 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} + * and the sequence of argument types {@code A*}. + * 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. + * The name {@code arg} stands for all the other method handle arguments. + * In the code examples for the Core Reflection API, the name {@code thisOrNull} + * stands for a null reference if the accessed method or field is static, + * and {@code this} otherwise. + * The names {@code aMethod}, {@code aField}, and {@code aConstructor} stand + * for reflective objects corresponding to the given members. + *

+ * The equivalence between looked-up method handles and underlying + * class members can break down in a few ways: + *

+ * + *

Access checking

+ * 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 + * {@link java.lang.reflect.Method#invoke Method.invoke} + * performs access checking against every caller, on every call. + *

+ * All access checks start from a {@code Lookup} object, which + * compares its recorded lookup class against all requests to + * create method handles. + * A single {@code Lookup} object can be used to create any number * of access-checked method handles, all checked against a single * lookup class. *

- * A class which needs to create method handles will call - * {@link MethodHandles#lookup MethodHandles.lookup} to create a factory for itself. - * It may then use this factory to create method handles on - * all of its methods, including private ones. - * It may also delegate the lookup (e.g., to a metaobject protocol) - * by passing the lookup object to other code. - * If this other code creates method handles, they will be access - * checked against the original lookup class, and not with any higher - * privileges. + * A {@code Lookup} object can be shared with other trusted code, + * such as a metaobject protocol. + * A shared {@code Lookup} object delegates the capability + * to create method handles on private members of the lookup class. + * Even if privileged code uses the {@code Lookup} object, + * the access checking is confined to the privileges of the + * original lookup class. *

- * Access checks only apply to named and reflected methods. - * Other method handle creation methods, such as - * {@link #convertArguments MethodHandles.convertArguments}, - * do not require any access checks, and can be done independently - * of any lookup class. - *

How access errors are handled

* 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 @@ -134,13 +231,13 @@ * thrown from the attempted lookup. *

* In general, the conditions under which a method handle may be - * created for a method {@code M} are exactly as restrictive as the conditions - * under which the lookup class could have compiled a call to {@code M}, - * or could have compiled an {@code ldc} instruction loading a - * {@code CONSTANT_MethodHandle} of M. + * 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}. + * 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}. * The same point is true of fields and constructors. *

- * In some cases, this access is obtained by the Java compiler by creating + * In some cases, access between nested classes is obtained by the Java compiler by creating * an wrapper method to access a private method of another class * in the same top-level declaration. * For example, a nested class {@code C.D} @@ -152,6 +249,14 @@ * A workaround for this limitation is the {@link Lookup#in Lookup.in} method, * which can transform a lookup on {@code C.E} into one on any of those other * classes, without special elevation of privilege. + *

+ * Access checks only apply to named and reflected methods, + * constructors, and fields. + * Other method handle creation methods, such as + * {@link #convertArguments MethodHandles.convertArguments}, + * do not require any access checks, and are done + * with static methods of {@link MethodHandles}, + * independently of any {@code Lookup} object. */ public static final class Lookup { @@ -197,12 +302,12 @@ return (mods != 0) ? mods : PACKAGE; } - /** Which class is performing the lookup? It is this class against + /** Tells which class is performing the lookup. It is this class against * which checks are performed for visibility and access permissions. *

* The class implies a maximum level of access permission, * but the permissions may be additionally limited by the bitmask - * {@link #lookupModes}, which controls whether non-public members + * {@link #lookupModes lookupModes}, which controls whether non-public members * can be accessed. */ public Class lookupClass() { @@ -214,7 +319,7 @@ return (allowedModes == TRUSTED) ? null : lookupClass; } - /** Which types of members can this lookup object produce? + /** Tells which access-protection classes of members this lookup object can produce. * The result is a bit-mask of the bits * {@linkplain #PUBLIC PUBLIC (0x01)}, * {@linkplain #PRIVATE PRIVATE (0x02)}, @@ -260,7 +365,7 @@ } /** - * Create a lookup on the specified new lookup class. + * Creates a lookup on the specified new lookup class. * The resulting object will report the specified * class as its own {@link #lookupClass lookupClass}. *

@@ -278,6 +383,10 @@ * then no members, not even public members, will be accessible. * (In all other cases, public members will continue to be accessible.) * + * + * @param requestedLookupClass the desired lookup class for the new lookup object + * @return a lookup object which reports the desired lookup class + * @throws NullPointerException if the argument is null */ public Lookup in(Class requestedLookupClass) { requestedLookupClass.getClass(); // null check @@ -325,11 +434,12 @@ } /** - * Display the name of the class from which lookups are to be made. + * Displays the name of the class from which lookups are to be made. * (The name is the one reported by {@link java.lang.Class#getName() Class.getName}.) * If there are restrictions on the access permitted to this lookup, * this is indicated by adding a suffix to the class name, consisting - * of a slash and a keyword. The keyword is chosen as follows: + * of a slash and a keyword. The keyword represents the strongest + * allowed access, and is chosen as follows: *

*

- * The invoker will behave like a call to {@link MethodHandle.invokeGeneric} with + * The invoker will behave like a call to {@link MethodHandle#invokeGeneric invokeGeneric} with * the indicated {@code type}. * That is, if the target is exactly of the given {@code type}, it will behave - * like {@code invokeExact}; otherwise it behave as if {@link MethodHandle.asType} + * like {@code invokeExact}; otherwise it behave as if {@link MethodHandle#asType asType} * is used to convert the target to the required {@code type}. *

* The type of the returned invoker will not be the given {@code type}, but rather @@ -973,12 +1070,13 @@ *

* This method is equivalent to the following code (though it may be more efficient): * 

-MethodHandle invoker = publicLookup()
-  .findVirtual(MethodHandle.class, "invokeGeneric", type)
+MethodHandle invoker = MethodHandles.genericInvoker(type);
 int spreadArgCount = type.parameterCount - objectArgCount;
 invoker = invoker.asSpreader(Object[].class, spreadArgCount);
 return invoker;
      *
+ *

+ * This method throws no reflective or security exceptions. * @param type the desired target type * @param objectArgCount number of fixed (non-varargs) {@code Object} arguments * @return a method handle suitable for invoking any method handle of the given type @@ -991,15 +1089,37 @@ } /** - * Produce a method handle which will take a invoke any method handle of the - * given type. The resulting invoker will have a type which is + * Produces a special invoker method handle which can be used to + * invoke any method handle of the given type, as if by {@code invokeExact}. + * The resulting invoker will have a type which is * exactly equal to the desired type, except that it will accept * an additional leading argument of type {@code MethodHandle}. *

* This method is equivalent to the following code (though it may be more efficient): * 

-     * lookup().findVirtual(MethodHandle.class, "invokeExact", type);
+publicLookup().findVirtual(MethodHandle.class, "invokeExact", type)
      *
+ * + *

+ * Discussion: + * Invoker method handles can be useful when working with variable method handles + * of unknown types. + * For example, to emulate an {@code invokeExact} call to a variable method + * handle {@code M}, extract its type {@code T}, + * look up the invoker method {@code X} for {@code T}, + * and call the invoker method, as {@code X.invokeGeneric(T, A...)}. + * (It would not work to call {@code X.invokeExact}, since the type {@code T} + * is unknown.) + * If spreading, collecting, or other argument transformations are required, + * they can be applied once to the invoker {@code X} and reused on many {@code M} + * method handle values, as long as they are compatible with the type of {@code X}. + *

+ * (Note: The invoker method is not available via the Core Reflection API. + * An attempt to call {@linkplain java.lang.reflect.Method#invoke Method.invoke} + * on the declared {@code invokeExact} or {@code invokeGeneric} method will raise an + * {@link java.lang.UnsupportedOperationException UnsupportedOperationException}.) + *

+ * This method throws no reflective or security exceptions. * @param type the desired target type * @return a method handle suitable for invoking any method handle of the given type */ @@ -1008,12 +1128,38 @@ return invokers(type).exactInvoker(); } + /** + * Produces a special invoker method handle which can be used to + * invoke any method handle of the given type, as if by {@code invokeGeneric}. + * The resulting invoker will have a type which is + * exactly equal to the desired type, except that it will accept + * an additional leading argument of type {@code MethodHandle}. + *

+ * Before invoking its target, the invoker will apply reference casts as + * necessary and unbox and widen primitive arguments, as if by {@link #convertArguments convertArguments}. + * The return value of the invoker will be an {@code Object} reference, + * boxing a primitive value if the original type returns a primitive, + * and always null if the original type returns void. + *

+ * This method is equivalent to the following code (though it may be more efficient): + * 

+publicLookup().findVirtual(MethodHandle.class, "invokeGeneric", type)
+     *
+ *

+ * This method throws no reflective or security exceptions. + * @param type the desired target type + * @return a method handle suitable for invoking any method handle convertible to the given type + */ + static public + MethodHandle genericInvoker(MethodType type) { + return invokers(type).genericInvoker(); + } + static Invokers invokers(MethodType type) { return MethodTypeImpl.invokers(IMPL_TOKEN, type); } /** - * WORK IN PROGRESS: * Perform value checking, exactly as if for an adapted method handle. * It is assumed that the given value is either null, of type T0, * or (if T0 is primitive) of the wrapper type corresponding to T0. @@ -1084,7 +1230,7 @@ /// method handle modification (creation from other method handles) /** - * Produce a method handle which adapts the type of the + * Produces a method handle which adapts the type of the * given method handle to a new type by pairwise argument conversion. * The original type and new type must have the same number of arguments. * The resulting method handle is guaranteed to report a type @@ -1123,6 +1269,7 @@ * @return a method handle which delegates to {@code target} after performing * any necessary argument conversions, and arranges for any * necessary return value conversions + * @throws NullPointerException if either argument is null * @throws WrongMethodTypeException if the conversion cannot be made * @see MethodHandle#asType * @see MethodHandles#explicitCastArguments @@ -1144,7 +1291,7 @@ } /** - * Produce a method handle which adapts the type of the + * Produces a method handle which adapts the type of the * given method handle to a new type by pairwise argument conversion. * The original type and new type must have the same number of arguments. * The resulting method handle is guaranteed to report a type @@ -1176,6 +1323,7 @@ * @return a method handle which delegates to {@code target} after performing * any necessary argument conversions, and arranges for any * necessary return value conversions + * @throws NullPointerException if either argument is null * @throws WrongMethodTypeException if the conversion cannot be made * @see MethodHandle#asType * @see MethodHandles#convertArguments @@ -1223,7 +1371,7 @@ */ /** - * Produce a method handle which adapts the calling sequence of the + * Produces a method handle which adapts the calling sequence of the * given method handle to a new type, by reordering the arguments. * The resulting method handle is guaranteed to report a type * which is equal to the desired new type. @@ -1271,6 +1419,7 @@ * @param reorder a string which controls the reordering * @return a method handle which delegates to {@code target} after it * drops unused arguments and moves and/or duplicates the other arguments + * @throws NullPointerException if any argument is null */ public static MethodHandle permuteArguments(MethodHandle target, MethodType newType, int... reorder) { @@ -1296,11 +1445,10 @@ } /** - * METHOD WILL BE REMOVED FOR PFD: * Equivalent to the following code: * 

      * int spreadPos = newType.parameterCount() - 1;
-     * Class spreadType = newType.parameterType(spreadPos);
+     * Class<?> spreadType = newType.parameterType(spreadPos);
      * int spreadCount = target.type().parameterCount() - spreadPos;
      * MethodHandle adapter = target.asSpreader(spreadType, spreadCount);
      * adapter = adapter.asType(newType);
@@ -1310,9 +1458,8 @@
      * @param newType the expected type of the new method handle
      * @return a method handle which spreads its final argument,
      *         before calling the original method handle
-     * @deprecated Use {@link MethodHandle#asSpreader}
      */
-    public static
+    /*non-public*/ static
     MethodHandle spreadArguments(MethodHandle target, MethodType newType) {
         MethodType oldType = target.type();
         int inargs  = newType.parameterCount();
@@ -1330,11 +1477,10 @@
     }
 
     /**
-     * METHOD WILL BE REMOVED FOR PFD:
      * Equivalent to the following code:
      * 
      * int collectPos = target.type().parameterCount() - 1;
-     * Class collectType = target.type().parameterType(collectPos);
+     * Class<?> collectType = target.type().parameterType(collectPos);
      * if (!collectType.isArray())  collectType = Object[].class;
      * int collectCount = newType.parameterCount() - collectPos;
      * MethodHandle adapter = target.asCollector(collectType, collectCount);
@@ -1345,9 +1491,8 @@
      * @param newType the expected type of the new method handle
      * @return a method handle which collects some trailing argument
      *         into an array, before calling the original method handle
-     * @deprecated Use {@link MethodHandle#asCollector} instead.
      */
-    public static
+    /*non-public*/ static
     MethodHandle collectArguments(MethodHandle target, MethodType newType) {
         MethodType oldType = target.type();
         int inargs  = newType.parameterCount();
@@ -1364,7 +1509,7 @@
     }
 
     /**
-     * Produce a method handle of the requested return type which returns the given
+     * Produces a method handle of the requested return type which returns the given
      * constant value every time it is invoked.
      * 

      * Before the method handle is returned, the passed-in value is converted to the requested type.
@@ -1375,12 +1520,15 @@
      * @param type the return type of the desired method handle
      * @param value the value to return
      * @return a method handle of the given return type and no arguments, which always returns the given value
-     * @throws WrongMethodTypeException if the value cannot be converted to the required return type
+     * @throws NullPointerException if the {@code type} argument is null
+     * @throws ClassCastException if the value cannot be converted to the required return type
+     * @throws IllegalArgumentException if the given type is {@code void.class}
      */
     public static
     MethodHandle constant(Class type, Object value) {
         if (type.isPrimitive()) {
-            if (type == void.class)  return identity(type);
+            if (type == void.class)
+                throw newIllegalArgumentException("void type");
             Wrapper w = Wrapper.forPrimitiveType(type);
             return identity(type).bindTo(w.convert(value, type));
         } else {
@@ -1389,64 +1537,22 @@
     }
 
     /**
-     * Produce a method handle of the requested type which returns the given
-     * constant value every time it is invoked.
-     * 

-     * Before the method handle is returned, the passed-in value is converted to the requested return type,
-     * as if by {@link #explicitCastArguments #explicitCastArguments}.
-     * That is, if the return type is primitive, the value is unboxed,
-     * and the primitive value is widened and/or narrowed.
-     * Otherwise, reference conversions are attempted.
-     * @param type the type of the desired method handle
-     * @param value the value to return
-     * @return a method handle of the given return type and no arguments, which always returns the given value
-     * @throws WrongMethodTypeException if the value cannot be converted to the required return type
+     * Produces a method handle which returns its sole argument when invoked.
+     * 
The identity function for {@code void} takes no arguments and returns no values.
+     * @param type the type of the sole parameter and return value of the desired method handle
+     * @return a unary method handle which accepts and returns the given type
+     * @throws NullPointerException if the argument is null
+     * @throws IllegalArgumentException if the given type is {@code void.class}
      */
     public static
-    MethodHandle constant(MethodType type, Object value) {
-        MethodHandle target = constant(type.returnType(), value);
-        int len = type.parameterCount();
-        if (len == 0)
-            return target.asType(type);
-        target = target.asType(type.dropParameterTypes(0, len));
-        return dropArguments(target, 0, type.parameterList().subList(0, len));
-    }
-
-     /**
-      * Produce a method handle which returns its sole argument when invoked.
-      * 
The identity function for {@code void} takes no arguments and returns no values.
-      * @param type the type of the sole parameter and return value of the desired method handle
-      * @return a unary method handle which accepts and returns the given type
-      */
-    public static
     MethodHandle identity(Class type) {
+        if (type == void.class)
+            throw newIllegalArgumentException("void type");
         return ValueConversions.identity(type);
     }
 
-     /**
-      * Produce a method handle of the requested type which returns its argument when invoked.
-      * If the return type differs from the first argument type, the argument will be
-      * converted as if by {@link #explicitCastArguments explicitCastArguments}.
-      * If there are additional arguments beyond the first, they are discarded.
-      * 
The identity function for {@code void} discards all its arguments.
-      * @param type the type of the desired method handle
-      * @return a method handle of the given type, which always returns its first argument
-      * @throws WrongMethodTypeException if the first argument cannot be converted to the required return type
-      */
-    public static
-    MethodHandle identity(MethodType type) {
-        MethodHandle target = identity(type.returnType());
-        int len = type.parameterCount();
-        if (len == 1)
-            return explicitCastArguments(target, type);
-        if (len == 0)
-            throw new IllegalArgumentException("not enough arguments");
-        target = explicitCastArguments(target, type.dropParameterTypes(1, len));
-        return dropArguments(target, 1, type.parameterList().subList(1, len));
-    }
-
     /**
-     * Produce a method handle which calls the original method handle {@code target},
+     * Produces a method handle which calls the original method handle {@code target},
      * after inserting the given argument(s) at the given position.
      * The formal parameters to {@code target} which will be supplied by those
      * arguments are called bound parameters, because the new method
@@ -1467,6 +1573,7 @@
      * @param values the series of arguments to insert
      * @return a method handle which inserts an additional argument,
      *         before calling the original method handle
+     * @throws NullPointerException if the {@code target} argument or the {@code values} array is null
      * @see MethodHandle#bindTo
      */
     public static
@@ -1501,7 +1608,7 @@
     }
 
     /**
-     * Produce a method handle which calls the original method handle,
+     * Produces a method handle which calls the original method handle,
      * after dropping the given argument(s) at the given position.
      * The type of the new method handle will insert the given argument
      * type(s), at that position, into the original handle's type.
@@ -1533,6 +1640,9 @@
      * @param pos position of first argument to drop (zero for the leftmost)
      * @return a method handle which drops arguments of the given types,
      *         before calling the original method handle
+     * @throws NullPointerException if the {@code target} argument is null,
+     *                              or if the {@code valueTypes} list or any of its elements is null
+     * @throws IllegalArgumentException if any of the {@code valueTypes} is {@code void.class}
      */
     public static
     MethodHandle dropArguments(MethodHandle target, int pos, List> valueTypes) {
@@ -1550,7 +1660,7 @@
     }
 
     /**
-     * Produce a method handle which calls the original method handle,
+     * Produces a method handle which calls the original method handle,
      * after dropping the given argument(s) at the given position.
      * The type of the new method handle will insert the given argument
      * type(s), at that position, into the original handle's type.
@@ -1563,6 +1673,9 @@
      * @param pos position of first argument to drop (zero for the leftmost)
      * @return a method handle which drops arguments of the given types,
      *         before calling the original method handle
+     * @throws NullPointerException if the {@code target} argument is null,
+     *                              or if the {@code valueTypes} array or any of its elements is null
+     * @throws IllegalArgumentException if any of the {@code valueTypes} is {@code void.class}
      */
     public static
     MethodHandle dropArguments(MethodHandle target, int pos, Class... valueTypes) {
@@ -1577,7 +1690,8 @@
      * 

      * The pre-processing is performed by one or more method handles,
      * specified in the elements of the {@code filters} array.
-     * (If there are no elements in the array, the original target is returned.)
+     * Null arguments in the array are ignored, and the corresponding arguments left unchanged.
+     * (If there are no non-null elements in the array, the original target is returned.)
      * Each filter is applied to the corresponding argument of the adapter.
      * 

      * If a filter {@code F} applies to the {@code N}th argument of
@@ -1607,12 +1721,16 @@
 MethodHandle f2 = filterArguments(cat, 0, upcase, upcase);
 assertEquals("XY", (String) f2.invokeExact("x", "y")); // XY
      * 

+     *
      * @param target the method handle to invoke after arguments are filtered
      * @param pos the position of the first argument to filter
      * @param filters method handles to call initially on filtered arguments
      * @return method handle which incorporates the specified argument filtering logic
-     * @throws IllegalArgumentException if an element of {@code filters} is null or
-     *          does not match a corresponding argument type of {@code target} as described above
+     * @throws NullPointerException if the {@code target} argument is null
+     *                              or if the {@code filters} array is null
+     * @throws IllegalArgumentException if a non-null element of {@code filters}
+     *          does not match a corresponding argument type of {@code target} as described above,
+     *          or if the {@code pos+filters.length} is greater than {@code target.type().parameterCount()}
      */
     public static
     MethodHandle filterArguments(MethodHandle target, int pos, MethodHandle... filters) {
@@ -1620,17 +1738,18 @@
         MethodHandle adapter = target;
         MethodType adapterType = targetType;
         int maxPos = targetType.parameterCount();
-        int curPos = pos;
+        if (pos + filters.length > maxPos)
+            throw newIllegalArgumentException("too many filters");
+        int curPos = pos-1;  // pre-incremented
         for (MethodHandle filter : filters) {
-            if (curPos >= maxPos)
-                throw newIllegalArgumentException("too many filters");
+            curPos += 1;
+            if (filter == null)  continue;  // ignore null elements of filters
             MethodType filterType = filter.type();
             if (filterType.parameterCount() != 1
                 || filterType.returnType() != targetType.parameterType(curPos))
                 throw newIllegalArgumentException("target and filter types do not match");
             adapterType = adapterType.changeParameterType(curPos, filterType.parameterType(0));
             adapter = MethodHandleImpl.filterArgument(IMPL_TOKEN, adapter, curPos, filter);
-            curPos += 1;
         }
         MethodType midType = adapter.type();
         if (midType != adapterType)
@@ -1665,7 +1784,8 @@
      * @param target the method handle to invoke before filtering the return value
      * @param filter method handle to call on the return value
      * @return method handle which incorporates the specified return value filtering logic
-     * @throws IllegalArgumentException if {@code filter} is null or
+     * @throws NullPointerException if either argument is null
+     * @throws IllegalArgumentException if {@code filter}
      *          does not match the return type of {@code target} as described above
      */
     public static
@@ -1675,9 +1795,11 @@
         if (filterType.parameterCount() != 1
             || filterType.parameterType(0) != targetType.returnType())
             throw newIllegalArgumentException("target and filter types do not match");
+        // result = fold( lambda(retval, arg...) { filter(retval) },
+        //                lambda(        arg...) { target(arg...) } )
         // FIXME: Too many nodes here.
-        MethodHandle returner = dropArguments(filter, 0, targetType.parameterList());
-        return foldArguments(returner, exactInvoker(target.type()).bindTo(target));
+        MethodHandle returner = dropArguments(filter, 1, targetType.parameterList());
+        return foldArguments(returner, target);
     }
 
     /**
@@ -1700,7 +1822,7 @@
      * (Note that {@link #dropArguments(MethodHandle,int,List) dropArguments} can be used to remove any arguments
      * that either the {@code combiner} or {@code target} does not wish to receive.
      * If some of the incoming arguments are destined only for the combiner,
-     * consider using {@link MethodHandle#asCollector} instead, since those
+     * consider using {@link MethodHandle#asCollector asCollector} instead, since those
      * arguments will not need to be live on the stack on entry to the
      * target.)
      * 

@@ -1719,6 +1841,7 @@
      * @param target the method handle to invoke after arguments are combined
      * @param combiner method handle to call initially on the incoming arguments
      * @return method handle which incorporates the specified argument folding logic
+     * @throws NullPointerException if either argument is null
      * @throws IllegalArgumentException if the first argument type of
      *          {@code target} is not the same as {@code combiner}'s return type,
      *          or if the following argument types of {@code target}
@@ -1767,6 +1890,7 @@
      * @param target method handle to call if test passes
      * @param fallback method handle to call if test fails
      * @return method handle which incorporates the specified if/then/else logic
+     * @throws NullPointerException if any argument is null
      * @throws IllegalArgumentException if {@code test} does not return boolean,
      *          or if all three method types do not match (with the return
      *          type of {@code test} changed to match that of {@code target}).
@@ -1835,6 +1959,7 @@
      * @param exType the type of exception which the handler will catch
      * @param handler method handle to call if a matching exception is thrown
      * @return method handle which incorporates the specified try/catch logic
+     * @throws NullPointerException if any argument is null
      * @throws IllegalArgumentException if {@code handler} does not accept
      *          the given exception type, or if the method handle types do
      *          not match in their return types and their
@@ -1865,12 +1990,14 @@
     }
 
     /**
-     * Produce a method handle which will throw exceptions of the given {@code exType}.
+     * Produces a method handle which will throw exceptions of the given {@code exType}.
      * The method handle will accept a single argument of {@code exType},
      * and immediately throw it as an exception.
      * 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.
+     * @return method handle which can throw the given exceptions
+     * @throws NullPointerException if either argument is null
      */
     public static
     MethodHandle throwException(Class returnType, Class exType) {
@@ -1878,11 +2005,22 @@
     }
 
     /**
-     * PROVISIONAL API, WORK IN PROGRESS:
-     * Produce a wrapper instance of the given "SAM" interface which redirects
+     * Produces an instance of the given "SAM" interface which redirects
      * its calls to the given method handle.
+     * 

      * A SAM interface is an interface which declares a single abstract method.
-     * The type must be public.  (No additional access checks are performed.)
+     * When determining the unique abstract method of a SAM interface,
+     * the public {@code Object} methods ({@code toString}, {@code equals}, {@code hashCode})
+     * are disregarded.  For example, {@link java.util.Comparator} is a SAM interface,
+     * even though it re-declares the {@code Object.equals} method.
+     * Also, if the SAM interface has a supertype,
+     * the SAM interface may override an inherited method.
+     * Any such overrides are respected, and the method handle will be accessible
+     * by either the inherited method or the SAM method.
+     * In particular, a {@linkplain java.lang.reflect.Method#isBridge bridge method}
+     * may be created if the methods have different return types.
+     * 

+     * The type must be public.  No additional access checks are performed.
      * 

      * The resulting instance of the required SAM type will respond to
      * invocation of the SAM type's single abstract method by calling
@@ -1894,6 +2032,17 @@
      * instance is created, as if by a call to {@code asType},
      * which may result in a {@code WrongMethodTypeException}.
      * 

+     * The wrapper instance will implement the requested SAM interface
+     * and its super-types, but no other SAM types.
+     * This means that the SAM instance will not unexpectedly
+     * pass an {@code instanceof} test for any unrequested type.
+     * 

+     * Implementation Note:
+     * Therefore, each SAM instance must implement a unique SAM type.
+     * Implementations may not bundle together
+     * multiple SAM types onto single implementation classes
+     * in the style of {@link java.awt.AWTEventMulticaster}.
+     * 

      * The method handle may throw an undeclared exception,
      * which means any checked exception (or other checked throwable)
      * not declared by the SAM type's single abstract method.
@@ -1901,56 +2050,46 @@
      * {@link java.lang.reflect.UndeclaredThrowableException UndeclaredThrowableException}
      * and thrown in that wrapped form.
      * 

-     * The wrapper instance is guaranteed to be of a non-public
-     * implementation class C in a package containing no classes
-     * or methods except system-defined classes and methods.
-     * The implementation class C will have no public supertypes
-     * or public methods beyond the following:
-     * 

-     * 

-     * (Note: When determining the unique abstract method of a SAM interface,
-     * the public {@code Object} methods ({@code toString}, {@code equals}, {@code hashCode})
-     * are disregarded.  For example, {@link java.util.Comparator} is a SAM interface,
-     * even though it re-declares the {@code Object.equals} method.)
-     * 

-     * No stable mapping is promised between the SAM type and
-     * the implementation class C.  Over time, several implementation
-     * classes might be used for the same SAM type.
-     * 

-     * This method is not guaranteed to return a distinct
-     * wrapper object for each separate call.  If the implementation is able
-     * to prove that a wrapper of the required SAM type
-     * has already been created for a given
-     * method handle, or for another method handle with the
-     * same behavior, the implementation may return that wrapper in place of
-     * a new wrapper.
-     * 

-     * This method is designed to apply to common use cases
-     * where a single method handle must interoperate with
-     * a type (class or interface) that implements a function-like
-     * API.  Additional variations, such as SAM classes with
-     * private constructors, or interfaces with multiple but related
-     * entry points, must be covered by hand-written or automatically
-     * generated adapter classes.  In those cases, consider implementing
-     * {@link java.dyn.MethodHandles.AsInstanceObject AsInstanceObject}
-     * in the adapters, so that generic code can extract the underlying
-     * method handle without knowing where the SAM adapter came from.
+     * Like {@link java.lang.Integer#valueOf Integer.valueOf},
+     * {@code asInstance} is a factory method whose results are defined
+     * by their behavior.
+     * It is not guaranteed to return a new instance for every call.
      * 

      * Future versions of this API may accept additional types,
      * such as abstract classes with single abstract methods.
+     * Future versions of this API may also equip wrapper instances
+     * with one or more additional public "marker" interfaces.
+     *
      * @param target the method handle to invoke from the wrapper
      * @param samType the desired type of the wrapper, a SAM type
      * @return a correctly-typed wrapper for the given {@code target}
+     * @throws NullPointerException if either argument is null
      * @throws IllegalArgumentException if the {@code samType} is not a
      *         valid argument to this method
      * @throws WrongMethodTypeException if the {@code target} cannot
      *         be converted to the type required by the SAM type
      */
+    // Other notes to implementors:
+    // 

+    // No stable mapping is promised between the SAM type and
+    // the implementation class C.  Over time, several implementation
+    // classes might be used for the same SAM type.
+    // 

+    // If the implementation is able
+    // to prove that a wrapper of the required SAM type
+    // has already been created for a given
+    // method handle, or for another method handle with the
+    // same behavior, the implementation may return that wrapper in place of
+    // a new wrapper.
+    // 

+    // This method is designed to apply to common use cases
+    // where a single method handle must interoperate with
+    // an interface that implements a function-like
+    // API.  Additional variations, such as SAM classes with
+    // private constructors, or interfaces with multiple but related
+    // entry points, must be covered by hand-written or automatically
+    // generated adapter classes.
+    //
     public static
      T asInstance(final MethodHandle target, final Class samType) {
         // POC implementation only; violates the above contract several ways
@@ -1963,15 +2102,15 @@
         final MethodHandle vaTarget = checkTarget.asSpreader(Object[].class, samMT.parameterCount());
         return samType.cast(Proxy.newProxyInstance(
                 samType.getClassLoader(),
-                new Class[]{ samType, AsInstanceObject.class },
+                new Class[]{ samType, WrapperInstance.class },
                 new InvocationHandler() {
                     private Object getArg(String name) {
-                        if ((Object)name == "getAsInstanceTarget")  return target;
-                        if ((Object)name == "getAsInstanceType")    return samType;
+                        if ((Object)name == "getWrapperInstanceTarget")  return target;
+                        if ((Object)name == "getWrapperInstanceType")    return samType;
                         throw new AssertionError();
                     }
                     public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
-                        if (method.getDeclaringClass() == AsInstanceObject.class)
+                        if (method.getDeclaringClass() == WrapperInstance.class)
                             return getArg(method.getName());
                         if (method.equals(sam))
                             return vaTarget.invokeExact(args);
@@ -1983,21 +2122,49 @@
     }
 
     /**
-     * PROVISIONAL API, WORK IN PROGRESS:
-     * Interface implemented by every object which is produced by {@link #asInstance asInstance}.
-     * The methods of this interface allow a caller to recover the parameters
-     * to {@code asInstance}.
-     * This allows applications to repeatedly convert between method handles
-     * and SAM objects, without the risk of creating unbounded delegation chains.
+     * Determine if the given object was produced by a call to {@link #asInstance asInstance}.
+     * @param x any reference
+     * @return true if the reference is not null and points to an object produced by {@code asInstance}
      */
-    public interface AsInstanceObject {
-        /** Produce or recover a target method handle which is behaviorally
-         *  equivalent to the SAM method of this object.
-         */
-        public MethodHandle getAsInstanceTarget();
-        /** Recover the SAM type for which this object was created.
-         */
-        public Class getAsInstanceType();
+    public static
+    boolean isWrapperInstance(Object x) {
+        return x instanceof WrapperInstance;
+    }
+
+    private static WrapperInstance asWrapperInstance(Object x) {
+        try {
+            if (x != null)
+                return (WrapperInstance) x;
+        } catch (ClassCastException ex) {
+        }
+        throw new IllegalArgumentException("not a wrapper instance");
+    }
+
+    /**
+     * Produces or recovers a target method handle which is behaviorally
+     * equivalent to the SAM method of this wrapper instance.
+     * The object {@code x} must have been produced by a call to {@link #asInstance asInstance}.
+     * This requirement may be tested via {@link #isWrapperInstance isWrapperInstance}.
+     * @param x any reference
+     * @return a method handle implementing the SAM method
+     * @throws IllegalArgumentException if the reference x is not to a wrapper instance
+     */
+    public static
+    MethodHandle wrapperInstanceTarget(Object x) {
+        return asWrapperInstance(x).getWrapperInstanceTarget();
+    }
+
+    /**
+     * Recover the SAM type for which this wrapper instance was created.
+     * The object {@code x} must have been produced by a call to {@link #asInstance asInstance}.
+     * This requirement may be tested via {@link #isWrapperInstance isWrapperInstance}.
+     * @param x any reference
+     * @return the SAM type for which the wrapper was created
+     * @throws IllegalArgumentException if the reference x is not to a wrapper instance
+     */
+    public static
+    Class wrapperInstanceType(Object x) {
+        return asWrapperInstance(x).getWrapperInstanceType();
     }
 
     private static
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/MethodType.java
--- a/jdk/src/share/classes/java/dyn/MethodType.java	Fri Feb 11 01:26:24 2011 -0800
+++ b/jdk/src/share/classes/java/dyn/MethodType.java	Fri Feb 11 01:26:28 2011 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2011, 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
@@ -31,6 +31,7 @@
 import java.util.List;
 import sun.dyn.Access;
 import sun.dyn.Invokers;
+import sun.dyn.MethodHandleImpl;
 import sun.dyn.MethodTypeImpl;
 import sun.dyn.util.BytecodeDescriptor;
 import static sun.dyn.MemberName.newIllegalArgumentException;
@@ -41,8 +42,8 @@
  * and expected  by a method handle caller.  Method types must be properly
  * matched between a method handle and all its callers,
  * and the JVM's operations enforce this matching at, specifically
- * during calls to {@link MethodHandle#invokeExact}
- * and {@link MethodHandle#invokeGeneric}, and during execution
+ * during calls to {@link MethodHandle#invokeExact MethodHandle.invokeExact}
+ * and {@link MethodHandle#invokeGeneric MethodHandle.invokeGeneric}, and during execution
  * of {@code invokedynamic} instructions.
  * 

  * The structure is a return type accompanied by any number of parameter types.
@@ -70,8 +71,9 @@
  * with the instructions in a class file's constant pool.
  * 

  * Like classes and strings, method types can also be represented directly
- * in a class file's constant pool as constants. The may be loaded by an {@code ldc}
- * instruction which refers to a suitable {@code CONSTANT_MethodType} constant pool entry.
+ * in a class file's constant pool as constants.
+ * 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 package summary.
  * 

@@ -124,15 +126,32 @@
         this.ptypes = ptypes;
     }
 
-    private void checkRtype(Class rtype) {
+    private static void checkRtype(Class rtype) {
         rtype.equals(rtype);  // null check
     }
-    private void checkPtypes(Class[] ptypes) {
+    private static int checkPtype(Class ptype) {
+        ptype.getClass();  //NPE
+        if (ptype == void.class)
+            throw newIllegalArgumentException("parameter type cannot be void");
+        if (ptype == double.class || ptype == long.class)  return 1;
+        return 0;
+    }
+    /** Return number of extra slots (count of long/double args). */
+    private static int checkPtypes(Class[] ptypes) {
+        int slots = 0;
         for (Class ptype : ptypes) {
-            ptype.equals(ptype);  // null check
-            if (ptype == void.class)
-                throw newIllegalArgumentException("parameter type cannot be void");
+            slots += checkPtype(ptype);
         }
+        checkSlotCount(ptypes.length + slots);
+        return slots;
+    }
+    private static void checkSlotCount(int count) {
+        if ((count & 0xFF) != count)
+            throw newIllegalArgumentException("bad parameter count "+count);
+    }
+    private static IndexOutOfBoundsException newIndexOutOfBoundsException(Object num) {
+        if (num instanceof Integer)  num = "bad index: "+num;
+        return new IndexOutOfBoundsException(num.toString());
     }
 
     static final HashMap internTable
@@ -140,27 +159,39 @@
 
     static final Class[] NO_PTYPES = {};
 
-    /** Find or create an instance of the given method type.
+    /**
+     * Find or create an instance of the given method type.
      * @param rtype  the return type
      * @param ptypes the parameter types
-     * @return a method type with the given parts
-     * @throws NullPointerException if rtype or any ptype is null
-     * @throws IllegalArgumentException if any of the ptypes is void
+     * @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}
      */
     public static
     MethodType methodType(Class rtype, Class[] ptypes) {
         return makeImpl(rtype, ptypes, false);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}. */
+    /**
+     * Finds or creates a method type with the given components.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
+     * @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}
+     */
     public static
-    MethodType methodType(Class rtype, List> ptypes) {
+    MethodType methodType(Class rtype, List> ptypes) {
         boolean notrust = false;  // random List impl. could return evil ptypes array
         return makeImpl(rtype, ptypes.toArray(NO_PTYPES), notrust);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
-     *  The leading parameter type is prepended to the remaining array.
+    /**
+     * 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.
+     * @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}
      */
     public static
     MethodType methodType(Class rtype, Class ptype0, Class... ptypes) {
@@ -170,25 +201,37 @@
         return makeImpl(rtype, ptypes1, true);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
-     *  The resulting method has no parameter types.
+    /**
+     * 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.
+     * @return a method type with the given return value
+     * @throws NullPointerException if {@code rtype} is null
      */
     public static
     MethodType methodType(Class rtype) {
         return makeImpl(rtype, NO_PTYPES, true);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
-     *  The resulting method has the single given parameter type.
+    /**
+     * 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.
+     * @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}
      */
     public static
     MethodType methodType(Class rtype, Class ptype0) {
         return makeImpl(rtype, new Class[]{ ptype0 }, true);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
-     *  The resulting method has the same parameter types as {@code ptypes},
-     *  and the specified return type.
+    /**
+     * 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 same parameter types as {@code ptypes},
+     * and the specified return type.
+     * @throws NullPointerException if {@code rtype} or {@code ptypes} is null
      */
     public static
     MethodType methodType(Class rtype, MethodType ptypes) {
@@ -237,17 +280,20 @@
     private static final MethodType[] objectOnlyTypes = new MethodType[20];
 
     /**
-     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
+     * Finds or creates a method type whose components are {@code Object} with an optional trailing {@code Object[]} array.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * All parameters and the return type will be {@code Object},
      * except the final varargs parameter if any, which will be {@code Object[]}.
      * @param objectArgCount number of parameters (excluding the varargs parameter if any)
      * @param varargs whether there will be a varargs parameter, of type {@code Object[]}
      * @return a totally generic method type, given only its count of parameters and varargs
+     * @throws IllegalArgumentException if {@code objectArgCount} is negative or greater than 255
      * @see #genericMethodType(int)
      */
     public static
     MethodType genericMethodType(int objectArgCount, boolean varargs) {
         MethodType mt;
+        checkSlotCount(objectArgCount);
         int ivarargs = (!varargs ? 0 : 1);
         int ootIndex = objectArgCount*2 + ivarargs;
         if (ootIndex < objectOnlyTypes.length) {
@@ -265,9 +311,12 @@
     }
 
     /**
+     * Finds or creates a method type whose components are all {@code Object}.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * All parameters and the return type will be Object.
      * @param objectArgCount number of parameters
      * @return a totally generic method type, given only its count of parameters
+     * @throws IllegalArgumentException if {@code objectArgCount} is negative or greater than 255
      * @see #genericMethodType(int, boolean)
      */
     public static
@@ -275,27 +324,41 @@
         return genericMethodType(objectArgCount, false);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
+    /**
+     * Finds or creates a method type with a single different parameter type.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * @param num    the index (zero-based) of the parameter type to change
      * @param nptype a new parameter type to replace the old one with
      * @return the same type, except with the selected parameter changed
+     * @throws IndexOutOfBoundsException if {@code num} is not a valid index into {@code parameterArray()}
+     * @throws IllegalArgumentException if {@code nptype} is {@code void.class}
+     * @throws NullPointerException if {@code nptype} is null
      */
     public MethodType changeParameterType(int num, Class nptype) {
         if (parameterType(num) == nptype)  return this;
+        checkPtype(nptype);
         Class[] nptypes = ptypes.clone();
         nptypes[num] = nptype;
         return makeImpl(rtype, nptypes, true);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
+    /**
+     * Finds or creates a method type with additional parameter types.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * @param num    the position (zero-based) of the inserted parameter type(s)
-     * @param ptypesToInsert zero or more a new parameter types to insert into the parameter list
+     * @param ptypesToInsert zero or more new parameter types to insert into the parameter list
      * @return the same type, except with the selected parameter(s) inserted
+     * @throws IndexOutOfBoundsException if {@code num} is negative or greater than {@code parameterCount()}
+     * @throws IllegalArgumentException if any element of {@code ptypesToInsert} is {@code void.class}
+     *                                  or if the resulting method type would have more than 255 parameter slots
+     * @throws NullPointerException if {@code ptypesToInsert} or any of its elements is null
      */
     public MethodType insertParameterTypes(int num, Class... ptypesToInsert) {
         int len = ptypes.length;
         if (num < 0 || num > len)
-            throw newIllegalArgumentException("num="+num); //SPECME
+            throw newIndexOutOfBoundsException(num);
+        int ins = checkPtypes(ptypesToInsert);
+        checkSlotCount(parameterSlotCount() + ptypesToInsert.length + ins);
         int ilen = ptypesToInsert.length;
         if (ilen == 0)  return this;
         Class[] nptypes = Arrays.copyOfRange(ptypes, 0, len+ilen);
@@ -304,40 +367,61 @@
         return makeImpl(rtype, nptypes, true);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
-     * @param ptypesToInsert zero or more a new parameter types to insert after the end of the parameter list
+    /**
+     * Finds or creates a method type with additional parameter types.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
+     * @param ptypesToInsert zero or more new parameter types to insert after the end of the parameter list
      * @return the same type, except with the selected parameter(s) appended
+     * @throws IllegalArgumentException if any element of {@code ptypesToInsert} is {@code void.class}
+     *                                  or if the resulting method type would have more than 255 parameter slots
+     * @throws NullPointerException if {@code ptypesToInsert} or any of its elements is null
      */
     public MethodType appendParameterTypes(Class... ptypesToInsert) {
         return insertParameterTypes(parameterCount(), ptypesToInsert);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
-     * @param ptypesToInsert zero or more a new parameter types to insert after the end of the parameter list
+    /**
+     * Finds or creates a method type with additional parameter types.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
+     * @param num    the position (zero-based) of the inserted parameter type(s)
+     * @param ptypesToInsert zero or more new parameter types to insert into the parameter list
+     * @return the same type, except with the selected parameter(s) inserted
+     * @throws IndexOutOfBoundsException if {@code num} is negative or greater than {@code parameterCount()}
+     * @throws IllegalArgumentException if any element of {@code ptypesToInsert} is {@code void.class}
+     *                                  or if the resulting method type would have more than 255 parameter slots
+     * @throws NullPointerException if {@code ptypesToInsert} or any of its elements is null
+     */
+    public MethodType insertParameterTypes(int num, List> ptypesToInsert) {
+        return insertParameterTypes(num, ptypesToInsert.toArray(NO_PTYPES));
+    }
+
+    /**
+     * Finds or creates a method type with additional parameter types.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
+     * @param ptypesToInsert zero or more new parameter types to insert after the end of the parameter list
      * @return the same type, except with the selected parameter(s) appended
+     * @throws IllegalArgumentException if any element of {@code ptypesToInsert} is {@code void.class}
+     *                                  or if the resulting method type would have more than 255 parameter slots
+     * @throws NullPointerException if {@code ptypesToInsert} or any of its elements is null
      */
     public MethodType appendParameterTypes(List> ptypesToInsert) {
         return insertParameterTypes(parameterCount(), ptypesToInsert);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
-     * @param num    the position (zero-based) of the inserted parameter type(s)
-     * @param ptypesToInsert zero or more a new parameter types to insert into the parameter list
-     * @return the same type, except with the selected parameter(s) inserted
-     */
-    public MethodType insertParameterTypes(int num, List> ptypesToInsert) {
-        return insertParameterTypes(num, ptypesToInsert.toArray(NO_PTYPES));
-    }
-
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
+    /**
+     * Finds or creates a method type with some parameter types omitted.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * @param start  the index (zero-based) of the first parameter type to remove
      * @param end    the index (greater than {@code start}) of the first parameter type after not to remove
      * @return the same type, except with the selected parameter(s) removed
+     * @throws IndexOutOfBoundsException if {@code start} is negative or greater than {@code parameterCount()}
+     *                                  or if {@code end} is negative or greater than {@code parameterCount()}
+     *                                  or if {@code start} is greater than {@code end}
      */
     public MethodType dropParameterTypes(int start, int end) {
         int len = ptypes.length;
         if (!(0 <= start && start <= end && end <= len))
-            throw newIllegalArgumentException("start="+start+" end="+end); //SPECME
+            throw newIndexOutOfBoundsException("start="+start+" end="+end);
         if (start == end)  return this;
         Class[] nptypes;
         if (start == 0) {
@@ -361,17 +445,20 @@
         return makeImpl(rtype, nptypes, true);
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
+    /**
+     * Finds or creates a method type with a different return type.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * @param nrtype a return parameter type to replace the old one with
      * @return the same type, except with the return type change
+     * @throws NullPointerException if {@code nrtype} is null
      */
     public MethodType changeReturnType(Class nrtype) {
         if (returnType() == nrtype)  return this;
         return makeImpl(nrtype, ptypes, true);
     }
 
-    /** Convenience method.
-     * Report if this type contains a primitive argument or return value.
+    /**
+     * Reports if this type contains a primitive argument or return value.
      * The return type {@code void} counts as a primitive.
      * @return true if any of the types are primitives
      */
@@ -379,8 +466,8 @@
         return form.hasPrimitives();
     }
 
-    /** Convenience method.
-     * Report if this type contains a wrapper argument or return value.
+    /**
+     * Reports if this type contains a wrapper argument or return value.
      * Wrappers are types which box primitive values, such as {@link Integer}.
      * The reference type {@code java.lang.Void} counts as a wrapper.
      * @return true if any of the types are wrappers
@@ -389,8 +476,9 @@
         return unwrap() != this;
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
-     * Erase all reference types to {@code Object}.
+    /**
+     * Erases all reference types to {@code Object}.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * All primitive types (including {@code void}) will remain unchanged.
      * @return a version of the original type with all reference types replaced
      */
@@ -398,8 +486,9 @@
         return form.erasedType();
     }
 
-    /** Convenience method for {@link #genericMethodType(int)}.
-     * Convert all types, both reference and primitive, to {@code Object}.
+    /**
+     * Converts all types, both reference and primitive, to {@code Object}.
+     * Convenience method for {@link #genericMethodType(int) genericMethodType}.
      * The expression {@code type.wrap().erase()} produces the same value
      * as {@code type.generic()}.
      * @return a version of the original type with all types replaced
@@ -408,8 +497,9 @@
         return genericMethodType(parameterCount());
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
-     * Convert all primitive types to their corresponding wrapper types.
+    /**
+     * Converts all primitive types to their corresponding wrapper types.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * All reference types (including wrapper types) will remain unchanged.
      * A {@code void} return type is changed to the type {@code java.lang.Void}.
      * The expression {@code type.wrap().erase()} produces the same value
@@ -420,8 +510,9 @@
         return hasPrimitives() ? wrapWithPrims(this) : this;
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
+    /**
      * Convert all wrapper types to their corresponding primitive types.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * All primitive types (including {@code void}) will remain unchanged.
      * A return type of {@code java.lang.Void} is changed to {@code void}.
      * @return a version of the original type with all wrapper types replaced
@@ -456,23 +547,33 @@
         return uwt;
     }
 
-    /** @param num the index (zero-based) of the desired parameter type
-     *  @return the selected parameter type
+    /**
+     * Returns the parameter type at the specified index, within this method type.
+     * @param num the index (zero-based) of the desired parameter type
+     * @return the selected parameter type
+     * @throws IndexOutOfBoundsException if {@code num} is not a valid index into {@code parameterArray()}
      */
     public Class parameterType(int num) {
         return ptypes[num];
     }
-    /** @return the number of parameter types */
+    /**
+     * Returns the number of parameter types in this method type.
+     * @return the number of parameter types
+     */
     public int parameterCount() {
         return ptypes.length;
     }
-    /** @return the return type */
+    /**
+     * Returns the return type of this method type.
+     * @return the return type
+     */
     public Class returnType() {
         return rtype;
     }
 
     /**
-     * Convenience method to present the arguments as a list.
+     * Presents the parameter types as a list (a convenience method).
+     * The list will be immutable.
      * @return the parameter types (as an immutable list)
      */
     public List> parameterList() {
@@ -480,7 +581,7 @@
     }
 
     /**
-     * Convenience method to present the arguments as an array.
+     * Presents the parameter types as an array (a convenience method).
      * Changes to the array will not result in changes to the type.
      * @return the parameter types (as a fresh copy if necessary)
      */
@@ -524,14 +625,14 @@
     }
 
     /**
+     * Returns a string representation of the method type,
+     * of the form {@code "(PT0,PT1...)RT"}.
      * The string representation of a method type is a
      * parenthesis enclosed, comma separated list of type names,
      * followed immediately by the return type.
      * 

      * Each type is represented by its
      * {@link java.lang.Class#getSimpleName simple name}.
-     * If a type name name is array, it the base type followed
-     * by [], rather than the Class.getName of the array type.
      */
     @Override
     public String toString() {
@@ -548,21 +649,22 @@
 
     /// Queries which have to do with the bytecode architecture
 
-    /** The number of JVM stack slots required to invoke a method
+    /** Reports the number of JVM stack slots required to invoke a method
      * of this type.  Note that (for historic reasons) the JVM requires
      * a second stack slot to pass long and double arguments.
-     * So this method returns {@link #parameterCount()} plus the
+     * So this method returns {@link #parameterCount() parameterCount} plus the
      * number of long and double parameters (if any).
      * 

      * This method is included for the benfit of applications that must
      * generate bytecodes that process method handles and invokedynamic.
      * @return the number of JVM stack slots for this type's parameters
+     * @deprecated Will be removed for PFD.
      */
     public int parameterSlotCount() {
         return form.parameterSlotCount();
     }
 
-    /** Number of JVM stack slots which carry all parameters including and after
+    /** Reports the number of JVM stack slots which carry all parameters including and after
      * the given position, which must be in the range of 0 to
      * {@code parameterCount} inclusive.  Successive parameters are
      * more shallowly stacked, and parameters are indexed in the bytecodes
@@ -583,6 +685,8 @@
      * @param num an index (zero-based, inclusive) within the parameter types
      * @return the index of the (shallowest) JVM stack slot transmitting the
      *         given parameter
+     * @throws IllegalArgumentException if {@code num} is negative or greater than {@code parameterCount()}
+     * @deprecated Will be removed for PFD.
      */
     public int parameterSlotDepth(int num) {
         if (num < 0 || num > ptypes.length)
@@ -590,7 +694,7 @@
         return form.parameterToArgSlot(num-1);
     }
 
-    /** The number of JVM stack slots required to receive a return value
+    /** Reports the number of JVM stack slots required to receive a return value
      * from a method of this type.
      * If the {@link #returnType() return type} is void, it will be zero,
      * else if the return type is long or double, it will be two, else one.
@@ -598,13 +702,15 @@
      * This method is included for the benfit of applications that must
      * generate bytecodes that process method handles and invokedynamic.
      * @return the number of JVM stack slots (0, 1, or 2) for this type's return value
+     * @deprecated Will be removed for PFD.
      */
     public int returnSlotCount() {
         return form.returnSlotCount();
     }
 
-    /** Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[])}.
-     * Find or create an instance of the given method type.
+    /**
+     * Find or create an instance of a method type, given the spelling of its bytecode descriptor.
+     * Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
      * Any class or interface name embedded in the descriptor string
      * will be resolved by calling {@link ClassLoader#loadClass(java.lang.String)}
      * on the given loader (or if it is null, on the system class loader).
@@ -614,10 +720,10 @@
      * not all reachable from a common class loader.
      * 

      * This method is included for the benfit of applications that must
-     * generate bytecodes that process method handles and invokedynamic.
-     * @param descriptor a bytecode-level signature string "(T...)T"
+     * generate bytecodes that process method handles and {@code invokedynamic}.
+     * @param descriptor a bytecode-level type descriptor string "(T...)T"
      * @param loader the class loader in which to look up the types
-     * @return a method type matching the bytecode-level signature
+     * @return a method type matching the bytecode-level type descriptor
      * @throws IllegalArgumentException if the string is not well-formed
      * @throws TypeNotPresentException if a named type cannot be found
      */
@@ -631,17 +737,17 @@
     }
 
     /**
-     * Create a bytecode descriptor representation of the method type.
+     * Produces a bytecode descriptor representation of the method type.
      * 

-     * Note that this is not a strict inverse of {@link #fromMethodDescriptorString}.
+     * Note that this is not a strict inverse of {@link #fromMethodDescriptorString fromMethodDescriptorString}.
      * Two distinct classes which share a common name but have different class loaders
      * will appear identical when viewed within descriptor strings.
      * 

      * This method is included for the benfit of applications that must
-     * generate bytecodes that process method handles and invokedynamic.
-     * {@link #fromMethodDescriptorString(java.lang.String, java.lang.ClassLoader)},
+     * generate bytecodes that process method handles and {@code invokedynamic}.
+     * {@link #fromMethodDescriptorString(java.lang.String, java.lang.ClassLoader) fromMethodDescriptorString},
      * because the latter requires a suitable class loader argument.
-     * @return the bytecode signature representation
+     * @return the bytecode type descriptor representation
      */
     public String toMethodDescriptorString() {
         return BytecodeDescriptor.unparse(this);
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/MutableCallSite.java
--- a/jdk/src/share/classes/java/dyn/MutableCallSite.java	Fri Feb 11 01:26:24 2011 -0800
+++ b/jdk/src/share/classes/java/dyn/MutableCallSite.java	Fri Feb 11 01:26:28 2011 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2011, 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
@@ -73,7 +73,7 @@
  * (This is a normal consequence of the Java Memory Model as applied
  * to object fields.)
  * 

- * The {@link #sync sync} operation provides a way to force threads
+ * The {@link #syncAll syncAll} operation provides a way to force threads
  * to accept a new target value, even if there is no other synchronization.
  * 

  * For target values which will be frequently updated, consider using
@@ -82,13 +82,17 @@
  */
 public class MutableCallSite extends CallSite {
     /**
-     * Make a blank call site object with the given method type.
-     * An initial target method is supplied which will throw
-     * an {@link IllegalStateException} if called.
+     * Creates a blank call site object with the given method type.
+     * The initial target is set to a method handle of the given type
+     * which will throw an {@link IllegalStateException} if called.
+     * 

+     * The type of the call site is permanently set to the given type.
      * 

      * Before this {@code CallSite} object is returned from a bootstrap method,
+     * or invoked in some other manner,
      * it is usually provided with a more useful target method,
      * via a call to {@link CallSite#setTarget(MethodHandle) setTarget}.
+     * @param type the method type that this call site will have
      * @throws NullPointerException if the proposed type is null
      */
     public MutableCallSite(MethodType type) {
@@ -96,8 +100,9 @@
     }
 
     /**
-     * Make a blank call site object, possibly equipped with an initial target method handle.
-     * @param target the method handle which will be the initial target of the call site
+     * Creates a call site object with an initial target method handle.
+     * The type of the call site is permanently set to the initial target's type.
+     * @param target the method handle that will be the initial target of the call site
      * @throws NullPointerException if the proposed target is null
      */
     public MutableCallSite(MethodHandle target) {
@@ -105,7 +110,59 @@
     }
 
     /**
-     * Perform a synchronization operation on each call site in the given array,
+     * Returns the target method of the call site, which behaves
+     * like a normal field of the {@code MutableCallSite}.
+     * 

+     * The interactions of {@code getTarget} with memory are the same
+     * as of a read from an ordinary variable, such as an array element or a
+     * non-volatile, non-final field.
+     * 

+     * In particular, the current thread may choose to reuse the result
+     * of a previous read of the target from memory, and may fail to see
+     * a recent update to the target by another thread.
+     *
+     * @return the linkage state of this call site, a method handle which can change over time
+     * @see #setTarget
+     */
+    @Override public final MethodHandle getTarget() {
+        return target;
+    }
+
+    /**
+     * Updates the target method of this call site, as a normal variable.
+     * The type of the new target must agree with the type of the old target.
+     * 

+     * The interactions with memory are the same
+     * as of a write to an ordinary variable, such as an array element or a
+     * non-volatile, non-final field.
+     * 

+     * In particular, unrelated threads may fail to see the updated target
+     * until they perform a read from memory.
+     * Stronger guarantees can be created by putting appropriate operations
+     * into the bootstrap method and/or the target methods used
+     * at any given call site.
+     *
+     * @param newTarget the new target
+     * @throws NullPointerException if the proposed new target is null
+     * @throws WrongMethodTypeException if the proposed new target
+     *         has a method type that differs from the previous target
+     * @see #getTarget
+     */
+    @Override public void setTarget(MethodHandle newTarget) {
+        checkTargetChange(this.target, newTarget);
+        setTargetNormal(newTarget);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public final MethodHandle dynamicInvoker() {
+        return makeDynamicInvoker();
+    }
+
+    /**
+     * Performs a synchronization operation on each call site in the given array,
      * forcing all other threads to throw away any cached values previously
      * loaded from the target of any of the call sites.
      * 

@@ -115,19 +172,29 @@
      * 

      * The overall effect is to force all future readers of each call site's target
      * to accept the most recently stored value.
-     * ("Most recently" is reckoned relative to the {@code sync} itself.)
-     * Conversely, the {@code sync} call may block until all readers have
+     * ("Most recently" is reckoned relative to the {@code syncAll} itself.)
+     * Conversely, the {@code syncAll} call may block until all readers have
      * (somehow) decached all previous versions of each call site's target.
      * 

-     * To avoid race conditions, calls to {@code setTarget} and {@code sync}
+     * To avoid race conditions, calls to {@code setTarget} and {@code syncAll}
      * should generally be performed under some sort of mutual exclusion.
      * Note that reader threads may observe an updated target as early
      * as the {@code setTarget} call that install the value
-     * (and before the {@code sync} that confirms the value).
+     * (and before the {@code syncAll} that confirms the value).
      * On the other hand, reader threads may observe previous versions of
-     * the target until the {@code sync} call returns
+     * the target until the {@code syncAll} call returns
      * (and after the {@code setTarget} that attempts to convey the updated version).
      * 

+     * This operation is likely to be expensive and should be used sparingly.
+     * If possible, it should be buffered for batch processing on sets of call sites.
+     * 

+     * If {@code sites} contains a null element,
+     * a {@code NullPointerException} will be raised.
+     * In this case, some non-null elements in the array may be
+     * processed before the method returns abnormally.
+     * Which elements these are (if any) is implementation-dependent.
+     *
+     * 
Java Memory Model details

      * 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
@@ -171,18 +238,17 @@
      * thereby ensuring communication of the new target value.
      * 

      * As long as the constraints of the Java Memory Model are obeyed,
-     * implementations may delay the completion of a {@code sync}
+     * implementations may delay the completion of a {@code syncAll}
      * operation while other threads ({@code T} above) continue to
      * use previous values of {@code S}'s target.
      * However, implementations are (as always) encouraged to avoid
      * livelock, and to eventually require all threads to take account
      * of the updated target.
-     * 

-     * This operation is likely to be expensive and should be used sparingly.
-     * If possible, it should be buffered for batch processing on sets of call sites.
+     *
      * 

-     * (This is a static method on a set of call sites, not a
-     * virtual method on a single call site, for performance reasons.
+     * Discussion:
+     * For performance reasons, {@code syncAll} is not a virtual method
+     * on a single call site, but rather applies to a set of call sites.
      * Some implementations may incur a large fixed overhead cost
      * for processing one or more synchronization operations,
      * but a small incremental cost for each additional call site.
@@ -191,15 +257,25 @@
      * in order to make them notice the updated target value.
      * However, it may be observed that a single call to synchronize
      * several sites has the same formal effect as many calls,
-     * each on just one of the sites.)
-     * 

+     * each on just one of the sites.
+     *
+     * 

+     * Implementation Note:
      * Simple implementations of {@code MutableCallSite} may use
      * a volatile variable for the target of a mutable call site.
-     * In such an implementation, the {@code sync} method can be a no-op,
+     * In such an implementation, the {@code syncAll} method can be a no-op,
      * and yet it will conform to the JMM behavior documented above.
+     *
+     * @param sites an array of call sites to be synchronized
+     * @throws NullPointerException if the {@code sites} array reference is null
+     *                              or the array contains a null
      */
-    public static void sync(MutableCallSite[] sites) {
+    public static void syncAll(MutableCallSite[] sites) {
+        if (sites.length == 0)  return;
         STORE_BARRIER.lazySet(0);
+        for (int i = 0; i < sites.length; i++) {
+            sites[i].getClass();  // trigger NPE on first null
+        }
         // FIXME: NYI
     }
     private static final AtomicInteger STORE_BARRIER = new AtomicInteger();
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/SwitchPoint.java
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/dyn/SwitchPoint.java	Fri Feb 11 01:26:28 2011 -0800
@@ -0,0 +1,195 @@
+/*
+ * Copyright (c) 2010, 2011, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package java.dyn;
+
+/**
+ * 

+ * A {@code SwitchPoint} is an object which can publish state transitions to other threads.
+ * A switch point is initially in the valid state, but may at any time be
+ * changed to the invalid state.  Invalidation cannot be reversed.
+ * A switch point can combine a guarded pair of method handles into a
+ * guarded delegator.
+ * The guarded delegator is a method handle which delegates to one of the old method handles.
+ * The state of the switch point determines which of the two gets the delegation.
+ * 

+ * A single switch point may be used to control any number of method handles.
+ * (Indirectly, therefore, it can control any number of call sites.)
+ * This is done by using the single switch point as a factory for combining
+ * any number of guarded method handle pairs into guarded delegators.
+ * 

+ * When a guarded delegator is created from a guarded pair, the pair
+ * is wrapped in a new method handle {@code M},
+ * which is permanently associated with the switch point that created it.
+ * Each pair consists of a target {@code T} and a fallback {@code F}.
+ * While the switch point is valid, invocations to {@code M} are delegated to {@code T}.
+ * After it is invalidated, invocations are delegated to {@code F}.
+ * 

+ * Invalidation is global and immediate, as if the switch point contained a
+ * volatile boolean variable consulted on every call to {@code M}.
+ * The invalidation is also permanent, which means the switch point
+ * can change state only once.
+ * The switch point will always delegate to {@code F} after being invalidated.
+ * At that point {@code guardWithTest} may ignore {@code T} and return {@code F}.
+ * 

+ * Here is an example of a switch point in action:
+ * 
+MethodType MT_str2 = MethodType.methodType(String.class, String.class);
+MethodHandle MH_strcat = MethodHandles.lookup()
+    .findVirtual(String.class, "concat", MT_str2);
+SwitchPoint spt = new SwitchPoint();
+// the following steps may be repeated to re-use the same switch point:
+MethodHandle worker1 = strcat;
+MethodHandle worker2 = MethodHandles.permuteArguments(strcat, MT_str2, 1, 0);
+MethodHandle worker = spt.guardWithTest(worker1, worker2);
+assertEquals("method", (String) worker.invokeExact("met", "hod"));
+SwitchPoint.invalidateAll(new SwitchPoint[]{ spt });
+assertEquals("hodmet", (String) worker.invokeExact("met", "hod"));
+ * 

+ * 

+ * Discussion:
+ * Switch points are useful without subclassing.  They may also be subclassed.
+ * This may be useful in order to associate application-specific invalidation logic
+ * with the switch point.
+ * 

+ * Implementation Note:
+ * A switch point behaves as if implemented on top of {@link MutableCallSite},
+ * approximately as follows:
+ * 
+public class SwitchPoint {
+  private static final MethodHandle
+    K_true  = MethodHandles.constant(boolean.class, true),
+    K_false = MethodHandles.constant(boolean.class, false);
+  private final MutableCallSite mcs;
+  private final MethodHandle mcsInvoker;
+  public SwitchPoint() {
+    this.mcs = new MutableCallSite(K_true);
+    this.mcsInvoker = mcs.dynamicInvoker();
+  }
+  public MethodHandle guardWithTest(
+                MethodHandle target, MethodHandle fallback) {
+    // Note:  mcsInvoker is of type ()boolean.
+    // Target and fallback may take any arguments, but must have the same type.
+    return MethodHandles.guardWithTest(this.mcsInvoker, target, fallback);
+  }
+  public static void invalidateAll(SwitchPoint[] spts) {
+    List<MutableCallSite> mcss = new ArrayList<>();
+    for (SwitchPoint spt : spts)  mcss.add(spt.mcs);
+    for (MutableCallSite mcs : mcss)  mcs.setTarget(K_false);
+    MutableCallSite.syncAll(mcss.toArray(new MutableCallSite[0]));
+  }
+}
+ * 

+ * @author Remi Forax, JSR 292 EG
+ */
+public class SwitchPoint {
+    private static final MethodHandle
+        K_true  = MethodHandles.constant(boolean.class, true),
+        K_false = MethodHandles.constant(boolean.class, false);
+
+    private final MutableCallSite mcs;
+    private final MethodHandle mcsInvoker;
+
+    /**
+     * Creates a new switch point.
+     */
+    public SwitchPoint() {
+        this.mcs = new MutableCallSite(K_true);
+        this.mcsInvoker = mcs.dynamicInvoker();
+    }
+
+    /**
+     * Returns a method handle which always delegates either to the target or the fallback.
+     * The method handle will delegate to the target exactly as long as the switch point is valid.
+     * After that, it will permanently delegate to the fallback.
+     * 

+     * The target and fallback must be of exactly the same method type,
+     * and the resulting combined method handle will also be of this type.
+     *
+     * @param target the method handle selected by the switch point as long as it is valid
+     * @param fallback the method handle selected by the switch point after it is invalidated
+     * @return a combined method handle which always calls either the target or fallback
+     * @throws NullPointerException if either argument is null
+     * @see MethodHandles#guardWithTest
+     */
+    public MethodHandle guardWithTest(MethodHandle target, MethodHandle fallback) {
+        if (mcs.getTarget() == K_false)
+            return fallback;  // already invalid
+        return MethodHandles.guardWithTest(mcsInvoker, target, fallback);
+    }
+
+    /**
+     * Sets all of the given switch points into the invalid state.
+     * After this call executes, no thread will observe any of the
+     * switch points to be in a valid state.
+     * 

+     * This operation is likely to be expensive and should be used sparingly.
+     * If possible, it should be buffered for batch processing on sets of switch points.
+     * 

+     * If {@code switchPoints} contains a null element,
+     * a {@code NullPointerException} will be raised.
+     * In this case, some non-null elements in the array may be
+     * processed before the method returns abnormally.
+     * Which elements these are (if any) is implementation-dependent.
+     *
+     * 

+     * Discussion:
+     * For performance reasons, {@code invalidateAll} is not a virtual method
+     * on a single switch point, but rather applies to a set of switch points.
+     * Some implementations may incur a large fixed overhead cost
+     * for processing one or more invalidation operations,
+     * but a small incremental cost for each additional invalidation.
+     * In any case, this operation is likely to be costly, since
+     * other threads may have to be somehow interrupted
+     * in order to make them notice the updated switch point state.
+     * However, it may be observed that a single call to invalidate
+     * several switch points has the same formal effect as many calls,
+     * each on just one of the switch points.
+     *
+     * 

+     * Implementation Note:
+     * Simple implementations of {@code SwitchPoint} may use
+     * a private {@link MutableCallSite} to publish the state of a switch point.
+     * In such an implementation, the {@code invalidateAll} method can
+     * simply change the call site's target, and issue one call to
+     * {@linkplain MutableCallSite#syncAll synchronize} all the
+     * private call sites.
+     *
+     * @param switchPoints an array of call sites to be synchronized
+     * @throws NullPointerException if the {@code switchPoints} array reference is null
+     *                              or the array contains a null
+     */
+    public static void invalidateAll(SwitchPoint[] switchPoints) {
+        if (switchPoints.length == 0)  return;
+        MutableCallSite[] sites = new MutableCallSite[switchPoints.length];
+        for (int i = 0; i < switchPoints.length; i++) {
+            SwitchPoint spt = switchPoints[i];
+            if (spt == null)  break;  // MSC.syncAll will trigger a NPE
+            sites[i] = spt.mcs;
+            spt.mcs.setTarget(K_false);
+        }
+        MutableCallSite.syncAll(sites);
+    }
+}
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/Switcher.java
--- a/jdk/src/share/classes/java/dyn/Switcher.java	Fri Feb 11 01:26:24 2011 -0800
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,130 +0,0 @@
-/*
- * Copyright (c) 2010, 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
- * under the terms of the GNU General Public License version 2 only, as
- * published by the Free Software Foundation.  Oracle designates this
- * particular file as subject to the "Classpath" exception as provided
- * by Oracle in the LICENSE file that accompanied this code.
- *
- * This code is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
- * version 2 for more details (a copy is included in the LICENSE file that
- * accompanied this code).
- *
- * You should have received a copy of the GNU General Public License version
- * 2 along with this work; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
- *
- * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
- * or visit www.oracle.com if you need additional information or have any
- * questions.
- */
-
-package java.dyn;
-
-/**
- * 

- * A {@code Switcher} is an object which can publish state transitions to other threads.
- * A switcher is initially in the valid state, but may at any time be
- * changed to the invalid state.  Invalidation cannot be reversed.
- * 

- * A single switcher may be used to create any number of guarded method handle pairs.
- * Each guarded pair is wrapped in a new method handle {@code M},
- * which is permanently associated with the switcher that created it.
- * Each pair consists of a target {@code T} and a fallback {@code F}.
- * While the switcher is valid, invocations to {@code M} are delegated to {@code T}.
- * After it is invalidated, invocations are delegated to {@code F}.
- * 

- * Invalidation is global and immediate, as if the switcher contained a
- * volatile boolean variable consulted on every call to {@code M}.
- * The invalidation is also permanent, which means the switcher
- * can change state only once.
- * 

- * Here is an example of a switcher in action:
- * 
-MethodType MT_str2 = MethodType.methodType(String.class, String.class);
-MethodHandle MH_strcat = MethodHandles.lookup()
-    .findVirtual(String.class, "concat", MT_str2);
-Switcher switcher = new Switcher();
-// the following steps may be repeated to re-use the same switcher:
-MethodHandle worker1 = strcat;
-MethodHandle worker2 = MethodHandles.permuteArguments(strcat, MT_str2, 1, 0);
-MethodHandle worker = switcher.guardWithTest(worker1, worker2);
-assertEquals("method", (String) worker.invokeExact("met", "hod"));
-switcher.invalidate();
-assertEquals("hodmet", (String) worker.invokeExact("met", "hod"));
- * 

- * 

- * Implementation Note:
- * A switcher behaves as if implemented on top of {@link MutableCallSite},
- * approximately as follows:
- * 
-public class Switcher {
-  private static final MethodHandle
-    K_true  = MethodHandles.constant(boolean.class, true),
-    K_false = MethodHandles.constant(boolean.class, false);
-  private final MutableCallSite mcs;
-  private final MethodHandle mcsInvoker;
-  public Switcher() {
-    this.mcs = new MutableCallSite(K_true);
-    this.mcsInvoker = mcs.dynamicInvoker();
-  }
-  public MethodHandle guardWithTest(
-                MethodHandle target, MethodHandle fallback) {
-    // Note:  mcsInvoker is of type boolean().
-    // Target and fallback may take any arguments, but must have the same type.
-    return MethodHandles.guardWithTest(this.mcsInvoker, target, fallback);
-  }
-  public static void invalidateAll(Switcher[] switchers) {
-    List mcss = new ArrayList<>();
-    for (Switcher s : switchers)  mcss.add(s.mcs);
-    for (MutableCallSite mcs : mcss)  mcs.setTarget(K_false);
-    MutableCallSite.sync(mcss.toArray(new MutableCallSite[0]));
-  }
-}
- * 

- * @author Remi Forax, JSR 292 EG
- */
-public class Switcher {
-    private static final MethodHandle
-        K_true  = MethodHandles.constant(boolean.class, true),
-        K_false = MethodHandles.constant(boolean.class, false);
-
-    private final MutableCallSite mcs;
-    private final MethodHandle mcsInvoker;
-
-    /** Create a switcher. */
-    public Switcher() {
-        this.mcs = new MutableCallSite(K_true);
-        this.mcsInvoker = mcs.dynamicInvoker();
-    }
-
-    /**
-     * Return a method handle which always delegates either to the target or the fallback.
-     * The method handle will delegate to the target exactly as long as the switcher is valid.
-     * After that, it will permanently delegate to the fallback.
-     * 

-     * The target and fallback must be of exactly the same method type,
-     * and the resulting combined method handle will also be of this type.
-     * @see MethodHandles#guardWithTest
-     */
-    public MethodHandle guardWithTest(MethodHandle target, MethodHandle fallback) {
-        if (mcs.getTarget() == K_false)
-            return fallback;  // already invalid
-        return MethodHandles.guardWithTest(mcsInvoker, target, fallback);
-    }
-
-    /** Set all of the given switchers into the invalid state. */
-    public static void invalidateAll(Switcher[] switchers) {
-        MutableCallSite[] sites = new MutableCallSite[switchers.length];
-        int fillp = 0;
-        for (Switcher switcher : switchers) {
-            sites[fillp++] = switcher.mcs;
-            switcher.mcs.setTarget(K_false);
-        }
-        MutableCallSite.sync(sites);
-    }
-}
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/VolatileCallSite.java
--- a/jdk/src/share/classes/java/dyn/VolatileCallSite.java	Fri Feb 11 01:26:24 2011 -0800
+++ b/jdk/src/share/classes/java/dyn/VolatileCallSite.java	Fri Feb 11 01:26:28 2011 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2011, 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
@@ -34,7 +34,7 @@
  * There may be a performance penalty for such tight coupling between threads.
  * 

  * Unlike {@code MutableCallSite}, there is no
- * {@linkplain MutableCallSite#sync sync operation} on volatile
+ * {@linkplain MutableCallSite#syncAll syncAll operation} on volatile
  * call sites, since every write to a volatile variable is implicitly
  * synchronized with reader threads.
  * 

@@ -44,36 +44,68 @@
  * @author John Rose, JSR 292 EG
  */
 public class VolatileCallSite extends CallSite {
-    /** Create a call site with a volatile target.
-     *  The initial target is set to a method handle
-     *  of the given type which will throw {@code IllegalStateException}.
+    /**
+     * Creates a call site with a volatile binding to its target.
+     * The initial target is set to a method handle
+     * of the given type which will throw an {@code IllegalStateException} if called.
+     * @param type the method type that this call site will have
      * @throws NullPointerException if the proposed type is null
      */
     public VolatileCallSite(MethodType type) {
         super(type);
     }
 
-    /** Create a call site with a volatile target.
-     *  The target is set to the given value.
+    /**
+     * Creates a call site with a volatile binding to its target.
+     * The target is set to the given value.
+     * @param target the method handle that will be the initial target of the call site
      * @throws NullPointerException if the proposed target is null
      */
     public VolatileCallSite(MethodHandle target) {
         super(target);
     }
 
-    /** Internal override to nominally final getTarget. */
-    @Override
-    MethodHandle getTarget0() {
+    /**
+     * Returns the target method of the call site, which behaves
+     * like a {@code volatile} field of the {@code VolatileCallSite}.
+     * 

+     * The interactions of {@code getTarget} with memory are the same
+     * as of a read from a {@code volatile} field.
+     * 

+     * In particular, the current thread is required to issue a fresh
+     * read of the target from memory, and must not fail to see
+     * a recent update to the target by another thread.
+     *
+     * @return the linkage state of this call site, a method handle which can change over time
+     * @see #setTarget
+     */
+    @Override public final MethodHandle getTarget() {
         return getTargetVolatile();
     }
 
     /**
-     * Set the target method of this call site, as a volatile variable.
-     * Has the same effect as {@link CallSite#setTarget CallSite.setTarget}, with the additional
-     * effects associated with volatiles, in the Java Memory Model.
+     * Updates the target method of this call site, as a volatile variable.
+     * The type of the new target must agree with the type of the old target.
+     * 

+     * The interactions with memory are the same as of a write to a volatile field.
+     * In particular, any threads is guaranteed to see the updated target
+     * the next time it calls {@code getTarget}.
+     * @param newTarget the new target
+     * @throws NullPointerException if the proposed new target is null
+     * @throws WrongMethodTypeException if the proposed new target
+     *         has a method type that differs from the previous target
+     * @see #getTarget
      */
     @Override public void setTarget(MethodHandle newTarget) {
         checkTargetChange(getTargetVolatile(), newTarget);
         setTargetVolatile(newTarget);
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public final MethodHandle dynamicInvoker() {
+        return makeDynamicInvoker();
+    }
 }
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/WrongMethodTypeException.java
--- a/jdk/src/share/classes/java/dyn/WrongMethodTypeException.java	Fri Feb 11 01:26:24 2011 -0800
+++ b/jdk/src/share/classes/java/dyn/WrongMethodTypeException.java	Fri Feb 11 01:26:28 2011 -0800
@@ -29,7 +29,7 @@
  * Thrown to indicate that code has attempted to call a method handle
  * via the wrong method type.  As with the bytecode representation of
  * normal Java method calls, method handle calls are strongly typed
- * to a specific signature associated with a call site.
+ * to a specific type descriptor associated with a call site.
  * 

  * This exception may also be thrown when two method handles are
  * composed, and the system detects that their types cannot be
diff -r 9e2483e6cfab -r 3b891698c4ec jdk/src/share/classes/java/dyn/package-info.java
--- a/jdk/src/share/classes/java/dyn/package-info.java	Fri Feb 11 01:26:24 2011 -0800
+++ b/jdk/src/share/classes/java/dyn/package-info.java	Fri Feb 11 01:26:28 2011 -0800
@@ -24,21 +24,20 @@
  */
 
 /**
- * This package contains dynamic language support provided directly by
+ * The {@code java.lang.invoke} package contains dynamic language support provided directly by
  * the Java core class libraries and virtual machine.
+ *
+ * 

+ * Historic Note: In some early versions of Java SE 7,
+ * the name of this package is {@code java.dyn}.
  * 

  * Certain types in this package have special relations to dynamic
  * language support in the virtual machine:
  *