1 /*
2 * Copyright (c) 2008, 2013, 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.lang.invoke;
27
28 import java.lang.reflect.*;
29 import java.security.AccessController;
30 import java.security.PrivilegedAction;
31 import sun.invoke.WrapperInstance;
32 import java.util.ArrayList;
33 import sun.reflect.CallerSensitive;
34 import sun.reflect.Reflection;
35 import sun.reflect.misc.ReflectUtil;
36
37 /**
38 * This class consists exclusively of static methods that help adapt
39 * method handles to other JVM types, such as interfaces.
40 */
41 public class MethodHandleProxies {
42
43 private MethodHandleProxies() { } // do not instantiate
44
45 /**
46 * Produces an instance of the given single-method interface which redirects
47 * its calls to the given method handle.
48 * <p>
49 * A single-method interface is an interface which declares a uniquely named method.
50 * When determining the uniquely named method of a single-method interface,
51 * the public {@code Object} methods ({@code toString}, {@code equals}, {@code hashCode})
52 * are disregarded. For example, {@link java.util.Comparator} is a single-method interface,
53 * even though it re-declares the {@code Object.equals} method.
54 * <p>
55 * The interface must be public. No additional access checks are performed.
56 * <p>
57 * The resulting instance of the required type will respond to
58 * invocation of the type's uniquely named method by calling
59 * the given target on the incoming arguments,
60 * and returning or throwing whatever the target
61 * returns or throws. The invocation will be as if by
62 * {@code target.invoke}.
63 * The target's type will be checked before the
64 * instance is created, as if by a call to {@code asType},
65 * which may result in a {@code WrongMethodTypeException}.
66 * <p>
67 * The uniquely named method is allowed to be multiply declared,
68 * with distinct type descriptors. (E.g., it can be overloaded,
69 * or can possess bridge methods.) All such declarations are
70 * connected directly to the target method handle.
71 * Argument and return types are adjusted by {@code asType}
72 * for each individual declaration.
73 * <p>
74 * The wrapper instance will implement the requested interface
75 * and its super-types, but no other single-method interfaces.
76 * This means that the instance will not unexpectedly
77 * pass an {@code instanceof} test for any unrequested type.
78 * <p style="font-size:smaller;">
79 * <em>Implementation Note:</em>
80 * Therefore, each instance must implement a unique single-method interface.
81 * Implementations may not bundle together
82 * multiple single-method interfaces onto single implementation classes
83 * in the style of {@link java.awt.AWTEventMulticaster}.
84 * <p>
85 * The method handle may throw an <em>undeclared exception</em>,
86 * which means any checked exception (or other checked throwable)
87 * not declared by the requested type's single abstract method.
88 * If this happens, the throwable will be wrapped in an instance of
89 * {@link java.lang.reflect.UndeclaredThrowableException UndeclaredThrowableException}
90 * and thrown in that wrapped form.
91 * <p>
92 * Like {@link java.lang.Integer#valueOf Integer.valueOf},
93 * {@code asInterfaceInstance} is a factory method whose results are defined
94 * by their behavior.
95 * It is not guaranteed to return a new instance for every call.
96 * <p>
97 * Because of the possibility of {@linkplain java.lang.reflect.Method#isBridge bridge methods}
98 * and other corner cases, the interface may also have several abstract methods
99 * with the same name but having distinct descriptors (types of returns and parameters).
100 * In this case, all the methods are bound in common to the one given target.
101 * The type check and effective {@code asType} conversion is applied to each
102 * method type descriptor, and all abstract methods are bound to the target in common.
103 * Beyond this type check, no further checks are made to determine that the
104 * abstract methods are related in any way.
105 * <p>
106 * Future versions of this API may accept additional types,
107 * such as abstract classes with single abstract methods.
108 * Future versions of this API may also equip wrapper instances
109 * with one or more additional public "marker" interfaces.
110 * <p>
111 * If a security manager is installed, this method is caller sensitive.
112 * During any invocation of the target method handle via the returned wrapper,
113 * the original creator of the wrapper (the caller) will be visible
114 * to context checks requested by the security manager.
115 *
116 * @param <T> the desired type of the wrapper, a single-method interface
117 * @param intfc a class object representing {@code T}
118 * @param target the method handle to invoke from the wrapper
119 * @return a correctly-typed wrapper for the given target
120 * @throws NullPointerException if either argument is null
121 * @throws IllegalArgumentException if the {@code intfc} is not a
122 * valid argument to this method
123 * @throws WrongMethodTypeException if the target cannot
124 * be converted to the type required by the requested interface
125 */
126 // Other notes to implementors:
127 // <p>
128 // No stable mapping is promised between the single-method interface and
129 // the implementation class C. Over time, several implementation
130 // classes might be used for the same type.
131 // <p>
132 // If the implementation is able
133 // to prove that a wrapper of the required type
134 // has already been created for a given
135 // method handle, or for another method handle with the
136 // same behavior, the implementation may return that wrapper in place of
137 // a new wrapper.
138 // <p>
139 // This method is designed to apply to common use cases
140 // where a single method handle must interoperate with
141 // an interface that implements a function-like
142 // API. Additional variations, such as single-abstract-method classes with
143 // private constructors, or interfaces with multiple but related
144 // entry points, must be covered by hand-written or automatically
145 // generated adapter classes.
146 //
147 @CallerSensitive
148 public static
149 <T> T asInterfaceInstance(final Class<T> intfc, final MethodHandle target) {
150 if (!intfc.isInterface() || !Modifier.isPublic(intfc.getModifiers()))
151 throw new IllegalArgumentException("not a public interface: "+intfc.getName());
152 final MethodHandle mh;
153 if (System.getSecurityManager() != null) {
154 final Class<?> caller = Reflection.getCallerClass();
155 final ClassLoader ccl = caller != null ? caller.getClassLoader() : null;
156 ReflectUtil.checkProxyPackageAccess(ccl, intfc);
157 mh = ccl != null ? bindCaller(target, caller) : target;
158 } else {
159 mh = target;
160 }
161 ClassLoader proxyLoader = intfc.getClassLoader();
162 if (proxyLoader == null) {
163 ClassLoader cl = Thread.currentThread().getContextClassLoader(); // avoid use of BCP
164 proxyLoader = cl != null ? cl : ClassLoader.getSystemClassLoader();
165 }
166 final Method[] methods = getSingleNameMethods(intfc);
167 if (methods == null)
168 throw new IllegalArgumentException("not a single-method interface: "+intfc.getName());
169 final MethodHandle[] vaTargets = new MethodHandle[methods.length];
170 for (int i = 0; i < methods.length; i++) {
171 Method sm = methods[i];
172 MethodType smMT = MethodType.methodType(sm.getReturnType(), sm.getParameterTypes());
173 MethodHandle checkTarget = mh.asType(smMT); // make throw WMT
174 checkTarget = checkTarget.asType(checkTarget.type().changeReturnType(Object.class));
175 vaTargets[i] = checkTarget.asSpreader(Object[].class, smMT.parameterCount());
176 }
177 final InvocationHandler ih = new InvocationHandler() {
178 private Object getArg(String name) {
179 if ((Object)name == "getWrapperInstanceTarget") return target;
180 if ((Object)name == "getWrapperInstanceType") return intfc;
181 throw new AssertionError();
182 }
183 public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
184 for (int i = 0; i < methods.length; i++) {
185 if (method.equals(methods[i]))
186 return vaTargets[i].invokeExact(args);
187 }
188 if (method.getDeclaringClass() == WrapperInstance.class)
189 return getArg(method.getName());
190 if (isObjectMethod(method))
191 return callObjectMethod(proxy, method, args);
192 throw new InternalError("bad proxy method: "+method);
193 }
194 };
195
196 final Object proxy;
197 if (System.getSecurityManager() != null) {
198 // sun.invoke.WrapperInstance is a restricted interface not accessible
199 // by any non-null class loader.
200 final ClassLoader loader = proxyLoader;
201 proxy = AccessController.doPrivileged(new PrivilegedAction<Object>() {
202 public Object run() {
203 return Proxy.newProxyInstance(
204 loader,
205 new Class<?>[]{ intfc, WrapperInstance.class },
206 ih);
207 }
208 });
209 } else {
210 proxy = Proxy.newProxyInstance(proxyLoader,
211 new Class<?>[]{ intfc, WrapperInstance.class },
212 ih);
213 }
214 return intfc.cast(proxy);
215 }
216
217 private static MethodHandle bindCaller(MethodHandle target, Class<?> hostClass) {
218 MethodHandle cbmh = MethodHandleImpl.bindCaller(target, hostClass);
219 if (target.isVarargsCollector()) {
220 MethodType type = cbmh.type();
221 int arity = type.parameterCount();
222 return cbmh.asVarargsCollector(type.parameterType(arity-1));
223 }
224 return cbmh;
225 }
226
227 /**
228 * Determines if the given object was produced by a call to {@link #asInterfaceInstance asInterfaceInstance}.
229 * @param x any reference
230 * @return true if the reference is not null and points to an object produced by {@code asInterfaceInstance}
231 */
232 public static
233 boolean isWrapperInstance(Object x) {
234 return x instanceof WrapperInstance;
235 }
236
237 private static WrapperInstance asWrapperInstance(Object x) {
238 try {
239 if (x != null)
240 return (WrapperInstance) x;
241 } catch (ClassCastException ex) {
242 }
243 throw new IllegalArgumentException("not a wrapper instance");
244 }
245
246 /**
247 * Produces or recovers a target method handle which is behaviorally
248 * equivalent to the unique method of this wrapper instance.
249 * The object {@code x} must have been produced by a call to {@link #asInterfaceInstance asInterfaceInstance}.
250 * This requirement may be tested via {@link #isWrapperInstance isWrapperInstance}.
251 * @param x any reference
252 * @return a method handle implementing the unique method
253 * @throws IllegalArgumentException if the reference x is not to a wrapper instance
254 */
255 public static
256 MethodHandle wrapperInstanceTarget(Object x) {
257 return asWrapperInstance(x).getWrapperInstanceTarget();
258 }
259
260 /**
261 * Recovers the unique single-method interface type for which this wrapper instance was created.
262 * The object {@code x} must have been produced by a call to {@link #asInterfaceInstance asInterfaceInstance}.
263 * This requirement may be tested via {@link #isWrapperInstance isWrapperInstance}.
264 * @param x any reference
265 * @return the single-method interface type for which the wrapper was created
266 * @throws IllegalArgumentException if the reference x is not to a wrapper instance
267 */
268 public static
269 Class<?> wrapperInstanceType(Object x) {
270 return asWrapperInstance(x).getWrapperInstanceType();
271 }
272
273 private static
274 boolean isObjectMethod(Method m) {
275 switch (m.getName()) {
276 case "toString":
277 return (m.getReturnType() == String.class
278 && m.getParameterTypes().length == 0);
279 case "hashCode":
280 return (m.getReturnType() == int.class
281 && m.getParameterTypes().length == 0);
282 case "equals":
283 return (m.getReturnType() == boolean.class
284 && m.getParameterTypes().length == 1
285 && m.getParameterTypes()[0] == Object.class);
286 }
287 return false;
288 }
289
290 private static
291 Object callObjectMethod(Object self, Method m, Object[] args) {
292 assert(isObjectMethod(m)) : m;
293 switch (m.getName()) {
294 case "toString":
295 return self.getClass().getName() + "@" + Integer.toHexString(self.hashCode());
296 case "hashCode":
297 return System.identityHashCode(self);
298 case "equals":
299 return (self == args[0]);
300 }
301 return null;
302 }
303
304 private static
305 Method[] getSingleNameMethods(Class<?> intfc) {
306 ArrayList<Method> methods = new ArrayList<>();
307 String uniqueName = null;
308 for (Method m : intfc.getMethods()) {
309 if (isObjectMethod(m)) continue;
310 if (!Modifier.isAbstract(m.getModifiers())) continue;
311 String mname = m.getName();
312 if (uniqueName == null)
313 uniqueName = mname;
314 else if (!uniqueName.equals(mname))
315 return null; // too many abstract methods
316 methods.add(m);
317 }
318 if (uniqueName == null) return null;
319 return methods.toArray(new Method[methods.size()]);
320 }
321 }