LinkerServices.java revision 1645:15d52fdd9168
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 84package jdk.dynalink.linker; 85 86import java.lang.invoke.MethodHandle; 87import java.lang.invoke.MethodHandles; 88import java.lang.invoke.MethodType; 89import java.util.function.Supplier; 90import jdk.dynalink.DynamicLinker; 91import jdk.dynalink.DynamicLinkerFactory; 92import jdk.dynalink.SecureLookupSupplier; 93import jdk.dynalink.linker.ConversionComparator.Comparison; 94import 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 */ 100public 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} 253