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.util.function.Supplier;

    90 import jdk.dynalink.DynamicLinker;

    91 import jdk.dynalink.DynamicLinkerFactory;

    92 import jdk.dynalink.SecureLookupSupplier;

    93 import jdk.dynalink.linker.ConversionComparator.Comparison;

    94 import jdk.dynalink.linker.support.TypeUtilities;

    95 

    96 /**

    97  * Interface for services provided to {@link GuardingDynamicLinker} instances by

    98  * the {@link DynamicLinker} that owns them.

    99  */

   100 public interface LinkerServices {

   101     /**

   102      * Similar to {@link MethodHandle#asType(MethodType)} except it also hooks

   103      * in method handles produced by all available

   104      * {@link GuardingTypeConverterFactory} implementations, providing for

   105      * language-specific type coercing of parameters. It will apply

   106      * {@link MethodHandle#asType(MethodType)} for all primitive-to-primitive,

   107      * wrapper-to-primitive, primitive-to-wrapper conversions as well as for all

   108      * upcasts. For all other conversions, it'll insert

   109      * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)}

   110      * with composite filters provided by {@link GuardingTypeConverterFactory}

   111      * implementations.

   112      *

   113      * @param handle target method handle

   114      * @param fromType the types of source arguments

   115      * @return a method handle that is a suitable combination of

   116      * {@link MethodHandle#asType(MethodType)},

   117      * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)},

   118      * and {@link MethodHandles#filterReturnValue(MethodHandle, MethodHandle)}

   119      * with {@link GuardingTypeConverterFactory}-produced type converters as

   120      * filters.

   121      */

   122     public MethodHandle asType(MethodHandle handle, MethodType fromType);

   123 

   124     /**

   125      * Similar to {@link #asType(MethodHandle, MethodType)} except it treats

   126      * return value type conversion specially. It only converts the return type

   127      * of the method handle when it can be done using a conversion that loses

   128      * neither precision nor magnitude, otherwise it leaves it unchanged. These

   129      * are the only return value conversions that should be performed by

   130      * individual language-specific linkers, and

   131      * {@link DynamicLinkerFactory#setPrelinkTransformer(GuardedInvocationTransformer)

   132      * pre-link transformer of the dynamic linker} should implement the strategy

   133      * for dealing with potentially lossy return type conversions in a manner

   134      * specific to the language runtime where the call site is located.

   135      *

   136      * @param handle target method handle

   137      * @param fromType the types of source arguments

   138      * @return a method handle that is a suitable combination of

   139      * {@link MethodHandle#asType(MethodType)}, and

   140      * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)}

   141      * with {@link GuardingTypeConverterFactory}-produced type converters as filters.

   142      */

   143     public default MethodHandle asTypeLosslessReturn(final MethodHandle handle, final MethodType fromType) {

   144         final Class<?> handleReturnType = handle.type().returnType();

   145         return asType(handle, TypeUtilities.isConvertibleWithoutLoss(handleReturnType, fromType.returnType()) ?

   146                 fromType : fromType.changeReturnType(handleReturnType));

   147     }

   148 

   149     /**

   150      * Given a source and target type, returns a method handle that converts

   151      * between them. Never returns null; in worst case it will return an

   152      * identity conversion (that might fail for some values at runtime). You

   153      * rarely need to use this method directly and should mostly rely on

   154      * {@link #asType(MethodHandle, MethodType)} instead. This method is needed

   155      * when you need to reuse existing type conversion machinery outside the

   156      * context of processing a link request.

   157      * @param sourceType the type to convert from

   158      * @param targetType the type to convert to

   159      * @return a method handle performing the conversion.

   160      */

   161     public MethodHandle getTypeConverter(Class<?> sourceType, Class<?> targetType);

   162 

   163     /**

   164      * Returns true if there might exist a conversion between the requested

   165      * types (either an automatic JVM conversion, or one provided by any

   166      * available {@link GuardingTypeConverterFactory}), or false if there

   167      * definitely does not exist a conversion between the requested types. Note

   168      * that returning true does not guarantee that the conversion will succeed

   169      * at runtime for all values (especially if the "from" or "to" types are

   170      * sufficiently generic), but returning false guarantees that it would fail.

   171      *

   172      * @param from the source type for the conversion

   173      * @param to the target type for the conversion

   174      * @return true if there can be a conversion, false if there can not.

   175      */

   176     public boolean canConvert(Class<?> from, Class<?> to);

   177 

   178     /**

   179      * Creates a guarded invocation delegating back to the {@link DynamicLinker}

   180      * that exposes this linker services object. The dynamic linker will then

   181      * itself delegate the linking to all of its managed

   182      * {@link GuardingDynamicLinker}s including potentially this one if no

   183      * linker responds earlier, so beware of infinite recursion. You'll

   184      * typically craft the link request so that it will be different than the

   185      * one you are currently trying to link.

   186      *

   187      * @param linkRequest a request for linking the invocation

   188      * @return a guarded invocation linked by some of the guarding dynamic

   189      * linkers managed by the top-level dynamic linker. Can be null if no

   190      * available linker is able to link the invocation. You will typically use

   191      * the elements of the returned invocation to compose your own invocation.

   192      * @throws Exception in case the top-level linker throws an exception

   193      */

   194     public GuardedInvocation getGuardedInvocation(LinkRequest linkRequest) throws Exception;

   195 

   196     /**

   197      * Determines which of the two type conversions from a source type to the

   198      * two target types is preferred. This is used for dynamic overloaded method

   199      * resolution. If the source type is convertible to exactly one target type

   200      * with a method invocation conversion, it is chosen, otherwise available

   201      * {@link ConversionComparator}s are consulted.

   202      * @param sourceType the source type.

   203      * @param targetType1 one potential target type

   204      * @param targetType2 another potential target type.

   205      * @return one of Comparison constants that establish which – if any

   206      * – of the target types is preferable for the conversion.

   207      */

   208     public Comparison compareConversion(Class<?> sourceType, Class<?> targetType1, Class<?> targetType2);

   209 

   210     /**

   211      * Modifies the method handle so that any parameters that can receive

   212      * potentially internal language runtime objects will have a filter added on

   213      * them to prevent them from escaping, potentially by wrapping them. It can

   214      * also potentially add an unwrapping filter to the return value. Basically

   215      * transforms the method handle using the transformer configured by

   216      * {@link DynamicLinkerFactory#setInternalObjectsFilter(MethodHandleTransformer)}.

   217      * @param target the target method handle

   218      * @return a method handle with parameters and/or return type potentially

   219      * filtered for wrapping and unwrapping.

   220      */

   221     public MethodHandle filterInternalObjects(final MethodHandle target);

   222 

   223     /**

   224      * Executes an operation within the context of a particular

   225      * {@code MethodHandles.Lookup} lookup object. Normally, methods on

   226      * {@code LinkerServices} are invoked as part of the linking mechanism in

   227      * which case Dynalink internally maintains a per-thread current lookup

   228      * (the one belonging to the descriptor of the call site being linked). This

   229      * lookup can be retrieved by any {@link GuardingTypeConverterFactory}

   230      * involved in linking if it needs to generate lookup-sensitive converters.

   231      * However, linker services' methods can be invoked outside the linking

   232      * process too when implementing invocation-time dispatch schemes, invoking

   233      * conversions at runtime, etc. If it becomes necessary to use any type

   234      * converter in this situation, and it needs a lookup, it will normally only

   235      * get {@link MethodHandles#publicLookup()} as the thread is not engaged in

   236      * a linking operation. If there is a way to meaningfully associate the

   237      * operation to the context of some caller class, consider performing it

   238      * within an invocation of this method and passing a full-strength lookup

   239      * for that class, as it will associate that lookup with the current thread

   240      * for the duration of the operation. Note that since you are passing a

   241      * {@link SecureLookupSupplier}, any invoked type converter factories will

   242      * still need to hold the necessary runtime permission to be able to get the

   243      * lookup should they need it.

   244      * @param <T> the type of the return value provided by the passed-in supplier.

   245      * @param operation the operation to execute in context of the specified lookup.

   246      * @param lookupSupplier secure supplier of the lookup

   247      * @return the return value of the action

   248      * @throws NullPointerException if either action or lookupSupplier are null.

   249      * @see GuardingTypeConverterFactory#convertToType(Class, Class, Supplier)

   250      */

   251     public <T> T getWithLookup(final Supplier<T> operation, final SecureLookupSupplier lookupSupplier);

   252 }