Класс MethodHandles

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

Согласно общепринятому соглашению, класс поиска этого объекта поиска будет Object.

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

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

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

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

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

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

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

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

Для получения данных класса режимы поиска этого объекта поиска должны включать исходный доступ.

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

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

Для получения данных класса режимы поиска этого объекта поиска должны включать исходный доступ.

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

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

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

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

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

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

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

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

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

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

Возвращённый VarHandle поддерживает только обычные режимы доступа get и set. Для всех остальных режимов доступа будет выброшено исключение UnsupportedOperationException.

Поддерживаются следующие типы компонентов (типы переменных): short, char, int, long, float и double.

Если ByteBuffer доступен только для чтения, любая операция доступа, кроме режимов чтения, приведёт к ReadOnlyBufferException.

Доступ к байтам по заданному индексу приведёт к IndexOutOfBoundsException, если индекс меньше 0 или больше предельного значения ByteBuffer за вычетом размера (в байтах) T.

Для байтовых буферов в куче доступ всегда является невыровненным. В результате возвращаемый дескриптор переменной поддерживает только обычные режимы доступа get и set. Для всех остальных режимов доступа будет выброшено исключение IllegalStateException.

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

• режимы доступа для чтения и записи для всех T. Режимы доступа get и set для long и double поддерживаются, но не гарантируют атомарность, как описано в разделе 17.7 Спецификации языка Java.
• режимы атомарного обновления для 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; в противном случае поведение будет таким, как если бы для преобразования цели к требуемому type использовался asType.

Тип возвращаемого дескриптора вызова не будет совпадать с заданным 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 целевого дескриптора, следующий — следующему аргументу и так далее. Функции-фильтры вызываются слева направо.

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

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

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

Пример:

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, перед которым и/или после которого могут находиться аргументы, не передаваемые фильтру. Если фильтр возвращает void, целевой дескриптор должен принимать все аргументы, не передаваемые фильтру. Аргументы не меняют порядок, а результат, возвращенный фильтром, заменяет (по порядку) всю подпоследовательность аргументов, изначально переданных адаптеру.

Типы аргументов фильтра (если они есть) заменяют в результирующем адаптированном дескрипторе метода ноль или один тип аргумента целевого дескриптора в позиции 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

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

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

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

Пример:

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 типов параметров целевого дескриптора должны точно совпадать с параметрами комбинирующего дескриптора.

Если комбинирующий дескриптор возвращает void, результат не вставляется, а первые 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, чтобы создать дескриптор метода с правильным типом возвращаемого значения.

Интуитивно каждый цикл образован одной или несколькими «частями», каждая из которых задает локальную переменную итерации и/или условие выхода из цикла. При каждой итерации цикла выполняется каждая часть по порядку. Часть может обновлять свою переменную итерации; кроме того, она может выполнять проверку и условный выход из цикла. Чтобы выразить эту логику в терминах дескрипторов методов, каждая часть задает до четырех независимых действий:

• init: инициализация переменной итерации v типа V перед выполнением цикла.
• step: при выполнении части — шаг обновления переменной итерации v.
• pred: при выполнении части — вычисление предиката для проверки выхода из цикла.
• fini: если часть приводит к выходу из цикла — выполнение завершающей функции для вычисления возвращаемого значения цикла.

Некоторые части могут быть опущены в соответствии с определенными правилами; в этом случае предусмотрено полезное поведение по умолчанию. Подробное описание приведено ниже.

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

Параметры цикла: Функция части может принимать все значения переменных итерации, которые она вправе принимать, а также дополнительные конечные параметры. Такие дополнительные значения называются параметрами цикла; их типы и значения обозначаются как (A...) и (a...). Они становятся параметрами результирующего дескриптора цикла и передаются при каждом выполнении цикла. (Поскольку функции init не принимают переменные итерации v, любой параметр функции init автоматически является параметром цикла a.) Как и в случае с переменными итерации, функции частей могут принимать параметры цикла, но это не обязательно. Эти параметры цикла являются инвариантными значениями, доступными во всем цикле.

Параметры, доступные повсюду: Каждая функция части, кроме init, может наблюдать все состояние цикла, поскольку ей можно передать полный список (v... a...) текущих значений переменных итерации и входных параметров цикла. Функции init могут наблюдать начальное состояние до цикла в виде (a...). Большинству функций частей не понадобятся все эти сведения, но формально они будут связаны с ними так, как если бы к ним применили dropArguments(MethodHandle, int, List). В частности, обозначением (V*) мы будем выражать произвольный префикс полной последовательности (V...) (и аналогично для (v*), (A*), (a*)). В этих обозначениях общий вид списка параметров функции init — (A*), а общий вид списка параметров функции, отличной от init, — (V*) или (V... A*).

Проверка структуры частей: Для соединения всех частей цикла при заданном наборе частей выполняется ряд проверок и корректировок. Они подробно описаны в следующих шагах. В этих шагах каждое употребление слова «должен» соответствует месту, где будет выброшено исключение IllegalArgumentException, если входные данные комбинатора цикла не удовлетворяют требуемому ограничению.

Эффективно идентичные последовательности: Список параметров A считается эффективно идентичным другому списку параметров B, если A и B идентичны либо если A короче и совпадает с собственным префиксом B. Говоря о неупорядоченном наборе списков параметров, мы считаем, что весь набор «эффективно идентичен», если он содержит самый длинный список и все его элементы эффективно идентичны этому самому длинному списку. Например, любой набор последовательностей типов вида (V*) эффективно идентичен; то же верно, если добавить больше последовательностей вида (V... A*).

Шаг 0: определить структуру частей.

1. Массив частей (типа MethodHandle[][]) не должен быть null и должен содержать как минимум один элемент.
2. Массив частей не может содержать значения null или подмассивы длиной больше четырех элементов.
3. Считается, что части длиной меньше четырех элементов дополнены значениями null до длины четыре. Дополнение выполняется добавлением элементов в конец массива.
4. Части, состоящие только из значений null, игнорируются.
5. Каждая часть рассматривается как кортеж из четырех функций, называемых «init», «step», «pred» и «fini».

Шаг 1A: определить типы переменных итерации (V...).

1. Тип переменной итерации для каждой части определяется типами возвращаемых значений функций init и step этой части.
2. Если обе функции опущены, у соответствующей части нет переменной итерации (в качестве типа для обозначения этого используется void). Если одна из функций опущена, тип возвращаемого значения другой функции определяет тип переменной итерации этой части. Если заданы обе функции, общий тип возвращаемого значения (они должны быть идентичны) определяет тип переменной итерации этой части.
3. Сформировать список типов возвращаемых значений (в порядке частей), исключив все вхождения void.
4. Этот список типов называется «типами переменных итерации» ((V...)).

Шаг 1B: определить параметры цикла (A...).

• Проверить и собрать списки параметров функций init (имеющие вид (A*)).
• Проверить и собрать суффиксы списков параметров функций step, pred и fini после удаления типов переменных итерации. (Они должны иметь вид (V... A*); следует собирать только части (A*).)
• Не собирать суффиксы списков параметров функций step, pred и fini, если они не начинаются со всех типов переменных итерации. (Эти типы будут проверены на шаге 2 вместе со всеми типами функций частей.)
• Опущенные функции частей игнорируются. (Иными словами, считается, что их списки параметров пусты.)
• Все собранные списки параметров должны быть эффективно идентичны.
• Самый длинный список параметров (который обязательно единственный) называется «внешним списком параметров» ((A...)).
• Если такого списка параметров нет, внешний список параметров считается пустой последовательностью.
• Объединенный список, состоящий из типов переменных итерации, за которыми следуют типы внешних параметров, называется «внутренним списком параметров».

Шаг 1C: определить тип возвращаемого значения цикла.

1. Проверить типы возвращаемых значений функций fini, не учитывая опущенные функции fini.
2. Если функций fini нет, тип возвращаемого значения цикла — void.
3. В противном случае общий тип возвращаемого значения R функций fini (типы их возвращаемых значений должны быть идентичны) определяет тип возвращаемого значения цикла.

Шаг 1D: проверить остальные типы.

1. Должна быть задана как минимум одна функция pred.
2. Тип возвращаемого значения каждой заданной функции pred должен быть boolean.

Шаг 2: определить списки параметров.

1. Список параметров результирующего дескриптора цикла будет совпадать с внешним списком параметров (A...).
2. Список параметров функций init будет скорректирован в соответствии с внешним списком параметров. (Обратите внимание, что их списки параметров уже эффективно идентичны этому списку.)
3. Список параметров каждой заданной функции, отличной от init (step, pred и fini), должен быть эффективно идентичен внутреннему списку параметров (V... A...).

Шаг 3: заполнить опущенные функции.

1. Если функция init опущена, использовать значение по умолчанию для типа переменной итерации этой части.
2. Если функция step опущена, использовать тождественную функцию типа переменной итерации этой части; перед параметром тождественной функции добавить отброшенные параметры для переменных итерации, отличных от void, в предшествующих частях. (Это превратит переменную цикла в локальный инвариант цикла.)
3. Если функция pred опущена, использовать константную функцию true. (С точки зрения этой части цикл продолжит выполняться. Обратите внимание, что в таких случаях соответствующая функция fini недостижима.)
4. Если функция fini опущена, использовать значение по умолчанию для типа возвращаемого значения цикла.

Шаг 4: заполнить отсутствующие типы параметров.

1. На этом этапе список параметров каждой функции init эффективно идентичен внешнему списку параметров (A...), но некоторые списки могут быть короче. Дополнить конец списка каждой функции init с коротким списком параметров.
2. На этом этапе список параметров каждой функции, отличной от init, эффективно идентичен внутреннему списку параметров (V... A...), но некоторые списки могут быть короче. Дополнить конец списка каждой функции, отличной от init, с коротким списком параметров.
3. Списки аргументов дополняются путем отбрасывания неиспользуемых конечных аргументов.

Заключительные замечания.

1. После выполнения этих шагов все части скорректированы путем добавления опущенных функций и аргументов.
2. Все функции init имеют общий список типов параметров (A...), который будет и у итогового дескриптора цикла.
3. Все функции fini имеют общий тип возвращаемого значения R, который будет и у итогового дескриптора цикла.
4. Все функции, кроме init, имеют общий список типов параметров (V... A...), состоящий из переменных итерации (не-void) V, за которыми следуют параметры цикла.
5. Типы возвращаемых значений каждой пары функций init и step совпадают: V.
6. Каждая функция, кроме init, может наблюдать текущие значения (v...) всех переменных итерации.
7. Каждая функция может наблюдать входные значения (a...) всех параметров цикла.

Пример. Как следует из шага 1A выше, комбинатор loop обладает следующим свойством:

• Заданы N частей Cn = {null, Sn, Pn} с n = 1..N.
• Предположим, что дескрипторы предикатов Pn либо являются null, либо не имеют параметров. (Только один Pn должен быть не-null.)
• Предположим, что дескрипторы шагов Sn имеют сигнатуры (B1..BX)Rn для некоторого постоянного X>=N.
• Пусть Q — количество типов, отличных от void, Rn, а (V1...VQ) — последовательность этих типов.
• Должно выполняться Vn == Bn для n = 1..min(X,Q).
• Типы параметров Vn будут интерпретироваться как локальные для цикла элементы состояния (V...).
• Все оставшиеся типы BQ+1..BX (если Q<X) определяют типы параметров результирующего дескриптора цикла (A...).

Выполнение цикла.

1. При вызове цикла входные значения цикла сохраняются в локальных переменных, чтобы передавать их каждой функции части. Эти локальные переменные инвариантны в цикле.
2. Каждая функция init выполняется в порядке частей (с передачей внешних аргументов (a...)), а значения, отличные от void, сохраняются в локальных переменных как переменные итерации (v...). Эти локальные переменные будут изменяться в цикле (если только соответствующие функции step не ведут себя как тождественные функции, как отмечено выше).
3. Всем функциям, кроме init, передается внутренний список параметров, состоящий из значений переменных итерации, отличных от void, (v...) (в порядке частей), а затем входных данных цикла (a...) (в порядке аргументов).
4. Затем функции step и pred выполняются в порядке частей (сначала step, затем pred), пока функция pred не вернет false.
5. Результат, отличный от void, вызова функции step используется для обновления соответствующего значения в последовательности (v...) переменных цикла. Обновленное значение сразу становится доступным всем последующим вызовам функций.
6. Если функция pred возвращает false, вызывается соответствующая функция fini, а полученное значение типа R возвращается как результат всего цикла.
7. Если все функции pred всегда возвращают true, функции fini никогда не вызываются, и цикл может завершиться только путем выбрасывания исключения.

Советы по использованию.

• Хотя каждая функция step получает текущие значения всех переменных цикла, иногда ей требуется наблюдать только текущее значение собственной переменной. В таком случае функции step может потребоваться явно отбросить все предшествующие переменные цикла. Для этого нужно указать их типы, например в выражении dropArguments(step, 0, V0.class, ...).
• Переменные цикла не обязательно должны изменяться: они могут быть инвариантами цикла. Часть может создать инвариант цикла с помощью подходящей функции init без функций step, pred или fini. Это может пригодиться, чтобы «подключить» входной аргумент цикла к функции step или pred соседней переменной цикла.
• Если некоторые функции частей являются виртуальными методами экземпляра, сам экземпляр удобно поместить в начальную инвариантную «переменную» цикла, используя начальную часть вроде new MethodHandle[]{identity(ObjType.class)}. В этом случае ссылка на экземпляр будет первым значением переменной итерации, и виртуальные методы будет удобно использовать в качестве частей, поскольку все они будут принимать начальную ссылку на экземпляр, соответствующую этому значению.

V... init...(A...);
boolean pred...(V..., A...);
V... step...(V..., A...);
R fini...(V..., A...);
R loop(A... a) {
  V... v... = init...(a...);
  for (;;) {
    for ((v, p, s, f) in (v..., pred..., step..., fini...)) {
      v = s(v..., a...);
      if (!p(v..., a...)) {
        return f(v..., a...);
      }
    }
  }
}

Дескриптор 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. Возвращаемое телом цикла значение типа V, отличное от void, обновляет ведущую переменную итерации. Результатом выполнения дескриптора цикла будет итоговое значение 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, отличный от V, также присутствует ведущая переменная итерации цикла этого типа. Эта переменная инициализируется с помощью необязательного дескриптора init либо значением по умолчанию типа V, если этот дескриптор равен null.

В каждой итерации переменные итерации передаются при вызове дескриптора body. Возвращаемое телом цикла значение типа V, отличное от void, обновляет ведущую переменную итерации. Результатом выполнения дескриптора цикла будет итоговое значение 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, если этот дескриптор равен null.

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

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

• Дескриптор 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 либо, если он выбрасывает исключение, значение null, ноль или 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. Объявление более узкого типа может привести к тому, что дескриптор try-finally выбросит ClassCastException, если тип исключения, выброшенного target, нельзя присвоить первому типу параметра cleanup. Обратите внимание, что исключения различных типов — VirtualMachineError, LinkageError и RuntimeException — теоретически могут быть выброшены практически любым кодом Java, и блок finally, перехватывающий, например, только IOException, замаскирует остальные исключения за ClassCastException.

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

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

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

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

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

Чтобы фильтры упаковки и распаковки были корректно сформированы, их типы должны иметь вид (A... , S) -> T и (A... , T) -> S соответственно, где T — тип целевого var handle. В этом случае полученный var handle будет иметь тип S и дополнительные координаты A... (которые будут добавлены к координатам целевого var handle).

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

Полученный var handle будет поддерживать те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой var handle.

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

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

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

Полученный var handle будет поддерживать те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой var handle.

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

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

Полученный var handle будет поддерживать те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой var handle.

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

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

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

Полученный var handle будет поддерживать те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой var handle.

Если R — тип возвращаемого значения фильтра, то:

• если R не является void, целевой var handle должен иметь координату типа R в позиции pos. Типы параметров фильтра заменят тип координаты в позиции pos целевого var handle. При вызове возвращённого var handle фильтр сначала вызывается, а его результат передаётся вместо координаты в позиции pos при последующем вызове целевого var handle.
• если R является void, типы параметров фильтра (если они есть) будут вставлены в список типов координат целевого var handle в позиции pos. В этом случае при вызове возвращённого var handle фильтр фактически выполняет побочное действие: принимает некоторые значения координат, после чего происходит последующий вызов целевого var handle.

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

Полученный var handle будет поддерживать те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой var handle.

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

Полученный var handle будет поддерживать те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой var handle.