Интерфейс LinkerServices

public interface LinkerServices

Интерфейс служб, предоставляемых экземплярам GuardingDynamicLinker объектом DynamicLinker, которому они принадлежат.

Начиная с:: 9

Краткое описание методов

Модификатор и тип	Метод	Описание
`MethodHandle`	`asType(MethodHandle handle, MethodType fromType)`	Аналогичен `MethodHandle.asType(MethodType)`, но дополнительно подключает дескрипторы методов, создаваемые всеми доступными реализациями `GuardingTypeConverterFactory`, обеспечивая преобразование типов параметров с учетом особенностей языка.
`default MethodHandle`	`asTypeLosslessReturn(MethodHandle handle, MethodType fromType)`	Аналогичен `asType(MethodHandle, MethodType)`, но особым образом обрабатывает преобразование типа возвращаемого значения.
`boolean`	`canConvert(Class<?> from, Class<?> to)`	Возвращает true, если между запрошенными типами может существовать преобразование (автоматическое преобразование JVM или преобразование, предоставляемое любой доступной реализацией `GuardingTypeConverterFactory`), и false, если между запрошенными типами преобразование заведомо невозможно.
`ConversionComparator.Comparison`	`compareConversion(Class<?> sourceType, Class<?> targetType1, Class<?> targetType2)`	Определяет, какое из двух преобразований исходного типа в два целевых типа является предпочтительным.
`MethodHandle`	`filterInternalObjects(MethodHandle target)`	Изменяет дескриптор метода, добавляя фильтр к любым параметрам, способным принимать потенциально внутренние объекты среды выполнения языка, чтобы предотвратить их утечку, в том числе путем оборачивания.
`GuardedInvocation`	`getGuardedInvocation(LinkRequest linkRequest)`	Создает защищенный вызов с делегированием обратно объекту `DynamicLinker`, предоставляющему этот объект служб линкера.
`MethodHandle`	`getTypeConverter(Class<?> sourceType, Class<?> targetType)`	Для исходного и целевого типов возвращает дескриптор метода, выполняющий преобразование между ними.
`<T> T`	`getWithLookup(Supplier<T> operation, SecureLookupSupplier lookupSupplier)`	Выполняет операцию в контексте заданного объекта поиска `MethodHandles.Lookup`.

Подробное описание методов

asType

MethodHandle asType(MethodHandle handle, MethodType fromType)

Аналогичен MethodHandle.asType(MethodType), но дополнительно подключает дескрипторы методов, создаваемые всеми доступными реализациями GuardingTypeConverterFactory, обеспечивая преобразование типов параметров с учетом особенностей языка. Метод применяет MethodHandle.asType(MethodType) для всех преобразований примитивного типа в примитивный, типа-оболочки в примитивный, примитивного типа в тип-оболочку, а также для всех расширяющих преобразований. Для всех остальных преобразований он вставляет MethodHandles.filterArguments(MethodHandle, int, MethodHandle...) с составными фильтрами, предоставляемыми реализациями GuardingTypeConverterFactory.

Параметры:: handle — целевой дескриптор метода; fromType — типы исходных аргументов
Возвращает:: дескриптор метода, представляющий собой подходящую комбинацию MethodHandle.asType(MethodType), MethodHandles.filterArguments(MethodHandle, int, MethodHandle...) и MethodHandles.filterReturnValue(MethodHandle, MethodHandle), где преобразователи типов, созданные GuardingTypeConverterFactory, используются в качестве фильтров.

asTypeLosslessReturn

default MethodHandle asTypeLosslessReturn(MethodHandle handle, MethodType fromType)

Аналогичен asType(MethodHandle, MethodType), но особым образом обрабатывает преобразование типа возвращаемого значения. Он преобразует тип возвращаемого значения дескриптора метода, только если это можно сделать без потери точности или величины; в противном случае он оставляет его без изменений. Это единственные преобразования возвращаемого значения, которые должны выполняться отдельными линкерами для конкретного языка. Стратегию обработки потенциально убыточных преобразований типа возвращаемого значения должен реализовывать pre-link transformer of the dynamic linker с учетом среды выполнения языка, в которой находится точка вызова.

Параметры:: handle — целевой дескриптор метода; fromType — типы исходных аргументов
Возвращает:: дескриптор метода, представляющий собой подходящую комбинацию MethodHandle.asType(MethodType) и MethodHandles.filterArguments(MethodHandle, int, MethodHandle...), где преобразователи типов, созданные GuardingTypeConverterFactory, используются в качестве фильтров.

getTypeConverter

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

Для исходного и целевого типов возвращает дескриптор метода, выполняющий преобразование между ними. Никогда не возвращает null; в худшем случае возвращается тождественное преобразование (которое может завершиться ошибкой для некоторых значений во время выполнения). Обычно этот метод не требуется вызывать напрямую — вместо этого следует полагаться на asType(MethodHandle, MethodType). Этот метод нужен, когда существующий механизм преобразования типов требуется повторно использовать вне контекста обработки запроса на связывание.

Параметры:: sourceType — тип, из которого выполняется преобразование; targetType — тип, в который выполняется преобразование
Возвращает:: дескриптор метода, выполняющий преобразование.

canConvert

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

Возвращает true, если между запрошенными типами может существовать преобразование (автоматическое преобразование JVM или преобразование, предоставляемое любой доступной реализацией GuardingTypeConverterFactory), и false, если между запрошенными типами преобразование заведомо невозможно. Обратите внимание: значение true не гарантирует, что преобразование будет успешно для всех значений во время выполнения (особенно если типы «from» или «to» достаточно общие), однако значение false гарантирует, что оно завершится неудачей.

Параметры:: from — исходный тип преобразования; to — целевой тип преобразования
Возвращает:: true, если преобразование возможно, и false, если невозможно.

getGuardedInvocation

GuardedInvocation getGuardedInvocation(LinkRequest linkRequest) throws Exception

Создает защищенный вызов с делегированием обратно объекту DynamicLinker, предоставляющему этот объект служб линкера. Затем динамический линкер сам передаст связывание всем управляемым им GuardingDynamicLinker, включая, возможно, и этот объект, если ни один линкер не обработает запрос раньше. Поэтому остерегайтесь бесконечной рекурсии. Обычно запрос на связывание формируют так, чтобы он отличался от запроса, который связывается в данный момент.

Параметры:: linkRequest — запрос на связывание вызова
Возвращает:: защищенный вызов, связанный одним из линкеров с проверкой условий, управляемых динамическим линкером верхнего уровня. Может быть равен null, если ни один доступный линкер не способен связать вызов. Обычно элементы возвращенного вызова используются для составления собственного вызова.
Выбрасывает:: Exception — если линкер верхнего уровня выбрасывает исключение

compareConversion

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

Определяет, какое из двух преобразований исходного типа в два целевых типа является предпочтительным. Используется для динамического разрешения перегрузки методов. Если исходный тип можно преобразовать ровно в один целевой тип с помощью преобразования при вызове метода, выбирается этот тип; в противном случае выполняется обращение к доступным ConversionComparator.

Параметры:: sourceType — исходный тип.; targetType1 — один из возможных целевых типов; targetType2 — другой возможный целевой тип.
Возвращает:: одну из констант Comparison, определяющую, какой из целевых типов предпочтительнее для преобразования, если такой тип есть.

filterInternalObjects

MethodHandle filterInternalObjects(MethodHandle target)

Изменяет дескриптор метода, добавляя фильтр к любым параметрам, способным принимать потенциально внутренние объекты среды выполнения языка, чтобы предотвратить их утечку, в том числе путем оборачивания. Также может добавить фильтр снятия обертки к возвращаемому значению. По сути, преобразует дескриптор метода с помощью трансформера, настроенного методом DynamicLinkerFactory.setInternalObjectsFilter(MethodHandleTransformer).

Параметры:: target — целевой дескриптор метода
Возвращает:: дескриптор метода с параметрами и/или типом возвращаемого значения, потенциально отфильтрованными для оборачивания и снятия обертки.

getWithLookup

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

Выполняет операцию в контексте заданного объекта поиска MethodHandles.Lookup. Обычно методы LinkerServices вызываются в рамках механизма связывания; в этом случае Dynalink внутренне хранит текущий объект поиска для каждого потока (тот, который относится к дескриптору связываемой точки вызова). Этот объект поиска может получить любая участвующая в связывании реализация GuardingTypeConverterFactory, если ей нужно создать преобразователи, зависящие от объекта поиска. Однако методы служб линкера могут вызываться и вне процесса связывания — например, при реализации схем диспетчеризации во время вызова или выполнении преобразований во время выполнения. Если в такой ситуации потребуется преобразователь типов, которому нужен объект поиска, обычно он получит только MethodHandles.publicLookup(), поскольку поток не выполняет операцию связывания. Если операцию можно осмысленно связать с контекстом некоторого вызывающего класса, рассмотрите возможность выполнить ее в рамках вызова этого метода и передать полноценный объект поиска для этого класса. Таким образом этот объект поиска будет связан с текущим потоком на время выполнения операции.

Параметры типа:

T — тип возвращаемого значения, предоставляемого переданным поставщиком.

Параметры:

operation — операция, выполняемая в контексте указанного объекта поиска.

lookupSupplier — защищенный поставщик объекта поиска

Возвращает:

возвращаемое значение действия

Выбрасывает:

NullPointerException — если action или lookupSupplier равны null.

См. также:

© 1993, 2025, 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/25/docs/api/jdk.dynalink/jdk/dynalink/linker/LinkerServices.html