--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/BeansLinker.java Mon Oct 19 08:39:06 2015 +0200
+++ b/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/BeansLinker.java Mon Oct 19 08:45:29 2015 +0200
@@ -83,7 +83,7 @@
package jdk.internal.dynalink.beans;
-import java.lang.invoke.MethodHandles;
+import java.lang.invoke.MethodHandles.Lookup;
import java.util.Collection;
import java.util.Collections;
import jdk.internal.dynalink.CallSiteDescriptor;
@@ -95,36 +95,59 @@
import jdk.internal.dynalink.linker.TypeBasedGuardingDynamicLinker;
/**
- * A linker for POJOs. Normally used as the ultimate fallback linker by the {@link DynamicLinkerFactory} so it is given
- * the chance to link calls to all objects that no other language runtime recognizes. Specifically, this linker will:
+ * A linker for ordinary Java objects. Normally used as the ultimate fallback
+ * linker by the {@link DynamicLinkerFactory} so it is given the chance to link
+ * calls to all objects that no other linker recognized. Specifically, this
+ * linker will:
* <ul>
- * <li>expose all public methods of form {@code setXxx()}, {@code getXxx()}, and {@code isXxx()} as property setters and
- * getters for {@code dyn:setProp} and {@code dyn:getProp} operations;</li>
- * <li>expose all public methods for invocation through {@code dyn:callMethod} operation;</li>
- * <li>expose all public methods for retrieval for {@code dyn:getMethod} operation; the methods thus retrieved can then
- * be invoked using {@code dyn:call};</li>
- * <li>expose all public fields as properties, unless there are getters or setters for the properties of the same name;</li>
- * <li>expose {@code dyn:getLength}, {@code dyn:getElem} and {@code dyn:setElem} on native Java arrays, as well as
- * {@link java.util.List} and {@link java.util.Map} objects; ({@code dyn:getLength} works on any
+ * <li>expose all public methods of form {@code setXxx()}, {@code getXxx()},
+ * and {@code isXxx()} as property setters and getters for {@code dyn:setProp}
+ * and {@code dyn:getProp} operations;</li>
+ * <li>expose all public methods for invocation through {@code dyn:callMethod}
+ * operation;</li>
+ * <li>expose all public methods for retrieval for {@code dyn:getMethod}
+ * operation; the methods thus retrieved can then be invoked using
+ * {@code dyn:call};</li>
+ * <li>expose all public fields as properties, unless there are getters or
+ * setters for the properties of the same name;</li>
+ * <li>expose {@code dyn:getLength}, {@code dyn:getElem} and
+ * {@code dyn:setElem} on native Java arrays, as well as {@link java.util.List}
+ * and {@link java.util.Map} objects; ({@code dyn:getLength} works on any
* {@link java.util.Collection});</li>
* <li>expose a virtual property named {@code length} on Java arrays;</li>
- * <li>expose {@code dyn:new} on instances of {@link StaticClass} as calls to constructors, including those static class
- * objects that represent Java arrays (their constructors take a single {@code int} parameter representing the length of
- * the array to create);</li>
- * <li>expose static methods, fields, and properties of classes in a similar manner to how instance method, fields, and
- * properties are exposed, on {@link StaticClass} objects.</li>
- * <li>expose a virtual property named {@code static} on instances of {@link java.lang.Class} to access their
- * {@link StaticClass}.</li>
+ * <li>expose {@code dyn:new} on instances of {@link StaticClass} as calls to
+ * constructors, including those static class objects that represent Java arrays
+ * (their constructors take a single {@code int} parameter representing the
+ * length of the array to create);</li>
+ * <li>expose static methods, fields, and properties of classes in a similar
+ * manner to how instance method, fields, and properties are exposed, on
+ * {@link StaticClass} objects.</li>
+ * <li>expose a virtual property named {@code static} on instances of
+ * {@link java.lang.Class} to access their {@link StaticClass}.</li>
* </ul>
- * <p><strong>Overloaded method resolution</strong> is performed automatically for property setters, methods, and
- * constructors. Additionally, manual overloaded method selection is supported by having a call site specify a name for
- * a method that contains an explicit signature, i.e. {@code dyn:getMethod:parseInt(String,int)}. You can use
- * non-qualified class names in such signatures regardless of those classes' packages, they will match any class with
- * the same non-qualified name. You only have to use a fully qualified class name in case non-qualified class names
- * would cause selection ambiguity (that is extremely rare).</p>
- * <p><strong>Variable argument invocation</strong> is handled for both methods and constructors.</p>
- * <p>Currently, only public fields and methods are supported. Any Lookup objects passed in the
- * {@link LinkRequest}s are ignored and {@link MethodHandles#publicLookup()} is used instead.</p>
+ * <p><strong>Overloaded method resolution</strong> is performed automatically
+ * for property setters, methods, and constructors. Additionally, manual
+ * overloaded method selection is supported by having a call site specify a name
+ * for a method that contains an explicit signature, i.e.
+ * {@code dyn:getMethod:parseInt(String,int)}. You can use non-qualified class
+ * names in such signatures regardless of those classes' packages, they will
+ * match any class with the same non-qualified name. You only have to use a
+ * fully qualified class name in case non-qualified class names would cause
+ * selection ambiguity (that is extremely rare). Overloaded resolution for
+ * constructors is not automatic as there is no logical place to attach that
+ * functionality to but if a language wishes to provide this functionality, it
+ * can use {@link #getConstructorMethod(Class, String)} as a useful building
+ * block for it.</p>
+ * <p><strong>Variable argument invocation</strong> is handled for both methods
+ * and constructors.</p>
+ * <p><strong>Caller sensitive methods</strong> can be linked as long as they
+ * are otherwise public and link requests have call site descriptors carrying
+ * full-strength {@link Lookup} objects and not weakened lookups or the public
+ * lookup.</p>
+ * <p>The class also exposes various static methods for discovery of available
+ * property and method names on classes and class instances, as well as access
+ * to per-class linkers using the {@link #getLinkerForClass(Class)}
+ * method.</p>
*/
public class BeansLinker implements GuardingDynamicLinker {
private static final ClassValue<TypeBasedGuardingDynamicLinker> linkers = new ClassValue<TypeBasedGuardingDynamicLinker>() {
@@ -140,15 +163,16 @@
};
/**
- * Creates a new POJO linker.
+ * Creates a new beans linker.
*/
public BeansLinker() {
}
/**
- * Returns a bean linker for a particular single class. Useful when you need to override or extend the behavior of
- * linking for some classes in your language runtime's linker, but still want to delegate to the default behavior in
- * some cases.
+ * Returns a bean linker for a particular single class. Useful when you need
+ * to override or extend the behavior of linking for some classes in your
+ * language runtime's linker, but still want to delegate to the default
+ * behavior in some cases.
* @param clazz the class
* @return a bean linker for that class
*/
@@ -157,9 +181,12 @@
}
/**
- * Returns true if the object is a Dynalink Java dynamic method.
+ * Returns true if the object is a Java dynamic method (e.g., one
+ * obtained through a {@code dyn:getMethod} call on a Java object or
+ * {@link StaticClass} or through
+ * {@link #getConstructorMethod(Class, String)}.
*
- * @param obj the object we want to test for being a dynamic method
+ * @param obj the object we want to test for being a Java dynamic method.
* @return true if it is a dynamic method, false otherwise.
*/
public static boolean isDynamicMethod(final Object obj) {
@@ -167,9 +194,10 @@
}
/**
- * Returns true if the object is a Dynalink Java constructor.
+ * Returns true if the object is a Java constructor (obtained through
+ * {@link #getConstructorMethod(Class, String)}}.
*
- * @param obj the object we want to test for being a constructor
+ * @param obj the object we want to test for being a Java constructor.
* @return true if it is a constructor, false otherwise.
*/
public static boolean isDynamicConstructor(final Object obj) {
@@ -177,10 +205,15 @@
}
/**
- * Return the dynamic method of constructor of the given class and the given signature.
+ * Return the dynamic method of constructor of the given class and the given
+ * signature. This method is useful for exposing a functionality for
+ * 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.
* @param clazz the class
* @param signature full signature of the constructor
- * @return DynamicMethod for the constructor
+ * @return dynamic method for the constructor
*/
public static Object getConstructorMethod(final Class<?> clazz, final String signature) {
return StaticClassLinker.getConstructorMethod(clazz, signature);