Module java.base

Class MethodHandle


  • public abstract class MethodHandle
    extends Object
    A MethodHandle is a reference to a Java-level method. It is typed according to the method's signature and can be invoked in three ways:
    1. invokeExact - using the exact signature match
    2. invoke - using a signature with the same number of arguments
    3. invokeWithArguments - using a Object array to hold the correct number of arguments

    In the case of #invokeExact, if the arguments do not match, based on a check of the MethodHandle's type(), a WrongMethodTypeException will be thrown.

    In the case of #invoke, each of the arguments will be converted to the correct type, before the call is initiated. If the conversion cannot occur, a WrongMethodTypeException will be thrown.

    Similar to #invoke, #invokeWithArguments will convert each of the arguments and place them on the stack before the call is initiated. If the conversion cannot occur, a WrongMethodTypeException will be thrown.

    A MethodHandle can be created using the MethodHandles factory.

    Since:
    1.7
    • Method Detail

      • invokeExact

        public final Object invokeExact​(Object... args)
                                 throws Throwable,
                                        WrongMethodTypeException
        Invoke the receiver MethodHandle against the supplied arguments. The types of the arguments must be an exact match for the MethodType of the MethodHandle.
        Parameters:
        args - The argument list for the polymorphic signature call
        Returns:
        The return value of the method
        Throws:
        Throwable - - To ensure type safety, must be marked as throwing Throwable.
        WrongMethodTypeException - - If the resolved method type is not exactly equal to the MethodHandle's type
      • invoke

        public final Object invoke​(Object... args)
                            throws Throwable,
                                   WrongMethodTypeException,
                                   ClassCastException
        Invoke the receiver MethodHandle against the supplied arguments. If the types of the arguments are not an exact match for the MethodType of the MethodHandle, conversions will be applied as possible. The signature and the MethodHandle's MethodType must have the same number of arguments.
        Parameters:
        args - The argument list for the polymorphic signature call
        Returns:
        The return value of the method. May be converted according to the conversion rules.
        Throws:
        Throwable - - To ensure type safety, must be marked as throwing Throwable.
        WrongMethodTypeException - - If the resolved method type cannot be converted to the MethodHandle's type
        ClassCastException - - if a conversion fails
      • type

        public MethodType type()
        The MethodType of the MethodHandle. Invocation must match this MethodType.
        Returns:
        the MethodType of the MethodHandle.
      • asSpreader

        public MethodHandle asSpreader​(Class<?> arrayClass,
                                       int spreadCount)
                                throws IllegalArgumentException,
                                       WrongMethodTypeException
        Produce a MethodHandle that has an array of type arrayClass as its last argument and replaces the array with spreadCount arguments from the array before calling the original MethodHandle. The MethodType of new the methodhandle and the original methodhandle will differ only in the regards to the last arguments.

        The array must contain exactly spreadCount arguments to be passed to the original methodhandle. The array may be null in the case when spreadCount is zero. Incorrect argument array size will cause the method to throw an IllegalArgumentException instead of invoking the target.

        Parameters:
        arrayClass - - the source array for the spread arguments
        spreadCount - - how many arguments to spread from the arrayClass
        Returns:
        a MethodHandle able to replace to the last parameter with spreadCount number of arguments
        Throws:
        IllegalArgumentException - - if arrayClass is not an array, the methodhandle has too few or too many parameters to satisfy spreadCount
        WrongMethodTypeException - - if it cannot convert from one MethodType to the new type.
      • asSpreader

        public MethodHandle asSpreader​(int spreadPosition,
                                       Class<?> arrayClass,
                                       int spreadCount)
                                throws IllegalArgumentException,
                                       WrongMethodTypeException
        Produce a MethodHandle that has an array of type arrayClass as its argument at the specified position and replaces the array with spreadCount arguments from the array before calling the original MethodHandle. The MethodType of new the methodhandle and the original methodhandle will differ only in the regards to the argument at the specified position.

        The array must contain exactly spreadCount arguments to be passed to the original methodhandle. The array may be null in the case when spreadCount is zero. Incorrect argument array size will cause the method to throw an IllegalArgumentException instead of invoking the target.

        Parameters:
        spreadPosition - - the starting position to spread
        arrayClass - - the source array for the spread arguments
        spreadCount - - how many arguments to spread from the arrayClass
        Returns:
        a MethodHandle able to replace to the specified parameter with spreadCount number of arguments
        Throws:
        IllegalArgumentException - - if arrayClass is not an array, the methodhandle has too few or too many parameters to satisfy spreadCount
        WrongMethodTypeException - - if it cannot convert from one MethodType to the new type.
      • asCollector

        public MethodHandle asCollector​(Class<?> arrayClass,
                                        int collectCount)
                                 throws IllegalArgumentException,
                                        WrongMethodTypeException,
                                        NullPointerException
        Returns a MethodHandle that collects the requested incoming arguments, which must match the types in MethodType incomingArgs, into an array of arrayClass, called T. This method can only be called on MethodHandles that have type() such that their last parameter can be assigned to from an instance of arrayClass. An IllegalArgumentException will be thrown if this is not the case. This take a MH with type (Something, Something, K)R and presents a MethodType with the form (Something, Something, T, T, T)R. Where K is assignable to from an array of arrayClass T.
        Parameters:
        arrayClass - - the class of the collect array. Usually matches the type of the last argument.
        collectCount - - the number of arguments of type 'T' to collect
        Returns:
        a MethodHandle which will collect collectCount arguments and pass them as the final argument
        Throws:
        IllegalArgumentException - if arrayClass is not an array or is not assignable to the last parameter of the MethodHandle, or collectCount is an invalid array size (less than 0 or more than 254)
        WrongMethodTypeException - if an asType call would fail when converting the final parameter to arrayClass
        NullPointerException - if arrayClass is null
      • asCollector

        public MethodHandle asCollector​(int collectPosition,
                                        Class<?> arrayClass,
                                        int collectCount)
                                 throws IllegalArgumentException,
                                        WrongMethodTypeException,
                                        NullPointerException
        Returns a MethodHandle that collects the requested incoming arguments, which must match the types in MethodType incomingArgs, into an array of arrayClass, called T.
        Parameters:
        collectPosition - - the starting position for the arguments to collect.
        arrayClass - - the class of the collect array. It matches the type of the argument at the specified position.
        collectCount - - the number of arguments of type 'T' to collect
        Returns:
        a MethodHandle which will collect collectCount arguments and pass them as the final argument
        Throws:
        IllegalArgumentException - if arrayClass is not an array or is not assignable to the last parameter of the MethodHandle, or collectCount is an invalid array size (less than 0 or more than 254)
        WrongMethodTypeException - if an asType call would fail when converting the final parameter to arrayClass
        NullPointerException - if arrayClass is null
      • asType

        public MethodHandle asType​(MethodType newType)
                            throws ClassCastException
        Returns a MethodHandle that presents as being of MethodType newType. It will convert the arguments used to match type(). If a conversion is invalid, a ClassCastException will be thrown. If newType == type(), then the original MethodHandle may be returned. TODO: Describe the type conversion rules here. If the return type T1 is void, any returned value is discarded If the return type T0 is void and T1 a reference, a null value is introduced. If the return type T0 is void and T1 a primitive, a zero value is introduced.
        Parameters:
        newType - the MethodType for invoking this method with
        Returns:
        A MethodHandle with MethodType newType
        Throws:
        ClassCastException - if any of the requested coercions are invalid.
      • invokeWithArguments

        public Object invokeWithArguments​(Object... args)
                                   throws Throwable,
                                          WrongMethodTypeException,
                                          ClassCastException
        Invoke the MethodHandle using an Object[] of arguments. The array must contain at exactly type().parameterCount() arguments. Each of the arguments in the array will be coerced to the appropriate type, if possible, based on the MethodType.
        Parameters:
        args - An array of Arguments, with length at exactly type().parameterCount() to be used in the call.
        Returns:
        An Object
        Throws:
        Throwable - May throw anything depending on the receiver MethodHandle.
        WrongMethodTypeException - if the target cannot be adjusted to the number of Objects being passed
        ClassCastException - if an argument cannot be converted
      • asVarargsCollector

        public MethodHandle asVarargsCollector​(Class<?> arrayParameter)
                                        throws IllegalArgumentException
        Create an varargs collector adapter on this MethodHandle. For asVarargsCollector(Class) MethodHandles, invokeExact requires that the arguments exactly match the underlying MethodType.

        invoke acts as normally unless the arities differ. In that case, the trailing arguments are converted as though by a call to #asCollector(Class, int) before invoking the underlying methodhandle.

        Parameters:
        arrayParameter - - the type of the array to collect the arguments into
        Returns:
        a varargs-collector methodhandle.
        Throws:
        IllegalArgumentException - - if the arrayParameter is not an array class or cannot be assigned to the last parameter of the MethodType
      • withVarargs

        public MethodHandle withVarargs​(boolean isVarArityNeeded)
                                 throws IllegalArgumentException
        Return a MethodHandle that is wrapped with an asVarargsCollector adapter if the handle is allowed to be variable arity.
        Parameters:
        isVarArityNeeded - - a boolean flag to tell whether the handle is converted to be variable arity or not.
        Returns:
        a MethodHandle with variable arity or fixed arity if isVarArityNeeded is false
        Throws:
        IllegalArgumentException - if isVarArity is true but there is no trailing array parameter in the parameter list of the handle.
      • asFixedArity

        public MethodHandle asFixedArity()
        Return a fixed arity version of the current MethodHandle.

        This is identical to the current method handle if isVarargsCollector() is false.

        If the current method is a varargs collector, then the returned handle will be the same but without the varargs nature.

        Returns:
        a fixed arity version of the current method handle