--- a/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/CallSiteDescriptor.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinker.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/DynamicLinkerFactory.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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.
+ *
+ * @param prioritizedLinker the single prioritized linker. Must not be null.
+ * @throws NullPointerException if null is passed.
+ */
+ public void setPrioritizedLinker(final GuardingDynamicLinker prioritizedLinker) {
+ this.prioritizedLinkers = Collections.singletonList(Objects.requireNonNull(prioritizedLinker));
}
/**
- * Sets a single prioritized linker. Identical to calling {@link #setPrioritizedLinkers(List)} with a single-element
- * list.
+ * 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 prioritizedLinker the single prioritized linker. Must not be null.
- * @throws IllegalArgumentException if null is passed.
+ * @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 setPrioritizedLinker(final GuardingDynamicLinker prioritizedLinker) {
- if(prioritizedLinker == null) {
- throw new IllegalArgumentException("prioritizedLinker == null");
- }
- this.prioritizedLinkers = Collections.singletonList(prioritizedLinker);
+ public void setFallbackLinkers(final List<? extends GuardingDynamicLinker> 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.
+ * @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 List<? extends GuardingDynamicLinker> fallbackLinkers) {
- this.fallbackLinkers = fallbackLinkers == null ? null : new ArrayList<>(fallbackLinkers);
+ public void setFallbackLinkers(final GuardingDynamicLinker... fallbackLinkers) {
+ setFallbackLinkers(fallbackLinkers == null ? null : Arrays.asList(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.
- *
- * @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.
- */
- public void setFallbackLinkers(final GuardingDynamicLinker... fallbackLinkers) {
- setFallbackLinkers(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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/BeansLinker.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/OverloadedMethod.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/beans/StaticClass.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/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/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardedInvocationTransformer.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardingDynamicLinker.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/GuardingTypeConverterFactory.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/LinkRequest.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/LinkerServices.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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 – if any
+ * – 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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/MethodHandleTransformer.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/MethodTypeConversionStrategy.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/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/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/CompositeTypeBasedGuardingDynamicLinker.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/DefaultInternalObjectFilter.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/Guards.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/Lookup.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/linker/support/SimpleLinkRequest.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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/nashorn/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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/package-info.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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>
+ * 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>
+ * Dynalink is closely related to, and relies on, the {@link java.lang.invoke}
+ * package.
* <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>
+ *
+ * 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>
+ * <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, 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, 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, any, 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, 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, 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, any, 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, 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[, any, 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[, any, 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[, any, 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>
- * Languages that wish to define and use their own linkers will also need to
- * use the {@link jdk.internal.dynalink.linker} package.
- * </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/nashorn/src/jdk.scripting.nashorn/share/classes/jdk/internal/dynalink/support/NameCodec.java Tue Oct 20 23:33:39 2015 +0200
+++ b/nashorn/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 });