- java.lang.Object
-
- java.lang.invoke.MethodHandles
-
public class MethodHandles extends Object
Factory class for creating and adapting MethodHandles.- Since:
- 1.7
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
MethodHandles.Lookup
A factory for creating MethodHandles that require access-checking on creation.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static MethodHandle
arrayConstructor(Class<?> arrayType)
Return a MethodHandle that produces an array of the requested type with the passed-in length.static MethodHandle
arrayElementGetter(Class<?> arrayType)
Return a MethodHandle able to read from the array.static MethodHandle
arrayElementSetter(Class<?> arrayType)
Return a MethodHandle able to write to the array.static VarHandle
arrayElementVarHandle(Class<?> arrayClass)
Factory method for creating a VarHandle for accessing elements of an array.static MethodHandle
arrayLength(Class<?> arrayType)
Return a MethodHandle that fetches the length from the passed-in array.static VarHandle
byteArrayViewVarHandle(Class<?> viewArrayClass, ByteOrder byteOrder)
Factory method for creating a VarHandle for accessing elements of a byte array using a view type.static VarHandle
byteBufferViewVarHandle(Class<?> viewArrayClass, ByteOrder byteOrder)
Factory method for creating a VarHandle for accessing elements of aByteBuffer
using a view type.static MethodHandle
catchException(MethodHandle tryHandle, Class<? extends Throwable> throwableClass, MethodHandle catchHandle)
Produce a MethodHandle that implements a try-catch block.static MethodHandle
collectArguments(MethodHandle target, int pos, MethodHandle filter)
Produce a MethodHandle that preprocesses some of the arguments by calling the filter handle.static MethodHandle
constant(Class<?> returnType, Object constantValue)
Create a MethodHandle that returns the constantValue on each invocation.static MethodHandle
countedLoop(MethodHandle loopCountHandle, MethodHandle initHandle, MethodHandle bodyHandle)
Produce a loop handle that executes a given number of iterations.static MethodHandle
countedLoop(MethodHandle startHandle, MethodHandle endHandle, MethodHandle initHandle, MethodHandle bodyHandle)
Produce a loop handle that iterates over a range of numbers by specifying the start value and the end value of the loop counter.static MethodHandle
doWhileLoop(MethodHandle initHandle, MethodHandle bodyHandle, MethodHandle predHandle)
Produce a loop handle that wraps an initializer, a loop body and a predicate to execute a do-while loop.static MethodHandle
dropArguments(MethodHandle originalHandle, int location, Class<?>... valueTypes)
This method returns a method handle that delegates to the original method handle, ignoring a particular range of arguments (starting at a given location and with given types).static MethodHandle
dropArguments(MethodHandle originalHandle, int location, List<Class<?>> valueTypes)
This method returns a method handle that delegates to the original method handle, ignoring a particular range of arguments (starting at a given location and with given types).static MethodHandle
dropArgumentsToMatch(MethodHandle originalHandle, int skippedArgumentCount, List<Class<?>> valueTypes, int location)
This method returns a method handle that delegates to the original method handle, skipping over a specified number of arguments at the given location.static MethodHandle
empty(MethodType targetMethodType)
Produces a constant method handle that ignores arguments and returns the default value for the return type of the requested MethodType.static MethodHandle
exactInvoker(MethodType type)
Return a MethodHandle that is the equivalent of calling MethodHandles.lookup().findVirtual(MethodHandle.class, "invokeExact", type).static MethodHandle
explicitCastArguments(MethodHandle handle, MethodType type)
Produce an adapter that converts the incoming arguments from type to the underlying MethodHandle's type and converts the return value as required.static MethodHandle
filterArguments(MethodHandle handle, int startPosition, MethodHandle... filters)
Produce a MethodHandle that adapts its arguments using the filter methodhandles before calling the underlying handle.static MethodHandle
filterReturnValue(MethodHandle handle, MethodHandle filter)
Return a MethodHandle that will adapt the return value of handle by running the filter on it and returning the result of the filter.static MethodHandle
foldArguments(MethodHandle handle, int foldPosition, MethodHandle preprocessor)
Produce a MethodHandle that preprocesses some of the arguments by calling the preprocessor handle.static MethodHandle
foldArguments(MethodHandle handle, MethodHandle preprocessor)
Produce a MethodHandle that preprocesses some of the arguments by calling the preprocessor handle.static MethodHandle
guardWithTest(MethodHandle guard, MethodHandle trueTarget, MethodHandle falseTarget)
Produce a MethodHandle that implements an if-else block.static MethodHandle
identity(Class<?> classType)
Produce a MethodHandle that acts as an identity function.static MethodHandle
insertArguments(MethodHandle originalHandle, int location, Object... values)
This method returns a method handle that delegates to the original method handle, adding a particular range of arguments (starting at a given location and with given types).static MethodHandle
invoker(MethodType type)
Return a MethodHandle that is the equivalent of calling MethodHandles.lookup().findVirtual(MethodHandle.class, "invoke", type).static MethodHandle
iteratedLoop(MethodHandle iteratorHandle, MethodHandle initHandle, MethodHandle bodyHandle)
Produce a loop handle that iterates over a range of values produced by anIterator<T>
Loop variables are updated by the return values of the corresponding step handles (including the loop body) in each iteration.static MethodHandles.Lookup
lookup()
Return a MethodHandles.Lookup object for the caller.static MethodHandle
loop(MethodHandle[]... handleClauses)
Produce a loop handle that wraps the logic of loop with an array of MethodHandle clausesstatic MethodHandle
permuteArguments(MethodHandle handle, MethodType permuteType, int... permute)
Produce a MethodHandle that will permute the incoming arguments according to the permute array.static MethodHandles.Lookup
privateLookupIn(Class<?> targetClass, MethodHandles.Lookup callerLookup)
Return a MethodHandles.Lookup object with full capabilities including the access to theprivate
members in the requested classstatic MethodHandles.Lookup
publicLookup()
Return a MethodHandles.Lookup object that is only able to accesspublic
members.static <T extends Member>
TreflectAs(Class<T> expected, MethodHandle target)
Gets the underlying Member of the providedtarget
MethodHandle.static MethodHandle
spreadInvoker(MethodType type, int fixedArgCount)
Return a MethodHandle that is able to invoke a MethodHandle of type as though by invoke after spreading the final Object[] parameter.static MethodHandle
throwException(Class<?> returnType, Class<? extends Throwable> exception)
Return a MethodHandle that will throw the passed in Exception object.static MethodHandle
tryFinally(MethodHandle tryHandle, MethodHandle finallyHandle)
Produce a MethodHandle that implements a try-finally block.static MethodHandle
varHandleExactInvoker(VarHandle.AccessMode accessMode, MethodType expectedType)
static MethodHandle
varHandleInvoker(VarHandle.AccessMode accessMode, MethodType expectedType)
static MethodHandle
whileLoop(MethodHandle initHandle, MethodHandle predHandle, MethodHandle bodyHandle)
Produce a loop handle that wraps an initializer, a loop body and a predicate to execute a while loop.static MethodHandle
zero(Class<?> targetType)
Produces a constant method handle with the default value for the requested target type.
-
-
-
Method Detail
-
lookup
public static MethodHandles.Lookup lookup()
Return a MethodHandles.Lookup object for the caller.- Returns:
- a MethodHandles.Lookup object
-
publicLookup
public static MethodHandles.Lookup publicLookup()
Return a MethodHandles.Lookup object that is only able to accesspublic
members.- Returns:
- a MethodHandles.Lookup object
-
privateLookupIn
public static MethodHandles.Lookup privateLookupIn(Class<?> targetClass, MethodHandles.Lookup callerLookup) throws NullPointerException, IllegalArgumentException, IllegalAccessException, SecurityException
Return a MethodHandles.Lookup object with full capabilities including the access to theprivate
members in the requested class- Parameters:
targetClass
- - the requested class containing private memberscallerLookup
- - a Lookup object specific to the caller- Returns:
- a MethodHandles.Lookup object with private access to the requested class
- Throws:
NullPointerException
- - if targetClass or callerLookup is nullIllegalArgumentException
- - if the requested Class is a primitive type or an array classIllegalAccessException
- - if access checking failsSecurityException
- - if the SecurityManager prevents access
-
reflectAs
public static <T extends Member> T reflectAs(Class<T> expected, MethodHandle target) throws SecurityException, NullPointerException, IllegalArgumentException, ClassCastException
Gets the underlying Member of the providedtarget
MethodHandle. This is done through an unchecked crack of the MethodHandle. Calling this method is equivalent to obtaining a lookup object capable of cracking thetarget
MethodHandle, callingLookup.revealDirect
on thetarget
MethodHandle and then callingMethodHandleInfo.reflectAs
. If a SecurityManager is present, this method requiresReflectPermission("suppressAccessChecks")
.- Type Parameters:
T
- the type of the underlying member- Parameters:
expected
- the expected Class of the underlying membertarget
- the direct MethodHandle to be cracked- Returns:
- the underlying member of the
target
MethodHandle - Throws:
SecurityException
- if the caller does not have the required permission (ReflectPermission("suppressAccessChecks")
)NullPointerException
- if either of the arguments arenull
IllegalArgumentException
- if thetarget
MethodHandle is not a direct MethodHandleClassCastException
- if the underlying member is not of theexpected
type
-
exactInvoker
public static MethodHandle exactInvoker(MethodType type) throws IllegalArgumentException
Return a MethodHandle that is the equivalent of calling MethodHandles.lookup().findVirtual(MethodHandle.class, "invokeExact", type).The MethodHandle has a method type that is the same as type except that an additional argument of MethodHandle will be added as the first parameter.
This method is not subject to the same security checks as a findVirtual call.
- Parameters:
type
- - the type of the invokeExact call to lookup- Returns:
- a MethodHandle equivalent to calling invokeExact on the first argument.
- Throws:
IllegalArgumentException
- if the resulting MethodHandle would take too many parameters.
-
invoker
public static MethodHandle invoker(MethodType type) throws IllegalArgumentException
Return a MethodHandle that is the equivalent of calling MethodHandles.lookup().findVirtual(MethodHandle.class, "invoke", type).The MethodHandle has a method type that is the same as type except that an additional argument of MethodHandle will be added as the first parameter.
This method is not subject to the same security checks as a findVirtual call.
- Parameters:
type
- - the type of the invoke call to lookup- Returns:
- a MethodHandle equivalent to calling invoke on the first argument.
- Throws:
IllegalArgumentException
- if the resulting MethodHandle would take too many parameters.
-
spreadInvoker
public static MethodHandle spreadInvoker(MethodType type, int fixedArgCount) throws IllegalArgumentException, NullPointerException
Return a MethodHandle that is able to invoke a MethodHandle of type as though by invoke after spreading the final Object[] parameter.When the
MethodHandle
is invoked, the argument array must contain exactly spreadCount arguments to be passed to the originalMethodHandle
. The array may be null in the case when spreadCount is zero. Incorrect argument array size will cause the method to throw anIllegalArgumentException
instead of invoking the target.- Parameters:
type
- - the type of the invoke method to look upfixedArgCount
- - the number of fixed arguments in the methodtype- Returns:
- a MethodHandle that invokes its first argument after spreading the Object array
- Throws:
IllegalArgumentException
- if the fixedArgCount is less than 0 or greater than type.ParameterCount(), or if the resulting MethodHandle would take too many parameters.NullPointerException
- if the type is null
-
guardWithTest
public static MethodHandle guardWithTest(MethodHandle guard, MethodHandle trueTarget, MethodHandle falseTarget) throws NullPointerException, IllegalArgumentException
Produce a MethodHandle that implements an if-else block. This MethodHandle is composed from three handles:- guard - a boolean returning handle that takes a subset of the arguments passed to the true and false targets
- trueTarget - the handle to call if the guard returns true
- falseTarget - the handle to call if the guard returns false
- Parameters:
guard
- - method handle returning boolean to determine which target to calltrueTarget
- - target method handle to call if guard is truefalseTarget
- - target method handle to call if guard is false- Returns:
- A MethodHandle that implements an if-else block.
- Throws:
NullPointerException
- - if any of the three method handles are nullIllegalArgumentException
- - if any of the following conditions are true: 1) trueTarget and falseTarget have different MethodTypes 2) the guard handle doesn't have a boolean return value 3) the guard handle doesn't take a subset of the target handle's arguments
-
catchException
public static MethodHandle catchException(MethodHandle tryHandle, Class<? extends Throwable> throwableClass, MethodHandle catchHandle) throws NullPointerException, IllegalArgumentException
Produce a MethodHandle that implements a try-catch block. This adapter acts as though the tryHandle were run inside a try block. If tryHandle throws an exception of type throwableClass, the catchHandle is invoked with the exception instance and the original arguments.The catchHandle may take a subset of the original arguments rather than the full set. Its first argument will be the exception instance.
Both the catchHandle and the tryHandle must have the same return type.
- Parameters:
tryHandle
- - the method handle to wrap with the try blockthrowableClass
- - the class of exception to be caught and handled by catchHandlecatchHandle
- - the method handle to call if an exception of type throwableClass is thrown by tryHandle- Returns:
- a method handle that will call catchHandle if tryHandle throws an exception of type throwableClass
- Throws:
NullPointerException
- - if any of the parameters are nullIllegalArgumentException
- - if tryHandle and catchHandle have different return types, or the catchHandle doesn't take a throwableClass as its first argument, of if catchHandle arguments[1-N] differ from tryHandle arguments[0-(N-1)]
-
tryFinally
public static MethodHandle tryFinally(MethodHandle tryHandle, MethodHandle finallyHandle) throws NullPointerException, IllegalArgumentException
Produce a MethodHandle that implements a try-finally block. This adapter acts as though the tryHandle runs inside a try block. If tryHandle throws an exception or returns as normal, the finallyHandle is invoked with the exception (if thrown out from tryHandle), the result from tryHandle plus the original arguments of tryHandle.The finallyHandle may take a subset of the original arguments rather than the full set. Its leading arguments will be the exception and the result from tryHandle which will be ignored if the return type of tryHandle is void.
Both the tryHandle and the finallyHandle must have the same return type.
- Parameters:
tryHandle
- - the method handle to wrap with the try blockfinallyHandle
- - the method handle to wrap with the finally block- Returns:
- a method handle that calls finallyHandle when tryHandle returns normally or throws out an exception
- Throws:
NullPointerException
- - if any of the parameters are nullIllegalArgumentException
- - if tryHandle and finallyHandle have different return types, or the finallyHandle doesn't take a Throwable type as its first argument, or the second argument of finallyHandle is inconsistent with the result type of tryHandle, of if finallyHandle arguments[1-N] differ from tryHandle arguments[0-(N-1)] in the case of the void result type of tryHandle, of if finallyHandle arguments[2-N] differ from tryHandle arguments[0-(N-2)] in the case of the non-void result type of tryHandle.
-
identity
public static MethodHandle identity(Class<?> classType) throws NullPointerException, IllegalArgumentException
Produce a MethodHandle that acts as an identity function. It will accept a single argument and return it.- Parameters:
classType
- - the type to use for the return and parameter types- Returns:
- an identity MethodHandle that returns its argument
- Throws:
NullPointerException
- - if the classType is nullIllegalArgumentException
- - if the classType is void.
-
constant
public static MethodHandle constant(Class<?> returnType, Object constantValue) throws NullPointerException, ClassCastException, IllegalArgumentException
Create a MethodHandle that returns the constantValue on each invocation.Conversions of the constantValue to the returnType occur if possible, otherwise a ClassCastException is thrown. For primitive returnType, widening primitive conversions are attempted. Otherwise, reference conversions are attempted.
- Parameters:
returnType
- - the return type of the MethodHandle.constantValue
- - the value to return from the MethodHandle when invoked- Returns:
- a MethodHandle that always returns the constantValue
- Throws:
NullPointerException
- - if the returnType is nullClassCastException
- - if the constantValue cannot be converted to returnTypeIllegalArgumentException
- - if the returnType is void
-
arrayElementGetter
public static MethodHandle arrayElementGetter(Class<?> arrayType) throws IllegalArgumentException
Return a MethodHandle able to read from the array. The MethodHandle's return type will be the same as the elements of the array. The MethodHandle will also accept two arguments - the first being the array, typed correctly, and the second will be theint
index into the array.- Parameters:
arrayType
- - the type of the array- Returns:
- a MethodHandle able to return values from the array
- Throws:
IllegalArgumentException
- - if arrayType is not actually an array
-
arrayElementSetter
public static MethodHandle arrayElementSetter(Class<?> arrayType) throws IllegalArgumentException
Return a MethodHandle able to write to the array. The MethodHandle will have a void return type and take three arguments: the first being the array, typed correctly, the second will be theint
index into the array, and the third will be the item to write into the array- Parameters:
arrayType
- - the type of the array- Returns:
- a MethodHandle able to write into the array
- Throws:
IllegalArgumentException
- - if arrayType is not actually an array
-
arrayElementVarHandle
public static VarHandle arrayElementVarHandle(Class<?> arrayClass) throws IllegalArgumentException
Factory method for creating a VarHandle for accessing elements of an array.- Parameters:
arrayClass
- The array type (not the component type)- Returns:
- A VarHandle that can access elements of arrays of type
arrayClass
- Throws:
NullPointerException
- IfarrayClass
is nullIllegalArgumentException
- IfarrayClass
is not an array type
-
byteArrayViewVarHandle
public static VarHandle byteArrayViewVarHandle(Class<?> viewArrayClass, ByteOrder byteOrder) throws IllegalArgumentException
Factory method for creating a VarHandle for accessing elements of a byte array using a view type.- Parameters:
viewArrayClass
- The view type to convert byte elements to.byteOrder
- The byte order to use when converting elements from byte to the view type- Returns:
- A VarHandle that can access elements of a byte array through a view type
- Throws:
IllegalArgumentException
- IfviewArrayClass
is not an array typeNullPointerException
- IfviewArrayClass
orbyteOrder
is null
-
byteBufferViewVarHandle
public static VarHandle byteBufferViewVarHandle(Class<?> viewArrayClass, ByteOrder byteOrder) throws IllegalArgumentException
Factory method for creating a VarHandle for accessing elements of aByteBuffer
using a view type.- Parameters:
viewArrayClass
- The view type to convert byte elements to.byteOrder
- The byte order to use when converting elements from byte to the view type- Returns:
- A VarHandle that can access elements of a
ByteBuffer
through a view type - Throws:
IllegalArgumentException
- IfviewArrayClass
is not an array typeNullPointerException
- IfviewArrayClass
orbyteOrder
is null
-
varHandleExactInvoker
public static MethodHandle varHandleExactInvoker(VarHandle.AccessMode accessMode, MethodType expectedType)
Create aMethodHandle
that is able to invoke a particularVarHandle.AccessMode
on aVarHandle
.When the
MethodHandle
is invoked, the arguments must match theMethodType
provided when theMethodHandle
was generated, plus the required preceding argument of typeVarHandle
.- Parameters:
accessMode
- - theVarHandle.AccessMode
to invoke when the generatedMethodHandle
is invoked.expectedType
- - the type to expect when invoking theVarHandle.AccessMode
.- Returns:
- a MethodHandle that invokes a particular
VarHandle.AccessMode
on aVarHandle
.
-
varHandleInvoker
public static MethodHandle varHandleInvoker(VarHandle.AccessMode accessMode, MethodType expectedType)
Create aMethodHandle
that is able to invoke a particularVarHandle.AccessMode
on aVarHandle
.When the
MethodHandle
is invoked, the arguments must be convertible to theMethodType
provided when theMethodHandle
was generated, plus the required preceding argument of typeVarHandle
.- Parameters:
accessMode
- - theVarHandle.AccessMode
to invoke when the generatedMethodHandle
is invoked.expectedType
- - the type to expect when invoking theVarHandle.AccessMode
.- Returns:
- a MethodHandle that invokes a particular
VarHandle.AccessMode
on aVarHandle
.
-
throwException
public static MethodHandle throwException(Class<?> returnType, Class<? extends Throwable> exception)
Return a MethodHandle that will throw the passed in Exception object. The return type is largely irrelevant as the method never completes normally. Any return type that is convenient can be used.- Parameters:
returnType
- - The return type for the methodexception
- - the type of Throwable to accept as an argument- Returns:
- a MethodHandle that throws the passed in exception object
-
filterReturnValue
public static MethodHandle filterReturnValue(MethodHandle handle, MethodHandle filter) throws NullPointerException, IllegalArgumentException
Return a MethodHandle that will adapt the return value of handle by running the filter on it and returning the result of the filter.If handle has a void return, filter must not take any parameters.
- Parameters:
handle
- - the MethodHandle that will have its return value adaptedfilter
- - the MethodHandle that will do the return adaptation.- Returns:
- a MethodHandle that will run the filter handle on the result of handle.
- Throws:
NullPointerException
- - if handle or filter is nullIllegalArgumentException
- - if the return type of handle differs from the type of the only argument to filter
-
filterArguments
public static MethodHandle filterArguments(MethodHandle handle, int startPosition, MethodHandle... filters) throws NullPointerException, IllegalArgumentException
Produce a MethodHandle that adapts its arguments using the filter methodhandles before calling the underlying handle.The type of the adapter is the type of the original handle with the filter argument types replacing their corresponding arguments. Each of the adapters must return the correct type for their corresponding argument.
If the filters array is empty or contains only null filters, the original handle will be returned.
- Parameters:
handle
- - the underlying methodhandle to call with the filtered argumentsstartPosition
- - the position to start applying the filters atfilters
- - the array of adapter handles to apply to the arguments- Returns:
- a MethodHandle that modifies the arguments by applying the filters before calling the underlying handle
- Throws:
NullPointerException
- - if handle or filters is nullIllegalArgumentException
- - if one of the filters is not applicable to the corresponding handle argument or there are more filters then arguments when starting at startPosition or startPosition is invalid or if the resulting MethodHandle would take too many parameters
-
foldArguments
public static MethodHandle foldArguments(MethodHandle handle, MethodHandle preprocessor) throws NullPointerException, IllegalArgumentException
Produce a MethodHandle that preprocesses some of the arguments by calling the preprocessor handle. If the preprocessor handle has a return type, it must be the same as the first argument type of the handle. If the preprocessor returns void, it does not contribute the first argument to the handle. In all cases, the preprocessor handle accepts a subset of the arguments for the handle.- Parameters:
handle
- - the handle to call after preprocessingpreprocessor
- - a methodhandle that preprocesses some of the incoming arguments- Returns:
- a MethodHandle that preprocesses some of the arguments to the handle before calling the next handle, possibly with an additional first argument
- Throws:
NullPointerException
- - if any of the arguments are nullIllegalArgumentException
- - if the preprocessor's return type is not void and it differs from the first argument type of the handle, or if the arguments taken by the preprocessor isn't a subset of the arguments to the handle
-
foldArguments
public static MethodHandle foldArguments(MethodHandle handle, int foldPosition, MethodHandle preprocessor) throws NullPointerException, IllegalArgumentException
Produce a MethodHandle that preprocesses some of the arguments by calling the preprocessor handle. If the preprocessor handle has a return type, it must be the same as the first argument type of the handle. If the preprocessor returns void, it does not contribute the first argument to the handle. In all cases, the preprocessor handle accepts a subset of the arguments for the handle.- Parameters:
handle
- - the handle to call after preprocessingfoldPosition
- - the starting position to fold argumentspreprocessor
- - a methodhandle that preprocesses some of the incoming arguments- Returns:
- a MethodHandle that preprocesses some of the arguments to the handle before calling the next handle, possibly with an additional first argument
- Throws:
NullPointerException
- - if any of the arguments are nullIllegalArgumentException
- - if the preprocessor's return type is not void and it differs from the first argument type of the handle, or if the arguments taken by the preprocessor isn't a subset of the arguments to the handle
-
permuteArguments
public static MethodHandle permuteArguments(MethodHandle handle, MethodType permuteType, int... permute) throws NullPointerException, IllegalArgumentException
Produce a MethodHandle that will permute the incoming arguments according to the permute array. The new handle will have a type of permuteType.The permutations can include duplicating or rearranging the arguments. The permute array must have the same number of items as there are parameters in the handle's type.
Each argument type must exactly match - no conversions are applied.
- Parameters:
handle
- - the original handle to call after permuting the argumentspermuteType
- - the new type of the adapter handlepermute
- - the reordering from the permuteType to the handle type- Returns:
- a MethodHandle that rearranges the arguments before calling the original handle
- Throws:
NullPointerException
- - if any of the arguments are nullIllegalArgumentException
- - if permute array is not the same length as handle.type().parameterCount() or if handle.type() and permuteType have different return types, or if the permute arguments don't match the handle.type()
-
collectArguments
public static MethodHandle collectArguments(MethodHandle target, int pos, MethodHandle filter) throws NullPointerException, IllegalArgumentException
Produce a MethodHandle that preprocesses some of the arguments by calling the filter handle. If the filter handle has a return type, it must be the same as the argument type at pos in the target arguments. If the filter returns void, it does not contribute an argument to the target arguments at pos. The filter handle consumes a subset (size equal to the filter's arity) of the returned handle's arguments, starting at pos.- Parameters:
target
- - the target to call after preprocessing the argumentspos
- - argument index in handle arguments where the filter will collect its arguments and/or insert its return value as an argument to the targetfilter
- - a MethodHandle that preprocesses some of the incoming arguments- Returns:
- a MethodHandle that preprocesses some of the arguments to the handle before calling the target with the new arguments
- Throws:
NullPointerException
- - if either target or filter are nullIllegalArgumentException
- - if the preprocessor's return type is not void and it differs from the target argument type at pos, if pos is not between 0 and the target's arity (exclusive for non-void filter, inclusive for void filter), or if the generated handle would have too many parameters
-
dropArguments
public static MethodHandle dropArguments(MethodHandle originalHandle, int location, Class<?>... valueTypes)
This method returns a method handle that delegates to the original method handle, ignoring a particular range of arguments (starting at a given location and with given types). The type of the returned method handle is the type of the original handle with the given types inserted in the parameter type list at the given location.- Parameters:
originalHandle
- - the original method handle to be transformedlocation
- - the location of the first argument to be removedvalueTypes
- - an array of the argument types to be removed- Returns:
- a MethodHandle - representing a transformed handle as described above
-
dropArguments
public static MethodHandle dropArguments(MethodHandle originalHandle, int location, List<Class<?>> valueTypes)
This method returns a method handle that delegates to the original method handle, ignoring a particular range of arguments (starting at a given location and with given types). The type of the returned method handle is the type of the original handle with the given types inserted in the parameter type list at the given location.- Parameters:
originalHandle
- - the original method handle to be transformedlocation
- - the location of the first argument to be removedvalueTypes
- - a List of the argument types to be removed- Returns:
- a MethodHandle - representing a transformed handle as described above
-
dropArgumentsToMatch
public static MethodHandle dropArgumentsToMatch(MethodHandle originalHandle, int skippedArgumentCount, List<Class<?>> valueTypes, int location)
This method returns a method handle that delegates to the original method handle, skipping over a specified number of arguments at the given location. The type of the returned method handle is the type of the original handle with the given types inserted in the parameter type list at the location after the skipped arguments.- Parameters:
originalHandle
- the original method handle to be transformedskippedArgumentCount
- the number of argument to be skipped from the original method handlevalueTypes
- a List of the argument types to be insertedlocation
- the (zero-indexed) location of the first argument to be removed- Returns:
- a MethodHandle representing a transformed handle as described above
-
explicitCastArguments
public static MethodHandle explicitCastArguments(MethodHandle handle, MethodType type) throws NullPointerException, WrongMethodTypeException
Produce an adapter that converts the incoming arguments from type to the underlying MethodHandle's type and converts the return value as required.The following conversions, beyond those allowed by
MethodHandle.asType(MethodType)
are also allowed:- A conversion to an interface is done without a cast
- A boolean is treated as a single bit unsigned integer and may be converted to other primitive types
- A primitive can also be cast using Java casting conversion if asType would have allowed Java method invocation conversion
- An unboxing conversion, possibly followed by a widening primitive conversion
- Parameters:
handle
- - the MethodHandle to invoke after converting the arguments to its typetype
- - the type to convert from- Returns:
- a MethodHandle which does the required argument and return conversions, if possible
- Throws:
NullPointerException
- - if either of the arguments are nullWrongMethodTypeException
- - if an illegal conversion is requested
-
insertArguments
public static MethodHandle insertArguments(MethodHandle originalHandle, int location, Object... values)
This method returns a method handle that delegates to the original method handle, adding a particular range of arguments (starting at a given location and with given types). The type of the returned method handle is the type of the original handle with the given types dropped from the parameter type list at the given location.- Parameters:
originalHandle
- - the original method handle to be transformedlocation
- - the location of the first argument to be insertedvalues
- - an array of the argument types to be inserted- Returns:
- a MethodHandle - representing a transformed handle as described above
-
arrayConstructor
public static MethodHandle arrayConstructor(Class<?> arrayType) throws NullPointerException, IllegalArgumentException
Return a MethodHandle that produces an array of the requested type with the passed-in length. The MethodHandle will have a MethodType of '(I)arrayType'.- Parameters:
arrayType
- The array class- Returns:
- a MethodHandle that produces an array of the requested type
- Throws:
NullPointerException
- if arrayType is nullIllegalArgumentException
- if arrayType is not an array- Since:
- 9
-
arrayLength
public static MethodHandle arrayLength(Class<?> arrayType) throws NullPointerException, IllegalArgumentException
Return a MethodHandle that fetches the length from the passed-in array. The MethodHandle will have a MethodType of '(arrayType)I'.- Parameters:
arrayType
- The array class- Returns:
- a MethodHandle that returns the length of the passed-in array
- Throws:
NullPointerException
- if arrayType is nullIllegalArgumentException
- if arrayType is not an array
-
empty
public static MethodHandle empty(MethodType targetMethodType) throws NullPointerException
Produces a constant method handle that ignores arguments and returns the default value for the return type of the requested MethodType.- Parameters:
targetMethodType
- the requested MethodType- Returns:
- a MethodHandle returning the default value for the return type of the requested MethodType
- Throws:
NullPointerException
- - if the requested MethodType is null
-
zero
public static MethodHandle zero(Class<?> targetType) throws NullPointerException
Produces a constant method handle with the default value for the requested target type.- Parameters:
targetType
- the requested target type- Returns:
- a MethodHandle without arguments that returns the default value of the requested target type
- Throws:
NullPointerException
- - if the requested target type is null
-
loop
public static MethodHandle loop(MethodHandle[]... handleClauses) throws IllegalArgumentException
Produce a loop handle that wraps the logic of loop with an array of MethodHandle clauses- Parameters:
handleClauses
- an array of MethodHandle clauses and each clause consists of initializer, step, predicate and finalizer.- Returns:
- a MethodHandle that represents the loop operation
- Throws:
IllegalArgumentException
- - if passed-in arguments are invalid or any constraint for clause is violated
-
whileLoop
public static MethodHandle whileLoop(MethodHandle initHandle, MethodHandle predHandle, MethodHandle bodyHandle) throws NullPointerException, IllegalArgumentException
Produce a loop handle that wraps an initializer, a loop body and a predicate to execute a while loop. Loop variables are updated by the return values of the corresponding step handles (including the loop body) in each iteration.- Parameters:
initHandle
- a MethodHandle that represents the initial value of loop variablepredHandle
- a MethodHandle that represents the loop conditionbodyHandle
- a MethodHandle that wraps the loop body to update the loop variable with its return value during iteration- Returns:
- a MethodHandle that represents the loop operation
- Throws:
NullPointerException
- - if the body handle or the predicate handle are nullIllegalArgumentException
- - if passed-in arguments are invalid or any constraint for while loop is violated
-
doWhileLoop
public static MethodHandle doWhileLoop(MethodHandle initHandle, MethodHandle bodyHandle, MethodHandle predHandle) throws NullPointerException, IllegalArgumentException
Produce a loop handle that wraps an initializer, a loop body and a predicate to execute a do-while loop. Loop variables are updated by the return values of the corresponding step handles (including the loop body) in each iteration.- Parameters:
initHandle
- a MethodHandle that represents the initial value of loop variablebodyHandle
- a MethodHandle that wraps the loop body to update the loop variable with its return value during iterationpredHandle
- a MethodHandle that represents the loop condition- Returns:
- a MethodHandle that represents the loop operation
- Throws:
NullPointerException
- - if the body handle or the predicate handle are nullIllegalArgumentException
- - if passed-in arguments are invalid or any constraint for while loop is violated
-
countedLoop
public static MethodHandle countedLoop(MethodHandle startHandle, MethodHandle endHandle, MethodHandle initHandle, MethodHandle bodyHandle) throws NullPointerException, IllegalArgumentException
Produce a loop handle that iterates over a range of numbers by specifying the start value and the end value of the loop counter. Loop variables are updated by the return values of the corresponding step handles (including the loop body) in each iteration.- Parameters:
startHandle
- a MethodHandle that returns the start value (inclusive) of the counter in a loopendHandle
- a MethodHandle that returns the end value (exclusive) of the counter in a loopinitHandle
- a MethodHandle that represents the initial value of loop variablebodyHandle
- a MethodHandle that wraps the loop body to update the loop variable with its return value during iteration- Returns:
- a MethodHandle that represents the loop operation
- Throws:
NullPointerException
- - if any of the start, end and body handle is nullIllegalArgumentException
- - if passed-in arguments are invalid
-
countedLoop
public static MethodHandle countedLoop(MethodHandle loopCountHandle, MethodHandle initHandle, MethodHandle bodyHandle) throws NullPointerException, IllegalArgumentException
Produce a loop handle that executes a given number of iterations.- Parameters:
loopCountHandle
- a MethodHandle that returns the number of iterations for loop counterinitHandle
- a MethodHandle that represents the initial value of loop variablebodyHandle
- a MethodHandle that wraps the loop body to update the loop variable with its return value during iteration- Returns:
- a MethodHandle that represents the loop operation
- Throws:
NullPointerException
- - if any of the loop count and body handle is nullIllegalArgumentException
- - if passed-in arguments are invalid
-
iteratedLoop
public static MethodHandle iteratedLoop(MethodHandle iteratorHandle, MethodHandle initHandle, MethodHandle bodyHandle) throws NullPointerException, IllegalArgumentException
Produce a loop handle that iterates over a range of values produced by anIterator<T>
Loop variables are updated by the return values of the corresponding step handles (including the loop body) in each iteration.- Parameters:
iteratorHandle
- a MethodHandle that returns Iterator or a subtype to start the loopinitHandle
- a MethodHandle that represents the initial value of loop variablebodyHandle
- a MethodHandle that wraps the loop body to update the loop variable with its return value during iteration- Returns:
- a MethodHandle that represents the Iterator-based loop operation
- Throws:
NullPointerException
- - if the loop body is nullIllegalArgumentException
- - if passed-in arguments are invalid
-
-