- java.lang.Object
-
- java.lang.invoke.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:- invokeExact - using the exact signature match
- invoke - using a signature with the same number of arguments
- 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 Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description MethodHandle
asCollector(int collectPosition, Class<?> arrayClass, int collectCount)
Returns a MethodHandle that collects the requested incoming arguments, which must match the types in MethodType incomingArgs, into an array of arrayClass, called T.MethodHandle
asCollector(Class<?> arrayClass, int collectCount)
Returns a MethodHandle that collects the requested incoming arguments, which must match the types in MethodType incomingArgs, into an array of arrayClass, called T.MethodHandle
asFixedArity()
Return a fixed arity version of the current MethodHandle.MethodHandle
asSpreader(int spreadPosition, Class<?> arrayClass, int spreadCount)
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.MethodHandle
asSpreader(Class<?> arrayClass, int spreadCount)
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.MethodHandle
asType(MethodType newType)
Returns a MethodHandle that presents as being of MethodType newType.MethodHandle
asVarargsCollector(Class<?> arrayParameter)
Create an varargs collector adapter on this MethodHandle.MethodHandle
bindTo(Object value)
Bind the value as the first argument to the MethodHandleObject
invoke(Object... args)
Invoke the receiver MethodHandle against the supplied arguments.Object
invokeExact(Object... args)
Invoke the receiver MethodHandle against the supplied arguments.Object
invokeWithArguments(Object... args)
Invoke the MethodHandle using an Object[] of arguments.Object
invokeWithArguments(List<?> args)
Helper method to callinvokeWithArguments(Object[])
.boolean
isVarargsCollector()
Determine whether this is anasVarargsCollector(Class)
MethodHandle.MethodType
type()
The MethodType of the MethodHandle.MethodHandle
withVarargs(boolean isVarArityNeeded)
Return a MethodHandle that is wrapped with an asVarargsCollector adapter if the handle is allowed to be variable arity.
-
-
-
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 typeClassCastException
- - 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 argumentsspreadCount
- - 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 spreadCountWrongMethodTypeException
- - 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 spreadarrayClass
- - the source array for the spread argumentsspreadCount
- - 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 spreadCountWrongMethodTypeException
- - 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 arrayClassNullPointerException
- 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 arrayClassNullPointerException
- 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 passedClassCastException
- if an argument cannot be converted
-
invokeWithArguments
public Object invokeWithArguments(List<?> args) throws Throwable, WrongMethodTypeException, ClassCastException, NullPointerException
Helper method to callinvokeWithArguments(Object[])
.- 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 passedClassCastException
- if an argument cannot be convertedNullPointerException
- if the args list is null
-
asVarargsCollector
public MethodHandle asVarargsCollector(Class<?> arrayParameter) throws IllegalArgumentException
Create an varargs collector adapter on this MethodHandle. ForasVarargsCollector(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
-
isVarargsCollector
public boolean isVarargsCollector()
Determine whether this is anasVarargsCollector(Class)
MethodHandle.- Returns:
- true if an
asVarargsCollector(Class)
handle, false otherwise.
-
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
-
bindTo
public MethodHandle bindTo(Object value) throws IllegalArgumentException, ClassCastException
Bind the value as the first argument to the MethodHandle- Parameters:
value
- the object to bind in- Returns:
- a new MethodHandle with the bound argument
- Throws:
IllegalArgumentException
- if the value is not compatible with the first argumentClassCastException
- if the value can't be cast to the type of the first argument
-
-