dynalink/linker/GuardedInvocation.java

102  * It is an immutable tuple of an invocation method handle, a guard method
103  * handle that defines the applicability of the invocation handle, zero or more
104  * switch points that can be used for external invalidation of the invocation
105  * handle, and an exception type that if thrown during an invocation of the
106  * method handle also invalidates it. The invocation handle is suitable for
107  * invocation if the guard handle returns true for its arguments, and as long
110  * the exception type are all optional (a guarded invocation having none of them
114     private final MethodHandle invocation;
120      * Creates a new unconditional guarded invocation. It is unconditional as it
123      * @param invocation the method handle representing the invocation. Must not
125      * @throws NullPointerException if invocation is null.
127     public GuardedInvocation(final MethodHandle invocation) {
128         this(invocation, null, (SwitchPoint)null, null);
132      * Creates a new guarded invocation, with a guard method handle.
134      * @param invocation the method handle representing the invocation. Must not
137      * compatible with the {@code invocation} handle as per
140      * null to represent an unconditional invocation.
141      * @throws NullPointerException if invocation is null.
143     public GuardedInvocation(final MethodHandle invocation, final MethodHandle guard) {
144         this(invocation, guard, (SwitchPoint)null, null);
148      * Creates a new guarded invocation that can be invalidated by a switch
151      * @param invocation the method handle representing the invocation. Must
155      * an unconditional invocation.
156      * @throws NullPointerException if invocation is null.
158     public GuardedInvocation(final MethodHandle invocation, final SwitchPoint switchPoint) {
159         this(invocation, null, switchPoint, null);
163      * Creates a new guarded invocation, with both a guard method handle and a
166      * @param invocation the method handle representing the invocation. Must
169      * compatible with the {@code invocation} handle as per
173      * unconditional invocation.
176      * @throws NullPointerException if invocation is null.
178     public GuardedInvocation(final MethodHandle invocation, final MethodHandle guard, final SwitchPoint switchPoint) {
179         this(invocation, guard, switchPoint, null);
183      * Creates a new guarded invocation, with a guard method handle, a
187      * @param invocation the method handle representing the invocation. Must not
190      * compatible with the {@code invocation} handle as per
194      * represents an unconditional invocation.
198      * invocation also invalidates it.
199      * @throws NullPointerException if invocation is null.
201     public GuardedInvocation(final MethodHandle invocation, final MethodHandle guard, final SwitchPoint switchPoint, final Class<? extends Throwable> exception) {
202         this.invocation = Objects.requireNonNull(invocation);
212      * Creates a new guarded invocation, with a guard method handle, any number
216      * @param invocation the method handle representing the invocation. Must not
219      * compatible with the {@code invocation} handle as per
223      * specified, this represents an unconditional invocation.
227      * invocation also invalidates it.
228      * @throws NullPointerException if invocation is null.
230     public GuardedInvocation(final MethodHandle invocation, final MethodHandle guard, final SwitchPoint[] switchPoints, final Class<? extends Throwable> exception) {
231         this.invocation = Objects.requireNonNull(invocation);
241      * Returns the invocation method handle.
243      * @return the invocation method handle. It will never be null.
246         return invocation;
260      * this invocation handle.
263      * this invocation handle. Can be null.
270      * Returns the exception type that if thrown by the invocation should
271      * invalidate the linkage of this guarded invocation.
281      * Returns true if and only if this guarded invocation has at least one
283      * @return true if and only if this guarded invocation has at least one
299      * Creates a new guarded invocation with different methods, preserving the switch point.
301      * @param newInvocation the new invocation
303      * @return a new guarded invocation with the replaced methods and the same switch point as this invocation.
310      * Create a new guarded invocation with an added switch point.
312      * method return the current guarded invocation with no changes.
313      * @return a guarded invocation with the added switch point.
329         return new GuardedInvocation(invocation, guard, newSwitchPoints, exception);
333         if (newInvocation == invocation && newGuard == guard) {
340      * Changes the type of the invocation, as if
341      * {@link MethodHandle#asType(MethodType)} was applied to its invocation
343      * parameter count potentially truncated for the guard). If the invocation
345      * @param newType the new type of the invocation.
346      * @return a guarded invocation with the new type applied to it.
349         return replaceMethodsOrThis(invocation.asType(newType), guard == null ? null : Guards.asType(guard, newType));
353      * Changes the type of the invocation, as if
355      * its invocation and its guard, if it has one (with return type changed to
357      * invocation already is of the required type, returns this object.
359      * @param newType the new type of the invocation.
360      * @return a guarded invocation with the new type applied to it.
363         return replaceMethodsOrThis(linkerServices.asType(invocation, newType), guard == null ? null :
368      * Changes the type of the invocation, as if
370      * applied to its invocation and
373      * count potentially truncated for the guard). If the invocation doesn't
376      * @param newType the new type of the invocation.
377      * @return a guarded invocation with the new type applied to it.
380         return replaceMethodsOrThis(linkerServices.asTypeLosslessReturn(invocation, newType), guard == null ? null :
385      * Changes the type of the invocation, as if
386      * {@link MethodHandle#asType(MethodType)} was applied to its invocation
388      * guard). If the invocation already is of the required type, returns this
391      * @return a guarded invocation with the new type applied to it.
398      * Applies argument filters to both the invocation and the guard
403      * @return a filtered invocation
406         return replaceMethods(MethodHandles.filterArguments(invocation, pos, filters),
412      * Makes an invocation that drops arguments in both the invocation and the
417      * @return an invocation that drops arguments
420         return replaceMethods(MethodHandles.dropArguments(invocation, pos, valueTypes),
426      * Makes an invocation that drops arguments in both the invocation and the
431      * @return an invocation that drops arguments
434         return replaceMethods(MethodHandles.dropArguments(invocation, pos, valueTypes),
441      * Composes the invocation, guard, switch points, and the exception into a
443      * or the invocation is invalidated.
453      * Composes the invocation, guard, switch points, and the exception into a
455      * or the invocation is invalidated.
467                         invocation :
470                                 invocation,