Интерфейс LinkerServices

public interface LinkerServices

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

Методы

Модификатор и тип	Метод	Описание
`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 не гарантирует, что преобразование будет успешным во время выполнения для всех значений (особенно если типы «из» или «в» достаточно обобщены), но возвращение 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(), так как нить не участвует в процессе ссылки. Если есть способ осмысленно связать операцию с контекстом какого-либо класса вызывающего лица, рассмотрите возможность выполнения этого в вызове этого метода и передачи полноправного поиска для этого класса, так как он свяжет этот поиск с текущей нитью на время выполнения операции. Обратите внимание, что поскольку вы передаёте SecureLookupSupplier, любые вызываемые фабрики преобразователей типов всё равно должны обладать необходимым правом выполнения, чтобы получить поиск, если им это понадобится.

Параметры типа:: T - тип возвращаемого значения, предоставляемого переданным поставщиком.
Параметры:: operation - операция, выполняемая в контексте указанного поиска.; lookupSupplier - безопасный поставщик поиска
Возвращает:: значение возврата действия
Исключения:: NullPointerException - если action или lookupSupplier равны null.
См. также:: GuardingTypeConverterFactory.convertToType(Class, Class, Supplier)

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