85  * <p>

    85  * Contains interfaces and classes that are used to link an {@code invokedynamic} call site.

    86  * Dynalink is a library for dynamic linking of high-level operations on objects.

    87  * These operations include "read a property",

    88  * "write a property", "invoke a function" and so on. Dynalink is primarily

    89  * useful for implementing programming languages where at least some expressions

    90  * have dynamic types (that is, types that can not be decided statically), and

    91  * the operations on dynamic types are expressed as

    92  * {@link java.lang.invoke.CallSite call sites}. These call sites will be

    93  * linked to appropriate target {@link java.lang.invoke.MethodHandle method handles}

    94  * at run time based on actual types of the values the expressions evaluated to.

    95  * These can change between invocations, necessitating relinking the call site

    96  * multiple times to accommodate new types; Dynalink handles all that and more.

    97  * <p>

    98  * Dynalink supports implementation of programming languages with object models

    99  * that differ (even radically) from the JVM's class-based model and have their

   100  * custom type conversions.

   101  * <p>

   102  * Dynalink is closely related to, and relies on, the {@link java.lang.invoke}

   103  * package.

   104  * <p>

   105  *

   106  * While {@link java.lang.invoke} provides a low level API for dynamic linking

   107  * of {@code invokedynamic} call sites, it does not provide a way to express

   108  * higher level operations on objects, nor methods that implement them. These

   109  * operations are the usual ones in object-oriented environments: property

   110  * access, access of elements of collections, invocation of methods and

   111  * constructors (potentially with multiple dispatch, e.g. link- and run-time

   112  * equivalents of Java overloaded method resolution). These are all functions

   113  * that are normally desired in a language on the JVM. If a language is

   114  * statically typed and its type system matches that of the JVM, it can

   115  * accomplish this with use of the usual invocation, field access, etc.

   116  * instructions (e.g. {@code invokevirtual}, {@code getfield}). However, if the

   117  * language is dynamic (hence, types of some expressions are not known until

   118  * evaluated at run time), or its object model or type system don't match

   119  * closely that of the JVM, then it should use {@code invokedynamic} call sites

   120  * instead and let Dynalink manage them.

   121  * <h2>Example</h2>

   122  * Dynalink is probably best explained by an example showing its use. Let's

   123  * suppose you have a program in a language where you don't have to declare the

   124  * type of an object and you want to access a property on it:

   125  * <pre>

   126  * var color = obj.color;

   127  * </pre>

   128  * If you generated a Java class to represent the above one-line program, its

   129  * bytecode would look something like this:

   130  * <pre>

   131  * aload 2 // load "obj" on stack

   132  * invokedynamic "GET:PROPERTY:color"(Object)Object // invoke property getter on object of unknown type

   133  * astore 3 // store the return value into local variable "color"

   134  * </pre>

   135  * In order to link the {@code invokedynamic} instruction, we need a bootstrap

   136  * method. A minimalist bootstrap method with Dynalink could look like this:

   137  * <pre>

   138  * import java.lang.invoke.*;

   139  * import jdk.dynalink.*;

   140  * import jdk.dynalink.support.*;

   141  *

   142  * class MyLanguageRuntime {

   143  *     private static final DynamicLinker dynamicLinker = new DynamicLinkerFactory().createLinker();

   144  *

   145  *     public static CallSite bootstrap(MethodHandles.Lookup lookup, String name, MethodType type) {

   146  *         return dynamicLinker.link(

   147  *             new SimpleRelinkableCallSite(

   148  *                 new CallSiteDescriptor(lookup, parseOperation(name), type)));

   149  *     }

   150  *

   151  *     private static Operation parseOperation(String name) {

   152  *         ...

   153  *     }

   154  * }

   155  * </pre>

   156  * There are several objects of significance in the above code snippet:

   157  * <ul>

   158  * <li>{@link jdk.dynalink.DynamicLinker} is the main object in Dynalink, it

   159  * coordinates the linking of call sites to method handles that implement the

   160  * operations named in them. It is configured and created using a

   161  * {@link jdk.dynalink.DynamicLinkerFactory}.</li>

   162  * <li>When the bootstrap method is invoked, it needs to create a

   163  * {@link java.lang.invoke.CallSite} object. In Dynalink, these call sites need

   164  * to additionally implement the {@link jdk.dynalink.RelinkableCallSite}

   165  * interface. "Relinkable" here alludes to the fact that if the call site

   166  * encounters objects of different types at run time, its target will be changed

   167  * to a method handle that can perform the operation on the newly encountered

   168  * type. {@link jdk.dynalink.support.SimpleRelinkableCallSite} and

   169  * {@link jdk.dynalink.support.ChainedCallSite} (not used in the above example)

   170  * are two implementations already provided by the library.</li>

   171  * <li>Dynalink uses {@link jdk.dynalink.CallSiteDescriptor} objects to

   172  * preserve the parameters to the bootstrap method: the lookup and the method type,

   173  * as it will need them whenever it needs to relink a call site.</li>

   174  * <li>Dynalink uses {@link jdk.dynalink.Operation} objects to express

   175  * dynamic operations. It does not prescribe how would you encode the operations

   176  * in your call site, though. That is why in the above example the

   177  * {@code parseOperation} function is left empty, and you would be expected to

   178  * provide the code to parse the string {@code "GET:PROPERTY:color"}

   179  * in the call site's name into a named property getter operation object as

   180  * {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY).named("color")}.

   181  * </ul>

   182  * <p>What can you already do with the above setup? {@code DynamicLinkerFactory}

   183  * by default creates a {@code DynamicLinker} that can link Java objects with the

   184  * usual Java semantics. If you have these three simple classes:

   185  * <pre>

   186  * public class A {

   187  *     public String color;

   188  *     public A(String color) { this.color = color; }

   189  * }

   190  *

   191  * public class B {

   192  *     private String color;

   193  *     public B(String color) { this.color = color; }

   194  *     public String getColor() { return color; }

   195  * }

   196  *

   197  * public class C {

   198  *     private int color;

   199  *     public C(int color) { this.color = color; }

   200  *     public int getColor() { return color; }

   201  * }

   202  * </pre>

   203  * and you somehow create their instances and pass them to your call site in your

   204  * programming language:

   205  * <pre>

   206  * for each(var obj in [new A("red"), new B("green"), new C(0x0000ff)]) {

   207  *     print(obj.color);

   208  * }

   209  * </pre>

   210  * then on first invocation, Dynalink will link the {@code .color} getter

   211  * operation to a field getter for {@code A.color}, on second invocation it will

   212  * relink it to {@code B.getColor()} returning a {@code String}, and finally on

   213  * third invocation it will relink it to {@code C.getColor()} returning an {@code int}.

   214  * The {@code SimpleRelinkableCallSite} we used above only remembers the linkage

   215  * for the last encountered type (it implements what is known as a <i>monomorphic

   216  * inline cache</i>). Another already provided implementation,

   217  * {@link jdk.dynalink.support.ChainedCallSite} will remember linkages for

   218  * several different types (it is a <i>polymorphic inline cache</i>) and is

   219  * probably a better choice in serious applications.

   220  * <h2>Dynalink and bytecode creation</h2>

   221  * {@code CallSite} objects are usually created as part of bootstrapping

   222  * {@code invokedynamic} instructions in bytecode. Hence, Dynalink is typically

   223  * used as part of language runtimes that compile programs into Java

   224  * {@code .class} bytecode format. Dynalink does not address the aspects of

   225  * either creating bytecode classes or loading them into the JVM. That said,

   226  * Dynalink can also be used without bytecode compilation (e.g. in language

   227  * interpreters) by creating {@code CallSite} objects explicitly and associating

   228  * them with representations of dynamic operations in the interpreted program

   229  * (e.g. a typical representation would be some node objects in a syntax tree).

   230  * <h2>Available operations</h2>

   231  * Dynalink defines several standard operations in its

   232  * {@link jdk.dynalink.StandardOperation} class. The linker for Java

   233  * objects can link all of these operations, and you are encouraged to at

   234  * minimum support and use these operations in your language too. The

   235  * standard operations {@code GET} and {@code SET} need to be combined with

   236  * at least one {@link jdk.dynalink.Namespace} to be useful, e.g. to express a

   237  * property getter, you'd use {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY)}.

   238  * Dynalink defines three standard namespaces in the {@link jdk.dynalink.StandardNamespace} class.

   239  * To associate a fixed name with an operation, you can use

   240  * {@link jdk.dynalink.NamedOperation} as in the previous example:

   241  * {@code StandardOperation.GET.withNamespace(StandardNamespace.PROPERTY).named("color")}

   242  * expresses a getter for the property named "color".

   243  * <h2>Operations on multiple namespaces</h2>

   244  * Some languages might not have separate namespaces on objects for

   245  * properties, elements, and methods, and a source language construct might

   246  * address several of them at once. Dynalink supports specifying multiple

   247  * {@link jdk.dynalink.Namespace} objects with {@link jdk.dynalink.NamespaceOperation}.

   248  * <h2>Language-specific linkers</h2>

   249  * Languages that define their own object model different than the JVM

   250  * class-based model and/or use their own type conversions will need to create

   251  * their own language-specific linkers. See the {@link jdk.dynalink.linker}

   252  * package and specifically the {@link jdk.dynalink.linker.GuardingDynamicLinker}

   253  * interface to get started.

   254  * <h2>Dynalink and Java objects</h2>

   255  * The {@code DynamicLinker} objects created by {@code DynamicLinkerFactory} by

   256  * default contain an internal instance of

   257  * {@code BeansLinker}, which is a language-specific linker

   258  * that implements the usual Java semantics for all of the above operations and

   259  * can link any Java object that no other language-specific linker has managed

   260  * to link. This way, all language runtimes have built-in interoperability with

   261  * ordinary Java objects. See {@link jdk.dynalink.beans.BeansLinker} for details

   262  * on how it links the various operations.

   263  * <h2>Cross-language interoperability</h2>

   264  * A {@code DynamicLinkerFactory} can be configured with a

   265  * {@link jdk.dynalink.DynamicLinkerFactory#setClassLoader(ClassLoader) class

   266  * loader}. It will try to instantiate all

   267  * {@link jdk.dynalink.linker.GuardingDynamicLinkerExporter} classes visible to

   268  * that class loader and compose the linkers they provide into the

   269  * {@code DynamicLinker} it creates. This allows for interoperability between

   270  * languages: if you have two language runtimes A and B deployed in your JVM and

   271  * they export their linkers through the above mechanism, language runtime A

   272  * will have a language-specific linker instance from B and vice versa inside

   273  * their {@code DynamicLinker} objects. This means that if an object from

   274  * language runtime B gets passed to code from language runtime A, the linker

   275  * from B will get a chance to link the call site in A when it encounters the

   276  * object from B.