changeset 1476:c3a5e415a09f

8139888: Improve Dynalink JavaDoc some more Reviewed-by: hannesw, sundar
author attila
date Tue, 20 Oct 2015 23:34:16 +0200
parents a8d5f14eebcc
children 490cafd88488
files src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/CallSiteDescriptor.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinker.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinkerFactory.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/BeansLinker.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/OverloadedMethod.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/StaticClass.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/package-info.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/package.html src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardedInvocationTransformer.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardingDynamicLinker.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardingTypeConverterFactory.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/LinkRequest.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/LinkerServices.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/MethodHandleTransformer.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/MethodTypeConversionStrategy.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/package-info.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/package.html src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/CompositeTypeBasedGuardingDynamicLinker.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/DefaultInternalObjectFilter.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/Guards.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/Lookup.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/SimpleLinkRequest.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/package-info.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/package-info.java src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/support/NameCodec.java
diffstat 25 files changed, 1075 insertions(+), 460 deletions(-) [+]
line wrap: on
line diff
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/CallSiteDescriptor.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/CallSiteDescriptor.java	Tue Oct 20 23:34:16 2015 +0200
@@ -83,7 +83,6 @@
 
 package jdk.internal.dynalink;
 
-import java.lang.invoke.CallSite;
 import java.lang.invoke.MethodHandles;
 import java.lang.invoke.MethodHandles.Lookup;
 import java.lang.invoke.MethodType;
@@ -94,13 +93,18 @@
 import jdk.internal.dynalink.support.NameCodec;
 
 /**
- * Interface for objects describing a call site. A call site descriptor contains
- * all the information about a call site necessary for linking it: the class
- * performing the lookups, the name of the method being invoked, and the method
- * signature. Call site descriptors are used in Dynalink in place of passing
- * {@link CallSite} objects to linkers so they can't directly manipulate them.
+ * Interface for objects containing the information necessary for linking a call
+ * site. This information is normally passed as parameters to bootstrap methods
+ * and consists of the {@code MethodHandles.Lookup} object on the caller class
+ * in which the call site occurs, the method name mentioned in the call site,
+ * and the method type of the call site. {@code CallSiteDescriptor} objects are
+ * used in Dynalink to capture and store these parameters for subsequent use by
+ * the {@link DynamicLinker}.
+ * <p>
  * The constructors of built-in {@link RelinkableCallSite} implementations all
- * take a call site descriptor. Call site descriptors must be immutable.
+ * take a call site descriptor.
+ * <p>
+ * Call site descriptors must be immutable.
  */
 public interface CallSiteDescriptor {
     /**
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinker.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinker.java	Tue Oct 20 23:34:16 2015 +0200
@@ -100,11 +100,17 @@
 import jdk.internal.dynalink.support.SimpleRelinkableCallSite;
 
 /**
- * The linker for {@link RelinkableCallSite} objects. Users of Dynalink have to
- * create a linker using the {@link DynamicLinkerFactory} and invoke its
- * {@link #link(RelinkableCallSite)} method from the invokedynamic bootstrap
- * methods to let it manage all the call sites they create. Usual usage would be
- * to create one class per language runtime to contain one linker instance as:
+ * The linker for {@link RelinkableCallSite} objects. A dynamic linker is a main
+ * objects when using Dynalink, it coordinates linking of call sites with
+ * linkers of available language runtimes that are represented by
+ * {@link GuardingDynamicLinker} objects (you only need to deal with these if
+ * you are yourself implementing a language runtime with its own object model
+ * and/or type conversions). To use Dynalink, you have to create one or more
+ * dynamic linkers using a {@link DynamicLinkerFactory}. Subsequently, you need
+ * to invoke its {@link #link(RelinkableCallSite)} method from
+ * {@code invokedynamic} bootstrap methods to let it manage all the call sites
+ * they create. Usual usage would be to create at least one class per language
+ * runtime to contain one linker instance as:
  * <pre>
  *
  * class MyLanguageRuntime {
@@ -122,29 +128,37 @@
  *     }
  * }
  * </pre>
- *
- * Note how there are three components you will need to provide here:
+ * The above setup of one static linker instance is often too simple. You will
+ * often have your language runtime have a concept of some kind of
+ * "context class loader" and you will want to create one dynamic linker per
+ * such class loader, to ensure it incorporates linkers for all other language
+ * runtimes visible to that class loader (see
+ * {@link DynamicLinkerFactory#setClassLoader(ClassLoader)}).
+ * <p>
+ * There are three components you need to provide in the above example:
  * <ul>
  *
- * <li>You're expected to provide a {@link GuardingDynamicLinker} for your own
- * language. If your runtime doesn't have its own language and/or object model
- * (i.e., it's a generic scripting shell), you don't need to implement a dynamic
- * linker; you would simply not invoke the {@code setPrioritizedLinker} method
- * on the factory.</li>
+ * <li>You are expected to provide a {@link GuardingDynamicLinker} for your own
+ * language. If your runtime doesn't have its own object model or type
+ * conversions, you don't need to implement a {@code GuardingDynamicLinker}; you
+ * would simply not invoke the {@code setPrioritizedLinker} method on the factory.</li>
  *
  * <li>The performance of the programs can depend on your choice of the class to
- * represent call sites. The above example used {@link SimpleRelinkableCallSite}, but
- * you might want to use {@link ChainedCallSite} instead. You'll need to
- * experiment and decide what fits your language runtime the best. You can
- * subclass either of these or roll your own if you need to.</li>
+ * represent call sites. The above example used
+ * {@link SimpleRelinkableCallSite}, but you might want to use
+ * {@link ChainedCallSite} instead. You'll need to experiment and decide what
+ * fits your runtime the best. You can further subclass either of these or
+ * implement your own.</li>
  *
  * <li>You also need to provide {@link CallSiteDescriptor}s to your call sites.
  * They are immutable objects that contain all the information about the call
  * site: the class performing the lookups, the name of the method being invoked,
- * and the method signature. The library provides a {@link SimpleCallSiteDescriptor},
- * or you can create your own descriptor classes, especially if you need to add
- * further information (values passed in additional parameters to the bootstrap method)
- * to them.</li>
+ * and the method signature. The library provides a
+ * {@link SimpleCallSiteDescriptor}, or you can create your own descriptor
+ * classes, especially if you need to add further information to them
+ * (typically, values passed in additional parameters to the bootstrap method).
+ * Since they are specified to be immutable, you can set up a cache for
+ * equivalent descriptors to have the call sites share them.</li>
  *
  * </ul>
  */
@@ -199,11 +213,12 @@
 
     /**
      * Returns the object representing the linker services of this class that
-     * are normally exposed to individual language-specific linkers.
-     * While as a user of this class you normally only care about the
-     * {@link #link(RelinkableCallSite)} method, in certain circumstances you
-     * might want to use the lower level services directly; either to lookup
-     * specific method handles, to access the type converters, and so on.
+     * are normally exposed to individual {@link GuardingDynamicLinker
+     * language-specific linkers}. While as a user of this class you normally
+     * only care about the {@link #link(RelinkableCallSite)} method, in certain
+     * circumstances you might want to use the lower level services directly;
+     * either to lookup specific method handles, to access the type converters,
+     * and so on.
      *
      * @return the object representing the linker services of this class.
      */
@@ -273,8 +288,9 @@
     /**
      * Returns a stack trace element describing the location of the
      * {@code invokedynamic} call site currently being linked on the current
-     * thread. The operation is potentially expensive and is intended for use in
-     * diagnostics code. For "free-floating" call sites (not associated with an
+     * thread. The operation is potentially expensive as it needs to generate a
+     * stack trace to inspect it and is intended for use in diagnostics code.
+     * For "free-floating" call sites (not associated with an
      * {@code invokedynamic} instruction), the result is not well-defined.
      *
      * @return a stack trace element describing the location of the call site
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinkerFactory.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinkerFactory.java	Tue Oct 20 23:34:16 2015 +0200
@@ -94,6 +94,7 @@
 import java.util.HashSet;
 import java.util.LinkedList;
 import java.util.List;
+import java.util.Objects;
 import java.util.ServiceLoader;
 import java.util.Set;
 import jdk.internal.dynalink.beans.BeansLinker;
@@ -107,17 +108,20 @@
 import jdk.internal.dynalink.linker.MethodTypeConversionStrategy;
 import jdk.internal.dynalink.linker.support.CompositeGuardingDynamicLinker;
 import jdk.internal.dynalink.linker.support.CompositeTypeBasedGuardingDynamicLinker;
+import jdk.internal.dynalink.linker.support.DefaultInternalObjectFilter;
 import jdk.internal.dynalink.linker.support.TypeUtilities;
 
 /**
- * A factory class for creating {@link DynamicLinker} objects. The usual dynamic
- * linker is a linker composed of all {@link GuardingDynamicLinker} objects
- * known and pre-created by the caller as well as any guarding linkers
- * automatically discovered as declared in
- * {@code /META-INF/services/jdk.internal.dynalink.linker.GuardingDynamicLinker}
- * resources in the classpath (see {@link ServiceLoader} for the description of
- * this mechanism), and the standard fallback {@link BeansLinker}.
- * See {@link DynamicLinker} documentation for tips on how to use this class.
+ * A factory class for creating {@link DynamicLinker} objects. Dynamic linkers
+ * are the central objects in Dynalink; these are composed of several
+ * {@link GuardingDynamicLinker} objects and coordinate linking of call sites
+ * with them. The usual dynamic linker is a linker
+ * composed of all {@link GuardingDynamicLinker} objects explicitly pre-created
+ * by the user of the factory and configured with
+ * {@link #setPrioritizedLinkers(List)}, as well as any
+ * {@link #setClassLoader(ClassLoader) automatically discovered} ones, and
+ * finally the ones configured with {@link #setFallbackLinkers(List)}; this last
+ * category usually includes {@link BeansLinker}.
  */
 public final class DynamicLinkerFactory {
     /**
@@ -147,9 +151,18 @@
     }
 
     /**
-     * Sets the class loader for automatic discovery of available linkers. If
-     * not set explicitly, then the thread context class loader of the thread
-     * invoking {@link #createLinker()} invocation will be used.
+     * Sets the class loader for automatic discovery of available guarding
+     * dynamic linkers. Guarding dynamic linker classes declared in
+     * {@code /META-INF/services/jdk.internal.dynalink.linker.GuardingDynamicLinker}
+     * resources available through this class loader will be automatically
+     * instantiated using the {@link ServiceLoader} mechanism and incorporated
+     * into {@code DynamicLinker}s that this factory creates. This allows for
+     * cross-language interoperability where call sites belonging to this language
+     * runtime can be linked by linkers from these autodiscovered runtimes if
+     * their native objects are passed to this runtime. If class loader is not
+     * set explicitly, then the thread context class loader of the thread
+     * invoking {@link #createLinker()} will be used. Can be invoked with null
+     * to signify system class loader.
      *
      * @param classLoader the class loader used for the automatic discovery of
      * available linkers.
@@ -160,73 +173,84 @@
     }
 
     /**
-     * Sets the prioritized linkers. Language runtimes using this framework will usually precreate at least the linker
-     * for their own language. These linkers will be consulted first in the resulting dynamic linker, before any
-     * autodiscovered linkers. If the framework also autodiscovers a linker of the same class as one of the prioritized
-     * linkers, it will be ignored and the explicit prioritized instance will be used.
+     * Sets the prioritized guarding dynamic linkers. Language runtimes using
+     * Dynalink will usually have at least one linker for their own language.
+     * These linkers will be consulted first by the resulting dynamic linker
+     * when it is linking call sites, before any autodiscovered and fallback
+     * linkers. If the factory also autodiscovers a linker class matching one
+     * of the prioritized linkers, the autodiscovered class will be ignored and
+     * the explicit prioritized instance will be used.
      *
-     * @param prioritizedLinkers the list of prioritized linkers. Null can be passed to indicate no prioritized linkers
-     * (this is also the default value).
+     * @param prioritizedLinkers the list of prioritized linkers. Can be null.
+     * @throws NullPointerException if any of the list elements are null.
      */
     public void setPrioritizedLinkers(final List<? extends GuardingDynamicLinker> prioritizedLinkers) {
-        this.prioritizedLinkers =
-                prioritizedLinkers == null ? null : new ArrayList<>(prioritizedLinkers);
+        this.prioritizedLinkers = reqireNonNullElements(prioritizedLinkers);
     }
 
     /**
-     * Sets the prioritized linkers. Language runtimes using this framework will usually precreate at least the linker
-     * for their own language. These linkers will be consulted first in the resulting dynamic linker, before any
-     * autodiscovered linkers. If the framework also autodiscovers a linker of the same class as one of the prioritized
-     * linkers, it will be ignored and the explicit prioritized instance will be used.
+     * Sets the prioritized guarding dynamic linkers. Identical to calling
+     * {@link #setPrioritizedLinkers(List)} with
+     * {@code Arrays.asList(prioritizedLinkers)}.
      *
-     * @param prioritizedLinkers a list of prioritized linkers.
+     * @param prioritizedLinkers an array of prioritized linkers. Can be null.
+     * @throws NullPointerException if any of the array elements are null.
      */
     public void setPrioritizedLinkers(final GuardingDynamicLinker... prioritizedLinkers) {
-        setPrioritizedLinkers(Arrays.asList(prioritizedLinkers));
+        setPrioritizedLinkers(prioritizedLinkers == null ? null : Arrays.asList(prioritizedLinkers));
     }
 
     /**
-     * Sets a single prioritized linker. Identical to calling {@link #setPrioritizedLinkers(List)} with a single-element
-     * list.
+     * Sets a single prioritized linker. Identical to calling
+     * {@link #setPrioritizedLinkers(List)} with a single-element list.
      *
      * @param prioritizedLinker the single prioritized linker. Must not be null.
-     * @throws IllegalArgumentException if null is passed.
+     * @throws NullPointerException if null is passed.
      */
     public void setPrioritizedLinker(final GuardingDynamicLinker prioritizedLinker) {
-        if(prioritizedLinker == null) {
-            throw new IllegalArgumentException("prioritizedLinker == null");
-        }
-        this.prioritizedLinkers = Collections.singletonList(prioritizedLinker);
+        this.prioritizedLinkers = Collections.singletonList(Objects.requireNonNull(prioritizedLinker));
     }
 
     /**
-     * Sets the fallback linkers. These linkers will be consulted last in the resulting composite linker, after any
-     * autodiscovered linkers. If the framework also autodiscovers a linker of the same class as one of the fallback
-     * linkers, it will be ignored and the explicit fallback instance will be used.
+     * Sets the fallback guarding dynamic linkers. These linkers will be
+     * consulted last by the resulting dynamic linker when it is linking call
+     * sites, after any autodiscovered and prioritized linkers. If the factory
+     * also autodiscovers a linker class matching one of the fallback linkers,
+     * the autodiscovered class will be ignored and the explicit fallback
+     * instance will be used.
      *
-     * @param fallbackLinkers the list of fallback linkers. Can be empty to indicate the caller wishes to set no
-     * fallback linkers.
+     * @param fallbackLinkers the list of fallback linkers. Can be empty to
+     * indicate the caller wishes to set no fallback linkers. Note that if this
+     * method is not invoked explicitly or is passed null, then the factory
+     * will create an instance of {@link BeansLinker} to serve as the default
+     * fallback linker.
+     * @throws NullPointerException if any of the list elements are null.
      */
     public void setFallbackLinkers(final List<? extends GuardingDynamicLinker> fallbackLinkers) {
-        this.fallbackLinkers = fallbackLinkers == null ? null : new ArrayList<>(fallbackLinkers);
+        this.fallbackLinkers = reqireNonNullElements(fallbackLinkers);
     }
 
     /**
-     * Sets the fallback linkers. These linkers will be consulted last in the resulting composite linker, after any
-     * autodiscovered linkers. If the framework also autodiscovers a linker of the same class as one of the fallback
-     * linkers, it will be ignored and the explicit fallback instance will be used.
+     * Sets the fallback guarding dynamic linkers. Identical to calling
+     * {@link #setFallbackLinkers(List)} with
+     * {@code Arrays.asList(fallbackLinkers)}.
      *
-     * @param fallbackLinkers the list of fallback linkers. Can be empty to indicate the caller wishes to set no
-     * fallback linkers. If it is left as null, the standard fallback {@link BeansLinker} will be used.
+     * @param fallbackLinkers an array of fallback linkers. Can be empty to
+     * indicate the caller wishes to set no fallback linkers. Note that if this
+     * method is not invoked explicitly or is passed null, then the factory
+     * will create an instance of {@link BeansLinker} to serve as the default
+     * fallback linker.
+     * @throws NullPointerException if any of the array elements are null.
      */
     public void setFallbackLinkers(final GuardingDynamicLinker... fallbackLinkers) {
-        setFallbackLinkers(Arrays.asList(fallbackLinkers));
+        setFallbackLinkers(fallbackLinkers == null ? null : Arrays.asList(fallbackLinkers));
     }
 
     /**
-     * Sets whether the linker created by this factory will invoke {@link MutableCallSite#syncAll(MutableCallSite[])}
-     * after a call site is relinked. Defaults to false. You probably want to set it to true if your runtime supports
-     * multithreaded execution of dynamically linked code.
+     * Sets whether the dynamic linker created by this factory will invoke
+     * {@link MutableCallSite#syncAll(MutableCallSite[])} after a call site is
+     * relinked. Defaults to false. You probably want to set it to true if your
+     * runtime supports multithreaded execution of dynamically linked code.
      * @param syncOnRelink true for invoking sync on relink, false otherwise.
      */
     public void setSyncOnRelink(final boolean syncOnRelink) {
@@ -234,10 +258,12 @@
     }
 
     /**
-     * Sets the unstable relink threshold; the number of times a call site is relinked after which it will be
-     * considered unstable, and subsequent link requests for it will indicate this.
-     * @param unstableRelinkThreshold the new threshold. Must not be less than zero. The value of zero means that
-     * call sites will never be considered unstable.
+     * Sets the unstable relink threshold; the number of times a call site is
+     * relinked after which it will be considered unstable, and subsequent link
+     * requests for it will indicate this.
+     * @param unstableRelinkThreshold the new threshold. Must not be less than
+     * zero. The value of zero means that call sites will never be considered
+     * unstable.
      * @see LinkRequest#isCallSiteUnstable()
      */
     public void setUnstableRelinkThreshold(final int unstableRelinkThreshold) {
@@ -248,53 +274,80 @@
     }
 
     /**
-     * Set the pre-link transformer. This is a {@link GuardedInvocationTransformer} that will get the final chance to modify the
-     * guarded invocation after it has been created by a component linker and before the dynamic linker links it into
-     * the call site. It is normally used to adapt the return value type of the invocation to the type of the call site.
-     * When not set explicitly, a default pre-link transformer will be used that simply calls
-     * {@link GuardedInvocation#asType(LinkerServices, MethodType)}
-     * @param prelinkTransformer the pre-link transformer for the dynamic linker.
+     * Set the pre-link transformer. This is a
+     * {@link GuardedInvocationTransformer} that will get the final chance to
+     * modify the guarded invocation after it has been created by a component
+     * linker and before the dynamic linker links it into the call site. It is
+     * normally used to adapt the return value type of the invocation to the
+     * type of the call site. When not set explicitly, a default pre-link
+     * transformer will be used that simply calls
+     * {@link GuardedInvocation#asType(LinkerServices, MethodType)}. Customized
+     * pre-link transformers are rarely needed; they are mostly used as a
+     * building block for implementing advanced techniques such as code
+     * deoptimization strategies.
+     * @param prelinkTransformer the pre-link transformer for the dynamic
+     * linker. Can be null to have the factory use the default transformer.
      */
     public void setPrelinkTransformer(final GuardedInvocationTransformer prelinkTransformer) {
         this.prelinkTransformer = prelinkTransformer;
     }
 
     /**
-     * Sets an object representing the conversion strategy for automatic type conversions. After
-     * {@link TypeConverterFactory#asType(MethodHandle, MethodType)} has
-     * applied all custom conversions to a method handle, it still needs to effect
-     * {@link TypeUtilities#isMethodInvocationConvertible(Class, Class) method invocation conversions} that
-     * can usually be automatically applied as per
-     * {@link java.lang.invoke.MethodHandle#asType(MethodType)}.
-     * However, sometimes language runtimes will want to customize even those conversions for their own call
-     * sites. A typical example is allowing unboxing of null return values, which is by default prohibited by
-     * ordinary {@code MethodHandles.asType}. In this case, a language runtime can install its own custom
-     * automatic conversion strategy, that can deal with null values. Note that when the strategy's
+     * Sets an object representing the conversion strategy for automatic type
+     * conversions. After
+     * {@link LinkerServices#asType(MethodHandle, MethodType)} has applied all
+     * custom conversions to a method handle, it still needs to effect
+     * {@link TypeUtilities#isMethodInvocationConvertible(Class, Class) method
+     * invocation conversions} that can usually be automatically applied as per
+     * {@link MethodHandle#asType(MethodType)}. However, sometimes language
+     * runtimes will want to customize even those conversions for their own call
+     * sites. A typical example is allowing unboxing of null return values,
+     * which is by default prohibited by ordinary
+     * {@code MethodHandles.asType()}. In this case, a language runtime can
+     * install its own custom automatic conversion strategy, that can deal with
+     * null values. Note that when the strategy's
      * {@link MethodTypeConversionStrategy#asType(MethodHandle, MethodType)}
-     * is invoked, the custom language conversions will already have been applied to the method handle, so by
-     * design the difference between the handle's current method type and the desired final type will always
-     * only be ones that can be subjected to method invocation conversions. The strategy also doesn't need to
-     * invoke a final {@code MethodHandle.asType()} as the converter factory will do that as the final step.
-     * @param autoConversionStrategy the strategy for applying method invocation conversions for the linker
-     * created by this factory.
+     * is invoked, the custom language conversions will already have been
+     * applied to the method handle, so by design the difference between the
+     * handle's current method type and the desired final type will always only
+     * be ones that can be subjected to method invocation conversions. The
+     * strategy also doesn't need to invoke a final
+     * {@code MethodHandle.asType()} as that will be done internally as the
+     * final step.
+     * @param autoConversionStrategy the strategy for applying method invocation
+     * conversions for the linker created by this factory. Can be null for no
+     * custom strategy.
      */
     public void setAutoConversionStrategy(final MethodTypeConversionStrategy autoConversionStrategy) {
         this.autoConversionStrategy = autoConversionStrategy;
     }
 
     /**
-     * Sets a method handle transformer that is supposed to act as the implementation of this linker factory's linkers'
-     * services {@link LinkerServices#filterInternalObjects(java.lang.invoke.MethodHandle)} method.
-     * @param internalObjectsFilter a method handle transformer filtering out internal objects, or null.
+     * Sets a method handle transformer that is supposed to act as the
+     * implementation of
+     * {@link LinkerServices#filterInternalObjects(MethodHandle)} for linker
+     * services of dynamic linkers created by this factory. Some language
+     * runtimes can have internal objects that should not escape their scope.
+     * They can add a transformer here that will modify the method handle so
+     * that any parameters that can receive potentially internal language
+     * runtime objects will have a filter added on them to prevent them from
+     * escaping, potentially by wrapping them. The transformer can also
+     * potentially add an unwrapping filter to the return value.
+     * {@link DefaultInternalObjectFilter} is provided as a convenience class
+     * for easily creating such filtering transformers.
+     * @param internalObjectsFilter a method handle transformer filtering out
+     * internal objects, or null.
      */
     public void setInternalObjectsFilter(final MethodHandleTransformer internalObjectsFilter) {
         this.internalObjectsFilter = internalObjectsFilter;
     }
 
     /**
-     * Creates a new dynamic linker consisting of all the prioritized, autodiscovered, and fallback linkers as well as
-     * the pre-link transformer.
-     *
+     * Creates a new dynamic linker based on the current configuration. This
+     * method can be invoked more than once to create multiple dynamic linkers.
+     * Autodiscovered linkers are newly instantiated on every invocation of this
+     * method. It is allowed to change the factory's configuration between
+     * invocations. The method is not thread safe.
      * @return the new dynamic Linker
      */
     public DynamicLinker createLinker() {
@@ -382,4 +435,15 @@
             knownLinkerClasses.add(linker.getClass());
         }
     }
+
+    private static <T> List<T> reqireNonNullElements(final List<T> list) {
+        if (list == null) {
+            return null;
+        }
+        for(final T t: list) {
+            Objects.requireNonNull(t);
+        }
+        return new ArrayList<>(list);
+    }
+
 }
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/BeansLinker.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/BeansLinker.java	Tue Oct 20 23:34:16 2015 +0200
@@ -210,10 +210,17 @@
      * selecting an overloaded constructor based on an explicit signature, as
      * this functionality is not otherwise exposed by Dynalink as
      * {@link StaticClass} objects act as overloaded constructors without
-     * explicit signature selection.
+     * explicit signature selection. Example usage would be:
+     * {@code getConstructorMethod(java.awt.Color.class, "int, int, int")}.
      * @param clazz the class
-     * @param signature full signature of the constructor
-     * @return dynamic method for the constructor
+     * @param signature full signature of the constructor. Note how you can use
+     * names of primitive types, array names with normal Java notation (e.g.
+     * {@code "int[]"}), and normally you can even use unqualified class names
+     * (e.g. {@code "String, List"} instead of
+     * {@code "java.lang.String, java.util.List"} as long as they don't cause
+     * ambiguity in the specific parameter position.
+     * @return dynamic method for the constructor or null if no constructor with
+     * the specified signature exists.
      */
     public static Object getConstructorMethod(final Class<?> clazz, final String signature) {
         return StaticClassLinker.getConstructorMethod(clazz, signature);
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/OverloadedMethod.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/OverloadedMethod.java	Tue Oct 20 23:34:16 2015 +0200
@@ -182,8 +182,8 @@
                     break;
                 }
             }
-            // Avoid keeping references to unrelated classes; this ruins the performance a bit, but avoids class loader
-            // memory leaks.
+            // Avoid keeping references to unrelated classes; this ruins the
+            // performance a bit, but avoids class loader memory leaks.
             if(classString.isVisibleFrom(callSiteClassLoader)) {
                 argTypesToMethods.put(classString, method);
             }
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/StaticClass.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/StaticClass.java	Tue Oct 20 23:34:16 2015 +0200
@@ -87,24 +87,45 @@
 import java.util.Objects;
 
 /**
- * Object that represents the static aspect of a class (its static methods,
- * properties, and fields, as well as construction of instances using
- * {@code "dyn:new"} operation). Objects of this class are recognized by the
- * {@link BeansLinker} as being special, and operations on them will be linked
- * against the represented class' static aspect. The {@code "class"} synthetic
- * property is additionally recognized and returns the Java {@link Class}
- * object, as per {@link #getRepresentedClass()} method. Conversely,
- * {@link Class} objects exposed through {@link BeansLinker} expose the
- * {@code "static"} synthetic property which returns an instance of this class.
- * Instances of this class act as namespaces for static members and as
- * constructors for classes, much the same way as specifying a class name in
- * Java does, except that in Dynalink they are expressed as actual objects
- * exposing static methods and properties of classes. As a special case,
- * {@code StaticClass} objects representing Java array types will act as
+ * Object that allows access to the static members of a class (its static
+ * methods, properties, and fields), as well as construction of instances using
+ * {@code "dyn:new"} operation. In Dynalink, {@link Class} objects are not
+ * treated specially and act as ordinary Java objects; you can use e.g. {@code
+ * "dyn:getProp:superclass"} as a property getter to invoke
+ * {@code clazz.getSuperclass()}. On the other hand, you can not use
+ * {@code Class} objects to access static members of a class, nor to create new
+ * instances of the class using {@code "dyn:new"}. This is consistent with how
+ * {@code Class} objects behave in Java: in Java, you write e.g.
+ * {@code new BitSet()} instead of {@code new BitSet.class()}. Similarly, you
+ * write {@code System.out} and not {@code System.class.out}. It is this aspect
+ * of using a class name as the constructor and a namespace for static members
+ * that {@code StaticClass} embodies.
+ * <p>
+ * Objects of this class are recognized by the {@link BeansLinker} as being
+ * special, and operations on them will be linked against the represented class'
+ * static members. The {@code "class"} synthetic property is additionally
+ * recognized and returns the Java {@link Class} object, just as in Java
+ * {@code System.class} evaluates to the {@code Class} object for the
+ * {@code} System class. Conversely, {@link Class} objects exposed through
+ * {@link BeansLinker} expose the {@code "static"} synthetic property which
+ * returns their {@code StaticClass} object (there is no equivalent to this in
+ * Java).
+ * <p>
+ * In summary, instances of this class act as namespaces for static members and
+ * as constructors for classes, much the same way as specifying a class name in
+ * Java language does, except that in Java this is just a syntactic element,
+ * while in Dynalink they are expressed as actual objects.
+ * <p>{@code StaticClass} objects representing Java array types will act as
  * constructors taking a single int argument and create an array of the
  * specified size.
+ * <p>
+ * If the class has several constructors, {@code dyn:new} on {@code StaticClass}
+ * will try to select the most specific applicable constructor. You might want
+ * to expose a mechanism in your language for selecting a constructor with an
+ * explicit signature through
+ * {@link BeansLinker#getConstructorMethod(Class, String)}.
  */
-public class StaticClass implements Serializable {
+public final class StaticClass implements Serializable {
     private static final ClassValue<StaticClass> staticClasses = new ClassValue<StaticClass>() {
         @Override
         protected StaticClass computeValue(final Class<?> type) {
@@ -139,7 +160,7 @@
 
     @Override
     public String toString() {
-        return "JavaClassStatics[" + clazz.getName() + "]";
+        return "StaticClass[" + clazz.getName() + "]";
     }
 
     private Object readResolve() {
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/package-info.java	Tue Oct 20 23:34:16 2015 +0200
@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2015, 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.
+ */
+
+/*
+ * This file is available under and governed by the GNU General Public
+ * License version 2 only, as published by the Free Software Foundation.
+ * However, the following notice accompanied the original version of this
+ * file, and Oracle licenses the original version of this file under the BSD
+ * license:
+ */
+/*
+   Copyright 2009-2013 Attila Szegedi
+
+   Licensed under both the Apache License, Version 2.0 (the "Apache License")
+   and the BSD License (the "BSD License"), with licensee being free to
+   choose either of the two at their discretion.
+
+   You may not use this file except in compliance with either the Apache
+   License or the BSD License.
+
+   If you choose to use this file in compliance with the Apache License, the
+   following notice applies to you:
+
+       You may obtain a copy of the Apache License at
+
+           http://www.apache.org/licenses/LICENSE-2.0
+
+       Unless required by applicable law or agreed to in writing, software
+       distributed under the License is distributed on an "AS IS" BASIS,
+       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+       implied. See the License for the specific language governing
+       permissions and limitations under the License.
+
+   If you choose to use this file in compliance with the BSD License, the
+   following notice applies to you:
+
+       Redistribution and use in source and binary forms, with or without
+       modification, are permitted provided that the following conditions are
+       met:
+       * Redistributions of source code must retain the above copyright
+         notice, this list of conditions and the following disclaimer.
+       * Redistributions in binary form must reproduce the above copyright
+         notice, this list of conditions and the following disclaimer in the
+         documentation and/or other materials provided with the distribution.
+       * Neither the name of the copyright holder nor the names of
+         contributors may be used to endorse or promote products derived from
+         this software without specific prior written permission.
+
+       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+       IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+       PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER
+       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+/**
+ * Contains the linker for ordinary Java objects.
+ * @since 1.9
+ */
+@jdk.Exported
+package jdk.internal.dynalink.beans;
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/package.html	Tue Oct 20 23:33:39 2015 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,86 +0,0 @@
-<!--
-   Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
-   DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
-
-   This code is free software; you can redistribute it and/or modify it
-   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.
--->
-
-<!--
-   This file is available under and governed by the GNU General Public
-   License version 2 only, as published by the Free Software Foundation.
-   However, the following notice accompanied the original version of this
-   file, and Oracle licenses the original version of this file under the BSD
-   license:
-
-   Copyright 2009-2013 Attila Szegedi
-
-   Licensed under both the Apache License, Version 2.0 (the "Apache License")
-   and the BSD License (the "BSD License"), with licensee being free to
-   choose either of the two at their discretion.
-
-   You may not use this file except in compliance with either the Apache
-   License or the BSD License.
-
-   If you choose to use this file in compliance with the Apache License, the
-   following notice applies to you:
-
-       You may obtain a copy of the Apache License at
-
-           http://www.apache.org/licenses/LICENSE-2.0
-
-       Unless required by applicable law or agreed to in writing, software
-       distributed under the License is distributed on an "AS IS" BASIS,
-       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-       implied. See the License for the specific language governing
-       permissions and limitations under the License.
-
-   If you choose to use this file in compliance with the BSD License, the
-   following notice applies to you:
-
-       Redistribution and use in source and binary forms, with or without
-       modification, are permitted provided that the following conditions are
-       met:
-       * Redistributions of source code must retain the above copyright
-         notice, this list of conditions and the following disclaimer.
-       * Redistributions in binary form must reproduce the above copyright
-         notice, this list of conditions and the following disclaimer in the
-         documentation and/or other materials provided with the distribution.
-       * Neither the name of the copyright holder nor the names of
-         contributors may be used to endorse or promote products derived from
-         this software without specific prior written permission.
-
-       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
-       IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
-       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-       PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER
-       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
-       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
-       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
-       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
--->
-  <body>
-    <p>
-      Contains the linker for POJOs.
-    </p>
-  </body>
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardedInvocationTransformer.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardedInvocationTransformer.java	Tue Oct 20 23:34:16 2015 +0200
@@ -106,8 +106,8 @@
      * request and the differing invocation created with the assistance of the
      * linker services. Whether or not {@code null} is an accepted return value
      * is dependent on the user of the filter.
-     * @throws NullPointerException is allowed if any of the passed arguments
-     * is null.
+     * @throws NullPointerException is allowed to be thrown by implementations
+     * if any of the passed arguments is null.
      */
     public GuardedInvocation filter(GuardedInvocation inv, LinkRequest linkRequest, LinkerServices linkerServices);
 }
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardingDynamicLinker.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardingDynamicLinker.java	Tue Oct 20 23:34:16 2015 +0200
@@ -83,30 +83,59 @@
 
 package jdk.internal.dynalink.linker;
 
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodType;
+import java.util.List;
+import jdk.internal.dynalink.DynamicLinkerFactory;
+
 /**
- * The base interface for language-specific dynamic linkers. Such linkers always have to produce method handles with
- * guards, as the validity of the method handle for calls at a call site inevitably depends on some condition (at the
- * very least, it depends on the receiver belonging to the language runtime of the linker). Language runtime
- * implementors will normally implement one for their own language, and declare it in the
- * <tt>META-INF/services/jdk.internal.dynalink.linker.GuardingDynamicLinker</tt> file within their JAR file.
+ * The base interface for language-specific dynamic linkers. Such linkers
+ * always have to produce method handles with guards, as the validity of the
+ * method handle for calls at a call site inevitably depends on some condition
+ * (at the very least, it depends on the receiver belonging to the language
+ * runtime of the linker). Language runtime implementors will normally implement
+ * the linking logic for their own language as one or more
+ * {@link GuardingDynamicLinker} classes. They will typically set them as
+ * {@link DynamicLinkerFactory#setPrioritizedLinkers(List) prioritized linkers}
+ * in the {@code DynamicLinkerFactory} they configure for themselves, and maybe also
+ * set some as {@link DynamicLinkerFactory#setFallbackLinkers(List) fallback
+ * linkers} to handle language-specific "property not found" etc. conditions.
+ * <p>
+ * Languages can declare the linkers they want to expose to other runtimes for
+ * {@link DynamicLinkerFactory#setClassLoader(ClassLoader) automatic discovery}
+ * in <tt>META-INF/services/jdk.internal.dynalink.linker.GuardingDynamicLinker</tt>
+ * resources of their JAR files.
+ * <p>
+ * Consider implementing {@link TypeBasedGuardingDynamicLinker} interface
+ * instead of this interface for those linkers that are based on the Java class
+ * of the objects. If you need to implement language-specific type conversions,
+ * have your {@code GuardingDynamicLinker} also implement the
+ * {@link GuardingTypeConverterFactory} interface.
  */
 public interface GuardingDynamicLinker {
     /**
-     * Creates a guarded invocation appropriate for a particular invocation with the specified arguments at a call site.
+     * Creates a guarded invocation appropriate for a particular invocation with
+     * the specified arguments at a call site.
      *
-     * @param linkRequest the object describing the request for linking a particular invocation
+     * @param linkRequest the object describing the request for linking a
+     * particular invocation
      * @param linkerServices linker services
-     * @return a guarded invocation with a method handle suitable for the arguments, as well as a guard condition that
-     * if fails should trigger relinking. Must return null if it can't resolve the invocation. If the returned
-     * invocation is unconditional (which is actually quite rare), the guard in the return value can be null. The
-     * invocation can also have any number of switch points for asynchronous invalidation of the linkage, as well as a
-     * {@link Throwable} subclass that describes an expected exception condition that also triggers relinking (often it
-     * is faster to rely on an infrequent but expected {@link ClassCastException} than on an always evaluated
-     * {@code instanceof} guard). While the linker must produce an
-     * invocation with parameter types matching those in the call site descriptor of the link request, it should not try
-     * to match the return type expected at the call site except when it can do it with only the conversions that lose
-     * neither precision nor magnitude, see {@link LinkerServices#asTypeLosslessReturn(java.lang.invoke.MethodHandle,
-     * java.lang.invoke.MethodType)} for further explanation.
+     * @return a guarded invocation with a method handle suitable for the
+     * arguments, as well as a guard condition that if fails should trigger
+     * relinking. Must return null if it can't resolve the invocation. If the
+     * returned invocation is unconditional (which is actually quite rare), the
+     * guard in the return value can be null. The invocation can also have any
+     * number of switch points for asynchronous invalidation of the linkage, as
+     * well as a {@link Throwable} subclass that describes an expected exception
+     * condition that also triggers relinking (often it is faster to rely on an
+     * infrequent but expected {@link ClassCastException} than on an always
+     * evaluated {@code instanceof} guard). While the linker must produce an
+     * invocation with parameter types matching those in the call site
+     * descriptor of the link request, it should not try to match the return
+     * type expected at the call site except when it can do it with only the
+     * conversions that lose neither precision nor magnitude, see
+     * {@link LinkerServices#asTypeLosslessReturn(MethodHandle, MethodType)} for
+     * further explanation.
      * @throws Exception if the operation fails for whatever reason
      */
     public GuardedInvocation getGuardedInvocation(LinkRequest linkRequest, LinkerServices linkerServices)
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardingTypeConverterFactory.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardingTypeConverterFactory.java	Tue Oct 20 23:34:16 2015 +0200
@@ -90,19 +90,36 @@
 import jdk.internal.dynalink.linker.support.TypeUtilities;
 
 /**
- * Optional interface that can be implemented by {@link GuardingDynamicLinker} implementations to provide
- * language-runtime specific implicit type conversion capabilities. Note that if you implement this interface, you will
- * very likely want to implement {@link ConversionComparator} interface too, as your additional language-specific
- * conversions, in absence of a strategy for prioritizing these conversions, will cause more ambiguity for
- * {@link BeansLinker} in selecting the correct overload when trying to link to an overloaded Java method.
+ * Optional interface that can be implemented by {@link GuardingDynamicLinker}
+ * implementations to provide language-specific type conversion capabilities.
+ * Note that if you implement this interface, you will very likely want to
+ * implement {@link ConversionComparator} interface too, as your additional
+ * language-specific conversions, in absence of a strategy for prioritizing
+ * these conversions, will cause more ambiguity for {@link BeansLinker} in
+ * selecting the correct overload when trying to link to an overloaded Java
+ * method.
  */
 public interface GuardingTypeConverterFactory {
     /**
-     * Returns a guarded type conversion that receives an Object of the specified source type and returns an Object
-     * converted to the specified target type. The type of the invocation is targetType(sourceType), while the type of
-     * the guard is boolean(sourceType). Note that this will never be invoked for type conversions allowed by the JLS
-     * 5.3 "Method Invocation Conversion", see {@link TypeUtilities#isMethodInvocationConvertible(Class, Class)} for
-     * details. An implementation can assume it is never requested to produce a converter for these conversions.
+     * Returns a guarded type conversion that receives a value of the specified
+     * source type and returns a value converted to the specified target type.
+     * Value types can be either primitives or reference types, including
+     * interfaces, so you can even provide converters for converting your
+     * language's objects to Java interfaces and classes by generating adapters
+     * for them.
+     * <p>
+     * The type of the invocation is {@code targetType(sourceType)}, while the
+     * type of the guard is {@code boolean(sourceType)}. You are allowed to
+     * return unconditional invocations (with no guard) if the source type is
+     * specific to your runtime and your runtime only.
+     * <p>Note that this method will never be invoked for type conversions
+     * allowed by the JLS 5.3 "Method Invocation Conversion", see
+     * {@link TypeUtilities#isMethodInvocationConvertible(Class, Class)} for
+     * details. An implementation can assume it is never requested to produce a
+     * converter for these conversions.
+     * <p>Dynalink is at liberty to either cache some of the returned converters
+     * or to repeatedly request the converter factory to create the same
+     * conversion.
      *
      * @param sourceType source type
      * @param targetType the target type.
@@ -110,19 +127,20 @@
      * on whose behalf a type converter is requested. When a converter is
      * requested as part of linking an {@code invokedynamic} instruction the
      * supplier will return the lookup passed to the bootstrap method, otherwise
-     * it will return the public lookup. For most conversions, the lookup is
-     * irrelevant. A typical case where the lookup might be needed is when the
-     * converter creates a Java adapter class on the fly (e.g. to convert some
-     * object from the dynamic language into a Java interface for
-     * interoperability). Invoking the {@link Supplier#get()} method on the
-     * passed supplier will be subject to the same security checks as
-     * {@link CallSiteDescriptor#getLookup()}. An implementation should avoid
-     * retrieving the lookup if it is not needed so to avoid the expense of
+     * it will return the public lookup. A typical case where the lookup might
+     * be needed is when the converter creates a Java adapter class on the fly
+     * (e.g. to convert some object from the dynamic language into a Java
+     * interface for interoperability). Invoking the {@link Supplier#get()}
+     * method on the passed supplier will be subject to the same security checks
+     * as {@link CallSiteDescriptor#getLookup()}. An implementation should avoid
+     * retrieving the lookup if it is not needed so as to avoid the expense of
      * {@code AccessController.doPrivileged} call.
      * @return a guarded invocation that can take an object (if it passes guard)
-     * and return another object that is its representation coerced into the target type. In case the factory is certain
-     * it is unable to handle a conversion, it can return null. In case the factory is certain that it can always handle
-     * the conversion, it can return an unconditional invocation (one whose guard is null).
+     * and return another object that is its representation coerced into the
+     * target type. In case the factory is certain it is unable to handle a
+     * conversion, it can return null. In case the factory is certain that it
+     * can always handle the conversion, it can return an unconditional
+     * invocation (one whose guard is null).
      * @throws Exception if there was an error during creation of the converter
      */
     public GuardedInvocation convertToType(Class<?> sourceType, Class<?> targetType, Supplier<MethodHandles.Lookup> lookupSupplier) throws Exception;
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/LinkRequest.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/LinkRequest.java	Tue Oct 20 23:34:16 2015 +0200
@@ -84,11 +84,14 @@
 package jdk.internal.dynalink.linker;
 
 import jdk.internal.dynalink.CallSiteDescriptor;
+import jdk.internal.dynalink.DynamicLinker;
 import jdk.internal.dynalink.DynamicLinkerFactory;
 
 /**
- * Represents a request to link a particular invocation at a particular call site. Instances of these requests are being
- * passed to {@link GuardingDynamicLinker}.
+ * Represents a request to link a particular invocation at a particular call
+ * site. Instances of these requests will be constructed and passed to all
+ * {@link GuardingDynamicLinker} objects managed by the {@link DynamicLinker}
+ * that is trying to link the call site.
  */
 public interface LinkRequest {
     /**
@@ -135,5 +138,5 @@
      * @return a new request identical to this one, except with the call site descriptor and arguments replaced with the
      * specified ones.
      */
-    public LinkRequest replaceArguments(CallSiteDescriptor callSiteDescriptor, Object[] arguments);
+    public LinkRequest replaceArguments(CallSiteDescriptor callSiteDescriptor, Object... arguments);
 }
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/LinkerServices.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/LinkerServices.java	Tue Oct 20 23:34:16 2015 +0200
@@ -92,41 +92,51 @@
 import jdk.internal.dynalink.linker.support.TypeUtilities;
 
 /**
- * Interface for services provided to {@link GuardingDynamicLinker} instances by the {@link DynamicLinker} that owns
- * them. You can think of it as the interface of the {@link DynamicLinker} that faces the {@link GuardingDynamicLinker}
- * s.
+ * Interface for services provided to {@link GuardingDynamicLinker} instances by
+ * the {@link DynamicLinker} that owns them.
  */
 public interface LinkerServices {
     /**
-     * Similar to {@link MethodHandle#asType(MethodType)} except it also hooks in method handles produced by
-     * {@link GuardingTypeConverterFactory} implementations, providing for language-specific type coercing of
-     * parameters. It will apply {@link MethodHandle#asType(MethodType)} for all primitive-to-primitive,
-     * wrapper-to-primitive, primitive-to-wrapper conversions as well as for all upcasts. For all other conversions,
-     * it'll insert {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)} with composite filters
-     * provided by {@link GuardingTypeConverterFactory} implementations.
+     * Similar to {@link MethodHandle#asType(MethodType)} except it also hooks
+     * in method handles produced by all available
+     * {@link GuardingTypeConverterFactory} implementations, providing for
+     * language-specific type coercing of parameters. It will apply
+     * {@link MethodHandle#asType(MethodType)} for all primitive-to-primitive,
+     * wrapper-to-primitive, primitive-to-wrapper conversions as well as for all
+     * upcasts. For all other conversions, it'll insert
+     * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)}
+     * with composite filters provided by {@link GuardingTypeConverterFactory}
+     * implementations.
      *
      * @param handle target method handle
      * @param fromType the types of source arguments
-     * @return a method handle that is a suitable combination of {@link MethodHandle#asType(MethodType)},
-     * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)}, and
-     * {@link MethodHandles#filterReturnValue(MethodHandle, MethodHandle)} with
-     * {@link GuardingTypeConverterFactory}-produced type converters as filters.
+     * @return a method handle that is a suitable combination of
+     * {@link MethodHandle#asType(MethodType)},
+     * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)},
+     * and {@link MethodHandles#filterReturnValue(MethodHandle, MethodHandle)}
+     * with {@link GuardingTypeConverterFactory}-produced type converters as
+     * filters.
      */
     public MethodHandle asType(MethodHandle handle, MethodType fromType);
 
     /**
-     * Similar to {@link #asType(MethodHandle, MethodType)} except it only converts the return type of the method handle
-     * when it can be done using a conversion that loses neither precision nor magnitude, otherwise it leaves it
-     * unchanged. The idea is that other conversions should not be performed by individual linkers, but instead the
-     * {@link DynamicLinkerFactory#setPrelinkTransformer(GuardedInvocationTransformer) pre-link transformer of
-     * the dynamic linker} should implement the strategy of dealing with potentially lossy return type conversions in a
-     * manner specific to the language runtime.
+     * Similar to {@link #asType(MethodHandle, MethodType)} except it treats
+     * return value type conversion specially. It only converts the return type
+     * of the method handle when it can be done using a conversion that loses
+     * neither precision nor magnitude, otherwise it leaves it unchanged. These
+     * are the only return value conversions that should be performed by
+     * individual language-specific linkers, and
+     * {@link DynamicLinkerFactory#setPrelinkTransformer(GuardedInvocationTransformer)
+     * pre-link transformer of the dynamic linker} should implement the strategy
+     * for dealing with potentially lossy return type conversions in a manner
+     * specific to the language runtime where the call site is located.
      *
      * @param handle target method handle
      * @param fromType the types of source arguments
-     * @return a method handle that is a suitable combination of {@link MethodHandle#asType(MethodType)}, and
-     * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)} with
-     * {@link GuardingTypeConverterFactory}-produced type converters as filters.
+     * @return a method handle that is a suitable combination of
+     * {@link MethodHandle#asType(MethodType)}, and
+     * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)}
+     * with {@link GuardingTypeConverterFactory}-produced type converters as filters.
      */
     public default MethodHandle asTypeLosslessReturn(final MethodHandle handle, final MethodType fromType) {
         final Class<?> handleReturnType = handle.type().returnType();
@@ -135,11 +145,13 @@
     }
 
     /**
-     * Given a source and target type, returns a method handle that converts between them. Never returns null; in worst
-     * case it will return an identity conversion (that might fail for some values at runtime). You rarely need to use
-     * this method directly; you should mostly rely on {@link #asType(MethodHandle, MethodType)} instead. You really
-     * only need this method if you have a piece of your program that is written in Java, and you need to reuse existing
-     * type conversion machinery in a non-invokedynamic context.
+     * Given a source and target type, returns a method handle that converts
+     * between them. Never returns null; in worst case it will return an
+     * identity conversion (that might fail for some values at runtime). You
+     * rarely need to use this method directly and should mostly rely on
+     * {@link #asType(MethodHandle, MethodType)} instead. This method is needed
+     * when you need to reuse existing type conversion machinery outside the
+     * context of processing a link request.
      * @param sourceType the type to convert from
      * @param targetType the type to convert to
      * @return a method handle performing the conversion.
@@ -147,11 +159,13 @@
     public MethodHandle getTypeConverter(Class<?> sourceType, Class<?> targetType);
 
     /**
-     * Returns true if there might exist a conversion between the requested types (either an automatic JVM conversion,
-     * or one provided by any available {@link GuardingTypeConverterFactory}), or false if there definitely does not
-     * exist a conversion between the requested types. Note that returning true does not guarantee that the conversion
-     * will succeed at runtime (notably, if the "from" or "to" types are sufficiently generic), but returning false
-     * guarantees that it would fail.
+     * Returns true if there might exist a conversion between the requested
+     * types (either an automatic JVM conversion, or one provided by any
+     * available {@link GuardingTypeConverterFactory}), or false if there
+     * definitely does not exist a conversion between the requested types. Note
+     * that returning true does not guarantee that the conversion will succeed
+     * at runtime for all values (especially if the "from" or "to" types are
+     * sufficiently generic), but returning false guarantees that it would fail.
      *
      * @param from the source type for the conversion
      * @param to the target type for the conversion
@@ -160,35 +174,47 @@
     public boolean canConvert(Class<?> from, Class<?> to);
 
     /**
-     * Creates a guarded invocation using the {@link DynamicLinker} that exposes this linker services interface. Linkers
-     * can typically use them to delegate linking of wrapped objects.
+     * Creates a guarded invocation delegating back to the {@link DynamicLinker}
+     * that exposes this linker services object. The dynamic linker will then
+     * itself delegate the linking to all of its managed
+     * {@link GuardingDynamicLinker}s including potentially this one if no
+     * linker responds earlier, so beware of infinite recursion. You'll
+     * typically craft the link request so that it will be different than the
+     * one you are currently trying to link.
      *
      * @param linkRequest a request for linking the invocation
-     * @return a guarded invocation linked by the top-level linker (or any of its delegates). Can be null if no
-     * available linker is able to link the invocation.
+     * @return a guarded invocation linked by some of the guarding dynamic
+     * linkers managed by the top-level dynamic linker. Can be null if no
+     * available linker is able to link the invocation. You will typically use
+     * the elements of the returned invocation to compose your own invocation.
      * @throws Exception in case the top-level linker throws an exception
      */
     public GuardedInvocation getGuardedInvocation(LinkRequest linkRequest) throws Exception;
 
     /**
-     * Determines which of the two type conversions from a source type to the two target types is preferred. This is
-     * used for dynamic overloaded method resolution. If the source type is convertible to exactly one target type with
-     * a method invocation conversion, it is chosen, otherwise available {@link ConversionComparator}s are consulted.
+     * Determines which of the two type conversions from a source type to the
+     * two target types is preferred. This is used for dynamic overloaded method
+     * resolution. If the source type is convertible to exactly one target type
+     * with a method invocation conversion, it is chosen, otherwise available
+     * {@link ConversionComparator}s are consulted.
      * @param sourceType the source type.
      * @param targetType1 one potential target type
      * @param targetType2 another potential target type.
-     * @return one of Comparison constants that establish which - if any - of the target types is preferable for the
-     * conversion.
+     * @return one of Comparison constants that establish which &ndash; if any
+     * &ndash; of the target types is preferable for the conversion.
      */
     public Comparison compareConversion(Class<?> sourceType, Class<?> targetType1, Class<?> targetType2);
 
     /**
-     * Modifies the method handle so that any parameters that can receive potentially internal language runtime objects
-     * will have a filter added on them to prevent them from escaping, potentially by wrapping them.
-     * It can also potentially add an unwrapping filter to the return value. Basically transforms the method
-     * handle using the transformer configured by {@link DynamicLinkerFactory#setInternalObjectsFilter(MethodHandleTransformer)}.
+     * Modifies the method handle so that any parameters that can receive
+     * potentially internal language runtime objects will have a filter added on
+     * them to prevent them from escaping, potentially by wrapping them. It can
+     * also potentially add an unwrapping filter to the return value. Basically
+     * transforms the method handle using the transformer configured by
+     * {@link DynamicLinkerFactory#setInternalObjectsFilter(MethodHandleTransformer)}.
      * @param target the target method handle
-     * @return a method handle with parameters and/or return type potentially filtered for wrapping and unwrapping.
+     * @return a method handle with parameters and/or return type potentially
+     * filtered for wrapping and unwrapping.
      */
     public MethodHandle filterInternalObjects(final MethodHandle target);
 }
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/MethodHandleTransformer.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/MethodHandleTransformer.java	Tue Oct 20 23:34:16 2015 +0200
@@ -84,9 +84,13 @@
 package jdk.internal.dynalink.linker;
 
 import java.lang.invoke.MethodHandle;
+import jdk.internal.dynalink.DynamicLinkerFactory;
 
 /**
  * A generic interface describing operations that transform method handles.
+ * Typical usage is for implementing
+ * {@link DynamicLinkerFactory#setInternalObjectsFilter(MethodHandleTransformer)
+ * internal objects filters}.
  */
 @FunctionalInterface
 public interface MethodHandleTransformer {
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/MethodTypeConversionStrategy.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/MethodTypeConversionStrategy.java	Tue Oct 20 23:34:16 2015 +0200
@@ -85,10 +85,14 @@
 
 import java.lang.invoke.MethodHandle;
 import java.lang.invoke.MethodType;
+import jdk.internal.dynalink.DynamicLinkerFactory;
 
 /**
  * Interface for objects representing a strategy for converting a method handle
- * to a new type.
+ * to a new type. Typical usage is for customizing a language runtime's handling
+ * of
+ * {@link DynamicLinkerFactory#setAutoConversionStrategy(MethodTypeConversionStrategy)
+ * method invocation conversions}.
  */
 @FunctionalInterface
 public interface MethodTypeConversionStrategy {
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/package-info.java	Tue Oct 20 23:34:16 2015 +0200
@@ -0,0 +1,117 @@
+/*
+ * Copyright (c) 2015, 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.
+ */
+
+/*
+ * This file is available under and governed by the GNU General Public
+ * License version 2 only, as published by the Free Software Foundation.
+ * However, the following notice accompanied the original version of this
+ * file, and Oracle licenses the original version of this file under the BSD
+ * license:
+ */
+/*
+   Copyright 2009-2013 Attila Szegedi
+
+   Licensed under both the Apache License, Version 2.0 (the "Apache License")
+   and the BSD License (the "BSD License"), with licensee being free to
+   choose either of the two at their discretion.
+
+   You may not use this file except in compliance with either the Apache
+   License or the BSD License.
+
+   If you choose to use this file in compliance with the Apache License, the
+   following notice applies to you:
+
+       You may obtain a copy of the Apache License at
+
+           http://www.apache.org/licenses/LICENSE-2.0
+
+       Unless required by applicable law or agreed to in writing, software
+       distributed under the License is distributed on an "AS IS" BASIS,
+       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+       implied. See the License for the specific language governing
+       permissions and limitations under the License.
+
+   If you choose to use this file in compliance with the BSD License, the
+   following notice applies to you:
+
+       Redistribution and use in source and binary forms, with or without
+       modification, are permitted provided that the following conditions are
+       met:
+       * Redistributions of source code must retain the above copyright
+         notice, this list of conditions and the following disclaimer.
+       * Redistributions in binary form must reproduce the above copyright
+         notice, this list of conditions and the following disclaimer in the
+         documentation and/or other materials provided with the distribution.
+       * Neither the name of the copyright holder nor the names of
+         contributors may be used to endorse or promote products derived from
+         this software without specific prior written permission.
+
+       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+       IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+       PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER
+       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+/**
+ * <p>
+ * Contains interfaces and classes needed by language runtimes to implement
+ * their own language-specific object models and type conversions. The main
+ * entry point is the
+ * {@link jdk.internal.dynalink.linker.GuardingDynamicLinker} interface. It needs to be
+ * implemented in order to provide linking for the runtime's own object model.
+ * A language runtime can have more than one guarding dynamic linker
+ * implementation. When a runtime is configuring Dynalink for itself, it will
+ * normally set these guarding linkers as the prioritized linkers in its
+ * {@link jdk.internal.dynalink.DynamicLinkerFactory} (and maybe some of them as fallback
+ * linkers, for e.g. handling "method not found" and similar errors in a
+ * language-specific manner if no other linker managed to handle the operation.)
+ * </p><p>
+ * A language runtime that wishes to make at least some of its linkers available
+ * to other language runtimes for interoperability will need to declare the
+ * class names of those linkers in
+ * {@code /META-INF/services/jdk.internal.dynalink.linker.GuardingDynamicLinker} file in
+ * its distribution (typically, JAR file).
+ * </p><p>
+ * Most language runtimes will be able to implement their own linking logic by
+ * implementing {@link jdk.internal.dynalink.linker.TypeBasedGuardingDynamicLinker}
+ * instead of {@link jdk.internal.dynalink.linker.GuardingDynamicLinker}; it allows for
+ * faster type-based linking dispatch.
+ * </p><p>
+ * Language runtimes that allow type conversions other than those provided by
+ * Java will need to have their guarding dynamic linker (or linkers) also
+ * implement the {@link jdk.internal.dynalink.linker.GuardingTypeConverterFactory}
+ * interface to provide the logic for these conversions.
+ * </p>
+ * @since 1.9
+ */
+@jdk.Exported
+package jdk.internal.dynalink.linker;
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/package.html	Tue Oct 20 23:33:39 2015 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,87 +0,0 @@
-<!--
-   Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
-   DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
-
-   This code is free software; you can redistribute it and/or modify it
-   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.
--->
-
-<!--
-   This file is available under and governed by the GNU General Public
-   License version 2 only, as published by the Free Software Foundation.
-   However, the following notice accompanied the original version of this
-   file, and Oracle licenses the original version of this file under the BSD
-   license:
-
-   Copyright 2009-2013 Attila Szegedi
-
-   Licensed under both the Apache License, Version 2.0 (the "Apache License")
-   and the BSD License (the "BSD License"), with licensee being free to
-   choose either of the two at their discretion.
-
-   You may not use this file except in compliance with either the Apache
-   License or the BSD License.
-
-   If you choose to use this file in compliance with the Apache License, the
-   following notice applies to you:
-
-       You may obtain a copy of the Apache License at
-
-           http://www.apache.org/licenses/LICENSE-2.0
-
-       Unless required by applicable law or agreed to in writing, software
-       distributed under the License is distributed on an "AS IS" BASIS,
-       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-       implied. See the License for the specific language governing
-       permissions and limitations under the License.
-
-   If you choose to use this file in compliance with the BSD License, the
-   following notice applies to you:
-
-       Redistribution and use in source and binary forms, with or without
-       modification, are permitted provided that the following conditions are
-       met:
-       * Redistributions of source code must retain the above copyright
-         notice, this list of conditions and the following disclaimer.
-       * Redistributions in binary form must reproduce the above copyright
-         notice, this list of conditions and the following disclaimer in the
-         documentation and/or other materials provided with the distribution.
-       * Neither the name of the copyright holder nor the names of
-         contributors may be used to endorse or promote products derived from
-         this software without specific prior written permission.
-
-       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
-       IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
-       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-       PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER
-       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
-       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
-       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
-       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
--->
-  <body>
-    <p>
-      Contains interfaces and classes needed by language runtimes to implement
-      their own language-specific linkers.
-    </p>
-  </body>
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/CompositeTypeBasedGuardingDynamicLinker.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/CompositeTypeBasedGuardingDynamicLinker.java	Tue Oct 20 23:34:16 2015 +0200
@@ -164,11 +164,12 @@
     }
 
     /**
-     * Returns true if any of the composite linkers return true from
+     * Returns true if at least one of the composite linkers returns true from
      * {@link TypeBasedGuardingDynamicLinker#canLinkType(Class)} for the type.
      * @param type the type to link
-     * @return true if any of the composite linkers can link calls for the
-     * receiver type, false otherwise.
+     * @return true true if at least one of the composite linkers returns true
+     * from {@link TypeBasedGuardingDynamicLinker#canLinkType(Class)}, false
+     * otherwise.
      */
     @Override
     public boolean canLinkType(final Class<?> type) {
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/DefaultInternalObjectFilter.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/DefaultInternalObjectFilter.java	Tue Oct 20 23:34:16 2015 +0200
@@ -92,13 +92,17 @@
 /**
  * Default implementation for a
  * {@link DynamicLinkerFactory#setInternalObjectsFilter(MethodHandleTransformer)}
- * that delegates to a pair of filtering method handles. Given a method handle
- * of {@code Object(Object)} type for filtering parameter and another one of the
- * same type for filtering return values, applies them to passed method handles,
- * on those parameter types and/or return value types that are declared to be
- * {@link Object}. Also handles {@link MethodHandle#isVarargsCollector() method
- * handles that support variable arity calls} with a last {@code Object[]}
- * parameter.
+ * that delegates to a pair of filtering method handles. It takes a method
+ * handle of {@code Object(Object)} type for filtering parameter values and
+ * another one of the same type for filtering return values. It applies them as
+ * parameter and return value filters on method handles passed to its
+ * {@link #transform(MethodHandle)} method, on those parameters and return values
+ * that are declared to have type {@link Object}. Also handles
+ * {@link MethodHandle#isVarargsCollector() method handles that support variable
+ * arity calls} with a last {@code Object[]} parameter. You can broadly think of
+ * the parameter filter as being a wrapping method for exposing internal runtime
+ * objects wrapped into an adapter with some public interface, and the return
+ * value filter as being its inverse unwrapping method.
  */
 public class DefaultInternalObjectFilter implements MethodHandleTransformer {
     private static final MethodHandle FILTER_VARARGS = new Lookup(MethodHandles.lookup()).findStatic(
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/Guards.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/Guards.java	Tue Oct 20 23:34:16 2015 +0200
@@ -92,7 +92,9 @@
 import jdk.internal.dynalink.linker.LinkerServices;
 
 /**
- * Utility methods for creating typical guards.
+ * Utility methods for creating typical guards for
+ * {@link MethodHandles#guardWithTest(MethodHandle, MethodHandle, MethodHandle)}
+ * and for adjusting their method types.
  */
 public final class Guards {
     private static final Logger LOG = Logger
@@ -189,8 +191,11 @@
     }
 
     /**
-     * Takes a guard-test method handle, and adapts it to the requested type, returning a boolean. Only applies
-     * conversions as per {@link MethodHandle#asType(MethodType)}.
+     * Takes a method handle intended to be used as a guard, and adapts it to
+     * the requested type, but returning a boolean. Applies
+     * {@link MethodHandle#asType(MethodType)} to convert types and uses
+     * {@link MethodHandles#dropArguments(MethodHandle, int, Class...)} to match
+     * the requested type arity.
      * @param test the test method handle
      * @param type the type to adapt the method handle to
      * @return the adapted method handle
@@ -200,8 +205,12 @@
     }
 
     /**
-     * Takes a guard-test method handle, and adapts it to the requested type, returning a boolean. Applies the passed
-     * {@link LinkerServices} object's {@link LinkerServices#asType(MethodHandle, MethodType)}.
+     * Takes a method handle intended to be used as a guard, and adapts it to
+     * the requested type, but returning a boolean. Applies
+     * {@link LinkerServices#asType(MethodHandle, MethodType)} to convert types
+     * and uses
+     * {@link MethodHandles#dropArguments(MethodHandle, int, Class...)} to match
+     * the requested type arity.
      * @param linkerServices the linker services to use for type conversions
      * @param test the test method handle
      * @param type the type to adapt the method handle to
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/Lookup.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/Lookup.java	Tue Oct 20 23:34:16 2015 +0200
@@ -96,7 +96,7 @@
  * methods within your own codebase (therefore it is an error if they are not
  * present).
  */
-public class Lookup {
+public final class Lookup {
     private final MethodHandles.Lookup lookup;
 
     /**
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/SimpleLinkRequest.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/SimpleLinkRequest.java	Tue Oct 20 23:34:16 2015 +0200
@@ -83,6 +83,7 @@
 
 package jdk.internal.dynalink.linker.support;
 
+import java.util.Objects;
 import jdk.internal.dynalink.CallSiteDescriptor;
 import jdk.internal.dynalink.linker.LinkRequest;
 
@@ -99,24 +100,27 @@
      * Creates a new link request.
      *
      * @param callSiteDescriptor the descriptor for the call site being linked.
+     * Must not be null.
      * @param callSiteUnstable true if the call site being linked is considered
      * unstable.
-     * @param arguments the arguments for the invocation
+     * @param arguments the arguments for the invocation. Must not be null.
+     * @throws NullPointerException if either {@code callSiteDescriptor} or
+     * {@code arguments} is null.
      */
     public SimpleLinkRequest(final CallSiteDescriptor callSiteDescriptor, final boolean callSiteUnstable, final Object... arguments) {
-        this.callSiteDescriptor = callSiteDescriptor;
+        this.callSiteDescriptor = Objects.requireNonNull(callSiteDescriptor);
         this.callSiteUnstable = callSiteUnstable;
-        this.arguments = arguments;
+        this.arguments = arguments.clone();
     }
 
     @Override
     public Object[] getArguments() {
-        return arguments != null ? arguments.clone() : null;
+        return arguments.clone();
     }
 
     @Override
     public Object getReceiver() {
-        return arguments != null && arguments.length > 0 ? arguments[0] : null;
+        return arguments.length > 0 ? arguments[0] : null;
     }
 
     @Override
@@ -130,7 +134,7 @@
     }
 
     @Override
-    public LinkRequest replaceArguments(final CallSiteDescriptor newCallSiteDescriptor, final Object[] newArguments) {
+    public LinkRequest replaceArguments(final CallSiteDescriptor newCallSiteDescriptor, final Object... newArguments) {
         return new SimpleLinkRequest(newCallSiteDescriptor, callSiteUnstable, newArguments);
     }
 }
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/package-info.java	Tue Oct 20 23:34:16 2015 +0200
@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2015, 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.
+ */
+
+/*
+ * This file is available under and governed by the GNU General Public
+ * License version 2 only, as published by the Free Software Foundation.
+ * However, the following notice accompanied the original version of this
+ * file, and Oracle licenses the original version of this file under the BSD
+ * license:
+ */
+/*
+   Copyright 2015 Attila Szegedi
+
+   Licensed under both the Apache License, Version 2.0 (the "Apache License")
+   and the BSD License (the "BSD License"), with licensee being free to
+   choose either of the two at their discretion.
+
+   You may not use this file except in compliance with either the Apache
+   License or the BSD License.
+
+   If you choose to use this file in compliance with the Apache License, the
+   following notice applies to you:
+
+       You may obtain a copy of the Apache License at
+
+           http://www.apache.org/licenses/LICENSE-2.0
+
+       Unless required by applicable law or agreed to in writing, software
+       distributed under the License is distributed on an "AS IS" BASIS,
+       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+       implied. See the License for the specific language governing
+       permissions and limitations under the License.
+
+   If you choose to use this file in compliance with the BSD License, the
+   following notice applies to you:
+
+       Redistribution and use in source and binary forms, with or without
+       modification, are permitted provided that the following conditions are
+       met:
+       * Redistributions of source code must retain the above copyright
+         notice, this list of conditions and the following disclaimer.
+       * Redistributions in binary form must reproduce the above copyright
+         notice, this list of conditions and the following disclaimer in the
+         documentation and/or other materials provided with the distribution.
+       * Neither the name of the copyright holder nor the names of
+         contributors may be used to endorse or promote products derived from
+         this software without specific prior written permission.
+
+       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+       IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+       PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER
+       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+/**
+ * <p>Contains classes that make it more convenient for language runtimes to
+ * implement their own language-specific object models and type conversions
+ * by providing basic implementations of some classes as well as various
+ * utilities.
+ * </p>
+ * @since 1.9
+ */
+@jdk.Exported
+package jdk.internal.dynalink.linker.support;
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/package-info.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/package-info.java	Tue Oct 20 23:34:16 2015 +0200
@@ -83,47 +83,322 @@
 
 /**
  * <p>
- * Dynalink is a library for dynamic linking high-level operations on objects
- * such as "read a property", "write a property", "invoke a function" and so on,
- * expressed as {@link java.lang.invoke.CallSite call sites}. As such, it is
- * closely related to, and relies on, the {@link java.lang.invoke} package.
- * </p><p>
- * While {@link java.lang.invoke} provides a JVM-level foundation for
- * application-specific dynamic linking of methods, it does not provide a way to
- * express higher level operations on objects, nor methods that implement them.
- * These operations are the usual regimen of operations in object-oriented
- * environments: property access, access of elements of collections, invocation
- * of constructors, invocation of named methods (potentially with multiple
- * dispatch, e.g. link- and run-time equivalents of Java overloaded method
- * resolution). These are all functions that are normally desired in a language
- * on the JVM. When a JVM language is statically typed and its type system
- * matches that of the JVM, it can accomplish this with use of the usual
- * invocation bytecodes ({@code INVOKEVIRTUAL} etc.) as well as field access
- * bytecodes ({@code GETFIELD}, {@code PUTFIELD}). However, if the language is
- * dynamic (hence, types of some expressions are not known at the time the
- * program is compiled to bytecode), or its type system doesn't match closely
- * that of the JVM, then it should use {@code invokedynamic} call sites and let
- * Dynalink link those.
- * </p><p>
- * Dynalink lets programs have their operations on objects of unknown static
- * types linked dynamically at run time. It also lets a language expose a linker
- * for its own object model. Finally, it provides a default linker for ordinary
- * Java objects. Two languages both exporting their linkers in the same JVM will
- * even be able to cross-link their operations with each other if an object
- * belonging to one language is passed to code from the other language.
- * </p>
+ * Dynalink is a library for dynamic linking high-level operations on objects.
+ * These operations include "read a property",
+ * "write a property", "invoke a function" and so on. Dynalink is primarily
+ * useful for implementing programming languages where at least some expressions
+ * have dynamic types (that is, types that can not be decided statically), and
+ * the operations on dynamic types are expressed as
+ * {@link java.lang.invoke.CallSite call sites}. These call sites will be
+ * linked to appropriate target {@link java.lang.invoke.MethodHandle method handles}
+ * at run time based on actual types of the values the expressions evaluated to.
+ * These can change between invocations, necessitating relinking the call site
+ * multiple times to accommodate new types; Dynalink handles all that and more.
  * <p>
- * Languages that use Dynalink will create and configure a
- * {@link jdk.internal.dynalink.DynamicLinkerFactory} and use it to create a
- * {@link jdk.internal.dynalink.DynamicLinker}.
- * The thus created dynamic linker will have to be used to link any
- * {@link jdk.internal.dynalink.RelinkableCallSite}s they create, most often from a
- * {@link java.lang.invoke} bootstrap method.
- * </p>
+ * Dynalink supports implementation of programming languages with object models
+ * that differ (even radically) from the JVM's class-based model and have their
+ * custom type conversions.
  * <p>
- * Languages that wish to define and use their own linkers will also need to
- * use the {@link jdk.internal.dynalink.linker} package.
- * </p>
+ * Dynalink is closely related to, and relies on, the {@link java.lang.invoke}
+ * package.
+ * <p>
+ *
+ * While {@link java.lang.invoke} provides a low level API for dynamic linking
+ * of {@code invokedynamic} call sites, it does not provide a way to express
+ * higher level operations on objects, nor methods that implement them. These
+ * operations are the usual ones in object-oriented environments: property
+ * access, access of elements of collections, invocation of methods and
+ * constructors (potentially with multiple dispatch, e.g. link- and run-time
+ * equivalents of Java overloaded method resolution). These are all functions
+ * that are normally desired in a language on the JVM. If a language is
+ * statically typed and its type system matches that of the JVM, it can
+ * accomplish this with use of the usual invocation, field access, etc.
+ * instructions (e.g. {@code invokevirtual}, {@code getfield}). However, if the
+ * language is dynamic (hence, types of some expressions are not known until
+ * evaluated at run time), or its object model or type system don't match
+ * closely that of the JVM, then it should use {@code invokedynamic} call sites
+ * instead and let Dynalink manage them.
+ * <h2>Example</h2>
+ * Dynalink is probably best explained by an example showing its use. Let's
+ * suppose you have a program in a language where you don't have to declare the
+ * type of an object and you want to access a property on it:
+ * <pre>
+ * var color = obj.color;
+ * </pre>
+ * If you generated a Java class to represent the above one-line program, its
+ * bytecode would look something like this:
+ * <pre>
+ * aload 2 // load "obj" on stack
+ * invokedynamic "dyn:getProp:color"(Object)Object // invoke property getter on object of unknown type
+ * astore 3 // store the return value into local variable "color"
+ * </pre>
+ * In order to link the {@code invokedynamic} instruction, we need a bootstrap
+ * method. A minimalist bootstrap method with Dynalink could look like this:
+ * <pre>
+ * import java.lang.invoke.*;
+ * import jdk.internal.dynalink.*;
+ * import jdk.internal.dynalink.support.*;
+ *
+ * class MyLanguageRuntime {
+ *     private static final DynamicLinker dynamicLinker = new DynamicLinkerFactory().createLinker();
+ *
+ *     public static CallSite bootstrap(MethodHandles.Lookup lookup, String name, MethodType type) {
+ *         return dynamicLinker.link(
+ *             new SimpleRelinkableCallSite(
+ *                 new SimpleCallSiteDescriptor(lookup, name, type)));
+ *     }
+ * }
+ * </pre>
+ * There are several objects of significance in the above code snippet:
+ * <ul>
+ * <li>{@link jdk.internal.dynalink.DynamicLinker} is the main object in Dynalink, it
+ * coordinates the linking of call sites to method handles that implement the
+ * operations named in them. It is configured and created using a
+ * {@link jdk.internal.dynalink.DynamicLinkerFactory}.</li>
+ * <li>When the bootstrap method is invoked, it needs to create a
+ * {@link java.lang.invoke.CallSite} object. In Dynalink, these call sites need
+ * to additionally implement the {@link jdk.internal.dynalink.RelinkableCallSite}
+ * interface. "Relinkable" here alludes to the fact that if the call site
+ * encounters objects of different types at run time, its target will be changed
+ * to a method handle that can perform the operation on the newly encountered
+ * type. {@link jdk.internal.dynalink.support.SimpleRelinkableCallSite} and
+ * {@link jdk.internal.dynalink.support.ChainedCallSite} (not used in the above example)
+ * are two implementations already provided by the library.</li>
+ * <li>Finally, Dynalink uses {@link jdk.internal.dynalink.CallSiteDescriptor} objects to
+ * preserve the parameters to the bootstrap method as it will need them whenever
+ * it needs to relink a call site. Again,
+ * {@link jdk.internal.dynalink.support.SimpleCallSiteDescriptor} is a simple
+ * implementation already provided by the library.</li>
+ * </ul>
+ * <p>What can you already do with the above setup? {@code DynamicLinkerFactory}
+ * by default creates a {@code DynamicLinker} that can link Java objects with the
+ * usual Java semantics. If you have these three simple classes:
+ * <pre>
+ * public class A {
+ *     public String color;
+ *     public A(String color) { this.color = color; }
+ * }
+ *
+ * public class B {
+ *     private String color;
+ *     public B(String color) { this.color = color; }
+ *     public String getColor() { return color; }
+ * }
+ *
+ * public class C {
+ *     private int color;
+ *     public C(int color) { this.color = color; }
+ *     public int getColor() { return color; }
+ * }
+ * </pre>
+ * and you somehow create their instances and pass them to your call site in your
+ * programming language:
+ * <pre>
+ * for each(var obj in [new A("red"), new B("green"), new C(0x0000ff)]) {
+ *     print(obj.color);
+ * }
+ * </pre>
+ * then on first invocation, Dynalink will link the {@code .color} getter
+ * operation to a field getter for {@code A.color}, on second invocation it will
+ * relink it to {@code B.getColor()} returning a {@code String}, and finally on
+ * third invocation it will relink it to {@code C.getColor()} returning an {@code int}.
+ * The {@code SimpleRelinkableCallSite} we used above only remembers the linkage
+ * for the last encountered type (it implements what is known as a <i>monomorphic
+ * inline cache</i>). Another already provided implementation,
+ * {@link jdk.internal.dynalink.support.ChainedCallSite} will remember linkages for
+ * several different types (it is a <i>polymorphic inline cache</i>) and is
+ * probably a better choice in serious applications.
+ * <h2>Dynalink and bytecode creation</h2>
+ * {@code CallSite} objects are usually created as part of bootstrapping
+ * {@code invokedynamic} instructions in bytecode. Hence, Dynalink is typically
+ * used as part of language runtimes that compile programs into Java
+ * {@code .class} bytecode format. Dynalink does not address the aspects of
+ * either creating bytecode classes or loading them into the JVM. That said,
+ * Dynalink can also be used without bytecode compilation (e.g. in language
+ * interpreters) by creating {@code CallSite} objects explicitly and associating
+ * them with representations of dynamic operations in the interpreted program
+ * (e.g. a typical representation would be some node objects in a syntax tree).
+ * <h2>Available operations</h2>
+ * The table below contains all operations defined by Dynalink. All of them have
+ * the prefix {@code "dyn:"} and this prefix is reserved for Dynalink use, with
+ * potential of future extensions. Elements of the name are separated with the
+ * COLON character. {@code $id} is used as a placeholder for an identifier for
+ * those operations that contain an identifier as part of their name.
+ * Identifiers in operation names need to be
+ * {@link jdk.internal.dynalink.support.NameCodec#encode(String) encoded}. Signatures are
+ * expressed in the usual JVM
+ * {@code (parameter-type1, parameter-type2, ...)return-type} format. The type
+ * "any" means that any type, either primitive or reference can be used (with
+ * obvious JVM limitation that {@code void} is disallowed as a parameter type
+ * but allowed as a return type.
+ * <p>&nbsp;
+ * <table summary="Dynalink defined operations" border="1" frame="border" cellpadding="5">
+ *   <thead>
+ *     <tr>
+ *       <th>Name</th>
+ *       <th>Signature</th>
+ *       <th>Semantics</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td>{@code dyn:getProp:$id}</td>
+ *       <td>(any)any</td>
+ *       <td>Retrieve the value of a named property on the object, with the
+ *           receiver being passed as the argument, and the property identifier
+ *           encoded in the operation name as {@code $id}.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:getProp}</td>
+ *       <td>(any,&nbsp;any)any</td>
+ *       <td>Retrieve the value of a named property on the object, with the
+ *           receiver being passed as the first, and the property identifier
+ *           being passed as the second argument.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:setProp:$id}</td>
+ *       <td>(any,&nbsp;any)void</td>
+ *       <td>Set the value of a named property on the object, with the
+ *           receiver being passed as the first, and the value to set being
+ *           passed as the second argument, with the property identifier
+ *           encoded in the operation name as {@code $id}.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:setProp}</td>
+ *       <td>(any,&nbsp;any,&nbsp;any)void</td>
+ *       <td>Set the value of a named property on the object, with the
+ *           receiver being passed as the first, the property identifier as the
+ *           second, and the value to set as the third argument.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:getElem:$id}</td>
+ *       <td>(any)any</td>
+ *       <td>Retrieve an element of a collection object (array, list, map,
+ *           etc.) with a fixed key encoded in the operation name as {@code $id}.
+ *           In this form, the key is necessarily a string as it is part of the
+ *           operation name, but runtimes are allowed to parse it as a number
+ *           literal when linking to a collection using numeric indices.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:getElem}</td>
+ *       <td>(any,&nbsp;any)any</td>
+ *       <td>Retrieve an element of a collection object (array, list, map,
+ *           etc.) with the receiver being passed as the first and the index
+ *           passed as the second argument.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:setElem:$id}</td>
+ *       <td>(any,&nbsp;any)void</td>
+ *       <td>Set an element of a collection object (array, list, map,
+ *           etc.) with a fixed key encoded in the operation name as {@code $id}.
+ *           The receiver is passed as the first, and the new element value as
+ *           the second argument. In this form, the key is necessarily a string
+ *           as it is part of the operation name, but runtimes are allowed to
+ *           parse it as a number literal when linking to a collection using
+ *           numeric indices.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:setElem}</td>
+ *       <td>(any,&nbsp;any,&nbsp;any)void</td>
+ *       <td>Set an element of a collection object (array, list, map,
+ *           etc.) with the receiver being passed as the first, the index
+ *           passed as the second, and the new element value as the third argument.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:getMethod:$id}</td>
+ *       <td>(any)any</td>
+ *       <td>Retrieve a named method on the object, identified by {@code $id}.
+ *           It is expected that at least the {@code "dyn:call"} operation is
+ *           applicable to the returned value.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:getMethod}</td>
+ *       <td>(any,&nbsp;any)any</td>
+ *       <td>Retrieve a named method on the object, with the receiver passed as
+ *           the first and the name of the method passed as the second argument.
+ *           It is expected that {@code "dyn:call"} operation is applicable to
+ *           the returned value.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:call}</td>
+ *       <td>(any[,&nbsp;any,&nbsp;any,...])any</td>
+ *       <td>Call a callable (method, function, etc.). The first argument
+ *           is the callable itself, and the rest are arguments passed to the
+ *           call. If the callable is an instance method, the {@code this}
+ *           argument should be the second argument, immediately following the
+ *           callable.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:callMethod:$id}</td>
+ *       <td>(any[,&nbsp;any,&nbsp;any,...])any</td>
+ *       <td>Call a named instance method on an object. The first argument
+ *           is the object on which the method is invoked, and the rest are
+ *           arguments passed to the call. Note that this method is not strictly
+ *           necessary, as it can be implemented as a composition of
+ *           {@code dyn:getMethod:$id} and {@code dyn:call}. It is a frequent
+ *           enough object-oriented pattern so it is convenient to provide it as
+ *           a separate operation.</td>
+ *     </tr>
+ *     <tr>
+ *       <td>{@code dyn:new}</td>
+ *       <td>(any[,&nbsp;any,&nbsp;any,...])any</td>
+ *       <td>Call a constructor. The first argument is the constructor itself,
+ *       and the rest are arguments passed to the constructor call.</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ * <h2>Composite operations</h2>
+ * Some languages might not have separate namespaces on objects for
+ * properties, elements, and methods. Dynalink supports specifying composite
+ * operations for this purpose using the VERTICAL LINE character as the
+ * separator. Typical syntax would be e.g.
+ * {@code "dyn:getProp|getElem|getMethod:color"}. Any combination of
+ * {@code "getProp"}, {@code "getElem"}, and {@code "getMethod"} in any order can be
+ * specified. The semantics of this is "return the first matching member, trying
+ * them in the specified order". Similarly, {@code "setProp"} and {@code "setElem"}
+ * can be combined too in both orders. Only compositions consisting of getter
+ * operations only and setter operations only are allowed. They can either have
+ * an identifier encoded in the name or not.
+ * <p>
+ * Even if the language itself doesn't distinguish some of the namespaces, it
+ * can be helpful to map different syntaxes to different compositions. E.g.
+ * source expression {@code obj.color} could map to
+ * {@code "dyn:getProp|getElem|getMethod:color"}, but a different source
+ * expression that looks like collection element access {@code obj[key]} could
+ * be expressed instead as {@code "dyn:getElem|getProp|getMethod"}. Finally, if
+ * the retrieved value is subsequently called, then it makes sense to bring
+ * {@code getMethod} to the front of the list: the getter part of the source
+ * expression {@code obj.color()} should be
+ * {@code "dyn:getMethod|getProp|getElem:color"} and the one for
+ * {@code obj[key]()} should be {@code "dyn:getMethod|getElem|getProp"}.
+ * <h2>Language-specific linkers</h2>
+ * Languages that define their own object model different than the JVM
+ * class-based model and/or use their own type conversions will need to create
+ * their own language-specific linkers. See the {@link jdk.internal.dynalink.linker}
+ * package and specifically the {@link jdk.internal.dynalink.linker.GuardingDynamicLinker}
+ * interface to get started.
+ * <h2>Dynalink and Java objects</h2>
+ * The {@code DynamicLinker} objects created by {@code DynamicLinkerFactory} by
+ * default contain an internal instance of
+ * {@code BeansLinker}, which is a language-specific linker
+ * that implements the usual Java semantics for all of the above operations and
+ * can link any Java object that no other language-specific linker has managed
+ * to link. This way, all language runtimes have built-in interoperability with
+ * ordinary Java objects. See {@link jdk.internal.dynalink.beans.BeansLinker} for details
+ * on how it links the various operations.
+ * <h2>Cross-language interoperability</h2>
+ * A {@code DynamicLinkerFactory} can be configured with a
+ * {@link jdk.internal.dynalink.DynamicLinkerFactory#setClassLoader(ClassLoader) class
+ * loader}. It will try to instantiate all linker classes declared in
+ * {@code META-INF/services/jdk.internal.dynalink.linker.GuardingDynamicLinker} resources
+ * visible to that class loader and compose them into the {@code DynamicLinker}
+ * it creates. This allows for interoperability between languages because if you
+ * have two language runtimes A and B deployed in your JVM and they expose their
+ * linkers through the above mechanism, language runtime A will have a
+ * language-specific linker instance from B and vice versa inside their
+ * {@code DynamicLinker} objects. This means that if an object from language
+ * runtime B gets passed to code from language runtime A, the linker from B will
+ * get a chance to link the call site in A when it encounters the object from B.
  * @since 1.9
  */
 @jdk.Exported
--- a/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/support/NameCodec.java	Tue Oct 20 23:33:39 2015 +0200
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/support/NameCodec.java	Tue Oct 20 23:34:16 2015 +0200
@@ -105,7 +105,7 @@
  * ensure that you mangle the names using {@link #encode(String)} when you're
  * emitting them in the bytecode.
  */
-public class NameCodec {
+public final class NameCodec {
     private static final char ESCAPE_CHAR = '\\';
     private static final char EMPTY_ESCAPE = '=';
     private static final String EMPTY_NAME = new String(new char[] { ESCAPE_CHAR, EMPTY_ESCAPE });