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 Redistribution and use in source and binary forms, with or without 37 modification, are permitted provided that the following conditions are 38 met: 39 * Redistributions of source code must retain the above copyright 40 notice, this list of conditions and the following disclaimer. 41 * Redistributions in binary form must reproduce the above copyright 42 notice, this list of conditions and the following disclaimer in the 43 documentation and/or other materials provided with the distribution. 44 * Neither the name of the copyright holder nor the names of 45 contributors may be used to endorse or promote products derived from 46 this software without specific prior written permission. 47 48 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 49 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 50 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 51 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER 52 BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 53 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 54 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 55 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 56 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 57 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 58 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 59 */ 60 61 package jdk.dynalink.linker; 62 63 import java.lang.invoke.MethodHandle; 64 import java.lang.invoke.MethodHandles; 65 import java.lang.invoke.MethodType; 66 import java.util.function.Supplier; 67 import jdk.dynalink.DynamicLinker; 68 import jdk.dynalink.DynamicLinkerFactory; 69 import jdk.dynalink.SecureLookupSupplier; 70 import jdk.dynalink.linker.ConversionComparator.Comparison; 71 import jdk.dynalink.linker.support.TypeUtilities; 72 73 /** 74 * Interface for services provided to {@link GuardingDynamicLinker} instances by 75 * the {@link DynamicLinker} that owns them. 76 */ 77 public interface LinkerServices { 78 /** 79 * Similar to {@link MethodHandle#asType(MethodType)} except it also hooks 80 * in method handles produced by all available 81 * {@link GuardingTypeConverterFactory} implementations, providing for 82 * language-specific type coercing of parameters. It will apply 83 * {@link MethodHandle#asType(MethodType)} for all primitive-to-primitive, 84 * wrapper-to-primitive, primitive-to-wrapper conversions as well as for all 85 * upcasts. For all other conversions, it'll insert 86 * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)} 87 * with composite filters provided by {@link GuardingTypeConverterFactory} 88 * implementations. 89 * 90 * @param handle target method handle 91 * @param fromType the types of source arguments 92 * @return a method handle that is a suitable combination of 93 * {@link MethodHandle#asType(MethodType)}, 94 * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)}, 95 * and {@link MethodHandles#filterReturnValue(MethodHandle, MethodHandle)} 96 * with {@link GuardingTypeConverterFactory}-produced type converters as 97 * filters. 98 */ asType(MethodHandle handle, MethodType fromType)99 public MethodHandle asType(MethodHandle handle, MethodType fromType); 100 101 /** 102 * Similar to {@link #asType(MethodHandle, MethodType)} except it treats 103 * return value type conversion specially. It only converts the return type 104 * of the method handle when it can be done using a conversion that loses 105 * neither precision nor magnitude, otherwise it leaves it unchanged. These 106 * are the only return value conversions that should be performed by 107 * individual language-specific linkers, and 108 * {@link DynamicLinkerFactory#setPrelinkTransformer(GuardedInvocationTransformer) 109 * pre-link transformer of the dynamic linker} should implement the strategy 110 * for dealing with potentially lossy return type conversions in a manner 111 * specific to the language runtime where the call site is located. 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)}, and 117 * {@link MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)} 118 * with {@link GuardingTypeConverterFactory}-produced type converters as filters. 119 */ asTypeLosslessReturn(final MethodHandle handle, final MethodType fromType)120 public default MethodHandle asTypeLosslessReturn(final MethodHandle handle, final MethodType fromType) { 121 final Class<?> handleReturnType = handle.type().returnType(); 122 return asType(handle, TypeUtilities.isConvertibleWithoutLoss(handleReturnType, fromType.returnType()) ? 123 fromType : fromType.changeReturnType(handleReturnType)); 124 } 125 126 /** 127 * Given a source and target type, returns a method handle that converts 128 * between them. Never returns null; in worst case it will return an 129 * identity conversion (that might fail for some values at runtime). You 130 * rarely need to use this method directly and should mostly rely on 131 * {@link #asType(MethodHandle, MethodType)} instead. This method is needed 132 * when you need to reuse existing type conversion machinery outside the 133 * context of processing a link request. 134 * @param sourceType the type to convert from 135 * @param targetType the type to convert to 136 * @return a method handle performing the conversion. 137 */ getTypeConverter(Class<?> sourceType, Class<?> targetType)138 public MethodHandle getTypeConverter(Class<?> sourceType, Class<?> targetType); 139 140 /** 141 * Returns true if there might exist a conversion between the requested 142 * types (either an automatic JVM conversion, or one provided by any 143 * available {@link GuardingTypeConverterFactory}), or false if there 144 * definitely does not exist a conversion between the requested types. Note 145 * that returning true does not guarantee that the conversion will succeed 146 * at runtime for all values (especially if the "from" or "to" types are 147 * sufficiently generic), but returning false guarantees that it would fail. 148 * 149 * @param from the source type for the conversion 150 * @param to the target type for the conversion 151 * @return true if there can be a conversion, false if there can not. 152 */ canConvert(Class<?> from, Class<?> to)153 public boolean canConvert(Class<?> from, Class<?> to); 154 155 /** 156 * Creates a guarded invocation delegating back to the {@link DynamicLinker} 157 * that exposes this linker services object. The dynamic linker will then 158 * itself delegate the linking to all of its managed 159 * {@link GuardingDynamicLinker}s including potentially this one if no 160 * linker responds earlier, so beware of infinite recursion. You'll 161 * typically craft the link request so that it will be different than the 162 * one you are currently trying to link. 163 * 164 * @param linkRequest a request for linking the invocation 165 * @return a guarded invocation linked by some of the guarding dynamic 166 * linkers managed by the top-level dynamic linker. Can be null if no 167 * available linker is able to link the invocation. You will typically use 168 * the elements of the returned invocation to compose your own invocation. 169 * @throws Exception in case the top-level linker throws an exception 170 */ getGuardedInvocation(LinkRequest linkRequest)171 public GuardedInvocation getGuardedInvocation(LinkRequest linkRequest) throws Exception; 172 173 /** 174 * Determines which of the two type conversions from a source type to the 175 * two target types is preferred. This is used for dynamic overloaded method 176 * resolution. If the source type is convertible to exactly one target type 177 * with a method invocation conversion, it is chosen, otherwise available 178 * {@link ConversionComparator}s are consulted. 179 * @param sourceType the source type. 180 * @param targetType1 one potential target type 181 * @param targetType2 another potential target type. 182 * @return one of Comparison constants that establish which – if any 183 * – of the target types is preferable for the conversion. 184 */ compareConversion(Class<?> sourceType, Class<?> targetType1, Class<?> targetType2)185 public Comparison compareConversion(Class<?> sourceType, Class<?> targetType1, Class<?> targetType2); 186 187 /** 188 * Modifies the method handle so that any parameters that can receive 189 * potentially internal language runtime objects will have a filter added on 190 * them to prevent them from escaping, potentially by wrapping them. It can 191 * also potentially add an unwrapping filter to the return value. Basically 192 * transforms the method handle using the transformer configured by 193 * {@link DynamicLinkerFactory#setInternalObjectsFilter(MethodHandleTransformer)}. 194 * @param target the target method handle 195 * @return a method handle with parameters and/or return type potentially 196 * filtered for wrapping and unwrapping. 197 */ filterInternalObjects(final MethodHandle target)198 public MethodHandle filterInternalObjects(final MethodHandle target); 199 200 /** 201 * Executes an operation within the context of a particular 202 * {@code MethodHandles.Lookup} lookup object. Normally, methods on 203 * {@code LinkerServices} are invoked as part of the linking mechanism in 204 * which case Dynalink internally maintains a per-thread current lookup 205 * (the one belonging to the descriptor of the call site being linked). This 206 * lookup can be retrieved by any {@link GuardingTypeConverterFactory} 207 * involved in linking if it needs to generate lookup-sensitive converters. 208 * However, linker services' methods can be invoked outside the linking 209 * process too when implementing invocation-time dispatch schemes, invoking 210 * conversions at runtime, etc. If it becomes necessary to use any type 211 * converter in this situation, and it needs a lookup, it will normally only 212 * get {@link MethodHandles#publicLookup()} as the thread is not engaged in 213 * a linking operation. If there is a way to meaningfully associate the 214 * operation to the context of some caller class, consider performing it 215 * within an invocation of this method and passing a full-strength lookup 216 * for that class, as it will associate that lookup with the current thread 217 * for the duration of the operation. Note that since you are passing a 218 * {@link SecureLookupSupplier}, any invoked type converter factories will 219 * still need to hold the necessary runtime permission to be able to get the 220 * lookup should they need it. 221 * @param <T> the type of the return value provided by the passed-in supplier. 222 * @param operation the operation to execute in context of the specified lookup. 223 * @param lookupSupplier secure supplier of the lookup 224 * @return the return value of the action 225 * @throws NullPointerException if either action or lookupSupplier are null. 226 * @see GuardingTypeConverterFactory#convertToType(Class, Class, Supplier) 227 */ getWithLookup(final Supplier<T> operation, final SecureLookupSupplier lookupSupplier)228 public <T> T getWithLookup(final Supplier<T> operation, final SecureLookupSupplier lookupSupplier); 229 } 230