public class GuardedInvocation extends Object
GuardingDynamicLinker.getGuardedInvocation(LinkRequest, LinkerServices)
and GuardingTypeConverterFactory.convertToType(Class, Class, Supplier)
. It is an immutable tuple of an invocation method handle, a guard method handle that defines the applicability of the invocation handle, zero or more switch points that can be used for external invalidation of the invocation handle, and an exception type that if thrown during an invocation of the method handle also invalidates it. The invocation handle is suitable for invocation if the guard handle returns true for its arguments, and as long as any of the switch points are not invalidated, and as long as it does not throw an exception of the designated type. The guard, the switch points, and the exception type are all optional (a guarded invocation having none of them is unconditionally valid).Constructor | Description |
---|---|
GuardedInvocation |
Creates a new unconditional guarded invocation. |
GuardedInvocation |
Creates a new guarded invocation, with a guard method handle. |
GuardedInvocation |
Creates a new guarded invocation, with both a guard method handle and a switch point that can be used to invalidate it. |
GuardedInvocation |
Creates a new guarded invocation, with a guard method handle, any number of switch points that can be used to invalidate it, and an exception that if thrown when invoked also invalidates it. |
GuardedInvocation |
Creates a new guarded invocation, with a guard method handle, a switch point that can be used to invalidate it, and an exception that if thrown when invoked also invalidates it. |
GuardedInvocation |
Creates a new guarded invocation that can be invalidated by a switch point. |
Modifier and Type | Method | Description |
---|---|---|
GuardedInvocation |
addSwitchPoint |
Create a new guarded invocation with an added switch point. |
GuardedInvocation |
asType |
Changes the type of the invocation, as if MethodHandle.asType(MethodType) was applied to its invocation and its guard, if it has one (with return type changed to boolean, and parameter count potentially truncated for the guard). |
GuardedInvocation |
asType |
Changes the type of the invocation, as if MethodHandle.asType(MethodType) was applied to its invocation and its guard, if it has one (with return type changed to boolean for guard). |
GuardedInvocation |
asType |
Changes the type of the invocation, as if LinkerServices.asType(MethodHandle, MethodType) was applied to its invocation and its guard, if it has one (with return type changed to boolean, and parameter count potentially truncated for the guard). |
GuardedInvocation |
asTypeSafeReturn |
Changes the type of the invocation, as if LinkerServices.asTypeLosslessReturn(MethodHandle, MethodType) was applied to its invocation and LinkerServices.asType(MethodHandle, MethodType) applied to its guard, if it has one (with return type changed to boolean, and parameter count potentially truncated for the guard). |
MethodHandle |
compose |
Composes the invocation, guard, switch points, and the exception into a composite method handle that knows how to fall back when the guard fails or the invocation is invalidated. |
MethodHandle |
compose |
Composes the invocation, guard, switch points, and the exception into a composite method handle that knows how to fall back when the guard fails or the invocation is invalidated. |
GuardedInvocation |
dropArguments |
Makes an invocation that drops arguments in both the invocation and the guard (if it exists and has at least pos parameters) with MethodHandles.dropArguments(MethodHandle, int, Class...) . |
GuardedInvocation |
dropArguments |
Makes an invocation that drops arguments in both the invocation and the guard (if it exists and has at least pos parameters) with MethodHandles.dropArguments(MethodHandle, int, List) . |
GuardedInvocation |
filterArguments |
Applies argument filters to both the invocation and the guard (if it exists and has at least pos + 1 parameters) with MethodHandles.filterArguments(MethodHandle, int, MethodHandle...) . |
Class |
getException() |
Returns the exception type that if thrown by the invocation should invalidate the linkage of this guarded invocation. |
MethodHandle |
getGuard() |
Returns the guard method handle. |
MethodHandle |
getInvocation() |
Returns the invocation method handle. |
SwitchPoint[] |
getSwitchPoints() |
Returns the switch points that can be used to invalidate the linkage of this invocation handle. |
boolean |
hasBeenInvalidated() |
Returns true if and only if this guarded invocation has at least one invalidated switch point. |
GuardedInvocation |
replaceMethods |
Creates a new guarded invocation with different methods, preserving the switch point. |
public GuardedInvocation(MethodHandle invocation)
invocation
- the method handle representing the invocation. Must not be null.NullPointerException
- if invocation is null.public GuardedInvocation(MethodHandle invocation, MethodHandle guard)
invocation
- the method handle representing the invocation. Must not be null.guard
- the method handle representing the guard. Must have be compatible with the invocation
handle as per MethodHandles.guardWithTest(MethodHandle, MethodHandle, MethodHandle)
. For some useful guards, check out the Guards
class. It can be null to represent an unconditional invocation.NullPointerException
- if invocation is null.public GuardedInvocation(MethodHandle invocation, SwitchPoint switchPoint)
invocation
- the method handle representing the invocation. Must not be null.switchPoint
- the optional switch point that can be used to invalidate this linkage. It can be null. If it is null, this represents an unconditional invocation.NullPointerException
- if invocation is null.public GuardedInvocation(MethodHandle invocation, MethodHandle guard, SwitchPoint switchPoint)
invocation
- the method handle representing the invocation. Must not be null.guard
- the method handle representing the guard. Must have be compatible with the invocation
handle as per MethodHandles.guardWithTest(MethodHandle, MethodHandle, MethodHandle)
. For some useful guards, check out the Guards
class. It can be null. If both it and the switch point are null, this represents an unconditional invocation.switchPoint
- the optional switch point that can be used to invalidate this linkage.NullPointerException
- if invocation is null.public GuardedInvocation(MethodHandle invocation, MethodHandle guard, SwitchPoint switchPoint, Class<? extends Throwable> exception)
invocation
- the method handle representing the invocation. Must not be null.guard
- the method handle representing the guard. Must have be compatible with the invocation
handle as per MethodHandles.guardWithTest(MethodHandle, MethodHandle, MethodHandle)
. For some useful guards, check out the Guards
class. It can be null. If it and the switch point and the exception are all null, this represents an unconditional invocation.switchPoint
- the optional switch point that can be used to invalidate this linkage.exception
- the optional exception type that is when thrown by the invocation also invalidates it.NullPointerException
- if invocation is null.public GuardedInvocation(MethodHandle invocation, MethodHandle guard, SwitchPoint[] switchPoints, Class<? extends Throwable> exception)
invocation
- the method handle representing the invocation. Must not be null.guard
- the method handle representing the guard. Must have be compatible with the invocation
handle as per MethodHandles.guardWithTest(MethodHandle, MethodHandle, MethodHandle)
. For some useful guards, check out the Guards
class. It can be null. If it and the exception are both null, and no switch points were specified, this represents an unconditional invocation.switchPoints
- optional switch points that can be used to invalidate this linkage.exception
- the optional exception type that is when thrown by the invocation also invalidates it.NullPointerException
- if invocation is null.public MethodHandle getInvocation()
public MethodHandle getGuard()
public SwitchPoint[] getSwitchPoints()
public Class<? extends Throwable> getException()
public boolean hasBeenInvalidated()
public GuardedInvocation replaceMethods(MethodHandle newInvocation, MethodHandle newGuard)
newInvocation
- the new invocationnewGuard
- the new guardpublic GuardedInvocation addSwitchPoint(SwitchPoint newSwitchPoint)
newSwitchPoint
- new switch point. Can be null in which case this method return the current guarded invocation with no changes.public GuardedInvocation asType(MethodType newType)
MethodHandle.asType(MethodType)
was applied to its invocation and its guard, if it has one (with return type changed to boolean, and parameter count potentially truncated for the guard). If the invocation already is of the required type, returns this object.newType
- the new type of the invocation.public GuardedInvocation asType(LinkerServices linkerServices, MethodType newType)
LinkerServices.asType(MethodHandle, MethodType)
was applied to its invocation and its guard, if it has one (with return type changed to boolean, and parameter count potentially truncated for the guard). If the invocation already is of the required type, returns this object.linkerServices
- the linker services to use for the conversionnewType
- the new type of the invocation.public GuardedInvocation asTypeSafeReturn(LinkerServices linkerServices, MethodType newType)
LinkerServices.asTypeLosslessReturn(MethodHandle, MethodType)
was applied to its invocation and LinkerServices.asType(MethodHandle, MethodType)
applied to its guard, if it has one (with return type changed to boolean, and parameter count potentially truncated for the guard). If the invocation doesn't change its type, returns this object.linkerServices
- the linker services to use for the conversionnewType
- the new type of the invocation.public GuardedInvocation asType(CallSiteDescriptor desc)
MethodHandle.asType(MethodType)
was applied to its invocation and its guard, if it has one (with return type changed to boolean for guard). If the invocation already is of the required type, returns this object.desc
- a call descriptor whose method type is adapted.public GuardedInvocation filterArguments(int pos, MethodHandle... filters)
pos + 1
parameters) with MethodHandles.filterArguments(MethodHandle, int, MethodHandle...)
.pos
- the position of the first argument being filteredfilters
- the argument filterspublic GuardedInvocation dropArguments(int pos, List<Class<?>> valueTypes)
pos
parameters) with MethodHandles.dropArguments(MethodHandle, int, List)
.pos
- the position of the first argument being droppedvalueTypes
- the types of the values being droppedpublic GuardedInvocation dropArguments(int pos, Class<?>... valueTypes)
pos
parameters) with MethodHandles.dropArguments(MethodHandle, int, Class...)
.pos
- the position of the first argument being droppedvalueTypes
- the types of the values being droppedpublic MethodHandle compose(MethodHandle fallback)
fallback
- the fallback method handle for when a switch point is invalidated, a guard returns false, or invalidating exception is thrown.public MethodHandle compose(MethodHandle guardFallback, MethodHandle switchpointFallback, MethodHandle catchFallback)
guardFallback
- the fallback method handle in case guard returns false.switchpointFallback
- the fallback method handle in case a switch point is invalidated.catchFallback
- the fallback method in case the exception handler triggers.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.dynalink/jdk/dynalink/linker/GuardedInvocation.html