Интерфейс LinkerServices

public interface LinkerServices

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

Since:: 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`, который экспонирует этот объект Linker services.
`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 не гарантирует, что преобразование будет успешным во время выполнения для всех значений (особенно если типы «из» или «в» достаточно обобщённые), но возврат 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 - другой потенциальный целевой тип.
Возвращает:: одно из значений сравнения, устанавливающих, какой из целевых типов предпочтительнее для преобразования.

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://download.java.net/java/early_access/jdk24/docs/api/jdk.dynalink/jdk/dynalink/linker/LinkerServices.html