Класс MethodHandles.Lookup

Объект с этим режимом поиска выполняет проверку доступа между модулями относительно класса поиска lookup class и предыдущего класса поиска previous lookup class, если он присутствует.

Если этот режим поиска установлен, предыдущий класс поиска previous lookup class всегда null.

Если этот режим поиска установлен, предыдущий класс поиска previous lookup class всегда null.

Если этот режим поиска установлен, объект Lookup должен быть создан исходным классом поиска, вызвав метод MethodHandles.lookup() или методом инициализации, вызванным виртуальной машиной. Объект Lookup с этим режимом поиска имеет полный привилегированный доступ.

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

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

Объект Lookup, созданный методами-фабриками, такими как метод lookup() и publicLookup(), имеет null предыдущий класс поиска. Объект Lookup имеет непустой предыдущий класс поиска, когда этот поиск был перенесен из старого класса поиска в одном модуле в новый класс поиска в другом модуле.

Недавно созданный объект поиска в классе вызывающего класса имеет все возможные биты установлены, кроме UNCONDITIONAL. Объект поиска нового класса поиска созданный из предыдущего объекта поиска может иметь некоторые биты режима установлены в ноль. Биты режима также могут быть непосредственно очищены. После очистки биты режима не могут быть восстановлены из пониженного объекта поиска. Цель этого — ограничить доступ через новый объект поиска, чтобы он мог получить доступ только к именам, которые можно достичь исходным объектом поиска, а также новым классом поиска.

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

• Если новый класс поиска отличается от старого класса поиска, т.е. доступ ORIGINAL теряется.
• Если новый класс поиска находится в другом модуле, чем старый, т.е. доступ MODULE теряется.
• Если новый класс поиска находится в другом пакете, чем старый, защищённые и по умолчанию (пакета) члены не будут доступны, т.е. доступ PROTECTED и PACKAGE теряются.
• Если новый класс поиска не находится в том же члене пакета, что и старый, частные члены не будут доступны, и защищённые члены не будут доступны благодаря наследованию, т.е. доступ PRIVATE теряется. (Защищённые члены могут оставаться доступными из-за совместного использования пакетов.)
• Если новый класс поиска не доступен для этого поиска, то ни один член, даже публичный, не будет доступен, т.е. все режимы доступа теряются.
• Если новый класс поиска, старый класс поиска и предыдущий класс поиска находятся в разных модулях, т.е. перемещение в третий модуль, все режимы доступа теряются.

Новый предыдущий класс поиска выбирается следующим образом:

• Если у нового объекта поиска установлен бит UNCONDITIONAL, новый предыдущий класс поиска — null.
• Если новый класс поиска находится в том же модуле, что и старый класс поиска, новый предыдущий класс поиска — старый предыдущий класс поиска.
• Если новый класс поиска находится в другом модуле, чем старый класс поиска, новый предыдущий класс поиска — старый класс поиска.

Возможности результирующего поиска по загрузке классов (используемые во время вызовов findClass(java.lang.String)) определяются загрузчиком класса поиска, который может измениться в результате этой операции.

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

Если этот поиск не является публичным, то следующее применимо независимо от его режимов поиска. PROTECTED и ORIGINAL всегда удаляются, поэтому результирующий режим поиска никогда не будет иметь этих прав доступа. При удалении PACKAGE результирующий поиск не будет иметь PACKAGE или PRIVATE доступа. При удалении MODULE результирующий поиск не будет иметь MODULE, PACKAGE, или PRIVATE доступа. При удалении PUBLIC результирующий поиск не имеет доступа.

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

Параметр bytes — это байты класса допустимого файла класса (как определено в Спецификации виртуальной машины Java) с именем класса в том же пакете, что и класс поиска.

Этот метод не выполняет инициализатор класса. Инициализатор класса может быть выполнен в более позднее время, как подробно описано в разделе 12.4 Спецификации языка Java.

Если присутствует менеджер безопасности и у этого поиска нет полного привилегированного доступа, сначала вызывается его метод checkPermission для проверки RuntimePermission("defineClass").

Этот метод эквивалентен вызову defineHiddenClass(bytes, initialize, options) как если бы скрытый класс был введён с приватным статическим конечным неопределённым полем, инициализированным заданными classData в первой инструкции инициализатора класса. Созданный класс связывается виртуальной машиной Java.

Методы MethodHandles::classData и MethodHandles::classDataAt могут быть использованы для получения classData.

• Если доступ запрещен, суффикс — «/noaccess».
• Если разрешен только безусловный доступ, суффикс — «/publicLookup».
• Если разрешен только публичный доступ к типам в экспортированных пакетах, суффикс — «/public».
• Если разрешен только публичный и модульный доступ, суффикс — «/module».
• Если разрешен публичный и пакетный доступ, суффикс — «/package».
• Если разрешены публичный, пакетный и частный доступ, суффикс — «/private».

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

Возвращаемый обработчик метода будет иметь переменную арность, если и только если бит переменной арности метода (0x0080) установлен.

При вызове возвращаемого обработчика метода класс метода будет инициализирован, если он ещё не был инициализирован.

Пример:

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle MH_asList = publicLookup().findStatic(Arrays.class,
  "asList", methodType(List.class, Object[].class));
assertEquals("[x, y]", MH_asList.invoke("x", "y").toString());
 

При вызове обработчик будет рассматривать первый аргумент как получатель и, для не-частных методов, производить диспетчеризацию на тип получателя, чтобы определить, какую реализацию метода использовать. Для частных методов вызывается метод с указанным именем в refc, на получателе. (Диспетчеризация идентична той, что выполняется инструкцией invokevirtual или invokeinterface)

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

Возвращаемый обработчик метода будет иметь переменную арность, если и только если бит переменной арности метода (0x0080) установлен.

Из-за общей эквивалентности инструкций invokevirtual и обработчиков методов, произведённых findVirtual, если класс MethodHandle, а строка имени соответствует invokeExact или invoke, результирующий обработчик метода эквивалентен обработчику, произведённому MethodHandles.exactInvoker или MethodHandles.invoker с тем же аргументом type.

Если класс VarHandle и строка имени соответствует имени метода с сигнатурно-полиморфным режимом доступа, результирующий обработчик метода эквивалентен обработчику, произведённому MethodHandles.varHandleInvoker(java.lang.invoke.VarHandle.AccessMode, java.lang.invoke.MethodType) с режимом доступа, соответствующим строке имени, и с теми же аргументами type.

Пример:

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle MH_concat = publicLookup().findVirtual(String.class,
  "concat", methodType(String.class, String.class));
MethodHandle MH_hashCode = publicLookup().findVirtual(Object.class,
  "hashCode", methodType(int.class));
MethodHandle MH_hashCode_String = publicLookup().findVirtual(String.class,
  "hashCode", methodType(int.class));
assertEquals("xy", (String) MH_concat.invokeExact("x", "y"));
assertEquals("xy".hashCode(), (int) MH_hashCode.invokeExact((Object)"xy"));
assertEquals("xy".hashCode(), (int) MH_hashCode_String.invokeExact("xy"));
// interface method:
MethodHandle MH_subSequence = publicLookup().findVirtual(CharSequence.class,
  "subSequence", methodType(CharSequence.class, int.class, int.class));
assertEquals("def", MH_subSequence.invoke("abcdefghi", 3, 6).toString());
// constructor "internal method" must be accessed differently:
MethodType MT_newString = methodType(void.class); //()V for new String()
try { assertEquals("impossible", lookup()
        .findVirtual(String.class, "<init>", MT_newString));
 } catch (NoSuchMethodException ex) { } // OK
MethodHandle MH_newString = publicLookup()
  .findConstructor(String.class, MT_newString);
assertEquals("", (String) MH_newString.invokeExact());
 

Требуемый тип должен иметь тип возврата void. (Это согласуется с обработкой JVM описателей типа конструктора.)

Возвращаемый обработчик метода будет иметь переменную арность, если и только если бит переменной арности конструктора (0x0080) установлен.

При вызове возвращаемого обработчика метода класс конструктора будет инициализирован, если он ещё не был инициализирован.

Пример:

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle MH_newArrayList = publicLookup().findConstructor(
  ArrayList.class, methodType(void.class, Collection.class));
Collection orig = Arrays.asList("x", "y");
Collection copy = (ArrayList) MH_newArrayList.invokeExact(orig);
assert(orig != copy);
assertEquals(orig, copy);
// a variable-arity constructor:
MethodHandle MH_newProcessBuilder = publicLookup().findConstructor(
  ProcessBuilder.class, methodType(void.class, String[].class));
ProcessBuilder pb = (ProcessBuilder)
  MH_newProcessBuilder.invoke("x", "y", "z");
assertEquals("[x, y, z]", pb.command().toString());
 

Контекст поиска определяется здесь классом поиска, его загрузчиком классов и режимами поиска.

Если targetClass находится в том же модуле, что и класс поиска, то класс поиска LC в модуле M1, а предыдущий класс поиска находится в модуле M0 или null, если он отсутствует, то targetClass доступен только в том случае, если выполняется одно из следующих условий:

• Если у этого поиска есть PRIVATE доступ, то targetClass является LC или другим классом в том же вложенном блоке LC.
• Если у этого поиска есть PACKAGE доступ, то targetClass находится в той же рабочей папке, что и LC.
• Если у этого поиска есть MODULE доступ, то targetClass является общедоступным типом в M1.
• Если у этого поиска есть PUBLIC доступ, то targetClass является общедоступным типом в пакете, экспортированном M1 по крайней мере в M0, если предыдущий класс поиска присутствует; в противном случае targetClass является общедоступным типом в пакете, экспортированном M1 безусловно.

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

В противном случае, targetClass находится в другом модуле, чем lookupClass, и если у этого поиска нет PUBLIC доступа, то lookupClass недоступен.

В противном случае, если у этого поиска нет предыдущего класса поиска, M1 — это модуль, содержащий lookupClass, а M2 — это модуль, содержащий targetClass, то targetClass доступен только в том случае, если

• M1 считывает M2, и
• targetClass является общедоступным и находится в пакете, экспортированном M2 по крайней мере в M1.

В противном случае, если у этого поиска есть предыдущий класс поиска, M1 и M2 такие же, как и раньше, а M0 — это модуль, содержащий предыдущий класс поиска, то targetClass доступен только в том случае, если одно из следующих условий истинно:

• targetClass находится в M0 и M1 считывает M0 и тип находится в пакете, экспортированном в по крайней мере M1.
• targetClass находится в M1 и M0 считывает M1 и тип находится в пакете, экспортированном по крайней мере в M0.
• targetClass находится в третьем модуле M2 и M0 и M1 считывают M2 и тип находится в пакете, экспортированном в по крайней мере M0 и M2.

В противном случае, targetClass недоступен.

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

Возвращаемый дескриптор метода будет иметь переменную арность только в том случае, если установлен модификатор переменной арности метода (0x0080)

(Примечание: внутренние методы JVM с именем "<init>" не видны для этой API, даже если инструкция invokespecial может ссылаться на них в особых случаях. Используйте findConstructor, чтобы безопасно получить доступ к методам инициализации экземпляров.)

Пример:

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
static class Listie extends ArrayList {
  public String toString() { return "[wee Listie]"; }
  static Lookup lookup() { return MethodHandles.lookup(); }
}
...
// no access to constructor via invokeSpecial:
MethodHandle MH_newListie = Listie.lookup()
  .findConstructor(Listie.class, methodType(void.class));
Listie l = (Listie) MH_newListie.invokeExact();
try { assertEquals("impossible", Listie.lookup().findSpecial(
        Listie.class, "<init>", methodType(void.class), Listie.class));
 } catch (NoSuchMethodException ex) { } // OK
// access to super and self methods via invokeSpecial:
MethodHandle MH_super = Listie.lookup().findSpecial(
  ArrayList.class, "toString" , methodType(String.class), Listie.class);
MethodHandle MH_this = Listie.lookup().findSpecial(
  Listie.class, "toString" , methodType(String.class), Listie.class);
MethodHandle MH_duper = Listie.lookup().findSpecial(
  Object.class, "toString" , methodType(String.class), Listie.class);
assertEquals("[]", (String) MH_super.invokeExact(l));
assertEquals(""+l, (String) MH_this.invokeExact(l));
assertEquals("[]", (String) MH_duper.invokeExact(l)); // ArrayList method
try { assertEquals("inaccessible", Listie.lookup().findSpecial(
        String.class, "toString", methodType(String.class), Listie.class));
 } catch (IllegalAccessException ex) { } // OK
Listie subl = new Listie() { public String toString() { return "[subclass]"; } };
assertEquals(""+l, (String) MH_this.invokeExact(subl)); // Listie method
 

Проверка доступа выполняется немедленно от имени класса поиска.

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

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

Если поле объявлено volatile, возвращаемое VarHandle переопределит доступ к полю (в сущности, проигнорирует объявление volatile) в соответствии с его заданными режимами доступа.

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

При вызове возвращаемого обработчика методов класс поля будет инициализирован, если он ещё не был инициализирован.

При вызове возвращаемого обработчика методов класс поля будет инициализирован, если он ещё не был инициализирован.

Проверка доступа выполняется немедленно от имени класса поиска.

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

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

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

Если поле объявлено volatile, возвращаемое VarHandle переопределит доступ к полю (в сущности, проигнорирует объявление volatile) в соответствии с его заданными режимами доступа.

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

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

Это почти эквивалентно следующему коду, с некоторыми различиями, отмеченными ниже:

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle mh0 = lookup().findVirtual(defc, name, type);
MethodHandle mh1 = mh0.bindTo(receiver);
mh1 = mh1.withVarargs(mh0.isVarargsCollector());
return mh1;
 

Возвращаемый обработчик метода будет иметь переменную арность, если и только если бит модификатора переменной арности метода (0x0080) установлен.

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

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

Возвращаемый обработчик метода будет иметь переменную арность, если и только если бит модификатора переменной арности метода (0x0080) установлен.

Если флаг accessible конструктора не установлен, проверка доступа выполняется немедленно от имени класса поиска.

Возвращаемый обработчик метода будет иметь переменную арность, если и только если бит модификатора переменной арности конструктора (0x0080) установлен.

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

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

Если поле является final, доступ для записи не будет разрешён, и проверка доступа не пройдёт, за исключением некоторых узких обстоятельств, документированных для Field.set. Обработчик метода возвращается только если соответствующий вызов метода Field объекта set мог вернуть нормальное значение. В частности, поля, которые являются одновременно static и final , никогда не могут быть установлены.

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

Проверка доступа выполняется немедленно от имени класса поиска, независимо от значения флага accessible поля.

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

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

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

Если поле объявлено volatile, возвращаемый VarHandle переопределит доступ к полю (эффективно проигнорирует объявление volatile) в соответствии с его указанными режимами доступа.

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