author | jrose |
Fri, 30 Apr 2010 23:48:23 -0700 | |
changeset 5722 | 4ada807383c8 |
parent 4537 | 7c3c7f8d5195 |
child 5725 | 16c1792b2ee6 |
permissions | -rw-r--r-- |
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
1 |
/* |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
2 |
* Copyright 2008-2009 Sun Microsystems, Inc. All Rights Reserved. |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
4 |
* |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
5 |
* This code is free software; you can redistribute it and/or modify it |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
7 |
* published by the Free Software Foundation. Sun designates this |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
8 |
* particular file as subject to the "Classpath" exception as provided |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
9 |
* by Sun in the LICENSE file that accompanied this code. |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
10 |
* |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
15 |
* accompanied this code). |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
16 |
* |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
17 |
* You should have received a copy of the GNU General Public License version |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
20 |
* |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
21 |
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
22 |
* CA 95054 USA or visit www.sun.com if you need additional information or |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
23 |
* have any questions. |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
24 |
*/ |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
25 |
|
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
26 |
package java.dyn; |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
27 |
|
4537 | 28 |
import sun.dyn.Access; |
29 |
||
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
30 |
/** |
5722
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
31 |
* A Java method handle is a deprecated proposal for extending |
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
32 |
* the basic method handle type with additional |
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
33 |
* programmer defined methods and fields. |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
34 |
* Its behavior as a method handle is determined at instance creation time, |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
35 |
* by providing the new instance with an "entry point" method handle |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
36 |
* to handle calls. This entry point must accept a leading argument |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
37 |
* whose type is the Java method handle itself or a supertype, and the |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
38 |
* entry point is always called with the Java method handle itself as |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
39 |
* the first argument. This is similar to ordinary virtual methods, which also |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
40 |
* accept the receiver object {@code this} as an implicit leading argument. |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
41 |
* The {@code MethodType} of the Java method handle is the same as that |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
42 |
* of the entry point method handle, with the leading parameter type |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
43 |
* omitted. |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
44 |
* <p> |
4537 | 45 |
* Here is an example of usage, creating a hybrid object/functional datum: |
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
46 |
* <p><blockquote><pre> |
4537 | 47 |
* class Greeter extends JavaMethodHandle { |
48 |
* private String greeting = "hello"; |
|
49 |
* public void setGreeting(String s) { greeting = s; } |
|
50 |
* public void run() { System.out.println(greeting+", "+greetee); } |
|
51 |
* private final String greetee; |
|
52 |
* Greeter(String greetee) { |
|
53 |
* super(RUN); // alternatively, super("run") |
|
54 |
* this.greetee = greetee; |
|
55 |
* } |
|
56 |
* // the entry point function is computed once: |
|
57 |
* private static final MethodHandle RUN |
|
58 |
* = MethodHandles.lookup().findVirtual(Greeter.class, "run", |
|
59 |
* MethodType.make(void.class)); |
|
60 |
* } |
|
61 |
* // class Main { public static void main(String... av) { ... |
|
62 |
* Greeter greeter = new Greeter("world"); |
|
63 |
* greeter.run(); // prints "hello, world" |
|
64 |
* // Statically typed method handle invocation (most direct): |
|
65 |
* MethodHandle mh = greeter; |
|
5722
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
66 |
* mh.<void>invokeExact(); // also prints "hello, world" |
4537 | 67 |
* // Dynamically typed method handle invocation: |
5722
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
68 |
* MethodHandles.invokeExact(greeter); // also prints "hello, world" |
4537 | 69 |
* greeter.setGreeting("howdy"); |
5722
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
70 |
* mh.invokeExact(); // prints "howdy, world" (object-like mutable behavior) |
4537 | 71 |
* </pre></blockquote> |
72 |
* <p> |
|
73 |
* In the example of {@code Greeter}, the method {@code run} provides the entry point. |
|
74 |
* The entry point need not be a constant value; it may be independently |
|
75 |
* computed in each call to the constructor. The entry point does not |
|
76 |
* even need to be a method on the {@code Greeter} class, though |
|
77 |
* that is the typical case. |
|
78 |
* <p> |
|
79 |
* The entry point may also be provided symbolically, in which case the the |
|
80 |
* {@code JavaMethodHandle} constructor performs the lookup of the entry point. |
|
81 |
* This makes it possible to use {@code JavaMethodHandle} to create an anonymous |
|
82 |
* inner class: |
|
83 |
* <p><blockquote><pre> |
|
84 |
* // We can also do this with symbolic names and/or inner classes: |
|
5722
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
85 |
* MethodHandles.invokeExact(new JavaMethodHandle("yow") { |
4537 | 86 |
* void yow() { System.out.println("yow, world"); } |
87 |
* }); |
|
88 |
* </pre></blockquote> |
|
89 |
* <p> |
|
90 |
* Here is similar lower-level code which works in terms of a bound method handle. |
|
91 |
* <p><blockquote><pre> |
|
92 |
* class Greeter { |
|
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
93 |
* public void run() { System.out.println("hello, "+greetee); } |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
94 |
* private final String greetee; |
4537 | 95 |
* Greeter(String greetee) { this.greetee = greetee; } |
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
96 |
* // the entry point function is computed once: |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
97 |
* private static final MethodHandle RUN |
4537 | 98 |
* = MethodHandles.findVirtual(Greeter.class, "run", |
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
99 |
* MethodType.make(void.class)); |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
100 |
* } |
4537 | 101 |
* // class Main { public static void main(String... av) { ... |
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
102 |
* Greeter greeter = new Greeter("world"); |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
103 |
* greeter.run(); // prints "hello, world" |
4537 | 104 |
* MethodHandle mh = MethodHanndles.insertArgument(Greeter.RUN, 0, greeter); |
5722
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
105 |
* mh.invokeExact(); // also prints "hello, world" |
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
106 |
* </pre></blockquote> |
4537 | 107 |
* Note that the method handle must be separately created as a view on the base object. |
108 |
* This increases footprint, complexity, and dynamic indirections. |
|
109 |
* <p> |
|
110 |
* Here is a pure functional value expressed most concisely as an anonymous inner class: |
|
111 |
* <p><blockquote><pre> |
|
112 |
* // class Main { public static void main(String... av) { ... |
|
113 |
* final String greetee = "world"; |
|
114 |
* MethodHandle greeter = new JavaMethodHandle("run") { |
|
115 |
* private void run() { System.out.println("hello, "+greetee); } |
|
116 |
* } |
|
5722
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
117 |
* greeter.invokeExact(); // prints "hello, world" |
4537 | 118 |
* </pre></blockquote> |
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
119 |
* <p> |
4537 | 120 |
* Here is an abstract parameterized lvalue, efficiently expressed as a subtype of MethodHandle, |
121 |
* and instantiated as an anonymous class. The data structure is a handle to 1-D array, |
|
122 |
* with a specialized index type (long). It is created by inner class, and uses |
|
123 |
* signature-polymorphic APIs throughout. |
|
124 |
* <p><blockquote><pre> |
|
125 |
* abstract class AssignableMethodHandle extends JavaMethodHandle { |
|
126 |
* private final MethodHandle setter; |
|
127 |
* public MethodHandle setter() { return setter; } |
|
128 |
* public AssignableMethodHandle(String get, String set) { |
|
129 |
* super(get); |
|
130 |
* MethodType getType = this.type(); |
|
131 |
* MethodType setType = getType.insertParameterType(getType.parameterCount(), getType.returnType()).changeReturnType(void.class); |
|
132 |
* this.setter = MethodHandles.publicLookup().bind(this, set, setType); |
|
133 |
* } |
|
134 |
* } |
|
135 |
* // class Main { public static void main(String... av) { ... |
|
136 |
* final Number[] stuff = { 123, 456 }; |
|
137 |
* AssignableMethodHandle stuffPtr = new AssignableMethodHandle("get", "set") { |
|
138 |
* public Number get(long i) { return stuff[(int)i]; } |
|
139 |
* public void set(long i, Object x) { stuff[(int)i] = x; } |
|
140 |
* } |
|
5722
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
141 |
* int x = (Integer) stuffPtr.<Number>invokeExact(1L); // 456 |
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
142 |
* stuffPtr.setter().<void>invokeExact(0L, (Number) 789); // replaces 123 with 789 |
4537 | 143 |
* </pre></blockquote> |
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
144 |
* @see MethodHandle |
5722
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
145 |
* @deprecated The JSR 292 EG intends to replace {@code JavaMethodHandle} with |
4ada807383c8
6939134: JSR 292 adjustments to method handle invocation
jrose
parents:
4537
diff
changeset
|
146 |
* an interface-based API for mixing method handle behavior with other classes. |
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
147 |
* @author John Rose, JSR 292 EG |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
148 |
*/ |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
149 |
public abstract class JavaMethodHandle |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
150 |
// Note: This is an implementation inheritance hack, and will be removed |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
151 |
// with a JVM change which moves the required hidden behavior onto this class. |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
152 |
extends sun.dyn.BoundMethodHandle |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
153 |
{ |
4537 | 154 |
private static final Access IMPL_TOKEN = Access.getToken(); |
155 |
||
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
156 |
/** |
4537 | 157 |
* When creating a {@code JavaMethodHandle}, the actual method handle |
158 |
* invocation behavior will be delegated to the specified {@code entryPoint}. |
|
159 |
* This may be any method handle which can take the newly constructed object |
|
160 |
* as a leading parameter. |
|
161 |
* <p> |
|
162 |
* The method handle type of {@code this} (i.e, the fully constructed object) |
|
163 |
* will be {@code entryPoint}, minus the leading argument. |
|
164 |
* The leading argument will be bound to {@code this} on every method |
|
165 |
* handle invocation. |
|
166 |
* @param entryPoint the method handle to handle calls |
|
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
167 |
*/ |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
168 |
protected JavaMethodHandle(MethodHandle entryPoint) { |
4537 | 169 |
super(entryPoint); |
170 |
} |
|
171 |
||
172 |
/** |
|
173 |
* Create a method handle whose entry point is a non-static method |
|
174 |
* visible in the exact (most specific) class of |
|
175 |
* the newly constructed object. |
|
176 |
* <p> |
|
177 |
* The method is specified by name and type, as if via this expression: |
|
178 |
* {@code MethodHandles.lookup().findVirtual(this.getClass(), name, type)}. |
|
179 |
* The class defining the method might be an anonymous inner class. |
|
180 |
* <p> |
|
181 |
* The method handle type of {@code this} (i.e, the fully constructed object) |
|
182 |
* will be the given method handle type. |
|
183 |
* A call to {@code this} will invoke the selected method. |
|
184 |
* The receiver argument will be bound to {@code this} on every method |
|
185 |
* handle invocation. |
|
186 |
* <p> |
|
187 |
* <i>Rationale:</i> |
|
188 |
* Although this constructor may seem to be a mere luxury, |
|
189 |
* it is not subsumed by the more general constructor which |
|
190 |
* takes any {@code MethodHandle} as the entry point argument. |
|
191 |
* In order to convert an entry point name to a method handle, |
|
192 |
* the self-class of the object is required (in order to do |
|
193 |
* the lookup). The self-class, in turn, is generally not |
|
194 |
* available at the time of the constructor invocation, |
|
195 |
* due to the rules of Java and the JVM verifier. |
|
196 |
* One cannot call {@code this.getClass()}, because |
|
197 |
* the value of {@code this} is inaccessible at the point |
|
198 |
* of the constructor call. (Changing this would require |
|
199 |
* change to the Java language, verifiers, and compilers.) |
|
200 |
* In particular, this constructor allows {@code JavaMethodHandle}s |
|
201 |
* to be created in combination with the anonymous inner class syntax. |
|
202 |
* @param entryPointName the name of the entry point method |
|
203 |
* @param type (optional) the desired type of the method handle |
|
204 |
*/ |
|
205 |
protected JavaMethodHandle(String entryPointName, MethodType type) { |
|
206 |
super(entryPointName, type, true); |
|
207 |
||
208 |
} |
|
209 |
||
210 |
/** |
|
211 |
* Create a method handle whose entry point is a non-static method |
|
212 |
* visible in the exact (most specific) class of |
|
213 |
* the newly constructed object. |
|
214 |
* <p> |
|
215 |
* The method is specified only by name. |
|
216 |
* There must be exactly one method of that name visible in the object class, |
|
217 |
* either inherited or locally declared. |
|
218 |
* (That is, the method must not be overloaded.) |
|
219 |
* <p> |
|
220 |
* The method handle type of {@code this} (i.e, the fully constructed object) |
|
221 |
* will be the same as the type of the selected non-static method. |
|
222 |
* The receiver argument will be bound to {@code this} on every method |
|
223 |
* handle invocation. |
|
224 |
* <p>ISSUE: This signature wildcarding feature does not correspond to |
|
225 |
* any MethodHandles.Lookup API element. Can we eliminate it? |
|
226 |
* Alternatively, it is useful for naming non-overloaded methods. |
|
227 |
* Shall we make type arguments optional in the Lookup methods, |
|
228 |
* throwing an error in cases of ambiguity? |
|
229 |
* <p> |
|
230 |
* For this method's rationale, see the documentation |
|
231 |
* for {@link #JavaMethodHandle(String,MethodType)}. |
|
232 |
* @param entryPointName the name of the entry point method |
|
233 |
*/ |
|
234 |
protected JavaMethodHandle(String entryPointName) { |
|
235 |
super(entryPointName, (MethodType) null, false); |
|
2707
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
236 |
} |
5a17df307cbc
6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff
changeset
|
237 |
} |