8172183: Provide a javadoc description for jdk.dynalink module

Reviewed-by: attila, jlaskey
This commit is contained in:
Athijegannathan Sundararajan 2017-01-03 22:14:41 +05:30
parent f8ccef1982
commit fe1956e041
4 changed files with 202 additions and 222 deletions
nashorn
READMERELEASE_README
src/jdk.dynalink/share/classes

@ -24,33 +24,33 @@ and downlaoded using
You can clone Nashorn Mercurial forest using this command:
hg fclone http://hg.openjdk.java.net/nashorn/jdk8 nashorn~jdk8
hg fclone http://hg.openjdk.java.net/nashorn/jdk9 nashorn~jdk9
To update your copy of the forest (fwith the latest code:
(cd nashorn~jdk8 ; hg fpull)
(cd nashorn~jdk9 ; hg fpull)
Or just the nashorn subdirectory with
(cd nashorn~jdk8/nashorn ; hg pull -u)
(cd nashorn~jdk9/nashorn ; hg pull -u)
To learn about Mercurial in detail, please visit http://hgbook.red-bean.com.
- How to build?
To build Nashorn, you need to install JDK 8. You may use the Nashorn
To build Nashorn, you need to install JDK 9. You may use the Nashorn
forest build (recommended) or down load from java.net. You will need to
set JAVA_HOME environmental variable to point to your JDK installation
directory.
cd nashorn~jdk8/nashorn/make
cd nashorn~jdk9/nashorn/make
ant clean; ant
- How to run?
Use the jjs script (see RELESE_README):
cd nashorn~jdk8/nashorn
cd nashorn~jdk9/nashorn
sh bin/jjs <your .js file>
Nashorn supports javax.script API. It is possible to drop nashorn.jar in
@ -64,7 +64,7 @@ Look for samples under the directory test/src/jdk/nashorn/api/scripting/.
Comprehensive development documentation is found in the Nashorn JavaDoc. You can
build it using:
cd nashorn~jdk8/nashorn/make
cd nashorn~jdk9/nashorn/make
ant javadoc
after which you can view the generated documentation at dist/javadoc/index.html.
@ -90,7 +90,7 @@ Alternatively, you can check it out elsewhere and make
test/script/external/test262 a symbolic link to that directory. After
you've done this, you can run the ECMA-262 tests using:
cd nashorn~jdk8/nashorn/make
cd nashorn~jdk9/nashorn/make
ant test262
Ant target to get/update external test suites:
@ -101,7 +101,7 @@ Ant target to get/update external test suites:
These tests take time, so we have a parallelized runner for them that
takes advantage of all processor cores on the computer:
cd nashorn~jdk8/nashorn/make
cd nashorn~jdk9/nashorn/make
ant test262parallel
- How to write your own test?

@ -1,20 +0,0 @@
The Nashorn repo is in the process of being migrated to OpenJDK and as such is
incomplete in several areas.
- The build system is not fully integrated. When complete, Nashorn will be
installed in its proper location in the JRE.
- Once integrated, the correct version of the JDK will be wrapped around
Nashorn. In the meantime, ensure you use JDK8 b68 or later.
- The jjs tool has not been implemented in binary form yet. Use "sh bin/jjs"
(or bin/jjs.bat on windows) in the interm.
- The Dynalink component is not fully integrated into Nashorn as yet, but will
be when details are finalized.
- And, finally Nashorn is still in development. To stay up to date, subscribe
to nashorn-dev@openjdk.java.net at
http://mail.openjdk.java.net/mailman/listinfo/nashorn-dev.

@ -82,197 +82,6 @@
*/
/**
* <p>
* Dynalink is a library for dynamic linking of 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>
*
* 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 "GET:PROPERTY: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.dynalink.*;
* import jdk.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 CallSiteDescriptor(lookup, parseOperation(name), type)));
* }
*
* private static Operation parseOperation(String name) {
* ...
* }
* }
* </pre>
* There are several objects of significance in the above code snippet:
* <ul>
* <li>{@link jdk.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.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.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.dynalink.support.SimpleRelinkableCallSite} and
* {@link jdk.dynalink.support.ChainedCallSite} (not used in the above example)
* are two implementations already provided by the library.</li>
* <li>Dynalink uses {@link jdk.dynalink.CallSiteDescriptor} objects to
* preserve the parameters to the bootstrap method: the lookup and the method type,
* as it will need them whenever it needs to relink a call site.</li>
* <li>Dynalink uses {@link jdk.dynalink.Operation} objects to express
* dynamic operations. It does not prescribe how would you encode the operations
* in your call site, though. That is why in the above example the
* {@code parseOperation} function is left empty, and you would be expected to
* provide the code to parse the string {@code "GET:PROPERTY:color"}
* in the call site's name into a named property getter operation object as
* {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY).named("color")}.
* </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.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>
* Dynalink defines several standard operations in its
* {@link jdk.dynalink.StandardOperation} class. The linker for Java
* objects can link all of these operations, and you are encouraged to at
* minimum support and use these operations in your language too. The
* standard operations {@code GET} and {@code SET} need to be combined with
* at least one {@link jdk.dynalink.Namespace} to be useful, e.g. to express a
* property getter, you'd use {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY)}.
* Dynalink defines three standard namespaces in the {@link jdk.dynalink.StandardNamespace} class.
* To associate a fixed name with an operation, you can use
* {@link jdk.dynalink.NamedOperation} as in the previous example:
* {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY).named("color")}
* expresses a getter for the property named "color".
* <h2>Operations on multiple namespaces</h2>
* Some languages might not have separate namespaces on objects for
* properties, elements, and methods, and a source language construct might
* address several of them at once. Dynalink supports specifying multiple
* {@link jdk.dynalink.Namespace} objects with {@link jdk.dynalink.NamespaceOperation}.
* <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.dynalink.linker}
* package and specifically the {@link jdk.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.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.dynalink.DynamicLinkerFactory#setClassLoader(ClassLoader) class
* loader}. It will try to instantiate all
* {@link jdk.dynalink.linker.GuardingDynamicLinkerExporter} classes visible to
* that class loader and compose the linkers they provide into the
* {@code DynamicLinker} it creates. This allows for interoperability between
* languages: if you have two language runtimes A and B deployed in your JVM and
* they export 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.
* Contains interfaces and classes that are used to link an {@code invokedynamic} call site.
*/
package jdk.dynalink;

@ -24,7 +24,198 @@
*/
/**
* Dynalink
* <p>
* Dynalink is a library for dynamic linking of 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>
*
* 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 "GET:PROPERTY: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.dynalink.*;
* import jdk.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 CallSiteDescriptor(lookup, parseOperation(name), type)));
* }
*
* private static Operation parseOperation(String name) {
* ...
* }
* }
* </pre>
* There are several objects of significance in the above code snippet:
* <ul>
* <li>{@link jdk.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.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.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.dynalink.support.SimpleRelinkableCallSite} and
* {@link jdk.dynalink.support.ChainedCallSite} (not used in the above example)
* are two implementations already provided by the library.</li>
* <li>Dynalink uses {@link jdk.dynalink.CallSiteDescriptor} objects to
* preserve the parameters to the bootstrap method: the lookup and the method type,
* as it will need them whenever it needs to relink a call site.</li>
* <li>Dynalink uses {@link jdk.dynalink.Operation} objects to express
* dynamic operations. It does not prescribe how would you encode the operations
* in your call site, though. That is why in the above example the
* {@code parseOperation} function is left empty, and you would be expected to
* provide the code to parse the string {@code "GET:PROPERTY:color"}
* in the call site's name into a named property getter operation object as
* {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY).named("color")}.
* </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.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>
* Dynalink defines several standard operations in its
* {@link jdk.dynalink.StandardOperation} class. The linker for Java
* objects can link all of these operations, and you are encouraged to at
* minimum support and use these operations in your language too. The
* standard operations {@code GET} and {@code SET} need to be combined with
* at least one {@link jdk.dynalink.Namespace} to be useful, e.g. to express a
* property getter, you'd use {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY)}.
* Dynalink defines three standard namespaces in the {@link jdk.dynalink.StandardNamespace} class.
* To associate a fixed name with an operation, you can use
* {@link jdk.dynalink.NamedOperation} as in the previous example:
* {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY).named("color")}
* expresses a getter for the property named "color".
* <h2>Operations on multiple namespaces</h2>
* Some languages might not have separate namespaces on objects for
* properties, elements, and methods, and a source language construct might
* address several of them at once. Dynalink supports specifying multiple
* {@link jdk.dynalink.Namespace} objects with {@link jdk.dynalink.NamespaceOperation}.
* <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.dynalink.linker}
* package and specifically the {@link jdk.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.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.dynalink.DynamicLinkerFactory#setClassLoader(ClassLoader) class
* loader}. It will try to instantiate all
* {@link jdk.dynalink.linker.GuardingDynamicLinkerExporter} classes visible to
* that class loader and compose the linkers they provide into the
* {@code DynamicLinker} it creates. This allows for interoperability between
* languages: if you have two language runtimes A and B deployed in your JVM and
* they export 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.
*/
module jdk.dynalink {
requires java.logging;