1 /*
2 * Copyright 2008-2009 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.dyn;
27
28 //import java.dyn.emu.*;
29 import impl.java.dyn.*;
30
31 /**
32 * A method handle is a typed reference to the entry point of a method.
33 * <p>
34 * Method handles are strongly typed according to signature.
35 * They are not distinguished by method name or enclosing class.
36 * A method handle must be invoked under a signature which exactly matches
37 * the method handle's own type.
38 * <p>
39 * Every method handle confesses its type via the <code>type</code> accessor.
40 * The structure of this type is a series of classes, one of which is
41 * the return type of the method (or <code>void.class</code> if none).
42 * <p>
43 * Every method handle appears as an object containing a method named
44 * <code>invoke</code>, whose signature exactly matches
45 * the method handle's type.
46 * A normal Java method call (using the <code>invokevirtual</code> instruction)
47 * can invoke this method from Java source code (if language support is present).
48 * <p>
49 * Every call to a method handle specifies an intended method type,
50 * which must exactly match the type of the method handle.
51 * (The type is specified in the <code>invokevirtual</code> instruction,
52 * via a {@code CONSTANT_NameAndType} constant pool entry.)
53 * The call looks within the receiver object for a method
54 * named <code>invoke</code> of the intended method type.
55 * The call fails with a {@link WrongMethodTypeException}
56 * if the method does not exist, even if there is an <code>invoke</code>
57 * method of a closely similar signature.
58 * <p>
59 * A method handle is an unrestricted capability to call a method.
60 * A method handle can be formed on a non-public method by a class
61 * that has access to that method; the resulting handle can be used
62 * in any place by any caller who receives a reference to it. Thus, access
63 * checking is performed when the method handle is created, not
64 * (as in reflection) every time it is called. Handles to non-public
65 * methods, or in non-public classes, should generally be kept secret.
66 * They should not be passed to untrusted code.
67 * <p>
68 * Bytecode in an extended JVM can directly call a method handle's
69 * <code>invoke</code> from an <code>invokevirtual</code> instruction.
70 * The receiver class type must be <code>MethodHandle</code> and the method name
71 * must be <code>invoke</code>. The signature of the invocation
72 * (after resolving symbolic type names) must exactly match the method type
73 * of the target method.
74 * <p>
75 * Bytecode in an extended JVM can directly obtain a method handle
76 * for any accessible method from a <code>ldc</code> instruction
77 * which refers to a <code>CONSTANT_Methodref</code> or
78 * <code>CONSTANT_InterfaceMethodref</code> constant pool entry.
79 * <p>
80 * All JVMs can also use a reflective API called <code>MethodHandles</code>
81 * for creating and calling method handles.
82 * <p>
83 * A method reference may refer either to a static or non-static method.
84 * In the non-static case, the method handle type includes an explicit
85 * receiver argument, prepended before any other arguments.
86 * In the method handle's type, the initial receiver argument is typed
87 * according to the class under which the method was initially requested.
88 * (E.g., if a non-static method handle is obtained via <code>ldc</code>,
89 * the type of the receiver is the class named in the constant pool entry.)
90 * <p>
91 * When a method handle to a virtual method is invoked, the method is
92 * always looked up in the receiver (that is, the first argument).
93 * <p>
94 * A non-virtual method handles to a specific virtual method implementation
95 * can also be created. These do not perform virtual lookup based on
96 * receiver type. Such a method handle simulates the effect of
97 * an <code>invokespecial</code> instruction to the same method.
98 *
99 * @see MethodType
100 * @see MethodHandles
101 * @author John Rose, JSR 292 EG
102 */
103 public class MethodHandle extends MethodHandleImpl {
104 // interface MethodHandle<T extends MethodType<R,A...>>
105 // { T type(); <R,A...> public R invoke(A...); }
106
107 final private MethodType type;
108
109 /**
110 * Report the type of this method handle.
111 * Every invocation of this method handle must exactly match this type.
112 * @return the method handle type
113 */
114 public MethodType type() {
115 return type;
116 }
117
118 /**
119 * The constructor for MethodHandle may only be called by privileged code.
120 * Subclasses may be in other packages, but must possess
121 * a token which they obtained from MH with a security check.
122 * @param token non-null object which proves access permission
123 * @param type type (permanently assigned) of the new method handle
124 */
125 protected MethodHandle(Access token, MethodType type) {
126 super(token);
127 this.type = type;
128 }
129 }