Класс MethodHandle

При наблюдении этого метода через API ядра отражения он будет представлен как единственный нативный метод, принимающий массив объектов и возвращающий объект. Если этот нативный метод вызывается напрямую через java.lang.reflect.Method.invoke, через JNI или косвенно через Lookup.unreflect, будет брошено исключение UnsupportedOperationException.

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

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

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

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

При наблюдении этого метода через API ядра отражения он будет представлен как единственный нативный метод, принимающий массив объектов и возвращающий объект. Если этот нативный метод вызывается напрямую через java.lang.reflect.Method.invoke, через JNI или косвенно через Lookup.unreflect, будет брошено исключение UnsupportedOperationException.

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

• Определение длины массива аргументов как N. Для нулевой ссылки, N=0.
• Сборка элементов массива как логического списка аргументов, каждый из которых статически типизирован как Object.
• Определение количества параметров типа этого обработчика метода, как M.
• Определение общего типа TN аргументов N или аргументов M, если меньше N, как TN=MethodType.genericMethodType(Math.min(N, M)).
• Если N больше M, выполняется проверка и действия для сокращения логического списка аргументов:
  • Проверка, что этот обработчик метода имеет переменное число аргументов с конечным параметром некоторого массива типа A[]. В противном случае вызов завершается с WrongMethodTypeException.
  • Сборка заключительных элементов (их N-M+1) из логического списка аргументов в один массив типа A[], используя преобразования asType для преобразования каждого заключительного аргумента в тип A.
  • Если любое из этих преобразований невозможно, вызов завершается либо с ClassCastException, если какой-либо заключительный элемент не может быть преобразован в A, или с NullPointerException, если какой-либо заключительный элемент является null, и A не является типом ссылки.
  • Замена логических аргументов, собранных в массив типа A[], самим массивом, сокращая список аргументов до длины M. Этот заключительный аргумент сохраняет статический тип A[].
  • Изменение типа TN путём изменения типа N-го параметра с Object на A[].
• Приведение исходного целевого обработчика метода MH0 к необходимому типу, как MH1 = MH0.asType(TN).
• Распространение списка аргументов в N отдельных аргументов A0, ....
• Вызов обработчика метода с изменённым типом на распакованных аргументах: MH1.invokeExact(A0, ...).
• Получение возвращаемого значения как ссылки Object.

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

В отличие от режима вызова generic, который может «переиспользовать» массив аргументов, передавая его напрямую целевому методу, этот режим вызова всегда создаёт новый параметр массива, даже если исходный массив, переданный invokeWithArguments, был бы приемлем как прямой аргумент целевого метода. Даже если число M фактических аргументов равно количеству аргументов N, и последний аргумент динамически является подходящим массивом типа A[], он всё равно будет упакован в новый массив с одним элементом, так как место вызова статически типизирует аргумент как Object, а не как тип массива. Это не специальное правило для этого метода, а скорее обычный эффект правил вызова с переменным числом аргументов .

Из-за действия шага asType, по мере необходимости применяются следующие преобразования аргументов:

• преобразование ссылки
• распаковка
• расширяющие преобразования примитивов
• преобразование переменного числа аргументов

Возвращаемое значение вызова упаковывается, если это примитив, или приводится к null, если возвращаемый тип — void.

В отличие от методов с полиморфизмом сигнатуры invokeExact и invoke, invokeWithArguments можно получить обычным способом через API ядра отражения и JNI. Поэтому он может быть использован как мост между нативным или рефлексивным кодом и обработчиками методов.

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

  invokeWithArguments(arguments.toArray())

Допустимы списки большого размера, если у этого метода-обработчика переменное количество аргументов. Подробности см. в invokeWithArguments(Object[]).

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

Новый метод-обработчик при вызове выполнит следующие шаги:

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

Этот метод обеспечивает ключевое поведенческое различие между invokeExact и обычным, неточным invoke. Два метода выполняют те же шаги, когда тип вызывающего точно совпадает с типом вызываемого, но когда типы отличаются, обычный invoke также вызывает asType (или какой-либо внутренний эквивалент), чтобы согласовать типы вызывающего и вызываемого.

Если текущий метод — это метод-обработчик с переменным количеством аргументов, преобразование списка аргументов может включать преобразование и сборку нескольких аргументов в массив, как описано в другом месте. Во всех остальных случаях все преобразования применяются попарно, то есть каждый аргумент или возвращаемое значение преобразуется ровно в один аргумент или возвращаемое значение (или не возвращается). Применённые преобразования определяются путём обращения к соответствующим типам компонентов старых и новых типов метода-обработчика.

Пусть T0 и T1 — это соответствующие новые и старые типы параметров или старые и новые типы возвращаемых значений. В частности, для некоторого допустимого индекса i, пусть T0=newType.parameterType(i) и T1=this.type().parameterType(i). Или же, двигаясь в другом направлении для возвращаемых значений, пусть T0=this.type().returnType() и T1=newType.returnType(). Если типы одинаковы, новый метод-обработчик не вносит изменений в соответствующий аргумент или возвращаемое значение (если таковое есть). В противном случае, если возможно, применяется одно из следующих преобразований:

• Если T0 и T1 — ссылки, то применяется приведение типа к T1. (Типы не обязательно должны быть связаны каким-либо определённым образом. Это связано с тем, что динамическое значение null может быть преобразовано в любой тип ссылки.)
• Если T0 и T1 — примитивные типы, то применяется преобразование вызова Java-метода (JLS 5.3), если оно существует. (В частности, T0 должен преобразовываться в T1 с помощью расширяющего преобразования примитивного типа.)
• Если T0 — примитивный тип, а T1 — ссылка, применяется преобразование приведения Java (JLS 5.5), если оно существует. (В частности, значение упаковывается из T0 в его оберточное класс, который затем расширяется по мере необходимости до T1.)
• Если T0 — ссылка, а T1 — примитивный тип, в runtime будет применено распаковывание, возможно, за которым последует преобразование вызова Java-метода (JLS 5.3) над примитивным значением. (Это расширяющие преобразования примитивных типов.) T0 должен быть оберточным классом или его супертипом. (В случае, когда T0 — это Object, это преобразования, разрешённые java.lang.reflect.Method.invoke.) Преобразование распаковки должно иметь возможность успеха, что означает, что если T0 сам по себе не является оберточным классом, должен существовать по крайней мере один оберточный класс TW, являющийся подтипом T0, и значение примитивного типа которого, полученное в результате распаковки, может быть расширено до T1.
• Если тип возвращаемого значения T1 помечен как void, любое возвращаемое значение отбрасывается
• Если тип возвращаемого значения T0 — void, а T1 — ссылка, вводится значение null.
• Если тип возвращаемого значения T0 — void, а T1 — примитивный тип, вводится нулевое значение.

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

Во время выполнения преобразования, применяемые к аргументам или возвращаемым значениям ссылочного типа, могут потребовать дополнительных проверок во время выполнения, которые могут завершиться ошибкой. Операция распаковки может завершиться ошибкой, потому что исходная ссылка равна null, что приведёт к NullPointerException. Операция распаковки или приведение типа ссылки также могут завершиться ошибкой при ссылке на объект неверного типа, что приведёт к ClassCastException. Хотя операция распаковки может принимать несколько типов обёрток, если ни одна из них недоступна, будет выброшено ClassCastException.

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

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

Перед вызовом целевого объекта адаптер проверяет, что массив содержит ровно достаточно элементов для предоставления правильного количества аргументов методу-обработчику целевого объекта. (Массив также может быть null, когда требуется ноль элементов.)

Когда адаптер вызывается, длина предоставленного array аргумента запрашивается так, как будто это делается с помощью array.length или arraylength байткода. Если адаптер принимает аргумент массива с нулевой длиной, предоставленный array аргумент может быть либо массивом нулевой длины, либо null; в противном случае адаптер выбросит NullPointerException, если массив null, и выбросит IllegalArgumentException, если массив не имеет необходимого количества элементов.

Вот несколько простых примеров методов-обработчиков с разбросом массивов:

MethodHandle equals = publicLookup()
  .findVirtual(String.class, "equals", methodType(boolean.class, Object.class));
assert( (boolean) equals.invokeExact("me", (Object)"me"));
assert(!(boolean) equals.invokeExact("me", (Object)"thee"));
// spread both arguments from a 2-array:
MethodHandle eq2 = equals.asSpreader(Object[].class, 2);
assert( (boolean) eq2.invokeExact(new Object[]{ "me", "me" }));
assert(!(boolean) eq2.invokeExact(new Object[]{ "me", "thee" }));
// try to spread from anything but a 2-array:
for (int n = 0; n <= 10; n++) {
  Object[] badArityArgs = (n == 2 ? new Object[0] : new Object[n]);
  try { assert((boolean) eq2.invokeExact(badArityArgs) && false); }
  catch (IllegalArgumentException ex) { } // OK
}
// spread both arguments from a String array:
MethodHandle eq2s = equals.asSpreader(String[].class, 2);
assert( (boolean) eq2s.invokeExact(new String[]{ "me", "me" }));
assert(!(boolean) eq2s.invokeExact(new String[]{ "me", "thee" }));
// spread second arguments from a 1-array:
MethodHandle eq1 = equals.asSpreader(Object[].class, 1);
assert( (boolean) eq1.invokeExact("me", new Object[]{ "me" }));
assert(!(boolean) eq1.invokeExact("me", new Object[]{ "thee" }));
// spread no arguments from a 0-array or null:
MethodHandle eq0 = equals.asSpreader(Object[].class, 0);
assert( (boolean) eq0.invokeExact("me", (Object)"me", new Object[0]));
assert(!(boolean) eq0.invokeExact("me", (Object)"thee", (Object[])null));
// asSpreader and asCollector are approximate inverses:
for (int n = 0; n <= 2; n++) {
    for (Class<?> a : new Class<?>[]{Object[].class, String[].class, CharSequence[].class}) {
        MethodHandle equals2 = equals.asSpreader(a, n).asCollector(a, n);
        assert( (boolean) equals2.invokeWithArguments("me", "me"));
        assert(!(boolean) equals2.invokeWithArguments("me", "thee"));
    }
}
MethodHandle caToString = publicLookup()
  .findStatic(Arrays.class, "toString", methodType(String.class, char[].class));
assertEquals("[A, B, C]", (String) caToString.invokeExact("ABC".toCharArray()));
MethodHandle caString3 = caToString.asCollector(char[].class, 3);
assertEquals("[A, B, C]", (String) caString3.invokeExact('A', 'B', 'C'));
MethodHandle caToString2 = caString3.asSpreader(char[].class, 2);
assertEquals("[A, B, C]", (String) caToString2.invokeExact('A', "BC".toCharArray()));

Этот метод очень похож на asSpreader(Class, int), но принимает дополнительный spreadArgPos аргумент, чтобы указать, в какой позиции списка параметров должно происходить распространение.

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

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

(Массив также может быть общей константой, когда arrayLength равно нулю.)

(Примечание: arrayType часто идентичен последнему типу параметра исходной цели. Это явный аргумент для симметрии с asSpreader, а также для того, чтобы цель могла использовать простой Object в качестве своего последнего типа параметра.)

Для создания адаптера сбора, который не ограничен определённым количеством собираемых аргументов, используйте asVarargsCollector или withVarargs вместо этого.

Вот несколько примеров обработчиков методов сбора массивов:

MethodHandle deepToString = publicLookup()
  .findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));
assertEquals("[won]",   (String) deepToString.invokeExact(new Object[]{"won"}));
MethodHandle ts1 = deepToString.asCollector(Object[].class, 1);
assertEquals(methodType(String.class, Object.class), ts1.type());
//assertEquals("[won]", (String) ts1.invokeExact(         new Object[]{"won"})); //FAIL
assertEquals("[[won]]", (String) ts1.invokeExact((Object) new Object[]{"won"}));
// arrayType can be a subtype of Object[]
MethodHandle ts2 = deepToString.asCollector(String[].class, 2);
assertEquals(methodType(String.class, String.class, String.class), ts2.type());
assertEquals("[two, too]", (String) ts2.invokeExact("two", "too"));
MethodHandle ts0 = deepToString.asCollector(Object[].class, 0);
assertEquals("[]", (String) ts0.invokeExact());
// collectors can be nested, Lisp-style
MethodHandle ts22 = deepToString.asCollector(Object[].class, 3).asCollector(String[].class, 2);
assertEquals("[A, B, [C, D]]", ((String) ts22.invokeExact((Object)'A', (Object)"B", "C", "D")));
// arrayType can be any primitive array type
MethodHandle bytesToString = publicLookup()
  .findStatic(Arrays.class, "toString", methodType(String.class, byte[].class))
  .asCollector(byte[].class, 3);
assertEquals("[1, 2, 3]", (String) bytesToString.invokeExact((byte)1, (byte)2, (byte)3));
MethodHandle longsToString = publicLookup()
  .findStatic(Arrays.class, "toString", methodType(String.class, long[].class))
  .asCollector(long[].class, 1);
assertEquals("[123]", (String) longsToString.invokeExact((long)123));

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

Этот метод очень похож на asCollector(Class, int), но отличается тем, что его collectArgPos аргумент указывает, с какой позиции в списке параметров аргументы должны собираться. Этот индекс начинается с нуля.

Тип и поведение адаптера будут такими же, как у целевого объекта, за исключением того, что определённые invoke и asType запросы могут привести к тому, что последующие позиционные аргументы будут собраны в конечный параметр целевого объекта. Кроме того, тип последнего параметра адаптера будет arrayType, даже если у целевого объекта другой тип последнего параметра.

Данная трансформация может вернуть this, если обработчик метода уже имеет переменную арность, а тип его конечного параметра идентичен arrayType.

При вызове с invokeExact, адаптер вызывает целевой объект без изменения аргументов. (Примечание: Это поведение отличается от коллектора фиксированной арности, так как он принимает весь массив неопределённой длины, а не фиксированное количество аргументов.)

При вызове с обычным, неточной invoke, если тип вызывающего объекта совпадает с типом адаптера, адаптер вызывает целевой объект так же, как с invokeExact. (Это обычное поведение для invoke, когда типы совпадают.)

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

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

Тип вызывающего объекта должен предоставить по меньшей мере достаточное количество аргументов, и правильного типа, чтобы удовлетворить требованию целевого объекта к позиционным аргументам перед конечным аргументом массива. Таким образом, вызывающий объект должен предоставить как минимум N-1 аргументов, где N — арность целевого объекта. Кроме того, должны существовать преобразования из входных аргументов в аргументы целевого объекта. Как и при других применениях обычного invoke, если эти основные требования не выполнены, может быть выброшено WrongMethodTypeException.

Во всех случаях, то, что возвращает целевой объект, возвращается адаптером без изменений.

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

Поведение asType также специализировано для адаптеров переменной арности, чтобы поддерживать инвариант, что обычный, неточный invoke всегда эквивалентен вызову asType для изменения типа целевого объекта, за которым следует invokeExact. Следовательно, адаптер переменной арности отвечает на запрос asType, создавая коллектор фиксированной арности, если и только если адаптер и запрашиваемый тип различаются по арности или типу конечного аргумента. Полученный коллектор фиксированной арности дополнительно корректирует свой тип (если необходимо) до запрашиваемого типа путём попарного преобразования, как если бы это было сделано с помощью другого применения asType.

Когда обработчик метода получен путём выполнения инструкции ldc с CONSTANT_MethodHandle константой, и целевой метод помечен как метод переменной арности (с модификатором бита 0x0080), обработчик метода будет принимать несколько арностей, как если бы константа обработчика метода была создана с помощью вызова asVarargsCollector.

Для создания адаптера сбора, который собирает определённое количество аргументов и тип которого отражает это определённое количество, используйте asCollector.

Никакие преобразования обработчиков методов не создают новых обработчиков методов с переменной арностью, если это не указано в документации. Следовательно, помимо asVarargsCollector и withVarargs, все методы в MethodHandle и MethodHandles вернут обработчик метода с фиксированной арностью, за исключением случаев, когда они указаны для возврата своего исходного операнда (например, asType типа самого обработчика метода).

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

Вот пример обработчика метода переменной арности для создания списков:

MethodHandle deepToString = publicLookup()
  .findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));
MethodHandle ts1 = deepToString.asVarargsCollector(Object[].class);
assertEquals("[won]",   (String) ts1.invokeExact(    new Object[]{"won"}));
assertEquals("[won]",   (String) ts1.invoke(         new Object[]{"won"}));
assertEquals("[won]",   (String) ts1.invoke(                      "won" ));
assertEquals("[[won]]", (String) ts1.invoke((Object) new Object[]{"won"}));
// findStatic of Arrays.asList(...) produces a variable arity method handle:
MethodHandle asList = publicLookup()
  .findStatic(Arrays.class, "asList", methodType(List.class, Object[].class));
assertEquals(methodType(List.class, Object[].class), asList.type());
assert(asList.isVarargsCollector());
assertEquals("[]", asList.invoke().toString());
assertEquals("[1]", asList.invoke(1).toString());
assertEquals("[two, too]", asList.invoke("two", "too").toString());
String[] argv = { "three", "thee", "tee" };
assertEquals("[three, thee, tee]", asList.invoke(argv).toString());
assertEquals("[three, thee, tee]", asList.invoke((Object[])argv).toString());
List ls = (List) asList.invoke((Object)argv);
assertEquals(1, ls.size());
assertEquals("[three, thee, tee]", Arrays.toString((Object[])ls.get(0)));

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

• вызов asVarargsCollector
• вызов метода lookup, который разрешается в метод или конструктор Java с переменной арностью
• инструкция ldc с константой CONSTANT_MethodHandle, которая разрешается в метод или конструктор Java с переменной арностью

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

В противном случае, полученный обработчик метода с фиксированной арностью имеет тот же тип и поведение, что и текущий обработчик метода, за исключением того, что isVarargsCollector будет false. Обработчик метода с фиксированной арностью может (или не может) быть предыдущим аргументом для asVarargsCollector.

Вот пример обработчика метода переменной арности для создания списков:

MethodHandle asListVar = publicLookup()
  .findStatic(Arrays.class, "asList", methodType(List.class, Object[].class))
  .asVarargsCollector(Object[].class);
MethodHandle asListFix = asListVar.asFixedArity();
assertEquals("[1]", asListVar.invoke(1).toString());
Exception caught = null;
try { asListFix.invoke((Object)1); }
catch (Exception ex) { caught = ex; }
assert(caught instanceof ClassCastException);
assertEquals("[two, too]", asListVar.invoke("two", "too").toString());
try { asListFix.invoke("two", "too"); }
catch (Exception ex) { caught = ex; }
assert(caught instanceof WrongMethodTypeException);
Object[] argv = { "three", "thee", "tee" };
assertEquals("[three, thee, tee]", asListVar.invoke(argv).toString());
assertEquals("[three, thee, tee]", asListFix.invoke(argv).toString());
assertEquals(1, ((List) asListVar.invoke((Object)argv)).size());
assertEquals("[three, thee, tee]", asListFix.invoke((Object)argv).toString());

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

Ссылка x должна быть преобразуема в тип первого параметра цели.

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

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

"MethodHandle" + type().toString()

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