| /* |
| * Copyright (c) 2008, 2009, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package java.dyn; |
| |
| import sun.dyn.Access; |
| |
| /** |
| * A Java method handle extends the basic method handle type with additional |
| * programmer defined methods and fields. |
| * Its behavior as a method handle is determined at instance creation time, |
| * by providing the new instance with an "entry point" method handle |
| * to handle calls. This entry point must accept a leading argument |
| * whose type is the Java method handle itself or a supertype, and the |
| * entry point is always called with the Java method handle itself as |
| * the first argument. This is similar to ordinary virtual methods, which also |
| * accept the receiver object {@code this} as an implicit leading argument. |
| * The {@code MethodType} of the Java method handle is the same as that |
| * of the entry point method handle, with the leading parameter type |
| * omitted. |
| * <p> |
| * Here is an example of usage, creating a hybrid object/functional datum: |
| * <p><blockquote><pre> |
| * class Greeter extends JavaMethodHandle { |
| * private String greeting = "hello"; |
| * public void setGreeting(String s) { greeting = s; } |
| * public void run() { System.out.println(greeting+", "+greetee); } |
| * private final String greetee; |
| * Greeter(String greetee) { |
| * super(RUN); // alternatively, super("run") |
| * this.greetee = greetee; |
| * } |
| * // the entry point function is computed once: |
| * private static final MethodHandle RUN |
| * = MethodHandles.lookup().findVirtual(Greeter.class, "run", |
| * MethodType.make(void.class)); |
| * } |
| * // class Main { public static void main(String... av) { ... |
| * Greeter greeter = new Greeter("world"); |
| * greeter.run(); // prints "hello, world" |
| * // Statically typed method handle invocation (most direct): |
| * MethodHandle mh = greeter; |
| * mh.<void>invoke(); // also prints "hello, world" |
| * // Dynamically typed method handle invocation: |
| * MethodHandles.invoke(greeter); // also prints "hello, world" |
| * greeter.setGreeting("howdy"); |
| * mh.invoke(); // prints "howdy, world" (object-like mutable behavior) |
| * </pre></blockquote> |
| * <p> |
| * In the example of {@code Greeter}, the method {@code run} provides the entry point. |
| * The entry point need not be a constant value; it may be independently |
| * computed in each call to the constructor. The entry point does not |
| * even need to be a method on the {@code Greeter} class, though |
| * that is the typical case. |
| * <p> |
| * The entry point may also be provided symbolically, in which case the the |
| * {@code JavaMethodHandle} constructor performs the lookup of the entry point. |
| * This makes it possible to use {@code JavaMethodHandle} to create an anonymous |
| * inner class: |
| * <p><blockquote><pre> |
| * // We can also do this with symbolic names and/or inner classes: |
| * MethodHandles.invoke(new JavaMethodHandle("yow") { |
| * void yow() { System.out.println("yow, world"); } |
| * }); |
| * </pre></blockquote> |
| * <p> |
| * Here is similar lower-level code which works in terms of a bound method handle. |
| * <p><blockquote><pre> |
| * class Greeter { |
| * public void run() { System.out.println("hello, "+greetee); } |
| * private final String greetee; |
| * Greeter(String greetee) { this.greetee = greetee; } |
| * // the entry point function is computed once: |
| * private static final MethodHandle RUN |
| * = MethodHandles.findVirtual(Greeter.class, "run", |
| * MethodType.make(void.class)); |
| * } |
| * // class Main { public static void main(String... av) { ... |
| * Greeter greeter = new Greeter("world"); |
| * greeter.run(); // prints "hello, world" |
| * MethodHandle mh = MethodHanndles.insertArgument(Greeter.RUN, 0, greeter); |
| * mh.invoke(); // also prints "hello, world" |
| * </pre></blockquote> |
| * Note that the method handle must be separately created as a view on the base object. |
| * This increases footprint, complexity, and dynamic indirections. |
| * <p> |
| * Here is a pure functional value expressed most concisely as an anonymous inner class: |
| * <p><blockquote><pre> |
| * // class Main { public static void main(String... av) { ... |
| * final String greetee = "world"; |
| * MethodHandle greeter = new JavaMethodHandle("run") { |
| * private void run() { System.out.println("hello, "+greetee); } |
| * } |
| * greeter.invoke(); // prints "hello, world" |
| * </pre></blockquote> |
| * <p> |
| * Here is an abstract parameterized lvalue, efficiently expressed as a subtype of MethodHandle, |
| * and instantiated as an anonymous class. The data structure is a handle to 1-D array, |
| * with a specialized index type (long). It is created by inner class, and uses |
| * signature-polymorphic APIs throughout. |
| * <p><blockquote><pre> |
| * abstract class AssignableMethodHandle extends JavaMethodHandle { |
| * private final MethodHandle setter; |
| * public MethodHandle setter() { return setter; } |
| * public AssignableMethodHandle(String get, String set) { |
| * super(get); |
| * MethodType getType = this.type(); |
| * MethodType setType = getType.insertParameterType(getType.parameterCount(), getType.returnType()).changeReturnType(void.class); |
| * this.setter = MethodHandles.publicLookup().bind(this, set, setType); |
| * } |
| * } |
| * // class Main { public static void main(String... av) { ... |
| * final Number[] stuff = { 123, 456 }; |
| * AssignableMethodHandle stuffPtr = new AssignableMethodHandle("get", "set") { |
| * public Number get(long i) { return stuff[(int)i]; } |
| * public void set(long i, Object x) { stuff[(int)i] = x; } |
| * } |
| * int x = (Integer) stuffPtr.<Number>invoke(1L); // 456 |
| * stuffPtr.setter().<void>invoke(0L, (Number) 789); // replaces 123 with 789 |
| * </pre></blockquote> |
| * @see MethodHandle |
| * @author John Rose, JSR 292 EG |
| */ |
| public abstract class JavaMethodHandle |
| // Note: This is an implementation inheritance hack, and will be removed |
| // with a JVM change which moves the required hidden behavior onto this class. |
| extends sun.dyn.BoundMethodHandle |
| { |
| private static final Access IMPL_TOKEN = Access.getToken(); |
| |
| /** |
| * When creating a {@code JavaMethodHandle}, the actual method handle |
| * invocation behavior will be delegated to the specified {@code entryPoint}. |
| * This may be any method handle which can take the newly constructed object |
| * as a leading parameter. |
| * <p> |
| * The method handle type of {@code this} (i.e, the fully constructed object) |
| * will be {@code entryPoint}, minus the leading argument. |
| * The leading argument will be bound to {@code this} on every method |
| * handle invocation. |
| * @param entryPoint the method handle to handle calls |
| */ |
| protected JavaMethodHandle(MethodHandle entryPoint) { |
| super(entryPoint); |
| } |
| |
| /** |
| * Create a method handle whose entry point is a non-static method |
| * visible in the exact (most specific) class of |
| * the newly constructed object. |
| * <p> |
| * The method is specified by name and type, as if via this expression: |
| * {@code MethodHandles.lookup().findVirtual(this.getClass(), name, type)}. |
| * The class defining the method might be an anonymous inner class. |
| * <p> |
| * The method handle type of {@code this} (i.e, the fully constructed object) |
| * will be the given method handle type. |
| * A call to {@code this} will invoke the selected method. |
| * The receiver argument will be bound to {@code this} on every method |
| * handle invocation. |
| * <p> |
| * <i>Rationale:</i> |
| * Although this constructor may seem to be a mere luxury, |
| * it is not subsumed by the more general constructor which |
| * takes any {@code MethodHandle} as the entry point argument. |
| * In order to convert an entry point name to a method handle, |
| * the self-class of the object is required (in order to do |
| * the lookup). The self-class, in turn, is generally not |
| * available at the time of the constructor invocation, |
| * due to the rules of Java and the JVM verifier. |
| * One cannot call {@code this.getClass()}, because |
| * the value of {@code this} is inaccessible at the point |
| * of the constructor call. (Changing this would require |
| * change to the Java language, verifiers, and compilers.) |
| * In particular, this constructor allows {@code JavaMethodHandle}s |
| * to be created in combination with the anonymous inner class syntax. |
| * @param entryPointName the name of the entry point method |
| * @param type (optional) the desired type of the method handle |
| */ |
| protected JavaMethodHandle(String entryPointName, MethodType type) { |
| super(entryPointName, type, true); |
| |
| } |
| |
| /** |
| * Create a method handle whose entry point is a non-static method |
| * visible in the exact (most specific) class of |
| * the newly constructed object. |
| * <p> |
| * The method is specified only by name. |
| * There must be exactly one method of that name visible in the object class, |
| * either inherited or locally declared. |
| * (That is, the method must not be overloaded.) |
| * <p> |
| * The method handle type of {@code this} (i.e, the fully constructed object) |
| * will be the same as the type of the selected non-static method. |
| * The receiver argument will be bound to {@code this} on every method |
| * handle invocation. |
| * <p>ISSUE: This signature wildcarding feature does not correspond to |
| * any MethodHandles.Lookup API element. Can we eliminate it? |
| * Alternatively, it is useful for naming non-overloaded methods. |
| * Shall we make type arguments optional in the Lookup methods, |
| * throwing an error in cases of ambiguity? |
| * <p> |
| * For this method's rationale, see the documentation |
| * for {@link #JavaMethodHandle(String,MethodType)}. |
| * @param entryPointName the name of the entry point method |
| */ |
| protected JavaMethodHandle(String entryPointName) { |
| super(entryPointName, (MethodType) null, false); |
| } |
| } |
