public interface LinkerServices
GuardingDynamicLinker
instances by
the DynamicLinker
that owns them.Modifier and Type | Method | Description |
---|---|---|
MethodHandle |
asType(MethodHandle handle,
MethodType fromType) |
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(MethodHandle handle,
MethodType fromType) |
Similar to
asType(MethodHandle, MethodType) except it treats
return value type conversion specially. |
boolean |
canConvert(Class<?> from,
Class<?> to) |
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(Class<?> sourceType,
Class<?> targetType1,
Class<?> targetType2) |
Determines which of the two type conversions from a source type to the
two target types is preferred.
|
MethodHandle |
filterInternalObjects(MethodHandle target) |
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(LinkRequest linkRequest) |
Creates a guarded invocation delegating back to the
DynamicLinker
that exposes this linker services object. |
MethodHandle |
getTypeConverter(Class<?> sourceType,
Class<?> targetType) |
Given a source and target type, returns a method handle that converts
between them.
|
<T> T |
getWithLookup(Supplier<T> operation,
SecureLookupSupplier lookupSupplier) |
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.GuardingTypeConverterFactory.convertToType(Class, Class, Supplier)
Copyright © 2015, 2016, Oracle and/or its affiliates. All rights reserved.
DRAFT 9-Ubuntu+0-9b144-1