Класс MethodHandles

Данный метод чувствителен к вызывающему объекту, что означает, что он может возвращать разные значения различным вызывающим объектам. В тех случаях, когда MethodHandles.lookup вызывается из контекста, где нет кадра вызова в стеке (например, при прямом вызове из присоединённого к JNI потока), IllegalCallerException выбрасывается. Чтобы получить lookup object в таком контексте, используйте вспомогательный класс, который будет неявно определён как вызывающий, или используйте publicLookup() для получения менее привилегированного lookup.

В соответствии с соглашениями, классом lookup данного объекта lookup будет Object.

Вызывающий объект, указанный как объект Lookup, в модуле M1, разрешено выполнять глубокое рефлексирование модуля M2 и пакета целевого класса, если и только если все следующие условия выполняются true:

• Если существует системный менеджер безопасности, его метод checkPermission вызывается для проверки ReflectPermission("suppressAccessChecks"), и он должен возвратить результат без исключений.
• Объект lookup вызывающего объекта должен иметь полный доступ с привилегиями. В частности:
  • Объект lookup вызывающего объекта должен иметь режим lookup MODULE. (Это необходимо, чтобы гарантировать, что исходный создатель lookup является членом определённого модуля, и следовательно любые последующие проверки на читаемость и квалифицированные экспортные параметры будут эффективны.)
  • Объект lookup вызывающего объекта должен иметь доступ PRIVATE. (Это необходимо, так как приложение, намеревающееся использовать взаимный доступ в рамках модуля с помощью MODULE в противном случае случайно поделится и глубоким рефлексированием своего модуля.)
• Целевой класс должен быть правильным классом, а не примитивным или массивом классов. (Таким образом, M2 корректно определён.)
• Если модуль вызывающего объекта M1 отличается от модуля целевого объекта M2, то должны быть истинны оба следующих утверждения:
  • M1 reads M2.
  • M2 opens пакет, содержащий целевой класс, по крайней мере, до M1.

Если любое из вышеперечисленных условий нарушено, метод завершается исключением.

В противном случае, если M1 и M2 являются одним и тем же модулем, данный метод возвращает Lookup на targetClass с полным доступом с привилегиями с предыдущим классом lookup.

В противном случае, M1 и M2 являются двумя разными модулями. Данный метод возвращает Lookup на targetClass, который записывает класс lookup вызывающего объекта как новый предыдущий класс lookup с доступом PRIVATE, но без доступа MODULE.

Полученный объект Lookup не имеет доступа ORIGINAL.

Скрытый класс с данными класса можно создать, вызвав Lookup::defineHiddenClassWithClassData. Этот метод вызовет инициализатор статического класса класса поиска заданного объекта поиска caller, если он ещё не был инициализирован.

Скрытый класс, созданный с помощью Lookup::defineHiddenClass, и нескрытые классы не имеют данных класса. null возвращается, если этот метод вызывается для объекта поиска для этих классов.

Режимы поиска (lookup modes) для этого поиска должны иметь оригинальный доступ для получения данных класса.

Скрытый класс с данными класса можно создать, вызвав Lookup::defineHiddenClassWithClassData. Этот метод вызовет инициализатор статического класса класса поиска заданного caller объекта поиска, если он ещё не был инициализирован.

Скрытый класс, созданный Lookup::defineHiddenClass, и нескрытые классы не имеют данных класса. null возвращается, если этот метод вызывается для объекта поиска для этих классов.

Режимы поиска (lookup modes) для этого поиска должны иметь оригинальный доступ для получения данных класса.

Если существует менеджер безопасности, его метод checkPermission вызывается с разрешением ReflectPermission("suppressAccessChecks").

Если возвращаемый обработчик метода вызывается с отрицательным размером массива, будет брошено исключение NegativeArraySizeException.

Если возвращаемый обработчик метода вызывается с ссылкой на массив null, будет брошено исключение NullPointerException.

При вызове возвращаемого обработчика метода, ссылка на массив и индекс массива проверяются. Будет брошено исключение NullPointerException, если ссылка на массив является null, и будет брошено исключение ArrayIndexOutOfBoundsException, если индекс отрицательный или если он больше или равен длине массива.

При вызове возвращаемого обработчика метода, ссылка на массив и индекс массива проверяются. Будет брошено исключение NullPointerException, если ссылка на массив равна null, и будет брошено исключение ArrayIndexOutOfBoundsException, если индекс отрицательный или если он больше или равен длине массива.

Некоторые режимы доступа возвращаемого VarHandle не поддерживаются в следующих условиях:

• если тип компонента отличается от byte, short, char, int, long, float или double, то атомарные режимы числовых обновлений не поддерживаются.
• если тип компонента отличается от boolean, byte, short, char, int или long, то атомарные режимы битовых обновлений не поддерживаются.

Если тип компонента является float или double, то режимы числового и атомарного обновления сравнивают значения, используя их битовое представление (см. Float.floatToRawIntBits(float) и Double.doubleToRawLongBits(double) соответственно).

При вызове возвращаемого VarHandle, ссылка на массив и индекс массива проверяются. Будет брошено исключение NullPointerException, если ссылка на массив равна null, и будет брошено исключение ArrayIndexOutOfBoundsException, если индекс отрицательный или если он больше или равен длине массива.

Поддерживаемые компонентные типы (типы переменных) — это short, char, int, long, float и double.

Обращение к байтам по заданному индексу приведет к исключению ArrayIndexOutOfBoundsException, если индекс меньше 0 или больше длины массива byte[] минус размер (в байтах) T.

Обращение к байтам по индексу может быть выровнено или не выровнено для T относительно базового адреса памяти, A, связанного с массивом и индексом. Если доступ не выровнен, доступ для любого режима, кроме get и set, приведет к исключению IllegalStateException. В таких случаях атомарный доступ гарантирован только относительно наибольшей степени двойки, которая делит НОД A и размер (в байтах) T. Если доступ выровнен, поддерживаются следующие режимы доступа, гарантирующие атомарный доступ:

• Режимы чтения-записи для всех T, за исключением режимов доступа get и set для long и double на 32-битных платформах.
• Режимы атомарного обновления для int, long, float или double. (Будущие основные релизы JDK могут поддерживать дополнительные типы для некоторых в настоящее время неподдерживаемых режимов доступа.)
• Числовые режимы атомарного обновления для int и long. (Будущие основные релизы JDK могут поддерживать дополнительные числовые типы для некоторых в настоящее время неподдерживаемых режимов доступа.)
• Битовые режимы атомарного обновления для int и long. (Будущие основные релизы JDK могут поддерживать дополнительные числовые типы для некоторых в настоящее время неподдерживаемых режимов доступа.)

Невыровненный доступ, а следовательно, и гарантии атомности, могут быть определены для массивов byte[] без работы с конкретным массивом. Учитывая index, T и его соответствующий упакованный тип, T_BOX, невыравнивание может быть определено следующим образом:

 int sizeOfT = T_BOX.BYTES;  // size in bytes of T
 int misalignedAtZeroIndex = ByteBuffer.wrap(new byte[0]).
     alignmentOffset(0, sizeOfT);
 int misalignedAtIndex = (misalignedAtZeroIndex + index) % sizeOfT;
 boolean isMisaligned = misalignedAtIndex != 0;
 

Если тип переменной — float или double, то режимы атомарного обновления сравнивают значения с использованием их битового представления (см. Float.floatToRawIntBits(float) и Double.doubleToRawLongBits(double) соответственно).

Поддерживаемые компонентные типы (типы переменных) — это short, char, int, long, float и double.

Обращение к любому режиму доступа, кроме чтения, вызовет исключение ReadOnlyBufferException, если ByteBuffer доступно только для чтения.

Обращение к байтам по заданному индексу приведет к исключению IndexOutOfBoundsException, если индекс меньше 0 или больше предела ByteBuffer минус размер (в байтах) T.

Обращение к байтам по индексу может быть выровнено или не выровнено для T относительно базового адреса памяти, A, связанного с ByteBuffer и индексом. Если доступ не выровнен, доступ для любого режима, кроме get и set, приведет к исключению IllegalStateException. В таких случаях атомарный доступ гарантирован только относительно наибольшей степени двойки, которая делит НОД A и размер (в байтах) T. Если доступ выровнен, поддерживаются следующие режимы доступа, гарантирующие атомарный доступ:

• Режимы чтения-записи для всех T, за исключением режимов доступа get и set для long и double на 32-битных платформах.
• Режимы атомарного обновления для int, long, float или double. (Будущие основные релизы JDK могут поддерживать дополнительные типы для некоторых в настоящее время неподдерживаемых режимов доступа.)
• Числовые режимы атомарного обновления для int и long. (Будущие основные релизы JDK могут поддерживать дополнительные числовые типы для некоторых в настоящее время неподдерживаемых режимов доступа.)
• Битовые режимы атомарного обновления для int и long. (Будущие основные релизы JDK могут поддерживать дополнительные числовые типы для некоторых в настоящее время неподдерживаемых режимов доступа.)

Невыровненный доступ, а следовательно, и гарантии атомности, могут быть определены для ByteBuffer, bb (прямого или иного), index, T и его соответствующего упакованного типа, T_BOX, следующим образом:

 int sizeOfT = T_BOX.BYTES;  // size in bytes of T
 ByteBuffer bb = ...
 int misalignedAtIndex = bb.alignmentOffset(index, sizeOfT);
 boolean isMisaligned = misalignedAtIndex != 0;
 

Если тип переменной — float или double, то режимы атомарного обновления сравнивают значения с использованием их битового представления (см. Float.floatToRawIntBits(float) и Double.doubleToRawLongBits(double) соответственно).

• единственный MethodHandle целевой обработчик
• ноль или более ведущих значений (считается leadingArgCount)
• массив Object[], содержащий последующие аргументы

Обработчик будет вызывать свой целевой обработчик как вызов invoke с указанными type. То есть, если целевой обработчик соответствует заданному type, он будет вести себя как invokeExact; в противном случае, он будет вести себя так, как будто используется asType для преобразования целевого обработчика к требуемому type.

Тип возвращаемого обработчика не будет заданным type, а будет иметь все параметры, кроме первого leadingArgCount, заменённые единственным массивом типа Object[], который будет последним параметром.

Перед вызовом целевого обработчика обработчик будет распылять конечный массив, применять необходимые преобразования ссылок и разворачивать и расширять примитивные аргументы. Если при вызове обработчика аргумент массива не содержит правильного количества элементов, обработчик выбросит IllegalArgumentException вместо вызова целевого обработчика.

Этот метод эквивалентен следующему коду (хотя он может быть более эффективным):

MethodHandle invoker = MethodHandles.invoker(type);
int spreadArgCount = type.parameterCount() - leadingArgCount;
invoker = invoker.asSpreader(Object[].class, spreadArgCount);
return invoker;

Этот метод эквивалентен следующему коду (хотя он может быть более эффективным): publicLookup().findVirtual(MethodHandle.class, "invokeExact", type)

Обсуждение: Обработчики методов могут быть полезны при работе с переменными обработчиками методов неизвестных типов. Например, чтобы эмулировать вызов invokeExact к переменной ручке метода M, извлечь его тип T, найти обработчик метода X для T и вызвать обработчик метода, как X.invoke(T, A...). (Не сработает вызов X.invokeExact, так как тип T неизвестен.) Если требуется распределение, сборка или другие преобразования аргументов, они могут быть применены один раз к обработчику X и повторно использоваться для многих значений обработчиков метода M, совместимых с типом X.

(Примечание: метод-обработчик недоступен через API основного отражения. Попытка вызвать java.lang.reflect.Method.invoke на объявленном invokeExact или invoke методе вызовет UnsupportedOperationException.)

Этот метод не генерирует отражательные или защитные исключения.

Перед вызовом целевого обработчика, если целевой обработчик отличается от ожидаемого типа, обработчик применит необходимые преобразования ссылок и преобразует, развернёт или расширит примитивные значения, как если бы использовалась asType. Аналогично, значение возврата будет преобразовано при необходимости. Если целевой обработчик является обработчиком метода с переменным количеством аргументов, будет выполнено требуемое преобразование арности, также как при использовании asType.

Этот метод эквивалентен следующему коду (хотя он может быть более эффективным): publicLookup().findVirtual(MethodHandle.class, "invoke", type)

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

(Примечание: метод-обработчик недоступен через API основного отражения. Попытка вызвать java.lang.reflect.Method.invoke на объявленном invokeExact или invoke методе вызовет UnsupportedOperationException.)

Этот метод не генерирует отражательные или защитные исключения.

Перед вызовом целевого обработчика, если тип режима доступа отличается от желаемого заданного типа, обработчик применит необходимые преобразования ссылок и преобразует, развернёт или расширит примитивные значения, как если бы использовалась asType. Аналогично, значение возврата будет преобразовано при необходимости.

Этот метод эквивалентен следующему коду (хотя он может быть более эффективным): publicLookup().findVirtual(VarHandle.class, accessMode.name(), type)

Если исходный тип и новый тип совпадают, возвращает target.

Разрешены те же преобразования, что и для MethodHandle.asType, а также некоторые дополнительные преобразования применяются, если эти преобразования не удаются. Для типов T0, T1 применяется одно из следующих преобразований, если это возможно, до или вместо любого преобразования, выполненного asType:

• Если T0 и T1 — ссылки, а T1 — тип интерфейса, то значение типа T0 передается как T1 без приведения типов. (Это обращение с интерфейсами следует принципам верификации байт-кода.)
• Если T0 — boolean, а T1 — другой примитивный тип, boolean преобразуется в значение типа byte, 1 для true, 0 для false. (Это обращение следует принципам верификации байт-кода.)
• Если T1 — boolean, а T0 — другой примитивный тип, T0 преобразуется в byte с помощью преобразования приведения Java (JLS 5.5), и бит младшего разряда результата проверяется, как если бы это было сделано с помощью (x & 1) != 0.
• Если T0 и T1 — примитивные типы, отличные от boolean, то применяется преобразование приведения Java (JLS 5.5). (Конкретно, T0 преобразуется в T1 с помощью расширения и/или сужения.)
• Если T0 — ссылка, а T1 — примитивный тип, то при выполнении будет применено преобразование распаковки, возможно, за которым следует преобразование приведения Java (JLS 5.5) для примитивного значения, а возможно, и преобразование из byte в boolean путем проверки бита младшего разряда.
• Если T0 — ссылка, а T1 — примитивный тип, и ссылка равна null во время выполнения, вводится значение нуля.

Перестановка определяется заданным массивом. Вызовите #I для количества входных параметров (значение newType.parameterCount()), и вызовите #O для количества выходных параметров (значение target.type().parameterCount()). Тогда длина массива перестановки должна быть #O, а каждый элемент должен быть целым числом, неотрицательным и меньше #I. Для каждого N меньше #O, N-й выходной аргумент будет взят из I-го входного аргумента, где I есть reorder[N].

Преобразования аргументов или возвращаемых значений не применяются. Тип каждого входного аргумента, определяемый newType, должен быть идентичен типу соответствующего выходного параметра или параметров в целевом обработчике метода. Тип возвращаемого значения newType должен быть идентичен типу возвращаемого значения исходного целевого обработчика.

Массив перестановки не обязательно должен задавать фактическую перестановку. Входной аргумент будет продублирован, если его индекс встречается в массиве более одного раза, а входной аргумент будет пропущен, если его индекс не встречается в массиве. Как и в случае с dropArguments, входные аргументы, которые не указаны в массиве перестановки, могут иметь любой тип, определяемый только newType.

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodType intfn1 = methodType(int.class, int.class);
MethodType intfn2 = methodType(int.class, int.class, int.class);
MethodHandle sub = ... (int x, int y) -> (x-y) ...;
assert(sub.type().equals(intfn2));
MethodHandle sub1 = permuteArguments(sub, intfn2, 0, 1);
MethodHandle rsub = permuteArguments(sub, intfn2, 1, 0);
assert((int)rsub.invokeExact(1, 100) == 99);
MethodHandle add = ... (int x, int y) -> (x+y) ...;
assert(add.type().equals(intfn2));
MethodHandle twice = permuteArguments(add, intfn1, 0, 0);
assert(twice.type().equals(intfn1));
assert((int)twice.invokeExact(21) == 42);

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

Перед возвратом обработчика метода переданное значение преобразуется к запрошенному типу. Если запрошенный тип примитивный, предпринимаются попытки расширяющих преобразований примитивных типов, иначе предпринимаются попытки преобразований ссылок.

Возвращаемый обработчик метода эквивалентен identity(type).bindTo(value).

Возвращаемый обработчик метода эквивалентен empty(methodType(type)). Он также эквивалентен explicitCastArguments(constant(Object.class, null), methodType(type)), так как explicitCastArguments преобразует null в значения по умолчанию.

Возвращаемый обработчик метода эквивалентен dropArguments(zero(type.returnType()), 0, type.parameterList()).

Тип нового обработчика метода будет исключать типы связанных параметров из исходного типа целевого объекта, так как новому обработчику метода больше не понадобятся эти аргументы, предоставляемые его вызывающими сторонами.

Каждый заданный объект аргумента должен соответствовать соответствующему типу связанного параметра. Если тип связанного параметра является примитивным, объект аргумента должен быть оберткой, и он будет распакован для получения примитивного значения.

Аргумент pos выбирает, какие параметры должны быть связаны. Он может изменяться от нуля до N-L (включительно), где N — арность целевого обработчика метода, а L — длина массива значений.

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

Аргумент pos может изменяться от нуля до N, где N — арность целевого объекта. Если pos равен нулю, фиктивные аргументы будут предшествовать реальным аргументам целевого объекта; если pos равен N, они будут следовать за ними.

Пример:

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle cat = lookup().findVirtual(String.class,
  "concat", methodType(String.class, String.class));
assertEquals("xy", (String) cat.invokeExact("x", "y"));
MethodType bigType = cat.type().insertParameterTypes(0, int.class, String.class);
MethodHandle d0 = dropArguments(cat, 0, bigType.parameterList().subList(0,2));
assertEquals(bigType, d0.type());
assertEquals("yz", (String) d0.invokeExact(123, "x", "y", "z"));

Этот метод также эквивалентен следующему коду:

 dropArguments(target, pos, valueTypes.toArray(new Class[0]))
 

Аргумент pos может изменяться от нуля до N, где N — арность целевого объекта. Если pos равен нулю, фиктивные аргументы будут предшествовать реальным аргументам целевого объекта; если pos равен N, они будут следовать за ними.

Результирующий обработчик будет иметь тот же тип возвращаемого значения, что и целевой обработчик.

В более формальном представлении, предположим эти два списка типов:

• Целевой обработчик имеет список типов параметров S..., M..., с количеством типов в S, указанным skip. Типы M - это те, которые должны соответствовать части данного списка типов newTypes.
• Список newTypes содержит типы P..., M..., A..., с количеством типов в P, указанным pos. Типы M - это те типы, которые должны соответствовать типам M в списке типов параметров целевого обработчика. Типы в A - дополнительные типы, обнаруженные после соответствующего подсписка.

Предварительная обработка выполняется одним или несколькими обработчиками методов, указанными в элементах массива filters. Первый элемент массива фильтров соответствует аргументу pos целевого обработчика, и так далее последовательно. Функции фильтра вызываются слева направо.

Нулевые аргументы в массиве обрабатываются как тождественные функции, а соответствующие аргументы остаются неизменными. (Если в массиве нет ненулевых элементов, возвращается исходный целевой обработчик.) Каждый фильтр применяется к соответствующему аргументу адаптера.

Если фильтр F применяется к аргументу под номером N целевого обработчика, то F должен быть обработчиком метода, принимающим ровно один аргумент. Тип единственного аргумента F заменяет соответствующий тип аргумента целевого обработчика в результирующем адаптированном обработчике методов. Тип возвращаемого значения F должен быть идентичен соответствующему параметру типа целевого обработчика.

Ошибка возникает, если есть элементы массива filters (нулевые или нет), которые не соответствуют позициям аргументов в целевом обработчике.

Пример:

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle cat = lookup().findVirtual(String.class,
  "concat", methodType(String.class, String.class));
MethodHandle upcase = lookup().findVirtual(String.class,
  "toUpperCase", methodType(String.class));
assertEquals("xy", (String) cat.invokeExact("x", "y"));
MethodHandle f0 = filterArguments(cat, 0, upcase);
assertEquals("Xy", (String) f0.invokeExact("x", "y")); // Xy
MethodHandle f1 = filterArguments(cat, 1, upcase);
assertEquals("xY", (String) f1.invokeExact("x", "y")); // xY
MethodHandle f2 = filterArguments(cat, 0, upcase, upcase);
assertEquals("XY", (String) f2.invokeExact("x", "y")); // XY

Вот псевдокод для результирующего адаптера. В коде T обозначает тип возвращаемого значения как для target, так и для результирующего адаптера. P/p и B/b представляют типы и значения параметров и аргументов, которые предшествуют и следуют за позицией фильтра pos, соответственно. A[i]/a[i] обозначают типы и значения отфильтрованных параметров и аргументов; они также представляют типы возвращаемых значений обработчиков filter[i]. Последние принимают аргументы v[i] типа V[i], которые также появляются в сигнатуре результирующего адаптера.

T target(P... p, A[i]... a[i], B... b);
A[i] filter[i](V[i]);
T adapter(P... p, V[i]... v[i], B... b) {
  return target(p..., filter[i](v[i])..., b...);
}

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

Если фильтр возвращает значение, целевой обработчик должен принять это значение как аргумент в позиции pos, предшествующие и/или последующие аргументы, не переданные фильтру. Если фильтр возвращает пустоту, целевой обработчик должен принять все аргументы, не переданные фильтру. Аргументы не переупорядочиваются, и возвращаемое фильтром значение заменяет (по порядку) всю подпоследовательность аргументов, изначально переданных адаптеру.

Типы аргументов (если таковые имеются) фильтра заменяют ноль или один тип аргумента целевого обработчика, в позиции pos, в результирующем адаптированном обработчике методов. Тип возвращаемого значения фильтра (если таковой имеется) должен быть идентичен типу аргумента целевого обработчика в позиции pos, и этот аргумент целевого обработчика предоставляется возвращаемым значением фильтра.

Во всех случаях, pos должно быть больше или равно нулю, а pos также должно быть меньше или равно арности целевого обработчика.

Пример:

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle deepToString = publicLookup()
  .findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));

MethodHandle ts1 = deepToString.asCollector(String[].class, 1);
assertEquals("[strange]", (String) ts1.invokeExact("strange"));

MethodHandle ts2 = deepToString.asCollector(String[].class, 2);
assertEquals("[up, down]", (String) ts2.invokeExact("up", "down"));

MethodHandle ts3 = deepToString.asCollector(String[].class, 3);
MethodHandle ts3_ts2 = collectArguments(ts3, 1, ts2);
assertEquals("[top, [up, down], strange]",
             (String) ts3_ts2.invokeExact("top", "up", "down", "strange"));

MethodHandle ts3_ts2_ts1 = collectArguments(ts3_ts2, 3, ts1);
assertEquals("[top, [up, down], [strange]]",
             (String) ts3_ts2_ts1.invokeExact("top", "up", "down", "strange"));

MethodHandle ts3_ts2_ts3 = collectArguments(ts3_ts2, 1, ts3);
assertEquals("[top, [[up, down, strange], charm], bottom]",
             (String) ts3_ts2_ts3.invokeExact("top", "up", "down", "strange", "charm", "bottom"));

Вот псевдокод для результирующего адаптера. В коде T представляет тип возвращаемого значения как для target, так и для результирующего адаптера. V/v обозначают тип возвращаемого значения и значение filter, которые также находятся в сигнатуре и аргументах target, соответственно, если только V не равно void. A/a и C/c представляют типы параметров и значения, предшествующие и последующие позиции сбора pos в сигнатуре target. Они также появляются в сигнатуре и аргументах результирующего адаптера, где они окружают B/b, которые представляют типы параметров и аргументы для filter (если таковые имеются).

T target(A...,V,C...);
V filter(B...);
T adapter(A... a,B... b,C... c) {
  V v = filter(b...);
  return target(a...,v,c...);
}
// and if the filter has no arguments:
T target2(A...,V,C...);
V filter2();
T adapter2(A... a,C... c) {
  V v = filter2();
  return target2(a...,v,c...);
}
// and if the filter has a void return:
T target3(A...,C...);
void filter3(B...);
T adapter3(A... a,B... b,C... c) {
  filter3(b...);
  return target3(a...,c...);
}

Адаптер сбора collectArguments(mh, 0, coll) эквивалентен адаптеру, который сначала "складывает" затронутые аргументы, а затем удаляет их, в отдельных шагах следующим образом:

mh = MethodHandles.dropArguments(mh, 1, coll.type().parameterList()); //step 2
mh = MethodHandles.foldArguments(mh, coll); //step 1

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

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

Тип возвращаемого значения фильтра заменяет тип возвращаемого значения целевого обработчика в результирующем адаптированном обработчике методов. Тип аргумента фильтра (если таковой имеется) должен быть идентичен типу возвращаемого значения целевого обработчика.

Пример:

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle cat = lookup().findVirtual(String.class,
  "concat", methodType(String.class, String.class));
MethodHandle length = lookup().findVirtual(String.class,
  "length", methodType(int.class));
System.out.println((String) cat.invokeExact("x", "y")); // xy
MethodHandle f0 = filterReturnValue(cat, length);
System.out.println((int) f0.invokeExact("x", "y")); // 2

Вот псевдокод для результирующего адаптера. В коде T/t представляют тип результата и значение target; V, тип результата filter; и A/a, типы и значения параметров и аргументов target, а также результирующего адаптера.

T target(A...);
V filter(T);
V adapter(A... a) {
  T t = target(a...);
  return filter(t);
}
// and if the target has a void return:
void target2(A...);
V filter2();
V adapter2(A... a) {
  target2(a...);
  return filter2();
}
// and if the filter has a void return:
T target3(A...);
void filter3(V);
void adapter3(A... a) {
  T t = target3(a...);
  filter3(t);
}

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

Предварительная обработка выполняется с помощью combiner, второго обработчика методов. Из аргументов, переданных адаптеру, первые N аргументов копируются в комбинирующий обработчик, который затем вызывается. (Здесь, N определено как количество параметров комбинирующего обработчика). После этого управление передаётся целевому обработчику, причём любой результат от комбинирующего обработчика вставляется перед исходными N входными аргументами.

Если комбинирующий обработчик возвращает значение, первый тип параметра целевого обработчика должен быть идентичен типу возвращаемого значения комбинирующего обработчика, а следующие N типы параметров целевого обработчика должны точно совпадать с типами параметров комбинирующего обработчика.

Если у комбинирующего обработчика пустое возвращаемое значение, результат не будет вставлен, и первые N типы параметров целевого обработчика должны точно совпадать с типами параметров комбинирующего обработчика.

Результирующий адаптер имеет тот же тип, что и целевой, за исключением того, что первый тип параметра опускается, если он соответствует результату комбинирующего обработчика.

(Обратите внимание, что dropArguments можно использовать для удаления любых аргументов, которые не требуются ни комбинирующим, ни целевым обработчикам. Если некоторые входные аргументы предназначены только для комбинирующего обработчика, рассмотрите использование asCollector, поскольку эти аргументы не должны быть активны в стеке при вызове целевого обработчика.)

Пример:

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle trace = publicLookup().findVirtual(java.io.PrintStream.class,
  "println", methodType(void.class, String.class))
    .bindTo(System.out);
MethodHandle cat = lookup().findVirtual(String.class,
  "concat", methodType(String.class, String.class));
assertEquals("boojum", (String) cat.invokeExact("boo", "jum"));
MethodHandle catTrace = foldArguments(cat, trace);
// also prints "boo":
assertEquals("boojum", (String) catTrace.invokeExact("boo", "jum"));

Вот псевдокод для результирующего адаптера. В коде T представляет тип возвращаемого значения target и результирующего адаптера. V/v представляют тип и значение параметра и аргумента target, предшествующего позиции сгиба; V также является типом возвращаемого значения combiner. A/a обозначают типы и значения N параметров и аргументов в позиции сгиба. B/b представляют типы и значения target параметров и аргументов, которые следуют за сложенными параметрами и аргументами.

// there are N arguments in A...
T target(V, A[N]..., B...);
V combiner(A...);
T adapter(A... a, B... b) {
  V v = combiner(a...);
  return target(v, a..., b...);
}
// and if the combiner has a void return:
T target2(A[N]..., B...);
void combiner2(A...);
T adapter2(A... a, B... b) {
  combiner2(a...);
  return target2(a..., b...);
}

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

Этот метод тесно связан с foldArguments(MethodHandle, MethodHandle), но позволяет контролировать позицию в списке параметров, в которой происходит сгиб. Аргумент, контролирующий это, pos, представляет собой индекс с нуля. Указанный метод foldArguments(MethodHandle, MethodHandle) предполагает позицию 0.

Вот псевдокод для результирующего адаптера. В коде T представляет собой единый тип возвращаемого значения трёх вовлечённых обработчиков; A/a, типы и значения target параметров и аргументов, потребляемых test; и B/b, типы и значения target параметров и аргументов, которые не потребляются test.

boolean test(A...);
T target(A...,B...);
T fallback(A...,B...);
T adapter(A... a,B... b) {
  if (test(a...))
    return target(a..., b...);
  else
    return fallback(a..., b...);
}

Целевой и обработчик исключений должны иметь одинаковые типы аргументов и возвращаемого значения, за исключением того, что обработчик исключений может опустить хвостовые аргументы (аналогично предикату в guardWithTest). Кроме того, обработчик исключений должен иметь дополнительный ведущий параметр типа exType или его супертипа.

Вот псевдокод для результирующего адаптера. В коде T представляет тип возвращаемого значения для target и handler, соответственно, и результирующего адаптера; A/a, типы и значения аргументов для результирующего обработчика, используемые handler; и B/b, типы и значения аргументов для результирующего обработчика, отбрасываемых handler.

T target(A..., B...);
T handler(ExType, A...);
T adapter(A... a, B... b) {
  try {
    return target(a..., b...);
  } catch (ExType ex) {
    return handler(ex, a...);
  }
}

Целевой и обработчик исключений должны возвращать один и тот же тип, даже если обработчик всегда генерирует исключение. (Это может произойти, например, потому, что обработчик моделирует блок finally). Для создания такого обработчика исключений, генерирующего исключение, комбинируйте логику создания обработчика с throwException, чтобы создать обработчик с правильным типом возвращаемого значения.

Обработчик pred описывает условие цикла, а body — его тело. Цикл, полученный с помощью данного метода, в каждой итерации сначала вычисляет предикат, а затем выполняет его тело (если предикат вычисляет значение true). Цикл завершается, как только предикат вычисляет значение false (в этом случае тело не выполняется).

Обработчик init описывает начальное значение дополнительной необязательной локальной переменной цикла. В каждой итерации эта локальная переменная цикла, если присутствует, передаётся в body и обновляется значением, возвращённым из её вызова. Результатом выполнения цикла будет окончательное значение дополнительной локальной переменной цикла (если она присутствует).

Для этих обработчиков аргументов выполняются следующие правила:

• Обработчик body не должен быть null; его тип должен иметь вид (V A...)V, где V не является void, в противном случае (A...)void. (В случае void мы присваиваем типу void имя V, и мы будем писать (V A...)V с пониманием, что тип void V тихо опускается из списка параметров, оставляя (A...)V.)
• Список параметров (V A...) тела называется внутренним списком параметров. Он будет ограничивать списки параметров других частей цикла.
• Если тип переменной итерации V опускается из внутреннего списка параметров, получившийся более короткий список (A...) называется внешним списком параметров.
• Тип возвращаемого значения тела V, если он не void, определяет тип дополнительной переменной состояния цикла. Тело должно принимать и возвращать значение этого типа V.
• Если init не является null, он должен иметь тип возвращаемого значения V. Его список параметров (некоторой формы (A*)) должен быть эквивалентен внешнему списку параметров (A...).
• Если init является null, переменная цикла будет инициализирована своим стандартным значением.
• Обработчик pred не должен быть null. Он должен иметь boolean в качестве типа возвращаемого значения. Его список параметров (либо пустой, либо вида (V A*)) должен быть эквивалентен внутреннему списку параметров.

Тип результата и сигнатура параметров полученного обработчика цикла определяются следующим образом:

• Тип результата обработчика цикла — это тип результата V тела.
• Типы параметров обработчика цикла — это типы (A...) из внешнего списка параметров.

Вот псевдокод для полученного обработчика цикла. В коде V/v представляют тип/значение единственной переменной цикла и тип результата цикла; а A/a — тип/значение аргумента, переданного в цикл.

V init(A...);
boolean pred(V, A...);
V body(V, A...);
V whileLoop(A... a...) {
  V v = init(a...);
  while (pred(v, a...)) {
    v = body(v, a...);
  }
  return v;
}

Обработчик pred описывает условие цикла, а body — его тело. Цикл, полученный с помощью данного метода, в каждой итерации сначала выполняет своё тело, а затем вычисляет предикат. Цикл завершается, как только предикат вычисляет значение false после выполнения тела.

Обработчик init описывает начальное значение дополнительной необязательной локальной переменной цикла. В каждой итерации эта локальная переменная цикла, если присутствует, передаётся в body и обновляется значением, возвращённым из её вызова. Результатом выполнения цикла будет окончательное значение дополнительной локальной переменной цикла (если она присутствует).

Для этих обработчиков аргументов выполняются следующие правила:

• Обработчик body не должен быть null; его тип должен иметь вид (V A...)V, где V не является void, в противном случае (A...)void. (В случае void мы присваиваем типу void имя V, и мы будем писать (V A...)V с пониманием, что тип void V тихо опускается из списка параметров, оставляя (A...)V.)
• Список параметров (V A...) тела называется внутренним списком параметров. Он будет ограничивать списки параметров других частей цикла.
• Если тип переменной итерации V опускается из внутреннего списка параметров, получившийся более короткий список (A...) называется внешним списком параметров.
• Тип возвращаемого значения тела V, если он не void, определяет тип дополнительной переменной состояния цикла. Тело должно принимать и возвращать значение этого типа V.
• Если init не является null, он должен иметь тип возвращаемого значения V. Его список параметров (некоторой формы (A*)) должен быть эквивалентен внешнему списку параметров (A...).
• Если init является null, переменная цикла будет инициализирована своим стандартным значением.
• Обработчик pred не должен быть null. Он должен иметь boolean в качестве типа возвращаемого значения. Его список параметров (либо пустой, либо вида (V A*)) должен быть эквивалентен внутреннему списку параметров.

Тип результата и сигнатура параметров полученного обработчика цикла определяются следующим образом:

• Тип результата обработчика цикла — это тип результата V тела.
• Типы параметров обработчика цикла — это типы (A...) из внешнего списка параметров.

Вот псевдокод для полученного обработчика цикла. В коде V/v представляют тип/значение единственной переменной цикла и тип результата цикла; а A/a — тип/значение аргумента, переданного в цикл.

V init(A...);
boolean pred(V, A...);
V body(V, A...);
V doWhileLoop(A... a...) {
  V v = init(a...);
  do {
    v = body(v, a...);
  } while (pred(v, a...));
  return v;
}

Количество итераций определяется результатом вычисления iterations обработчика. Счётчик итераций i — это дополнительная переменная цикла итерации типа int. Она будет инициализирована значением 0 и увеличиваться на 1 на каждой итерации.

Если body обработчик возвращает значение нетипа void типа V, также присутствует ведущая переменная цикла итерации этого типа. Эта переменная инициализируется с помощью необязательного init обработчика или по умолчанию для типа V, если этот обработчик null.

На каждой итерации переменные итерации передаются в вызов body обработчика. Значение, отличное от void, возвращаемое из тела (типа V), обновляет ведущую переменную итерации. Результатом выполнения цикла обработчика будет конечное значение V этой переменной (или void, если переменной V нет).

Для аргументных обработчиков выполняются следующие правила:

• iterations обработчик не должен быть null и должен возвращать тип int, который здесь обозначается как I в списках типов параметров.
• body обработчик не должен быть null; его тип должен быть вида (V I A...)V, где V не является void, или же (I A...)void. (В случае void мы присваиваем типу void имя V, и мы будем писать (V I A...)V, понимая, что тип void V незаметно удаляется из списка параметров, оставляя (I A...)V.)
• Список параметров (V I A...) тела вносит вклад в список типов, называемый внутренним списком параметров. Он будет ограничивать списки параметров других частей цикла.
• В качестве специального случая, если тело вносит вклад только в типы V и I без дополнительных типов A, то внутренний список параметров дополняется типами аргументов A... iterations обработчика.
• Если типы переменных итерации (V I) удаляются из внутреннего списка параметров, полученный более короткий список (A...) называется внешним списком параметров.
• Тип возврата тела V, если он не void, определяет тип дополнительной переменной состояния цикла. Тело должно принимать ведущий параметр и возвращать значение этого типа V.
• Если init не является null, оно должно иметь тип возврата V. Его список параметров (некоторой формы (A*)) должен быть эффективно идентичным внешнему списку параметров (A...).
• Если init равно null, переменная цикла будет инициализирована своим значением по умолчанию.
• Список параметров iterations (некоторой формы (A*)) должен быть эффективно идентичен внешнему списку параметров (A...).

Тип результата и сигнатура параметров результирующего обработчика цикла определяются следующим образом:

• Тип результата обработчика цикла — это тип результата V тела.
• Типы параметров обработчика цикла — это типы (A...) из внешнего списка параметров.

Вот псевдокод для результирующего обработчика цикла. В коде V/v представляют тип/значение второй переменной цикла, а также тип результата цикла; а A.../a... представляют аргументы, передаваемые в цикл.

int iterations(A...);
V init(A...);
V body(V, int, A...);
V countedLoop(A... a...) {
  int end = iterations(a...);
  V v = init(a...);
  for (int i = 0; i < end; ++i) {
    v = body(v, i, a...);
  }
  return v;
}

Счётчик цикла i — это переменная итерации цикла типа int. Обработчики start и end определяют начальное (включительно) и конечное (исключительно) значения счётчика цикла. Счётчик цикла будет инициализирован значением int, полученным от оценки обработчика start, и доходить до значения, возвращаемого обработчиком end (исключая), с шагом 1.

Если обработчик body возвращает тип, отличный от void, то присутствует ведущая переменная итерации этого типа. Эта переменная инициализируется с помощью необязательного обработчика init или значения по умолчанию типа V, если такой обработчик отсутствует null.

На каждой итерации переменные итерации передаются в вызов обработчика body. Значение, отличное от void, возвращённое из тела (типа V), обновляет ведущую переменную итерации. Результатом выполнения обработчика цикла будет итоговое значение V этой переменной (или void, если переменной V нет).

Для аргументных обработчиков выполняются следующие правила:

• Обработчики start и end не должны быть null и оба должны возвращать общий тип int, здесь обозначаемый как I в списках типов параметров.
• Обработчик body не должен быть null; его тип должен иметь вид (V I A...)V, где V — тип, отличный от void, или же (I A...)void. (В случае void мы присваиваем типу void имя V, и будем писать (V I A...)V, понимая, что тип void V тихо удаляется из списка параметров, оставляя (I A...)V.)
• Список параметров (V I A...) тела вносит вклад в список типов, называемый внутренним списком параметров. Он будет ограничивать списки параметров других частей цикла.
• В качестве специального случая, если тело вносит вклад только в типы V и I без дополнительных типов A, то внутренний список параметров дополняется типами аргументов A... обработчика end.
• Если типы переменных итерации (V I) удаляются из внутреннего списка параметров, то получившийся более короткий список (A...) называется внешним списком параметров.
• Тип возврата тела V, если он не пустой void, определяет тип дополнительной переменной состояния цикла. Тело должно принимать в качестве ведущего параметра и возвращать значение этого типа V.
• Если init не пустой null, он должен иметь тип возврата V. Его список параметров (некоторой формы (A*)) должен быть эффективно идентичен внешнему списку параметров (A...).
• Если init пустой null, переменная цикла будет инициализирована своим значением по умолчанию.
• Список параметров start (некоторой формы (A*)) должен быть эффективно идентичен внешнему списку параметров (A...).
• Аналогично, список параметров end должен быть эффективно идентичен внешнему списку параметров.

Тип результата и сигнатура параметров результирующего обработчика цикла определяются следующим образом:

• Тип результата обработчика цикла — это тип результата V тела.
• Типы параметров обработчика цикла — это типы (A...) из внешнего списка параметров.

Вот псевдокод для результирующего обработчика цикла. В коде V/v представляют тип/значение второй переменной цикла, а также тип результата цикла; а A.../a... — аргументы, передаваемые в цикл.

int start(A...);
int end(A...);
V init(A...);
V body(V, int, A...);
V countedLoop(A... a...) {
  int e = end(a...);
  int s = start(a...);
  V v = init(a...);
  for (int i = s; i < e; ++i) {
    v = body(v, i, a...);
  }
  return v;
}

Сам итератор определяется значением iterator обработчика. Каждое производимое им значение хранится в переменной цикла типа T.

Если body обработчик возвращает тип, отличный от void, V, то присутствует ведущая переменная цикла этого типа. Эта переменная инициализируется с помощью необязательного init обработчика или по умолчанию типа V, если этот обработчик отсутствует.

В каждом цикле переменные цикла передаются в вызов body обработчика. Не-void значение, возвращённое из тела (типа V), обновляет ведущую переменную цикла. Результатом выполнения обработчика цикла будет конечное значение переменной V (или void, если переменной цикла нет).

Для аргументных обработчиков действуют следующие правила:

• body обработчик не должен быть null; его тип должен быть формы (V T A...)V, где V не void, или же (T A...)void. (В случае void мы присваиваем тип void имени V, и мы будем писать (V T A...)V, понимая, что тип void V тихо исключается из списка параметров, оставляя (T A...)V.)
• Список параметров (V T A...) тела вносит вклад в список типов, называемый внутренним списком параметров. Он будет ограничивать списки параметров других частей цикла.
• В качестве специального случая, если тело вносит вклад только в типы V и T без дополнительных типов A, то внутренний список параметров расширяется типами аргументов A... iterator обработчика; если это null, то добавляется единственный тип Iterable, образуя A... список.
• Если типы переменных цикла (V T) исключаются из внутреннего списка параметров, получившийся более короткий список (A...) называется внешним списком параметров.
• Тип возврата тела V, если он не void, определяет тип дополнительной переменной состояния цикла. Тело должно принимать ведущий параметр и возвращать значение этого типа V.
• Если init не null, то он должен иметь тип возврата V. Его список параметров (некоторой формы (A*)) должен быть эффективно идентичным внешнему списку параметров (A...).
• Если init - null, переменная цикла будет инициализирована своим значением по умолчанию (по умолчанию).
• Если iterator обработчик не null, то он должен иметь тип возврата java.util.Iterator или подтип его. Итератор, который он производит при выполнении цикла, должен генерировать значения, которые можно преобразовать к типу T.
• Список параметров iterator, который не null (некоторой формы (A*)), должен быть эффективно идентичным внешнему списку параметров (A...).
• Если iterator - null, он по умолчанию принимает обработчик метода, который ведёт себя как Iterable.iterator(). В этом случае внутренний список параметров (V T A...) должен содержать по меньшей мере один тип A, а параметр обработчика итератора корректируется для принятия ведущего типа A, как если бы он был преобразован методом asType. Ведущий тип A должен быть Iterable или подтипом его. Этот этап преобразования, производимый при построении цикла, не должен выбрасывать WrongMethodTypeException исключение.

Тип T может быть либо примитивным, либо ссылочным. Поскольку тип Iterator<T> стирается в представлении обработчика метода до базового типа Iterator, комбинатор iteratedLoop корректирует ведущий тип аргумента для body на Object, как если бы он был преобразован методом asType. Поэтому, если во время выполнения цикла появляется итератор неправильного типа, могут возникнуть исключения времени выполнения, являющиеся результатом динамических преобразований, выполняемых MethodHandle.asType(MethodType).

Тип результата и подпись параметров получившегося обработчика цикла определяются следующим образом:

• Тип результата обработчика цикла - это тип результата V тела.
• Типы параметров обработчика цикла - это типы (A...) из внешнего списка параметров.

Вот псевдокод для получившегося обработчика цикла. В коде V/v представляют тип/значение переменной цикла, а также тип результата цикла; T/t представляют элементы структуры, по которой итерируется цикл, а A.../a... - аргументы, передаваемые циклу.

Iterator<T> iterator(A...);  // defaults to Iterable::iterator
V init(A...);
V body(V,T,A...);
V iteratedLoop(A... a...) {
  Iterator<T> it = iterator(a...);
  V v = init(a...);
  while (it.hasNext()) {
    T t = it.next();
    v = body(v, t, a...);
  }
  return v;
}

Обработчик cleanup будет получать один или два дополнительных ведущих аргумента. Первый — это исключение, сгенерированное во время выполнения обработчика target, или null, если исключение не было сгенерировано. Второй — результат выполнения обработчика target, или, если он сгенерирует исключение, нулевое, или false значение требуемого типа в качестве заполнителя. Второй аргумент отсутствует, если обработчик target имеет тип возвращаемого значения void. (Обратите внимание, что, за исключением преобразований типов аргументов, комбинаторы представляют void значения в списках параметров, опуская соответствующие парадоксальные аргументы, а не вставляя null или нулевые значения.)

Обработчики target и cleanup должны иметь одинаковые соответствующие типы аргументов и возвращаемых значений, за исключением того, что обработчик cleanup может опускать хвостовые аргументы. Также обработчик cleanup должен иметь один или два дополнительных ведущих параметра:

• тип Throwable, который будет содержать исключение, сгенерированное обработчиком target (если таковое имеется); и
• параметр того же типа, что и тип возвращаемого значения обоих обработчиков target и cleanup, который будет содержать результат выполнения обработчика target. Этот параметр отсутствует, если target возвращает void.

Псевдокод для результирующего адаптера выглядит следующим образом. В коде V представляет тип возвращаемого значения конструкции try/finally; A/a — типы и значения аргументов результирующего обработчика, потребляемые очисткой; и B/b — те же значения аргументов, отбрасываемые очисткой.

V target(A..., B...);
V cleanup(Throwable, V, A...);
V adapter(A... a, B... b) {
  V result = (zero value for V);
  Throwable throwable = null;
  try {
    result = target(a..., b...);
  } catch (Throwable t) {
    throwable = t;
    throw t;
  } finally {
    result = cleanup(throwable, result, a...);
  }
  return result;
}

Обратите внимание, что сохранённые аргументы (a... в псевдокоде) не могут быть изменены во время выполнения целевого кода и передаются неизменными от вызывающей стороны к обработке, если она вызывается.

Целевой и обработчик очистки должны возвращать один и тот же тип, даже если обработчик очистки всегда генерирует исключение. Для создания такого генерирующего исключения обработчика очистки комбинируйте логику очистки с throwException, чтобы создать обработчик метода с нужным типом возвращаемого значения.

Обратите внимание, что tryFinally никогда не преобразует исключения в нормальные возвращаемые значения. В редких случаях, когда исключения необходимо преобразовать таким образом, сначала оберните цель с помощью catchException(MethodHandle, Class, MethodHandle), чтобы захватить выходящее исключение, а затем оберните с помощью tryFinally.

Рекомендуется, чтобы первый тип параметра cleanup объявлялся как Throwable, а не как узкий подтип. Это гарантирует, что cleanup всегда будет вызываться с любым исключением, которое target сгенерирует. Объявление более узкого типа может привести к генерации исключения ClassCastException обработчиком try-finally, если тип исключения, сгенерированного target, не может быть приведён к первому типу параметра cleanup. Обратите внимание, что различные типы исключений VirtualMachineError, LinkageError и RuntimeException могут в принципе генерироваться практически любым Java-кодом, и блок finally, который ловит (скажем) только IOException, скроет любые другие под ClassCastException.

Для значения селектора n, где значение n попадает в диапазон [0, N), и где N — количество обработчиков целевых методов, обработчик табличного переключения вызовет n-ый обработчик методов из списка целевых обработчиков методов.

Для значения селектора, которое не попадает в диапазон [0, N), обработчик табличного переключения вызовет указанный обработчик падения.

Все обработчики методов, передаваемые в этот метод, должны иметь одинаковый тип с дополнительным требованием, что ведущий параметр должен быть типа int. Ведущий параметр представляет селектор.

Любые хвостовые параметры, присутствующие в типе, также будут присутствовать в возвращаемом обработчике табличного переключения. Любые аргументы, назначенные этим параметрам, будут переданы вместе со значением селектора выбранному обработчику метода при его вызове.

Предоставленный макет определяет тип носителя^PREVIEW, размер в байтах^PREVIEW, выравнивание в байтах^PREVIEW и порядок байтов^PREVIEW, связанные с возвращаемым varHandle.

Список типов координат, связанных с возвращаемым varHandle, равен (MemorySegment, long), где тип координаты long соответствует смещению в байтах в указанный сегмент памяти. Таким образом, возвращаемый varHandle обращается к байтам по смещению в заданном сегменте памяти, собирая байты в значение типа varHandle или извлекая из него байты. Кроме того, операция доступа будет учитывать порядок следования байтов (endianness) и ограничения на выравнивание, выраженные в предоставленном макете.

В качестве примера рассмотрим макет памяти, представленный экземпляром GroupLayout^PREVIEW, созданным следующим образом:

    GroupLayout seq = java.lang.foreign.MemoryLayout.structLayout(
            MemoryLayout.paddingLayout(4),
            ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN).withName("value")
    );

    VarHandle handle = MethodHandles.memorySegmentViewVarHandle(ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN)); //(MemorySegment, long) -> int
    handle = MethodHandles.insertCoordinates(handle, 1, 4); //(MemorySegment) -> int

При вызове, например, VarHandle.set(Object...) на результирующем varHandle, входное значение (типа T, где T - тип последнего параметра первой функции фильтрации) обрабатывается с помощью первой функции фильтрации, а затем передаётся целевому varHandle. Аналогично, при вызове, например, VarHandle.get(Object...) на результирующем varHandle, возвращаемое значение, полученное от целевого varHandle (типа T, где T - тип последнего параметра второй функции фильтрации), обрабатывается второй функцией фильтрации и возвращается вызывающей стороне. Более сложные типы режимов доступа, такие как VarHandle.AccessMode.COMPARE_AND_EXCHANGE, могут применять оба фильтра одновременно.

Для того, чтобы функции фильтров преобразования в/из упакованный тип были корректны, их типы должны иметь вид (A... , S) -> T и (A... , T) -> S соответственно, где T - тип целевого varHandle. В этом случае результирующий varHandle будет иметь тип S и будет содержать дополнительные координаты A... (которые будут добавлены к координатам целевого varHandle).

Если функции фильтров преобразования в/из упакованный тип выбрасывают какие-либо проверенные исключения при вызове, результирующий varHandle будет выбрасывать исключение IllegalStateException.

Результирующий varHandle будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой varHandle.

При вызове, например, VarHandle.get(Object...) на результирующей обработке переменных, входящие координатные значения, начиная с позиции pos (типа C1, C2 ... Cn, где C1, C2 ... Cn — возвращаемые типы функций фильтрации по одному аргументу) преобразуются в новые значения (типа S1, S2 ... Sn, где S1, S2 ... Sn — типы параметров функций фильтрации по одному аргументу), а затем передаются (вместе с любой координатой, которая не была изменена адаптацией) целевой обработке переменных.

Для корректности координатных фильтров их типы должны быть в форме S1 -> T1, S2 -> T1 ... Sn -> Tn, где T1, T2 ... Tn — типы координат, начиная с позиции pos целевой обработки переменных.

Если любая из функций-фильтров при вызове генерирует проверяемое исключение, результирующая обработка переменных сгенерирует IllegalStateException.

Результирующая обработка переменных будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевая обработка переменных.

При вызове, например, VarHandle.get(Object...) на результирующей обработке переменных, входящие координатные значения объединяются со значениями связанных координат и затем передаются целевой обработке переменных.

Для корректности связанных координат их типы должны быть T1, T2 ... Tn , где T1, T2 ... Tn — типы координат, начиная с позиции pos целевой обработки переменных.

Результирующая обработка переменных будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевая обработка переменных.

Перестановка задается заданным массивом. Пусть newCoordinates.size() — количество входящих координат, а #O — количество исходящих координат (количество координат, связанных с целевой обработкой переменных). Тогда длина массива перестановки должна быть равна #O, а каждый элемент должен быть целым неотрицательным числом, меньшим чем #I. Для каждого N, меньшего чем #O, N-я исходящая координата будет взята из I-й входящей координаты, где I это reorder[N].

Преобразования значений координат не применяются. Тип каждой входящей координаты, как определяется newCoordinates, должен быть идентичен типу соответствующей исходящей координаты в целевой обработке переменных.

Массив перестановки не обязательно должен определять фактическую перестановку. Входящая координата будет дублирована, если её индекс встречается в массиве более одного раза, и входящая координата будет отброшена, если её индекс не встречается в массиве.

Результирующая обработка переменных будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевая обработка переменных.

Если R — тип возвращаемого значения фильтра (который не может быть void), целевой обработчик переменной должен принимать значение типа R в качестве координаты в позиции pos, предваряемое и/или сопровождаемое любыми координатами, не переданными фильтру. Координаты не переупорядочиваются, и возвращаемый фильтром результат заменяет (в порядке) всю подпоследовательность координат, изначально переданных адаптеру.

Типы аргументов (если таковые имеются) фильтра заменяют ноль или одну координаты типа целевого обработчика переменной в позиции pos в результирующем адаптированном обработчике переменной. Тип возвращаемого значения фильтра должен быть идентичен типу координаты целевого обработчика переменной в позиции pos, и эта координата целевого обработчика переменной поставляется значением, возвращаемым фильтром.

Если какой-либо из фильтров генерирует проверяемое исключение при вызове, результирующий обработчик переменной сгенерирует IllegalStateException.

Результирующий обработчик переменной будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой обработчик переменной.

Аргумент pos может находиться в диапазоне от нуля до N, где N — арность типов координат целевого обработчика переменной. Если pos равно нулю, фиктивные координаты будут предшествовать реальным аргументам цели; если pos равно N, они будут следовать за ними.

Результирующий обработчик переменной будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой обработчик переменной.