/*
* Copyright (c) 2010, 2013, 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 jdk.nashorn.internal.lookup;
import java.lang.invoke.MethodHandle;
import java.lang.invoke.MethodHandles;
import java.lang.invoke.MethodType;
import java.lang.invoke.SwitchPoint;
import java.lang.reflect.Method;
import java.util.List;
/**
* Wrapper for all method handle related functions used in Nashorn. This interface only exists
* so that instrumentation can be added to all method handle operations.
*/
public interface MethodHandleFunctionality {
/**
* Wrapper for {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)}
*
* @param target target method handle
* @param pos start argument index
* @param filters filters
*
* @return filtered handle
*/
public MethodHandle filterArguments(MethodHandle target, int pos, MethodHandle... filters);
/**
* Wrapper for {@link MethodHandles#filterReturnValue(MethodHandle, MethodHandle)}
*
* @param target target method handle
* @param filter filter
*
* @return filtered handle
*/
public MethodHandle filterReturnValue(MethodHandle target, MethodHandle filter);
/**
* Wrapper for {@link MethodHandles#guardWithTest(MethodHandle, MethodHandle, MethodHandle)}
*
* @param test test method handle
* @param target target method handle when test is true
* @param fallback fallback method handle when test is false
*
* @return guarded handles
*/
public MethodHandle guardWithTest(MethodHandle test, MethodHandle target, MethodHandle fallback);
/**
* Wrapper for {@link MethodHandles#insertArguments(MethodHandle, int, Object...)}
*
* @param target target method handle
* @param pos start argument index
* @param values values to insert
*
* @return handle with bound arguments
*/
public MethodHandle insertArguments(MethodHandle target, int pos, Object... values);
/**
* Wrapper for {@link MethodHandles#dropArguments(MethodHandle, int, Class...)}
*
* @param target target method handle
* @param pos start argument index
* @param valueTypes valueTypes of arguments to drop
*
* @return handle with dropped arguments
*/
public MethodHandle dropArguments(MethodHandle target, int pos, Class<?>... valueTypes);
/**
* Wrapper for {@link MethodHandles#dropArguments(MethodHandle, int, List)}
*
* @param target target method handle
* @param pos start argument index
* @param valueTypes valueTypes of arguments to drop
*
* @return handle with dropped arguments
*/
public MethodHandle dropArguments(final MethodHandle target, final int pos, final List<Class<?>> valueTypes);
/**
* Wrapper for {@link MethodHandles#foldArguments(MethodHandle, MethodHandle)}
*
* @param target target method handle
* @param combiner combiner to apply for fold
*
* @return folded method handle
*/
public MethodHandle foldArguments(MethodHandle target, MethodHandle combiner);
/**
* Wrapper for {@link MethodHandles#explicitCastArguments(MethodHandle, MethodType)}
*
* @param target target method handle
* @param type type to cast to
*
* @return modified method handle
*/
public MethodHandle explicitCastArguments(MethodHandle target, MethodType type);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles#arrayElementGetter(Class)}
*
* @param arrayClass class for array
*
* @return array element getter
*/
public MethodHandle arrayElementGetter(Class<?> arrayClass);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles#arrayElementSetter(Class)}
*
* @param arrayClass class for array
*
* @return array element setter
*/
public MethodHandle arrayElementSetter(Class<?> arrayClass);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles#throwException(Class, Class)}
*
* @param returnType ignored, but method signature will use it
* @param exType exception type that will be thrown
*
* @return exception thrower method handle
*/
public MethodHandle throwException(Class<?> returnType, Class<? extends Throwable> exType);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles#catchException(MethodHandle, Class, MethodHandle)}
*
* @param target target method
* @param exType exception type
* @param handler the method handle to call when exception is thrown
*
* @return exception thrower method handle
*/
public MethodHandle catchException(final MethodHandle target, final Class<? extends Throwable> exType, final MethodHandle handler);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles#constant(Class, Object)}
*
* @param type type of constant
* @param value constant value
*
* @return method handle that returns said constant
*/
public MethodHandle constant(Class<?> type, Object value);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles#identity(Class)}
*
* @param type type of value
*
* @return method handle that returns identity argument
*/
public MethodHandle identity(Class<?> type);
/**
* Wrapper for {@link java.lang.invoke.MethodHandle#asType(MethodType)}
*
* @param handle method handle for type conversion
* @param type type to convert to
*
* @return method handle with given type conversion applied
*/
public MethodHandle asType(MethodHandle handle, MethodType type);
/**
* Wrapper for {@link java.lang.invoke.MethodHandle#asCollector(Class, int)}
*
* @param handle handle to convert
* @param arrayType array type for collector array
* @param arrayLength length of collector array
*
* @return method handle with collector
*/
public MethodHandle asCollector(MethodHandle handle, Class<?> arrayType, int arrayLength);
/**
* Wrapper for {@link java.lang.invoke.MethodHandle#asSpreader(Class, int)}
*
* @param handle handle to convert
* @param arrayType array type for spread
* @param arrayLength length of spreader
*
* @return method handle as spreader
*/
public MethodHandle asSpreader(MethodHandle handle, Class<?> arrayType, int arrayLength);
/**
* Wrapper for {@link java.lang.invoke.MethodHandle#bindTo(Object)}
*
* @param handle a handle to which to bind a receiver
* @param x the receiver
*
* @return the bound handle
*/
public MethodHandle bindTo(MethodHandle handle, Object x);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles.Lookup#findGetter(Class, String, Class)}
*
* @param explicitLookup explicit lookup to be used
* @param clazz class to look in
* @param name name of field
* @param type type of field
*
* @return getter method handle for virtual field
*/
public MethodHandle getter(MethodHandles.Lookup explicitLookup, Class<?> clazz, String name, Class<?> type);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles.Lookup#findStaticGetter(Class, String, Class)}
*
* @param explicitLookup explicit lookup to be used
* @param clazz class to look in
* @param name name of field
* @param type type of field
*
* @return getter method handle for static field
*/
public MethodHandle staticGetter(MethodHandles.Lookup explicitLookup, Class<?> clazz, String name, Class<?> type);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles.Lookup#findSetter(Class, String, Class)}
*
* @param explicitLookup explicit lookup to be used
* @param clazz class to look in
* @param name name of field
* @param type type of field
*
* @return setter method handle for virtual field
*/
public MethodHandle setter(MethodHandles.Lookup explicitLookup, Class<?> clazz, String name, Class<?> type);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles.Lookup#findStaticSetter(Class, String, Class)}
*
* @param explicitLookup explicit lookup to be used
* @param clazz class to look in
* @param name name of field
* @param type type of field
*
* @return setter method handle for static field
*/
public MethodHandle staticSetter(MethodHandles.Lookup explicitLookup, Class<?> clazz, String name, Class<?> type);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles.Lookup#unreflect(Method)}
*
* Unreflect a method as a method handle
*
* @param method method to unreflect
* @return unreflected method as method handle
*/
public MethodHandle find(Method method);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles.Lookup#findStatic(Class, String, MethodType)}
*
* @param explicitLookup explicit lookup to be used
* @param clazz class to look in
* @param name name of method
* @param type method type
*
* @return method handle for static method
*/
public MethodHandle findStatic(MethodHandles.Lookup explicitLookup, Class<?> clazz, String name, MethodType type);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles.Lookup#findVirtual(Class, String, MethodType)}
*
* @param explicitLookup explicit lookup to be used
* @param clazz class to look in
* @param name name of method
* @param type method type
*
* @return method handle for virtual method
*/
public MethodHandle findVirtual(MethodHandles.Lookup explicitLookup, Class<?> clazz, String name, MethodType type);
/**
* Wrapper for {@link java.lang.invoke.MethodHandles.Lookup#findSpecial(Class, String, MethodType, Class)}
*
* @param explicitLookup explicit lookup to be used
* @param clazz class to look in
* @param name name of method
* @param type method type
* @param thisClass thisClass
*
* @return method handle for virtual method
*/
public MethodHandle findSpecial(MethodHandles.Lookup explicitLookup, Class<?> clazz, String name, MethodType type, final Class<?> thisClass);
/**
* Wrapper for SwitchPoint creation. Just like {@code new SwitchPoint()} but potentially
* tracked
*
* @return new switch point
*/
public SwitchPoint createSwitchPoint();
/**
* Wrapper for {@link SwitchPoint#guardWithTest(MethodHandle, MethodHandle)}
*
* @param sp switch point
* @param before method handle when switchpoint is valid
* @param after method handle when switchpoint is invalidated
*
* @return guarded method handle
*/
public MethodHandle guardWithTest(SwitchPoint sp, MethodHandle before, MethodHandle after);
/**
* Wrapper for {@link MethodType#methodType(Class, Class...)}
*
* @param returnType return type for method type
* @param paramTypes parameter types for method type
*
* @return the method type
*/
public MethodType type(Class<?> returnType, Class<?>... paramTypes);
}