1 /* |
|
2 * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. |
|
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
4 * |
|
5 * This code is free software; you can redistribute it and/or modify it |
|
6 * under the terms of the GNU General Public License version 2 only, as |
|
7 * published by the Free Software Foundation. Oracle designates this |
|
8 * particular file as subject to the "Classpath" exception as provided |
|
9 * by Oracle in the LICENSE file that accompanied this code. |
|
10 * |
|
11 * This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 * version 2 for more details (a copy is included in the LICENSE file that |
|
15 * accompanied this code). |
|
16 * |
|
17 * You should have received a copy of the GNU General Public License version |
|
18 * 2 along with this work; if not, write to the Free Software Foundation, |
|
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 * |
|
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
22 * or visit www.oracle.com if you need additional information or have any |
|
23 * questions. |
|
24 */ |
|
25 |
|
26 /* |
|
27 * This file is available under and governed by the GNU General Public |
|
28 * License version 2 only, as published by the Free Software Foundation. |
|
29 * However, the following notice accompanied the original version of this |
|
30 * file, and Oracle licenses the original version of this file under the BSD |
|
31 * license: |
|
32 */ |
|
33 /* |
|
34 Copyright 2009-2013 Attila Szegedi |
|
35 |
|
36 Licensed under both the Apache License, Version 2.0 (the "Apache License") |
|
37 and the BSD License (the "BSD License"), with licensee being free to |
|
38 choose either of the two at their discretion. |
|
39 |
|
40 You may not use this file except in compliance with either the Apache |
|
41 License or the BSD License. |
|
42 |
|
43 If you choose to use this file in compliance with the Apache License, the |
|
44 following notice applies to you: |
|
45 |
|
46 You may obtain a copy of the Apache License at |
|
47 |
|
48 http://www.apache.org/licenses/LICENSE-2.0 |
|
49 |
|
50 Unless required by applicable law or agreed to in writing, software |
|
51 distributed under the License is distributed on an "AS IS" BASIS, |
|
52 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or |
|
53 implied. See the License for the specific language governing |
|
54 permissions and limitations under the License. |
|
55 |
|
56 If you choose to use this file in compliance with the BSD License, the |
|
57 following notice applies to you: |
|
58 |
|
59 Redistribution and use in source and binary forms, with or without |
|
60 modification, are permitted provided that the following conditions are |
|
61 met: |
|
62 * Redistributions of source code must retain the above copyright |
|
63 notice, this list of conditions and the following disclaimer. |
|
64 * Redistributions in binary form must reproduce the above copyright |
|
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 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.internal.dynalink.*; |
|
140 * import jdk.internal.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.internal.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.internal.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.internal.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.internal.dynalink.support.SimpleRelinkableCallSite} and |
|
169 * {@link jdk.internal.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.internal.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.internal.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 new NamedOperation(StandardOperation.GET_PROPERTY), "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.internal.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.internal.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. To associate |
|
235 * a fixed name with an operation, you can use |
|
236 * {@link jdk.internal.dynalink.NamedOperation} as in the above example where |
|
237 * {@code StandardOperation.GET_PROPERTY} was combined with the name |
|
238 * {@code "color"} in a {@code NamedOperation} to form a property getter for the |
|
239 * property named "color". |
|
240 * <h2>Composite operations</h2> |
|
241 * Some languages might not have separate namespaces on objects for |
|
242 * properties, elements, and methods, and a source language construct might |
|
243 * address two or three of them. Dynalink supports specifying composite |
|
244 * operations for this purpose using the |
|
245 * {@link jdk.internal.dynalink.CompositeOperation} class. |
|
246 * <h2>Language-specific linkers</h2> |
|
247 * Languages that define their own object model different than the JVM |
|
248 * class-based model and/or use their own type conversions will need to create |
|
249 * their own language-specific linkers. See the {@link jdk.internal.dynalink.linker} |
|
250 * package and specifically the {@link jdk.internal.dynalink.linker.GuardingDynamicLinker} |
|
251 * interface to get started. |
|
252 * <h2>Dynalink and Java objects</h2> |
|
253 * The {@code DynamicLinker} objects created by {@code DynamicLinkerFactory} by |
|
254 * default contain an internal instance of |
|
255 * {@code BeansLinker}, which is a language-specific linker |
|
256 * that implements the usual Java semantics for all of the above operations and |
|
257 * can link any Java object that no other language-specific linker has managed |
|
258 * to link. This way, all language runtimes have built-in interoperability with |
|
259 * ordinary Java objects. See {@link jdk.internal.dynalink.beans.BeansLinker} for details |
|
260 * on how it links the various operations. |
|
261 * <h2>Cross-language interoperability</h2> |
|
262 * A {@code DynamicLinkerFactory} can be configured with a |
|
263 * {@link jdk.internal.dynalink.DynamicLinkerFactory#setClassLoader(ClassLoader) class |
|
264 * loader}. It will try to instantiate all |
|
265 * {@link jdk.internal.dynalink.linker.GuardingDynamicLinkerExporter} classes visible to |
|
266 * that class loader and compose the linkers they provide into the |
|
267 * {@code DynamicLinker} it creates. This allows for interoperability between |
|
268 * languages: if you have two language runtimes A and B deployed in your JVM and |
|
269 * they export their linkers through the above mechanism, language runtime A |
|
270 * will have a language-specific linker instance from B and vice versa inside |
|
271 * their {@code DynamicLinker} objects. This means that if an object from |
|
272 * language runtime B gets passed to code from language runtime A, the linker |
|
273 * from B will get a chance to link the call site in A when it encounters the |
|
274 * object from B. |
|
275 */ |
|
276 @jdk.Exported |
|
277 package jdk.internal.dynalink; |
|