65 notice, this list of conditions and the following disclaimer in the 66 documentation and/or other materials provided with the distribution. 67 * Neither the name of the copyright holder nor the names of 68 contributors may be used to endorse or promote products derived from 69 this software without specific prior written permission. 70 71 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 72 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 73 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 74 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER 75 BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 76 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 77 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 78 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 79 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 80 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 81 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 82 */ 83 84 /** 85 * <p> 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.*; | 65 notice, this list of conditions and the following disclaimer in the 66 documentation and/or other materials provided with the distribution. 67 * Neither the name of the copyright holder nor the names of 68 contributors may be used to endorse or promote products derived from 69 this software without specific prior written permission. 70 71 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 72 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 73 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 74 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER 75 BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 76 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 77 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 78 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 79 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 80 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 81 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 82 */ 83 84 /** 85 * Contains interfaces and classes that are used to link an {@code invokedynamic} call site. 86 * 87 * <h2>Example</h2> 88 * Dynalink is probably best explained by an example showing its use. Let's 89 * suppose you have a program in a language where you don't have to declare the 90 * type of an object and you want to access a property on it: 91 * <pre> 92 * var color = obj.color; 93 * </pre> 94 * If you generated a Java class to represent the above one-line program, its 95 * bytecode would look something like this: 96 * <pre> 97 * aload 2 // load "obj" on stack 98 * invokedynamic "GET:PROPERTY:color"(Object)Object // invoke property getter on object of unknown type 99 * astore 3 // store the return value into local variable "color" 100 * </pre> 101 * In order to link the {@code invokedynamic} instruction, we need a bootstrap 102 * method. A minimalist bootstrap method with Dynalink could look like this: 103 * <pre> 104 * import java.lang.invoke.*; 105 * import jdk.dynalink.*; 106 * import jdk.dynalink.support.*; |