1 /*

     2  * Copyright (c) 2008, 2009, 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 package java.dyn;

    27 

    28 import sun.dyn.Access;

    29 

    30 /**

    31  * A Java method handle is a deprecated proposal for extending

    32  * the basic method handle type with additional

    33  * programmer defined methods and fields.

    34  * Its behavior as a method handle is determined at instance creation time,

    35  * by providing the new instance with an "entry point" method handle

    36  * to handle calls.  This entry point must accept a leading argument

    37  * whose type is the Java method handle itself or a supertype, and the

    38  * entry point is always called with the Java method handle itself as

    39  * the first argument.  This is similar to ordinary virtual methods, which also

    40  * accept the receiver object {@code this} as an implicit leading argument.

    41  * The {@code MethodType} of the Java method handle is the same as that

    42  * of the entry point method handle, with the leading parameter type

    43  * omitted.

    44  * <p>

    45  * Here is an example of usage, creating a hybrid object/functional datum:

    46  * <p><blockquote><pre>

    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;

    66  * mh.<void>invokeExact();  // also prints "hello, world"

    67  * // Dynamically typed method handle invocation:

    68  * MethodHandles.invokeExact(greeter);  // also prints "hello, world"

    69  * greeter.setGreeting("howdy");

    70  * mh.invokeExact();  // prints "howdy, world" (object-like mutable behavior)

    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:

    85  * MethodHandles.invokeExact(new JavaMethodHandle("yow") {

    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 {

    93  *         public void run() { System.out.println("hello, "+greetee); }

    94  *         private final String greetee;

    95  *         Greeter(String greetee) { this.greetee = greetee; }

    96  *         // the entry point function is computed once:

    97  *         private static final MethodHandle RUN

    98  *             = MethodHandles.findVirtual(Greeter.class, "run",

    99  *                   MethodType.make(void.class));

   100  *     }

   101  *     // class Main { public static void main(String... av) { ...

   102  *     Greeter greeter = new Greeter("world");

   103  *     greeter.run();  // prints "hello, world"

   104  *     MethodHandle mh = MethodHanndles.insertArgument(Greeter.RUN, 0, greeter);

   105  *     mh.invokeExact();  // also prints "hello, world"

   106  * </pre></blockquote>

   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  *     }

   117  *     greeter.invokeExact();  // prints "hello, world"

   118  * </pre></blockquote>

   119  * <p>

   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  *     }

   141  *     int x = (Integer) stuffPtr.<Number>invokeExact(1L);  // 456

   142  *     stuffPtr.setter().<void>invokeExact(0L, (Number) 789);  // replaces 123 with 789

   143  * </pre></blockquote>

   144  * @see MethodHandle

   145  * @deprecated The JSR 292 EG intends to replace {@code JavaMethodHandle} with

   146  * an interface-based API for mixing method handle behavior with other classes.

   147  * @author John Rose, JSR 292 EG

   148  */

   149 public abstract class JavaMethodHandle

   150         // Note: This is an implementation inheritance hack, and will be removed

   151         // with a JVM change which moves the required hidden behavior onto this class.

   152         extends sun.dyn.BoundMethodHandle

   153 {

   154     private static final Access IMPL_TOKEN = Access.getToken();

   155 

   156     /**

   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

   167      */

   168     protected JavaMethodHandle(MethodHandle entryPoint) {

   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);

   236     }

   237 }