public class MethodHandles extends Object
Modifier and Type | Class and Description |
---|---|
static class |
MethodHandles.Lookup
A factory for creating MethodHandles that require access-checking on creation.
|
Modifier and Type | Method and Description |
---|---|
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 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 |
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 |
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,
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 MethodHandles.Lookup |
lookup()
Return a MethodHandles.Lookup object for the caller.
|
static 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 |
publicLookup()
Return a MethodHandles.Lookup object that is only able to access
public members. |
static <T extends Member> |
reflectAs(Class<T> expected,
MethodHandle target)
Gets the underlying Member of the provided
target 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.
|
public static MethodHandles.Lookup lookup()
public static MethodHandles.Lookup publicLookup()
public
members.public static <T extends Member> T reflectAs(Class<T> expected, MethodHandle target) throws SecurityException, NullPointerException, IllegalArgumentException, ClassCastException
target
MethodHandle. This is done through an unchecked crack of the MethodHandle.
Calling this method is equivalent to obtaining a lookup object capable of cracking the target
MethodHandle, calling
Lookup.revealDirect
on the target
MethodHandle and then calling MethodHandleInfo.reflectAs
.
If a SecurityManager is present, this method requires ReflectPermission("suppressAccessChecks")
.T
- the type of the underlying memberexpected
- the expected Class of the underlying membertarget
- the direct MethodHandle to be crackedtarget
MethodHandleSecurityException
- if the caller does not have the required permission (ReflectPermission("suppressAccessChecks")
)NullPointerException
- if either of the arguments are null
IllegalArgumentException
- if the target
MethodHandle is not a direct MethodHandleClassCastException
- if the underlying member is not of the expected
typepublic static MethodHandle exactInvoker(MethodType type) throws IllegalArgumentException
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.
type
- - the type of the invokeExact call to lookupIllegalArgumentException
- if the resulting MethodHandle would take too many parameters.public static MethodHandle invoker(MethodType type) throws IllegalArgumentException
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.
type
- - the type of the invoke call to lookupIllegalArgumentException
- if the resulting MethodHandle would take too many parameters.public static MethodHandle spreadInvoker(MethodType type, int fixedArgCount) throws IllegalArgumentException, NullPointerException
When the MethodHandle
is invoked, the argument 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.
type
- - the type of the invoke method to look upfixedArgCount
- - the number of fixed arguments in the methodtypeIllegalArgumentException
- 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 nullpublic static MethodHandle guardWithTest(MethodHandle guard, MethodHandle trueTarget, MethodHandle falseTarget) throws NullPointerException, IllegalArgumentException
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 falseNullPointerException
- - 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 argumentspublic static MethodHandle catchException(MethodHandle tryHandle, Class<? extends Throwable> throwableClass, MethodHandle catchHandle) throws NullPointerException, IllegalArgumentException
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.
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 tryHandleNullPointerException
- - 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)]public static MethodHandle identity(Class<?> classType) throws NullPointerException, IllegalArgumentException
classType
- - the type to use for the return and parameter typesNullPointerException
- - if the classType is nullIllegalArgumentException
- - if the classType is void.public static MethodHandle constant(Class<?> returnType, Object constantValue) throws NullPointerException, ClassCastException, IllegalArgumentException
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.
returnType
- - the return type of the MethodHandle.constantValue
- - the value to return from the MethodHandle when invokedNullPointerException
- - if the returnType is nullClassCastException
- - if the constantValue cannot be converted to returnTypeIllegalArgumentException
- - if the returnType is voidpublic static MethodHandle arrayElementGetter(Class<?> arrayType) throws IllegalArgumentException
int
index into the array.arrayType
- - the type of the arrayIllegalArgumentException
- - if arrayType is not actually an arraypublic static MethodHandle arrayElementSetter(Class<?> arrayType) throws IllegalArgumentException
int
index into the array,
and the third will be the item to write into the arrayarrayType
- - the type of the arrayIllegalArgumentException
- - if arrayType is not actually an arraypublic static MethodHandle throwException(Class<?> returnType, Class<? extends Throwable> exception)
returnType
- - The return type for the methodexception
- - the type of Throwable to accept as an argumentpublic static MethodHandle filterReturnValue(MethodHandle handle, MethodHandle filter) throws NullPointerException, IllegalArgumentException
If handle has a void return, filter must not take any parameters.
handle
- - the MethodHandle that will have its return value adaptedfilter
- - the MethodHandle that will do the return adaptation.NullPointerException
- - if handle or filter is nullIllegalArgumentException
- - if the return type of handle differs from the type of the only argument to filterpublic static MethodHandle filterArguments(MethodHandle handle, int startPosition, MethodHandle... filters) throws NullPointerException, IllegalArgumentException
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.
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 argumentsNullPointerException
- - 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 parameterspublic static MethodHandle foldArguments(MethodHandle handle, MethodHandle preprocessor) throws NullPointerException, IllegalArgumentException
handle
- - the handle to call after preprocessingpreprocessor
- - a methodhandle that preprocesses some of the incoming argumentsNullPointerException
- - 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 handlepublic static MethodHandle permuteArguments(MethodHandle handle, MethodType permuteType, int... permute) throws NullPointerException, IllegalArgumentException
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.
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 typeNullPointerException
- - 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()public static MethodHandle collectArguments(MethodHandle target, int pos, MethodHandle filter) throws NullPointerException, IllegalArgumentException
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 argumentsNullPointerException
- - 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 parameterspublic static MethodHandle dropArguments(MethodHandle originalHandle, int location, Class<?>... valueTypes)
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 removedpublic static MethodHandle dropArguments(MethodHandle originalHandle, int location, List<Class<?>> valueTypes)
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 removedpublic static MethodHandle explicitCastArguments(MethodHandle handle, MethodType type) throws NullPointerException, WrongMethodTypeException
The following conversions, beyond those allowed by MethodHandle.asType(MethodType)
are also allowed:
handle
- - the MethodHandle to invoke after converting the arguments to its typetype
- - the type to convert fromNullPointerException
- - if either of the arguments are nullWrongMethodTypeException
- - if an illegal conversion is requestedpublic static MethodHandle insertArguments(MethodHandle originalHandle, int location, Object... values)
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 insertedEclipse OpenJ9 website.
To raise a bug report or suggest an improvement create an Eclipse OpenJ9 issue.
Copyright © 1993, 2025 IBM Corp. and others.