OpenJDK 1.23 · jdk.dynalink.LinkerServicesImpl · APIdia, the JavaDoc alternative

Modifier and Type	Class and Description
private static class	LinkerServicesImpl.LinkerException Used to marshal a checked exception out of Supplier.get() in getGuardedInvocation.

Modifier and Type	Field and Description
private final MethodHandleTransformer	internalObjectsFilter
private static final ThreadLocal<SecureLookupSupplier>	threadLookupSupplier
private final GuardingDynamicLinker	topLevelLinker
private final TypeConverterFactory	typeConverterFactory

Access	Constructor and Description
pack-priv	LinkerServicesImpl(final TypeConverterFactory the type converter factory exposed by the services. typeConverterFactory, final GuardingDynamicLinker the top level linker used by the services. topLevelLinker, final MethodHandleTransformer a method handle transformer that is supposed to act as the implementation of this services' `filterInternalObjects(java.lang.invoke.MethodHandle)` method. internalObjectsFilter) Creates a new linker services object.

Method Summary

Modifier and Type	Method and Description
public MethodHandle	asType(final MethodHandle target method handle handle, final MethodType the types of source arguments fromType) Implements jdk.dynalink.linker.LinkerServices.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.
public boolean	canConvert(final Class<?> the source type for the conversion from, final Class<?> the target type for the conversion to) Implements jdk.dynalink.linker.LinkerServices.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.
public ConversionComparator.Comparison	compareConversion(final Class<?> the source type. sourceType, final Class<?> one potential target type targetType1, final Class<?> another potential target type. targetType2) Implements jdk.dynalink.linker.LinkerServices.compareConversion. Determines which of the two type conversions from a source type to the two target types is preferred.
public MethodHandle	filterInternalObjects(final MethodHandle the target method handle target) Implements jdk.dynalink.linker.LinkerServices.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.
pack-priv static MethodHandles.Lookup	getCurrentLookup()
public GuardedInvocation	getGuardedInvocation(final LinkRequest a request for linking the invocation linkRequest) Implements jdk.dynalink.linker.LinkerServices.getGuardedInvocation. Creates a guarded invocation delegating back to the `DynamicLinker` that exposes this linker services object.
public MethodHandle	getTypeConverter(final Class<?> the type to convert from sourceType, final Class<?> the type to convert to targetType) Implements jdk.dynalink.linker.LinkerServices.getTypeConverter. Given a source and target type, returns a method handle that converts between them.
public <T> T	getWithLookup(final Supplier<T> the operation to execute in context of the specified lookup. operation, final SecureLookupSupplier secure supplier of the lookup lookupSupplier) Implements jdk.dynalink.linker.LinkerServices.getWithLookup. Executes an operation within the context of a particular `MethodHandles.Lookup` lookup object.
private static <T> T	getWithLookupInternal(final Supplier<T> operation, final SecureLookupSupplier lookupSupplier)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

internalObjectsFilter	back to summary
private final MethodHandleTransformer internalObjectsFilter

threadLookupSupplier	back to summary
private static final ThreadLocal<SecureLookupSupplier> threadLookupSupplier

topLevelLinker	back to summary
private final GuardingDynamicLinker topLevelLinker

typeConverterFactory	back to summary
private final TypeConverterFactory typeConverterFactory

LinkerServicesImpl	back to summary
pack-priv LinkerServicesImpl(final TypeConverterFactory typeConverterFactory, final GuardingDynamicLinker topLevelLinker, final MethodHandleTransformer internalObjectsFilter) Creates a new linker services object. Parameters typeConverterFactory:TypeConverterFactory the type converter factory exposed by the services. topLevelLinker:GuardingDynamicLinker the top level linker used by the services. internalObjectsFilter:MethodHandleTransformer a method handle transformer that is supposed to act as the implementation of this services' `filterInternalObjects(java.lang.invoke.MethodHandle)` method.

Method Detail

asType back to summary

asType	back to summary
public MethodHandle asType(final MethodHandle handle, final MethodType fromType) Implements jdk.dynalink.linker.LinkerServices.asType. Doc from jdk.dynalink.linker.LinkerServices.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. 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. Parameters handle:MethodHandle target method handle fromType:MethodType the types of source arguments Returns:MethodHandle a method handle that is a suitable combination of `MethodHandle#asType(MethodType)`, `MethodHandles#filterArguments(MethodHandle, int, MethodHandle...)`, and `MethodHandles#filterReturnValue(MethodHandle, MethodHandle)` with `GuardingTypeConverterFactory`-produced type converters as filters. Annotations @Override

public MethodHandle asType(final MethodHandle handle, final MethodType fromType)

Implements jdk.dynalink.linker.LinkerServices.asType.

Doc from jdk.dynalink.linker.LinkerServices.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. 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.

Parameters

handle:MethodHandle: target method handle
fromType:MethodType: the types of source arguments

Returns:MethodHandle

a method handle that is a suitable combination of MethodHandle#asType(MethodType), MethodHandles#filterArguments(MethodHandle, int, MethodHandle...), and MethodHandles#filterReturnValue(MethodHandle, MethodHandle) with GuardingTypeConverterFactory-produced type converters as filters.

Annotations

@Override

canConvert back to summary

canConvert	back to summary
public boolean canConvert(final Class<?> from, final Class<?> to) Implements jdk.dynalink.linker.LinkerServices.canConvert. Doc from jdk.dynalink.linker.LinkerServices.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. 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. Parameters from:Class<?> the source type for the conversion to:Class<?> the target type for the conversion Returns:boolean true if there can be a conversion, false if there can not. Annotations @Override

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

Implements jdk.dynalink.linker.LinkerServices.canConvert.

Doc from jdk.dynalink.linker.LinkerServices.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. 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.

Parameters

from:Class<?>: the source type for the conversion
to:Class<?>: the target type for the conversion

Returns:boolean

true if there can be a conversion, false if there can not.

Annotations

@Override

compareConversion back to summary

compareConversion	back to summary
public ConversionComparator.Comparison compareConversion(final Class<?> sourceType, final Class<?> targetType1, final Class<?> targetType2) Implements jdk.dynalink.linker.LinkerServices.compareConversion. Doc from jdk.dynalink.linker.LinkerServices.compareConversion. Determines which of the two type conversions from a source type to the two target types is preferred. This is used for dynamic overloaded method resolution. If the source type is convertible to exactly one target type with a method invocation conversion, it is chosen, otherwise available `ConversionComparator`s are consulted. Parameters sourceType:Class<?> the source type. targetType1:Class<?> one potential target type targetType2:Class<?> another potential target type. Returns:ConversionComparator.Comparison one of Comparison constants that establish which – if any – of the target types is preferable for the conversion. Annotations @Override

public ConversionComparator.Comparison compareConversion(final Class<?> sourceType, final Class<?> targetType1, final Class<?> targetType2)

Implements jdk.dynalink.linker.LinkerServices.compareConversion.

Doc from jdk.dynalink.linker.LinkerServices.compareConversion.

Determines which of the two type conversions from a source type to the two target types is preferred. This is used for dynamic overloaded method resolution. If the source type is convertible to exactly one target type with a method invocation conversion, it is chosen, otherwise available ConversionComparators are consulted.

Parameters

sourceType:Class<?>: the source type.
targetType1:Class<?>: one potential target type
targetType2:Class<?>: another potential target type.

Returns:ConversionComparator.Comparison

one of Comparison constants that establish which – if any – of the target types is preferable for the conversion.

Annotations

@Override

filterInternalObjects back to summary

filterInternalObjects	back to summary
public MethodHandle filterInternalObjects(final MethodHandle target) Implements jdk.dynalink.linker.LinkerServices.filterInternalObjects. Doc from jdk.dynalink.linker.LinkerServices.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. It can also potentially add an unwrapping filter to the return value. Basically transforms the method handle using the transformer configured by `DynamicLinkerFactory#setInternalObjectsFilter(MethodHandleTransformer)`. Parameters target:MethodHandle the target method handle Returns:MethodHandle a method handle with parameters and/or return type potentially filtered for wrapping and unwrapping. Annotations @Override

public MethodHandle filterInternalObjects(final MethodHandle target)

Implements jdk.dynalink.linker.LinkerServices.filterInternalObjects.

Doc from jdk.dynalink.linker.LinkerServices.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. It can also potentially add an unwrapping filter to the return value. Basically transforms the method handle using the transformer configured by DynamicLinkerFactory#setInternalObjectsFilter(MethodHandleTransformer).

Parameters

target:MethodHandle: the target method handle

Returns:MethodHandle

a method handle with parameters and/or return type potentially filtered for wrapping and unwrapping.

Annotations

@Override

getCurrentLookup	back to summary
pack-priv static MethodHandles.Lookup getCurrentLookup()

getGuardedInvocation back to summary

getGuardedInvocation	back to summary
public GuardedInvocation getGuardedInvocation(final LinkRequest linkRequest) throws Exception Implements jdk.dynalink.linker.LinkerServices.getGuardedInvocation. Doc from jdk.dynalink.linker.LinkerServices.getGuardedInvocation. Creates a guarded invocation delegating back to the `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. Parameters linkRequest:LinkRequest a request for linking the invocation Returns:GuardedInvocation a guarded invocation linked by some of the guarding dynamic linkers managed by the top-level dynamic linker. Can be null if no available linker is able to link the invocation. You will typically use the elements of the returned invocation to compose your own invocation. Annotations @Override Exceptions Exception: in case the top-level linker throws an exception

public GuardedInvocation getGuardedInvocation(final LinkRequest linkRequest) throws Exception

Implements jdk.dynalink.linker.LinkerServices.getGuardedInvocation.

Doc from jdk.dynalink.linker.LinkerServices.getGuardedInvocation.

Creates a guarded invocation delegating back to the DynamicLinker that exposes this linker services object. The dynamic linker will then itself delegate the linking to all of its managed GuardingDynamicLinkers 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.

Parameters

linkRequest:LinkRequest: a request for linking the invocation

Returns:GuardedInvocation

a guarded invocation linked by some of the guarding dynamic linkers managed by the top-level dynamic linker. Can be null if no available linker is able to link the invocation. You will typically use the elements of the returned invocation to compose your own invocation.

Annotations

@Override

Exceptions

Exception:: in case the top-level linker throws an exception

getTypeConverter back to summary

getTypeConverter	back to summary
public MethodHandle getTypeConverter(final Class<?> sourceType, final Class<?> targetType) Implements jdk.dynalink.linker.LinkerServices.getTypeConverter. Doc from jdk.dynalink.linker.LinkerServices.getTypeConverter. Given a source and target type, returns a method handle that converts between them. Never returns null; in worst case it will return an identity conversion (that might fail for some values at runtime). You rarely need to use this method directly and should mostly rely on `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. Parameters sourceType:Class<?> the type to convert from targetType:Class<?> the type to convert to Returns:MethodHandle a method handle performing the conversion. Annotations @Override

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

Implements jdk.dynalink.linker.LinkerServices.getTypeConverter.

Doc from jdk.dynalink.linker.LinkerServices.getTypeConverter.

Given a source and target type, returns a method handle that converts between them. Never returns null; in worst case it will return an identity conversion (that might fail for some values at runtime). You rarely need to use this method directly and should mostly rely on 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.

Parameters

sourceType:Class<?>: the type to convert from
targetType:Class<?>: the type to convert to

Returns:MethodHandle

a method handle performing the conversion.

Annotations

@Override

getWithLookup back to summary

getWithLookup	back to summary
public <T> T getWithLookup(final Supplier<T> operation, final SecureLookupSupplier lookupSupplier) Implements jdk.dynalink.linker.LinkerServices.getWithLookup. Doc from jdk.dynalink.linker.LinkerServices.getWithLookup. Executes an operation within the context of a particular `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. Parameters <T> the type of the return value provided by the passed-in supplier. operation:Supplier<T> the operation to execute in context of the specified lookup. lookupSupplier:SecureLookupSupplier secure supplier of the lookup Returns:T the return value of the action Annotations @Override

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

Implements jdk.dynalink.linker.LinkerServices.getWithLookup.

Doc from jdk.dynalink.linker.LinkerServices.getWithLookup.

Executes an operation within the context of a particular 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.

Parameters

<T>: the type of the return value provided by the passed-in supplier.
operation:Supplier<T>: the operation to execute in context of the specified lookup.
lookupSupplier:SecureLookupSupplier: secure supplier of the lookup

Returns:T

the return value of the action

Annotations

@Override

getWithLookupInternal	back to summary
private static <T> T getWithLookupInternal(final Supplier<T> operation, final SecureLookupSupplier lookupSupplier)

pack-priv final Class LinkerServicesImpl

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class LinkerServicesImpl.LinkerException

Field Summary

Constructor Summary

Field Detail

Constructor Detail