/*
 * 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.
/**
 * 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 MethodHandles.filterArguments(MethodHandle, int, MethodHandle...) 
Params:
target –  target method handle
pos –     start argument index
filters – filters
Returns:
filtered handle/**
     * 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 MethodHandles.filterReturnValue(MethodHandle, MethodHandle) 
Params:
target –  target method handle
filter –  filter
Returns:
filtered handle/**
     * 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 MethodHandles.guardWithTest(MethodHandle, MethodHandle, MethodHandle) 
Params:
test –     test method handle
target –   target method handle when test is true
fallback – fallback method handle when test is false
Returns:
guarded handles/**
     * 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 MethodHandles.insertArguments(MethodHandle, int, Object...) 
Params:
target – target method handle
pos –    start argument index
values – values to insert
Returns:
handle with bound arguments/**
     * 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 MethodHandles.dropArguments(MethodHandle, int, Class<?>...) 
Params:
target –     target method handle
pos –        start argument index
valueTypes – valueTypes of arguments to drop
Returns:
handle with dropped arguments/**
     * 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 MethodHandles.dropArguments(MethodHandle, int, List<Class<?>>) 
Params:
target –     target method handle
pos –        start argument index
valueTypes – valueTypes of arguments to drop
Returns:
handle with dropped arguments/**
     * 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 MethodHandles.foldArguments(MethodHandle, MethodHandle) 
Params:
target –   target method handle
combiner – combiner to apply for fold
Returns:
folded method handle/**
     * 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 MethodHandles.explicitCastArguments(MethodHandle, MethodType) 
Params:
target –  target method handle
type –    type to cast to
Returns:
modified method handle/**
     * 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 MethodHandles.arrayElementGetter(Class<?>) 
Params:
arrayClass – class for array
Returns:
array element getter/**
     * 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 MethodHandles.arrayElementSetter(Class<?>) 
Params:
arrayClass – class for array
Returns:
array element setter/**
     * 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 MethodHandles.throwException(Class<?>, Class<? extends Throwable>) 
Params:
returnType – ignored, but method signature will use it
exType –     exception type that will be thrown
Returns:
exception thrower method handle/**
     * 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 MethodHandles.catchException(MethodHandle, Class<? extends Throwable>, MethodHandle) 
Params:
target –  target method
exType –  exception type
handler – the method handle to call when exception is thrown
Returns:
exception thrower method handle/**
     * 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 MethodHandles.constant(Class<?>, Object) 
Params:
type –  type of constant
value – constant value
Returns:
method handle that returns said constant/**
     * 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 MethodHandles.identity(Class<?>) 
Params:
type –  type of value
Returns:
method handle that returns identity argument/**
     * 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 MethodHandle.asType(MethodType) 
Params:
handle –  method handle for type conversion
type –    type to convert to
Returns:
method handle with given type conversion applied/**
     * 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 MethodHandle.asCollector(Class<?>, int) 
Params:
handle –      handle to convert
arrayType –   array type for collector array
arrayLength – length of collector array
Returns:
method handle with collector/**
     * 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 MethodHandle.asSpreader(Class<?>, int) 
Params:
handle –      handle to convert
arrayType –   array type for spread
arrayLength – length of spreader
Returns:
method handle as spreader/**
     * 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 MethodHandle.bindTo(Object) 
Params:
handle – a handle to which to bind a receiver
x –      the receiver
Returns:
the bound handle/**
     * 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 Lookup.findGetter(Class<?>, String, Class<?>) 
Params:
explicitLookup – explicit lookup to be used
clazz –          class to look in
name –           name of field
type –           type of field
Returns:
getter method handle for virtual field/**
     * 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 Lookup.findStaticGetter(Class<?>, String, Class<?>) 
Params:
explicitLookup – explicit lookup to be used
clazz –          class to look in
name –           name of field
type –           type of field
Returns:
getter method handle for static field/**
     * 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 Lookup.findSetter(Class<?>, String, Class<?>) 
Params:
explicitLookup – explicit lookup to be used
clazz –          class to look in
name –           name of field
type –           type of field
Returns:
setter method handle for virtual field/**
     * 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 Lookup.findStaticSetter(Class<?>, String, Class<?>) 
Params:
explicitLookup – explicit lookup to be used
clazz –          class to look in
name –           name of field
type –           type of field
Returns:
setter method handle for static field/**
     * 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 Lookup.unreflect(Method) Unreflect a method as a method handle 
Params:
method – method to unreflect
Returns:
unreflected method as method handle/**
     * 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 Lookup.findStatic(Class<?>, String, MethodType) 
Params:
explicitLookup – explicit lookup to be used
clazz –          class to look in
name –           name of method
type –           method type
Returns:
method handle for static 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 Lookup.findVirtual(Class<?>, String, MethodType) 
Params:
explicitLookup – explicit lookup to be used
clazz –          class to look in
name –           name of method
type –           method type
Returns:
method handle for virtual method/**
     * 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 Lookup.findSpecial(Class<?>, String, MethodType, Class<?>) 
Params:
explicitLookup – explicit lookup to be used
clazz –          class to look in
name –           name of method
type –           method type
thisClass –      thisClass
Returns:
method handle for virtual method/**
     * 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 new SwitchPoint() but potentially tracked 
Returns:
new switch point/**
     * Wrapper for SwitchPoint creation. Just like {@code new SwitchPoint()} but potentially
     * tracked
     *
     * @return new switch point
     */
    public SwitchPoint createSwitchPoint();

    
Wrapper for SwitchPoint.guardWithTest(MethodHandle, MethodHandle) 
Params:
sp –     switch point
before – method handle when switchpoint is valid
after –  method handle when switchpoint is invalidated
Returns:
guarded method handle/**
     * 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 MethodType.methodType(Class<?>, Class<?>...) 
Params:
returnType –  return type for method type
paramTypes –  parameter types for method type
Returns:
the method type/**
     * 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);

}