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 }