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

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

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

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

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

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

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

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

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

Выполнение происходит в несколько этапов:

• Определяется длина массива аргументов, как N. Для null ссылки, N=0.
• Определяется общий тип TN аргументов N как TN=MethodType.genericMethodType(N).
• Оригинальный обработчик метода MH0 приводится к требуемому типу, как MH1 = MH0.asType(TN).
• Массив разворачивается в N отдельных аргументов A0, ....
• Вызывается обработчик метода с изменённым типом над распакованными аргументами: MH1.invokeExact(A0, ...).
• Результат берётся как Object ссылка.

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

• преобразование ссылки
• распаковка
• расширение преобразований примитивных типов

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

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

MethodHandle invoker = MethodHandles.spreadInvoker(this.type(), 0);
Object result = invoker.invokeExact(this, arguments);

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

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

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

invokeWithArguments(arguments.toArray()

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

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

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

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

Создает обработчик метода для распределения массива, который принимает аргумент массива в конце и распространяет его элементы как позиционные аргументы. Новый обработчик метода адаптирует текущий обработчик метода как свой целевой объект. Тип адаптера будет таким же, как тип целевого объекта, за исключением того, что последние arrayLength параметры типа целевого объекта заменяются одним параметром массива типа arrayType.

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

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

Перед вызовом целевого объекта адаптер проверяет, что массив содержит ровно достаточно элементов для правильного количества аргументов для целевого обработчика метода. (Массив также может быть 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 ? null : 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()));

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

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

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

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

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

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

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

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));

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

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

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

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

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

Возвращает строковое представление обработчика метода, начиная со строки "MethodHandle" и заканчивая строковым представлением типа обработчика метода. Другими словами, этот метод возвращает строку, равную значению:

"MethodHandle" + type().toString()

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