1 /*
   2  * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * This file is available under and governed by the GNU General Public
  28  * License version 2 only, as published by the Free Software Foundation.
  29  * However, the following notice accompanied the original version of this
  30  * file, and Oracle licenses the original version of this file under the BSD
  31  * license:
  32  */
  33 /*
  34    Copyright 2009-2013 Attila Szegedi
  35 
  36    Licensed under both the Apache License, Version 2.0 (the "Apache License")
  37    and the BSD License (the "BSD License"), with licensee being free to
  38    choose either of the two at their discretion.
  39 
  40    You may not use this file except in compliance with either the Apache
  41    License or the BSD License.
  42 
  43    If you choose to use this file in compliance with the Apache License, the
  44    following notice applies to you:
  45 
  46        You may obtain a copy of the Apache License at
  47 
  48            http://www.apache.org/licenses/LICENSE-2.0
  49 
  50        Unless required by applicable law or agreed to in writing, software
  51        distributed under the License is distributed on an "AS IS" BASIS,
  52        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
  53        implied. See the License for the specific language governing
  54        permissions and limitations under the License.
  55 
  56    If you choose to use this file in compliance with the BSD License, the
  57    following notice applies to you:
  58 
  59        Redistribution and use in source and binary forms, with or without
  60        modification, are permitted provided that the following conditions are
  61        met:
  62        * Redistributions of source code must retain the above copyright
  63          notice, this list of conditions and the following disclaimer.
  64        * Redistributions in binary form must reproduce the above copyright
  65          notice, this list of conditions and the following disclaimer in the
  66          documentation and/or other materials provided with the distribution.
  67        * Neither the name of the copyright holder nor the names of
  68          contributors may be used to endorse or promote products derived from
  69          this software without specific prior written permission.
  70 
  71        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  72        IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  73        TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  74        PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER
  75        BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  76        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  77        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  78        BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  79        WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  80        OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  81        ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  82 */
  83 
  84 package jdk.dynalink.linker;
  85 
  86 import java.lang.invoke.MethodHandle;
  87 import java.lang.invoke.MethodHandles;
  88 import java.lang.invoke.MethodType;
  89 import java.lang.invoke.SwitchPoint;
  90 import java.util.List;
  91 import java.util.Objects;
  92 import java.util.function.Supplier;
  93 import jdk.dynalink.CallSiteDescriptor;
  94 import jdk.dynalink.linker.support.Guards;
  95 
  96 /**
  97  * Represents a conditionally valid method handle. Usually produced as a return
  98  * value of
  99  * {@link GuardingDynamicLinker#getGuardedInvocation(LinkRequest, LinkerServices)}
 100  * and
 101  * {@link GuardingTypeConverterFactory#convertToType(Class, Class, Supplier)}.
 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
 108  * as any of the switch points are not invalidated, and as long as it does not
 109  * throw an exception of the designated type. The guard, the switch points, and
 110  * the exception type are all optional (a guarded invocation having none of them
 111  * is unconditionally valid).
 112  */
 113 public class GuardedInvocation {
 114     private final MethodHandle invocation;
 115     private final MethodHandle guard;
 116     private final Class<? extends Throwable> exception;
 117     private final SwitchPoint[] switchPoints;
 118 
 119     /**
 120      * Creates a new unconditional guarded invocation. It is unconditional as it
 121      * has no invalidations.
 122      *
 123      * @param invocation the method handle representing the invocation. Must not
 124      * be null.
 125      * @throws NullPointerException if invocation is null.
 126      */
 127     public GuardedInvocation(final MethodHandle invocation) {
 128         this(invocation, null, (SwitchPoint)null, null);
 129     }
 130 
 131     /**
 132      * Creates a new guarded invocation, with a guard method handle.
 133      *
 134      * @param invocation the method handle representing the invocation. Must not
 135      * be null.
 136      * @param guard the method handle representing the guard. Must have be
 137      * compatible with the {@code invocation} handle as per
 138      * {@link MethodHandles#guardWithTest(MethodHandle, MethodHandle, MethodHandle)}.
 139      * For some useful guards, check out the {@link Guards} class. It can be
 140      * null to represent an unconditional invocation.
 141      * @throws NullPointerException if invocation is null.
 142      */
 143     public GuardedInvocation(final MethodHandle invocation, final MethodHandle guard) {
 144         this(invocation, guard, (SwitchPoint)null, null);
 145     }
 146 
 147     /**
 148      * Creates a new guarded invocation that can be invalidated by a switch
 149      * point.
 150      *
 151      * @param invocation the method handle representing the invocation. Must
 152      * not be null.
 153      * @param switchPoint the optional switch point that can be used to
 154      * invalidate this linkage. It can be null. If it is null, this represents
 155      * an unconditional invocation.
 156      * @throws NullPointerException if invocation is null.
 157      */
 158     public GuardedInvocation(final MethodHandle invocation, final SwitchPoint switchPoint) {
 159         this(invocation, null, switchPoint, null);
 160     }
 161 
 162     /**
 163      * Creates a new guarded invocation, with both a guard method handle and a
 164      * switch point that can be used to invalidate it.
 165      *
 166      * @param invocation the method handle representing the invocation. Must
 167      * not be null.
 168      * @param guard the method handle representing the guard. Must have be
 169      * compatible with the {@code invocation} handle as per
 170      * {@link MethodHandles#guardWithTest(MethodHandle, MethodHandle, MethodHandle)}.
 171      * For some useful guards, check out the {@link Guards} class. It can be
 172      * null. If both it and the switch point are null, this represents an
 173      * unconditional invocation.
 174      * @param switchPoint the optional switch point that can be used to
 175      * invalidate this linkage.
 176      * @throws NullPointerException if invocation is null.
 177      */
 178     public GuardedInvocation(final MethodHandle invocation, final MethodHandle guard, final SwitchPoint switchPoint) {
 179         this(invocation, guard, switchPoint, null);
 180     }
 181 
 182     /**
 183      * Creates a new guarded invocation, with a guard method handle, a
 184      * switch point that can be used to invalidate it, and an exception that if
 185      * thrown when invoked also invalidates it.
 186      *
 187      * @param invocation the method handle representing the invocation. Must not
 188      * be null.
 189      * @param guard the method handle representing the guard. Must have be
 190      * compatible with the {@code invocation} handle as per
 191      * {@link MethodHandles#guardWithTest(MethodHandle, MethodHandle, MethodHandle)}.
 192      * For some useful guards, check out the {@link Guards} class. It can be
 193      * null. If it and the switch point and the exception are all null, this
 194      * represents an unconditional invocation.
 195      * @param switchPoint the optional switch point that can be used to
 196      * invalidate this linkage.
 197      * @param exception the optional exception type that is when thrown by the
 198      * invocation also invalidates it.
 199      * @throws NullPointerException if invocation is null.
 200      */
 201     public GuardedInvocation(final MethodHandle invocation, final MethodHandle guard, final SwitchPoint switchPoint, final Class<? extends Throwable> exception) {
 202         this.invocation = Objects.requireNonNull(invocation);
 203         this.guard = guard;
 204         this.switchPoints = switchPoint == null ? null : new SwitchPoint[] { switchPoint };
 205         if (exception != null && !Throwable.class.isAssignableFrom(exception)) {
 206             throw new IllegalArgumentException(exception.getName() + " is not assignable from Throwable");
 207         }
 208         this.exception = exception;
 209     }
 210 
 211     /**
 212      * Creates a new guarded invocation, with a guard method handle, any number
 213      * of switch points that can be used to invalidate it, and an exception that
 214      * if thrown when invoked also invalidates it.
 215      *
 216      * @param invocation the method handle representing the invocation. Must not
 217      * be null.
 218      * @param guard the method handle representing the guard. Must have be
 219      * compatible with the {@code invocation} handle as per
 220      * {@link MethodHandles#guardWithTest(MethodHandle, MethodHandle, MethodHandle)}.
 221      * For some useful guards, check out the {@link Guards} class. It can be
 222      * null. If it and the exception are both null, and no switch points were
 223      * specified, this represents an unconditional invocation.
 224      * @param switchPoints optional switch points that can be used to
 225      * invalidate this linkage.
 226      * @param exception the optional exception type that is when thrown by the
 227      * invocation also invalidates it.
 228      * @throws NullPointerException if invocation is null.
 229      */
 230     public GuardedInvocation(final MethodHandle invocation, final MethodHandle guard, final SwitchPoint[] switchPoints, final Class<? extends Throwable> exception) {
 231         this.invocation = Objects.requireNonNull(invocation);
 232         this.guard = guard;
 233         this.switchPoints = switchPoints == null ? null : switchPoints.clone();
 234         if (exception != null && !Throwable.class.isAssignableFrom(exception)) {
 235             throw new IllegalArgumentException(exception.getName() + " is not assignable from Throwable");
 236         }
 237         this.exception = exception;
 238     }
 239 
 240     /**
 241      * Returns the invocation method handle.
 242      *
 243      * @return the invocation method handle. It will never be null.
 244      */
 245     public MethodHandle getInvocation() {
 246         return invocation;
 247     }
 248 
 249     /**
 250      * Returns the guard method handle.
 251      *
 252      * @return the guard method handle. Can be null.
 253      */
 254     public MethodHandle getGuard() {
 255         return guard;
 256     }
 257 
 258     /**
 259      * Returns the switch points that can be used to invalidate the linkage of
 260      * this invocation handle.
 261      *
 262      * @return the switch points that can be used to invalidate the linkage of
 263      * this invocation handle. Can be null.
 264      */
 265     public SwitchPoint[] getSwitchPoints() {
 266         return switchPoints == null ? null : switchPoints.clone();
 267     }
 268 
 269     /**
 270      * Returns the exception type that if thrown by the invocation should
 271      * invalidate the linkage of this guarded invocation.
 272      *
 273      * @return the exception type that if thrown should be used to invalidate
 274      * the linkage. Can be null.
 275      */
 276     public Class<? extends Throwable> getException() {
 277         return exception;
 278     }
 279 
 280     /**
 281      * Returns true if and only if this guarded invocation has at least one
 282      * invalidated switch point.
 283      * @return true if and only if this guarded invocation has at least one
 284      * invalidated switch point.
 285      */
 286     public boolean hasBeenInvalidated() {
 287         if (switchPoints == null) {
 288             return false;
 289         }
 290         for (final SwitchPoint sp : switchPoints) {
 291             if (sp.hasBeenInvalidated()) {
 292                 return true;
 293             }
 294         }
 295         return false;
 296     }
 297 
 298     /**
 299      * Creates a new guarded invocation with different methods, preserving the switch point.
 300      *
 301      * @param newInvocation the new invocation
 302      * @param newGuard the new guard
 303      * @return a new guarded invocation with the replaced methods and the same switch point as this invocation.
 304      */
 305     public GuardedInvocation replaceMethods(final MethodHandle newInvocation, final MethodHandle newGuard) {
 306         return new GuardedInvocation(newInvocation, newGuard, switchPoints, exception);
 307     }
 308 
 309     /**
 310      * Create a new guarded invocation with an added switch point.
 311      * @param newSwitchPoint new switch point. Can be null in which case this
 312      * method return the current guarded invocation with no changes.
 313      * @return a guarded invocation with the added switch point.
 314      */
 315     public GuardedInvocation addSwitchPoint(final SwitchPoint newSwitchPoint) {
 316         if (newSwitchPoint == null) {
 317             return this;
 318         }
 319 
 320         final SwitchPoint[] newSwitchPoints;
 321         if (switchPoints != null) {
 322             newSwitchPoints = new SwitchPoint[switchPoints.length + 1];
 323             System.arraycopy(switchPoints, 0, newSwitchPoints, 0, switchPoints.length);
 324             newSwitchPoints[switchPoints.length] = newSwitchPoint;
 325         } else {
 326             newSwitchPoints = new SwitchPoint[] { newSwitchPoint };
 327         }
 328 
 329         return new GuardedInvocation(invocation, guard, newSwitchPoints, exception);
 330     }
 331 
 332     private GuardedInvocation replaceMethodsOrThis(final MethodHandle newInvocation, final MethodHandle newGuard) {
 333         if (newInvocation == invocation && newGuard == guard) {
 334             return this;
 335         }
 336         return replaceMethods(newInvocation, newGuard);
 337     }
 338 
 339     /**
 340      * Changes the type of the invocation, as if
 341      * {@link MethodHandle#asType(MethodType)} was applied to its invocation
 342      * and its guard, if it has one (with return type changed to boolean, and
 343      * parameter count potentially truncated for the guard). If the invocation
 344      * already is of the required type, returns this object.
 345      * @param newType the new type of the invocation.
 346      * @return a guarded invocation with the new type applied to it.
 347      */
 348     public GuardedInvocation asType(final MethodType newType) {
 349         return replaceMethodsOrThis(invocation.asType(newType), guard == null ? null : Guards.asType(guard, newType));
 350     }
 351 
 352     /**
 353      * Changes the type of the invocation, as if
 354      * {@link LinkerServices#asType(MethodHandle, MethodType)} was applied to
 355      * its invocation and its guard, if it has one (with return type changed to
 356      * boolean, and parameter count potentially truncated for the guard). If the
 357      * invocation already is of the required type, returns this object.
 358      * @param linkerServices the linker services to use for the conversion
 359      * @param newType the new type of the invocation.
 360      * @return a guarded invocation with the new type applied to it.
 361      */
 362     public GuardedInvocation asType(final LinkerServices linkerServices, final MethodType newType) {
 363         return replaceMethodsOrThis(linkerServices.asType(invocation, newType), guard == null ? null :
 364             Guards.asType(linkerServices, guard, newType));
 365     }
 366 
 367     /**
 368      * Changes the type of the invocation, as if
 369      * {@link LinkerServices#asTypeLosslessReturn(MethodHandle, MethodType)} was
 370      * applied to its invocation and
 371      * {@link LinkerServices#asType(MethodHandle, MethodType)} applied to its
 372      * guard, if it has one (with return type changed to boolean, and parameter
 373      * count potentially truncated for the guard). If the invocation doesn't
 374      * change its type, returns this object.
 375      * @param linkerServices the linker services to use for the conversion
 376      * @param newType the new type of the invocation.
 377      * @return a guarded invocation with the new type applied to it.
 378      */
 379     public GuardedInvocation asTypeSafeReturn(final LinkerServices linkerServices, final MethodType newType) {
 380         return replaceMethodsOrThis(linkerServices.asTypeLosslessReturn(invocation, newType), guard == null ? null :
 381             Guards.asType(linkerServices, guard, newType));
 382     }
 383 
 384     /**
 385      * Changes the type of the invocation, as if
 386      * {@link MethodHandle#asType(MethodType)} was applied to its invocation
 387      * and its guard, if it has one (with return type changed to boolean for
 388      * guard). If the invocation already is of the required type, returns this
 389      * object.
 390      * @param desc a call descriptor whose method type is adapted.
 391      * @return a guarded invocation with the new type applied to it.
 392      */
 393     public GuardedInvocation asType(final CallSiteDescriptor desc) {
 394         return asType(desc.getMethodType());
 395     }
 396 
 397     /**
 398      * Applies argument filters to both the invocation and the guard
 399      * (if it exists and has at least {@code pos + 1} parameters) with
 400      * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)}.
 401      * @param pos the position of the first argument being filtered
 402      * @param filters the argument filters
 403      * @return a filtered invocation
 404      */
 405     public GuardedInvocation filterArguments(final int pos, final MethodHandle... filters) {
 406         return replaceMethods(MethodHandles.filterArguments(invocation, pos, filters),
 407                 guard == null || pos >= guard.type().parameterCount() ?
 408                         guard : MethodHandles.filterArguments(guard, pos, filters));
 409     }
 410 
 411     /**
 412      * Makes an invocation that drops arguments in both the invocation and the
 413      * guard (if it exists and has at least {@code pos} parameters) with
 414      * {@link MethodHandles#dropArguments(MethodHandle, int, List)}.
 415      * @param pos the position of the first argument being dropped
 416      * @param valueTypes the types of the values being dropped
 417      * @return an invocation that drops arguments
 418      */
 419     public GuardedInvocation dropArguments(final int pos, final List<Class<?>> valueTypes) {
 420         return replaceMethods(MethodHandles.dropArguments(invocation, pos, valueTypes),
 421                 guard == null || pos > guard.type().parameterCount() ?
 422                     guard : MethodHandles.dropArguments(guard, pos, valueTypes));
 423     }
 424 
 425     /**
 426      * Makes an invocation that drops arguments in both the invocation and the
 427      * guard (if it exists and has at least {@code pos} parameters) with
 428      * {@link MethodHandles#dropArguments(MethodHandle, int, Class...)}.
 429      * @param pos the position of the first argument being dropped
 430      * @param valueTypes the types of the values being dropped
 431      * @return an invocation that drops arguments
 432      */
 433     public GuardedInvocation dropArguments(final int pos, final Class<?>... valueTypes) {
 434         return replaceMethods(MethodHandles.dropArguments(invocation, pos, valueTypes),
 435                 guard == null || pos > guard.type().parameterCount() ?
 436                         guard : MethodHandles.dropArguments(guard, pos, valueTypes));
 437     }
 438 
 439 
 440     /**
 441      * Composes the invocation, guard, switch points, and the exception into a
 442      * composite method handle that knows how to fall back when the guard fails
 443      * or the invocation is invalidated.
 444      * @param fallback the fallback method handle for when a switch point is
 445      * invalidated, a guard returns false, or invalidating exception is thrown.
 446      * @return a composite method handle.
 447      */
 448     public MethodHandle compose(final MethodHandle fallback) {
 449         return compose(fallback, fallback, fallback);
 450     }
 451 
 452     /**
 453      * Composes the invocation, guard, switch points, and the exception into a
 454      * composite method handle that knows how to fall back when the guard fails
 455      * or the invocation is invalidated.
 456      * @param switchpointFallback the fallback method handle in case a switch
 457      * point is invalidated.
 458      * @param guardFallback the fallback method handle in case guard returns
 459      * false.
 460      * @param catchFallback the fallback method in case the exception handler
 461      * triggers.
 462      * @return a composite method handle.
 463      */
 464     public MethodHandle compose(final MethodHandle guardFallback, final MethodHandle switchpointFallback, final MethodHandle catchFallback) {
 465         final MethodHandle guarded =
 466                 guard == null ?
 467                         invocation :
 468                         MethodHandles.guardWithTest(
 469                                 guard,
 470                                 invocation,
 471                                 guardFallback);
 472 
 473         final MethodHandle catchGuarded =
 474                 exception == null ?
 475                         guarded :
 476                         MethodHandles.catchException(
 477                                 guarded,
 478                                 exception,
 479                                 MethodHandles.dropArguments(
 480                                     catchFallback,
 481                                     0,
 482                                     exception));
 483 
 484         if (switchPoints == null) {
 485             return catchGuarded;
 486         }
 487 
 488         MethodHandle spGuarded = catchGuarded;
 489         for (final SwitchPoint sp : switchPoints) {
 490             spGuarded = sp.guardWithTest(spGuarded, switchpointFallback);
 491         }
 492 
 493         return spGuarded;
 494     }
 495 }