Класс StringConcatFactory

java.lang.Object

java.lang.invoke.StringConcatFactory

public final class StringConcatFactory extends Object

Методы для облегчения создания методов конкатенации строк, которые могут быть использованы для эффективной конкатенации известного числа аргументов известных типов, возможно, после адаптации типов и частичной оценки аргументов. Эти методы обычно используются в качестве методов-bootstrap для invokedynamic мест вызова, чтобы поддерживать функцию конкатенации строк языка программирования Java.

Непрямой доступ к поведению, заданному предоставленным MethodHandle, происходит по порядку через две фазы:

Связывание происходит при вызове методов в этом классе. Они принимают в качестве аргументов тип метода, описывающий количество и типы конкатенируемых аргументов, и необязательно шаблон строки, плюс константы, участвующие в конкатенации строк. Подробности о допустимых формах шаблона описаны ниже. Связывание может включать динамическую загрузку нового класса, реализующего ожидаемое поведение конкатенации. CallSite содержит MethodHandle, указывающий на точный метод конкатенации. Методы конкатенации могут быть общими для разных CallSite , например, если методы связывания производят их как чистые функции.
Вызов происходит при вызове сгенерированного метода конкатенации с точными динамическими аргументами. Это может происходить много раз для одного метода конкатенации. Метод, на который ссылается поведение MethodHandle, вызывается со статическими аргументами и любыми дополнительными динамическими аргументами, предоставленными при вызове, как если бы это был вызов MethodHandle.invoke(Object...).

Этот класс предоставляет два вида методов связывания: простую версию (makeConcat(java.lang.invoke.MethodHandles.Lookup, String, MethodType)) только с динамическими аргументами и расширенную версию (makeConcatWithConstants(java.lang.invoke.MethodHandles.Lookup, String, MethodType, String, Object...)) с расширенными формами захвата постоянных аргументов. Расширенная стратегия может производить немного лучший байт-код вызова, за счет увеличения числа форм методов конкатенации строк, присутствующих во время выполнения, так как эти формы будут включать статические аргументы-константы.

API Note:: Существует ограничение JVM (ограничение структуры файла класса): ни один метод не может вызываться более чем с 255 слотами. Это ограничивает количество статических и динамических аргументов, которые можно передать методу-bootstrap. Поскольку существуют потенциальные стратегии конкатенации, использующие MethodHandle комбинаторы, нам нужно зарезервировать несколько пустых слотов в списке параметров для захвата временных результатов. Вот почему методы-bootstrap в этом фабричном классе не принимают более 200 слотов аргументов. Пользователи, которым требуется более 200 слотов аргументов в конкатенации, должны разбить большую конкатенацию на меньшие выражения.
Since:: 9

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

Модификатор и тип	Метод	Описание
`static CallSite`	`makeConcat(MethodHandles.Lookup lookup, String name, MethodType concatType)`	Обеспечивает создание оптимизированных методов конкатенации строк, которые могут быть использованы для эффективной конкатенации известного числа аргументов известных типов, возможно, после адаптации типов и частичной оценки аргументов.
`static CallSite`	`makeConcatWithConstants(MethodHandles.Lookup lookup, String name, MethodType concatType, String recipe, Object... constants)`	Обеспечивает создание оптимизированных методов конкатенации строк, которые могут быть использованы для эффективной конкатенации известного числа аргументов известных типов, возможно, после адаптации типов и частичной оценки аргументов.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

makeConcat

public static CallSite makeConcat(MethodHandles.Lookup lookup, String name, MethodType concatType) throws StringConcatException

Обеспечивает создание оптимизированных методов конкатенации строк, которые могут быть использованы для эффективной конкатенации известного числа аргументов известных типов, возможно, после адаптации типа и частичной оценки аргументов. Обычно используется как метод-«загрузчик» для


 invokedynamic

сайтов вызовов, чтобы поддерживать функцию «конкатенации строк» языка программирования Java.

При вызове целевого метода, возвращенного этим методом, возвращается результат конкатенации строк, принимающий все аргументы функции, переданные методу привязки, в качестве входных данных для конкатенации. Подпись целевого метода задается concatType. Для целевого метода, принимающего:

ноль входных данных, результат конкатенации — пустая строка;
один входной параметр, результат конкатенации — единственный входной параметр, преобразованный согласно JLS 5.1.11 «Преобразование строки»; в противном случае
два или более входных данных, входные данные конкатенируются согласно требованиям, указанным в JLS 15.18.1 «Оператор конкатенации строк +». Входные данные преобразуются согласно JLS 5.1.11 «Преобразование строки» и объединяются слева направо.

Предположим, что аргументы привязки следующие:

concatType, описывающий подпись CallSite

Тогда должны выполняться следующие инварианты привязки:

Количество слотов параметров в concatType меньше или равно 200
Тип возвращаемого значения в concatType совместим с String

Параметры:: lookup - Представляет контекст поиска с привилегиями доступа вызывающего метода. В частности, контекст поиска должен иметь полные привилегии доступа. При использовании с invokedynamic, это автоматически стекируется виртуальной машиной.; name - Имя реализуемого метода. Это имя произвольное и не имеет значения для этого метода привязки. При использовании с invokedynamic, это предоставляется NameAndType структуры InvokeDynamic и автоматически стекируется виртуальной машиной.; concatType - Ожидаемая подпись CallSite. Типы параметров представляют типы аргументов конкатенации; тип возвращаемого значения всегда совместим с String. При использовании с invokedynamic, это предоставляется NameAndType структуры InvokeDynamic и автоматически стекируется виртуальной машиной.
Возвращаемое значение:: CallSite, чья цель может быть использована для выполнения конкатенации строк с динамическими аргументами конкатенации, описанными заданным concatType.
Исключения:: StringConcatException - Если нарушены какие-либо инварианты привязки, описанные здесь, или контекст поиска не имеет привилегий частного доступа.; NullPointerException - Если любой из входных аргументов равен null. Это никогда не произойдёт, когда метод-загрузчик вызывается с invokedynamic.
См. Спецификацию языка Java:: 5.1.11 Преобразование строки
15.18.1 Оператор конкатенации строк +

makeConcatWithConstants

public static CallSite makeConcatWithConstants(MethodHandles.Lookup lookup, String name, MethodType concatType, String recipe, Object... constants) throws StringConcatException


 invokedynamic

сайтов вызовов, чтобы поддерживать функцию «конкатенации строк» языка программирования Java.

При вызове целевого метода, возвращенного этим методом, возвращается результат конкатенации строк, принимающий все аргументы функции и константы, переданные методу привязки, в качестве входных данных для конкатенации. Подпись целевого метода задается concatType, и не включает константы. Для целевого метода, принимающего:

ноль входных данных, результат конкатенации — пустая строка;
один входной параметр, результат конкатенации — единственный входной параметр, преобразованный согласно JLS 5.1.11 «Преобразование строки»; в противном случае
два или более входных данных, входные данные конкатенируются согласно требованиям, указанным в JLS 15.18.1 «Оператор конкатенации строк +». Входные данные преобразуются согласно JLS 5.1.11 «Преобразование строки» и объединяются слева направо.

«Рецепт» конкатенации — это строковое описание способа построения конкатенированной строки из аргументов и констант. Рецепт обрабатывается слева направо, и каждый символ представляет входной параметр для конкатенации. Символы рецепта означают:

\1 (Unicode 0001): обычный аргумент. Этот входной параметр передается динамическому аргументу и предоставляется во время вызова метода конкатенации. Этот входной параметр может быть null.
\2 (Unicode 0002): константа. Этот входной параметр передается статическому аргументу загрузки. Эта константа может быть любым значением, представимым в пуле констант. При необходимости фабрика вызовет toString для выполнения однократного преобразования строки.
Любое другое значение символа: константа-символ.

Предположим, что аргументы привязки следующие:

concatType, описывающий подпись CallSite
recipe, описывающий строковый рецепт
constants, массив аргументов-констант

Тогда должны выполняться следующие инварианты привязки:

Количество слотов параметров в concatType меньше или равно 200
Количество параметров в concatType равно количеству тегов \1 в recipe
Тип возвращаемого значения в concatType совместим с String, и соответствует типу возвращаемого значения возвращаемого MethodHandle
Количество элементов в constants равно количеству тегов \2 в recipe

Примечание API:: Генераторы кода имеют три различных способа обработки константной строковой операнды S в выражении конкатенации строк. Во-первых, S может быть материализован как ссылка (используя ldc) и передан как обычный аргумент (рецепт '\1'). Во-вторых, S может быть сохранён в пуле констант и передан как константа (рецепт '\2'). Наконец, если S не содержит ни одного из символов рецепта ('\1', '\2'), то S может быть вставлен в сам рецепт, вызывая вставку его символов в результат.
Параметры:: lookup - Представляет контекст поиска с привилегиями доступа вызывающего метода. В частности, контекст поиска должен иметь полные привилегии доступа. При использовании с invokedynamic, это автоматически стекируется виртуальной машиной.; name - Имя реализуемого метода. Это имя произвольное и не имеет значения для этого метода привязки. При использовании с invokedynamic, это предоставляется NameAndType структуры InvokeDynamic и автоматически стекируется виртуальной машиной.; concatType - Ожидаемая подпись CallSite. Типы параметров представляют типы динамических аргументов конкатенации; тип возвращаемого значения всегда совместим с String. При использовании с invokedynamic, это предоставляется NameAndType структуры InvokeDynamic и автоматически стекируется виртуальной машиной.; recipe - Рецепт конкатенации, описанный выше.; constants - Аргумент vararg, представляющий константы, переданные методу привязки.
Возвращаемое значение:: CallSite, чья цель может быть использована для выполнения конкатенации строк с динамическими аргументами конкатенации, описанными заданным concatType.
Исключения:: StringConcatException - Если нарушены какие-либо инварианты привязки, описанные здесь, или контекст поиска не имеет привилегий частного доступа.; NullPointerException - Если любой из входных аргументов равен null, или любая константа в recipe равна null. Это никогда не произойдёт, когда метод-загрузчик вызывается с invokedynamic.
См. Спецификацию языка Java:: 5.1.11 Преобразование строки
15.18.1 Оператор конкатенации строк +

© 1993, 2021, 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/17/docs/api/java.base/java/lang/invoke/StringConcatFactory.html