public interface LinkerServices
GuardingDynamicLinker
instances by the DynamicLinker
that owns them.Modifier and Type | Method | Description |
---|---|---|
MethodHandle |
asType |
Similar to MethodHandle.asType(MethodType) except it also hooks in method handles produced by all available GuardingTypeConverterFactory implementations, providing for language-specific type coercing of parameters. |
default MethodHandle |
asTypeLosslessReturn |
Similar to asType(MethodHandle, MethodType) except it treats return value type conversion specially. |
boolean |
canConvert |
Returns true if there might exist a conversion between the requested types (either an automatic JVM conversion, or one provided by any available GuardingTypeConverterFactory ), or false if there definitely does not exist a conversion between the requested types. |
ConversionComparator.Comparison |
compareConversion |
Determines which of the two type conversions from a source type to the two target types is preferred. |
MethodHandle |
filterInternalObjects |
Modifies the method handle so that any parameters that can receive potentially internal language runtime objects will have a filter added on them to prevent them from escaping, potentially by wrapping them. |
GuardedInvocation |
getGuardedInvocation |
Creates a guarded invocation delegating back to the DynamicLinker that exposes this linker services object. |
MethodHandle |
getTypeConverter |
Given a source and target type, returns a method handle that converts between them. |
<T> T |
getWithLookup |
Executes an operation within the context of a particular MethodHandles.Lookup lookup object. |
MethodHandle asType(MethodHandle handle, MethodType fromType)
MethodHandle.asType(MethodType)
except it also hooks in method handles produced by all available GuardingTypeConverterFactory
implementations, providing for language-specific type coercing of parameters. It will apply MethodHandle.asType(MethodType)
for all primitive-to-primitive, wrapper-to-primitive, primitive-to-wrapper conversions as well as for all upcasts. For all other conversions, it'll insert MethodHandles.filterArguments(MethodHandle, int, MethodHandle...)
with composite filters provided by GuardingTypeConverterFactory
implementations.handle
- target method handlefromType
- the types of source argumentsMethodHandle.asType(MethodType)
, MethodHandles.filterArguments(MethodHandle, int, MethodHandle...)
, and MethodHandles.filterReturnValue(MethodHandle, MethodHandle)
with GuardingTypeConverterFactory
-produced type converters as filters.default MethodHandle asTypeLosslessReturn(MethodHandle handle, MethodType fromType)
asType(MethodHandle, MethodType)
except it treats return value type conversion specially. It only converts the return type of the method handle when it can be done using a conversion that loses neither precision nor magnitude, otherwise it leaves it unchanged. These are the only return value conversions that should be performed by individual language-specific linkers, and pre-link transformer of the dynamic linker
should implement the strategy for dealing with potentially lossy return type conversions in a manner specific to the language runtime where the call site is located.handle
- target method handlefromType
- the types of source argumentsMethodHandle.asType(MethodType)
, and MethodHandles.filterArguments(MethodHandle, int, MethodHandle...)
with GuardingTypeConverterFactory
-produced type converters as filters.MethodHandle getTypeConverter(Class<?> sourceType, Class<?> targetType)
asType(MethodHandle, MethodType)
instead. This method is needed when you need to reuse existing type conversion machinery outside the context of processing a link request.sourceType
- the type to convert fromtargetType
- the type to convert toboolean canConvert(Class<?> from, Class<?> to)
GuardingTypeConverterFactory
), or false if there definitely does not exist a conversion between the requested types. Note that returning true does not guarantee that the conversion will succeed at runtime for all values (especially if the "from" or "to" types are sufficiently generic), but returning false guarantees that it would fail.from
- the source type for the conversionto
- the target type for the conversionGuardedInvocation getGuardedInvocation(LinkRequest linkRequest) throws Exception
DynamicLinker
that exposes this linker services object. The dynamic linker will then itself delegate the linking to all of its managed GuardingDynamicLinker
s including potentially this one if no linker responds earlier, so beware of infinite recursion. You'll typically craft the link request so that it will be different than the one you are currently trying to link.linkRequest
- a request for linking the invocationException
- in case the top-level linker throws an exceptionConversionComparator.Comparison compareConversion(Class<?> sourceType, Class<?> targetType1, Class<?> targetType2)
ConversionComparator
s are consulted.sourceType
- the source type.targetType1
- one potential target typetargetType2
- another potential target type.MethodHandle filterInternalObjects(MethodHandle target)
DynamicLinkerFactory.setInternalObjectsFilter(MethodHandleTransformer)
.target
- the target method handle<T> T getWithLookup(Supplier<T> operation, SecureLookupSupplier lookupSupplier)
MethodHandles.Lookup
lookup object. Normally, methods on LinkerServices
are invoked as part of the linking mechanism in which case Dynalink internally maintains a per-thread current lookup (the one belonging to the descriptor of the call site being linked). This lookup can be retrieved by any GuardingTypeConverterFactory
involved in linking if it needs to generate lookup-sensitive converters. However, linker services' methods can be invoked outside the linking process too when implementing invocation-time dispatch schemes, invoking conversions at runtime, etc. If it becomes necessary to use any type converter in this situation, and it needs a lookup, it will normally only get MethodHandles.publicLookup()
as the thread is not engaged in a linking operation. If there is a way to meaningfully associate the operation to the context of some caller class, consider performing it within an invocation of this method and passing a full-strength lookup for that class, as it will associate that lookup with the current thread for the duration of the operation. Note that since you are passing a SecureLookupSupplier
, any invoked type converter factories will still need to hold the necessary runtime permission to be able to get the lookup should they need it.T
- the type of the return value provided by the passed-in supplier.operation
- the operation to execute in context of the specified lookup.lookupSupplier
- secure supplier of the lookupNullPointerException
- if either action or lookupSupplier are null.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.dynalink/jdk/dynalink/linker/LinkerServices.html