Класс MethodHandles

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

По соглашению, классом lookup этого объекта lookup будет Object.

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

• Объект 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 для этого поиска должны иметь оригинальный доступ для извлечения данных класса.

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

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

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

Доступ приведет к ReadOnlyBufferException для всех режимов доступа, отличных от чтения, если ByteBuffer является только для чтения.

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

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

Для прямых буферов доступ к байтам по индексу может быть выровнен или невыровнен для 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 во время выполнения, вводится значение 0.

Переупорядочение задаётся массив. Назовем количество входных параметров (значение newType.parameterCount()) и количество выходных параметров (значение 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 (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 обозначают типы и значения параметров и аргументов на позиции складывания. 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 определяют начальное (включительно) и конечное (исключительно) значения счётчика цикла. Счётчик цикла будет инициализирован значением, возвращаемым из оценки обработчика 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, то присутствует ведущая переменная цикла этого типа. Эта переменная инициализируется с помощью необязательного init обработчика или по умолчанию для типа V, если этот обработчик null.

В каждой итерации переменные цикла передаются в вызов 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 или нулевые значения.)

Обработчики cleanup и 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, если тип исключения, брошенного target, не может быть приведён к первому типу параметра cleanup. Обратите внимание, что различные типы исключений VirtualMachineError, LinkageError и RuntimeException могут, в принципе, быть выброшены практически любым кодом Java, и блок finally, который ловит (скажем), только IOException, скрывает любые другие исключения за ClassCastException.

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

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

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

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

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

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

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

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

При вызове, например, 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 — тип возвращаемого значения фильтра, то:

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

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

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

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

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