Spec-Zone.ru › OpenJDK 17

Класс StackWalker

java.lang.Object
java.lang.StackWalker
public final class StackWalker extends Object
Объект для обхода стека вызовов.

Метод walk открывает последовательный поток объектов StackFrame для текущего потока и затем применяет заданную функцию для обхода потока StackFrame. Поток сообщает об элементах стека в порядке, от самой верхней рамки, представляющей точку выполнения, в которой был сгенерирован стек, до самой нижней. Поток StackFrame закрывается, когда метод walk возвращается. Если будет попытка повторного использования закрытого потока, будет брошено исключение IllegalStateException.

Параметры обхода стека объекта StackWalker определяют информацию об объектах StackFrame, которые должны быть возвращены. По умолчанию кадры стека API рефлексии и реализации классов скрыты (hidden), а для StackFrame доступны имя класса и имя метода, но не Class reference.

Объект StackWalker потокобезопасен. Несколько потоков могут использовать один объект StackWalker для обхода собственного стека. Проверка разрешений выполняется при создании объекта StackWalker в соответствии с запрошенными параметрами. Дальнейшая проверка разрешений во время обхода стека не выполняется.

Примечание API:
Примеры

1. Для поиска первого вызывающего метода, отфильтровав известный список классов реализации:


     StackWalker walker = StackWalker.getInstance(Option.RETAIN_CLASS_REFERENCE);
     Optional<Class<?>> callerClass = walker.walk(s ->
         s.map(StackFrame::getDeclaringClass)
          .filter(interestingClasses::contains)
          .findFirst());
 

2. Для получения снимка первых 10 кадров стека текущего потока:


     List<StackFrame> stack = StackWalker.getInstance().walk(s ->
         s.limit(10).collect(Collectors.toList()));
 
Если не указано иное, передача аргумента null в конструктор или метод в этом классе StackWalker приведет к выбрасыванию исключения NullPointerException.
С тех пор:
9

Краткое описание вложенных классов

Модификатор и тип Класс Описание
static enum  StackWalker.Option
Параметр обхода стека для настройки информации о кадре стека, полученной объектом StackWalker.
static interface  StackWalker.StackFrame
Объект StackFrame представляет вызов метода, возвращаемый методом StackWalker.

Краткое описание методов

Модификатор и тип Метод Описание
void forEach(Consumer<? super StackWalker.StackFrame> action)
Выполняет заданное действие для каждого элемента потока StackFrame текущего потока, начиная с верхней части стека, которая является методом, вызывающим этот метод forEach.
Class<?> getCallerClass()
Возвращает объект Class вызывающего метода, который вызвал метод, вызвавший getCallerClass.
static StackWalker getInstance()
Возвращает экземпляр StackWalker.
static StackWalker getInstance(StackWalker.Option option)
Возвращает экземпляр StackWalker с заданным параметром, определяющим информацию о кадре стека, к которой он имеет доступ.
static StackWalker getInstance(Set<StackWalker.Option> options)
Возвращает экземпляр StackWalker с заданным параметром options, определяющим информацию о кадре стека, к которой он имеет доступ.
static StackWalker getInstance(Set<StackWalker.Option> options, int estimateDepth)
Возвращает экземпляр StackWalker с заданным параметром options, определяющим информацию о кадре стека, к которой он имеет доступ.
<T> T walk(Function<? super Stream<StackWalker.StackFrame>,? extends T> function)
Применяет заданную функцию к потоку объектов StackFrame для текущего потока, начиная с верхней части стека, которая является методом, вызывающим этот метод walk.

Методы, унаследованные от класса java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Подробное описание методов

getInstance

public static StackWalker getInstance()
Возвращает экземпляр StackWalker.

Этот StackWalker сконфигурирован для пропуска всех скрытых кадров стека и не сохраняет ссылку на класс.

Возвращает:
экземпляр StackWalker , сконфигурированный для пропуска всех скрытых кадров стека и без сохранения ссылки на класс.

getInstance

public static StackWalker getInstance(StackWalker.Option option)
Возвращает экземпляр StackWalker с заданным параметром, определяющим информацию о кадрах стека, к которой он может получить доступ.

Если менеджер безопасности присутствует и заданный option включает Option.RETAIN_CLASS_REFERENCE, он вызывает его метод checkPermission для RuntimePermission("getStackWalkerWithClassReference").

Параметры:
option - stack walking option
Возвращает:
экземпляр StackWalker , сконфигурированный с заданным параметром
Исключения:
SecurityException - если менеджер безопасности существует и его метод checkPermission отклоняет доступ.

getInstance

public static StackWalker getInstance(Set<StackWalker.Option> options)
Возвращает экземпляр StackWalker с заданным набором options , определяющим информацию о кадрах стека, к которой он может получить доступ. Если заданный набор options пустой, этот StackWalker сконфигурирован для пропуска всех скрытых кадров стека и не сохраняет ссылку на класс.

Если менеджер безопасности присутствует и заданный набор options содержит Option.RETAIN_CLASS_REFERENCE, он вызывает его метод checkPermission для RuntimePermission("getStackWalkerWithClassReference").

Параметры:
options - stack walking option
Возвращает:
экземпляр StackWalker , сконфигурированный с заданными параметрами
Исключения:
SecurityException - если менеджер безопасности существует и его метод checkPermission отклоняет доступ.

getInstance

public static StackWalker getInstance(Set<StackWalker.Option> options, int estimateDepth)
Возвращает экземпляр StackWalker с заданным набором options , определяющим информацию о кадрах стека, к которой он может получить доступ. Если заданный набор options пустой, этот StackWalker сконфигурирован для пропуска всех скрытых кадров стека и не сохраняет ссылку на класс.

Если менеджер безопасности присутствует и заданный набор options содержит Option.RETAIN_CLASS_REFERENCE, он вызывает его метод checkPermission для RuntimePermission("getStackWalkerWithClassReference").

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

Параметры:
options - stack walking options
estimateDepth - Приблизительное число кадров стека, которые нужно пройти.
Возвращает:
экземпляр StackWalker , сконфигурированный с заданными параметрами
Исключения:
IllegalArgumentException - если estimateDepth <= 0
SecurityException - если менеджер безопасности существует и его метод checkPermission отклоняет доступ.

walk

public <T> T walk(Function<? super Stream<StackWalker.StackFrame>,? extends T> function)
Применяет заданную функцию к потоку StackFrame для текущего потока, проходя от верхнего кадра стека, который является методом, вызывающим этот метод walk.

Поток Stream<StackFrame> будет закрыт после возвращения из этого метода. При повторном использовании закрытого объекта Stream<StackFrame>, будет выброшено IllegalStateException.

Примечание API:
Например, чтобы найти первые 10 вызывающих кадров, сначала пропуская кадры, у которых объявляющий класс находится в пакете com.foo:

 List<StackFrame> frames = StackWalker.getInstance().walk(s ->
     s.dropWhile(f -> f.getClassName().startsWith("com.foo."))
      .limit(10)
      .collect(Collectors.toList()));
 

Этот метод принимает Function , принимающий Stream<StackFrame>, а не возвращает Stream<StackFrame> и не позволяет вызывающему методу напрямую манипулировать потоком. Виртуальная машина Java может свободно переупорядочить стек управления потока, например, с помощью деоптимизации. Принимая параметр Function, этот метод обеспечивает доступ к кадрам стека через стабильный вид стека управления потока.

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

Примечание реализации:
Реализация стабилизирует стек, привязывая к нему кадр, специфичный для обработки стека, и гарантирует, что обработка стека выполняется над привязанным кадром. При закрытии или повторном использовании объекта потока будет выброшено IllegalStateException.
Параметры типа:
T - тип результата применения функции к потоку кадра стека.
Параметры:
function - функция, которая принимает поток кадров стека и возвращает результат.
Возвращает:
результат применения функции к потоку кадров стека.

forEach

public void forEach(Consumer<? super StackWalker.StackFrame> action)
Выполняет заданное действие для каждого элемента потока StackFrame текущего потока, начиная с верхнего кадра стека, который является методом, вызывающим этот метод forEach.

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

walk(s -> { s.forEach(action); return null; });
Параметры:
action - действие, которое должно быть выполнено для каждого StackFrame стека текущего потока

getCallerClass

public Class<?> getCallerClass()
Получает объект Class вызывающего метода, который вызвал метод, вызвавший getCallerClass.

Этот метод фильтрует кадры рефлексии, MethodHandle и скрытые кадры независимо от SHOW_REFLECT_FRAMES и SHOW_HIDDEN_FRAMES опций, с которыми этот StackWalker сконфигурирован.

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

Этот метод вызывает UnsupportedOperationException , если этот StackWalker не сконфигурирован с опцией RETAIN_CLASS_REFERENCE.

Примечание API:
Например, Util::getResourceBundle загружает ресурсный пакет от имени вызывающего метода. Он вызывает getCallerClass для идентификации класса, метод которого вызвал Util::getResourceBundle. Затем он получает загрузчик классов этого класса и использует загрузчик для загрузки ресурсного пакета. В этом примере вызывающим классом является MyTool.

 class Util {
     private final StackWalker walker = StackWalker.getInstance(Option.RETAIN_CLASS_REFERENCE);
     public ResourceBundle getResourceBundle(String bundleName) {
         Class<?> caller = walker.getCallerClass();
         return ResourceBundle.getBundle(bundleName, Locale.getDefault(), caller.getClassLoader());
     }
 }

 class MyTool {
     private final Util util = new Util();
     private void init() {
         ResourceBundle rb = util.getResourceBundle("mybundle");
     }
 }
 
Эквивалентный способ поиска вызывающего класса с помощью метода walk выглядит следующим образом (фильтруя кадры рефлексии, MethodHandle и скрытые кадры, не показанные ниже):

     Optional<Class<?>> caller = walker.walk(s ->
         s.map(StackFrame::getDeclaringClass)
          .skip(2)
          .findFirst());
 
Когда метод getCallerClass вызывается из метода, являющегося самым нижним кадром стека, например, метода static public void main, запущенного запускающим модулем java, или метода, вызванного из потока, подключенного к JNI, выбросится IllegalCallerException.
Возвращает:
объект Class вызывающего метода, вызвавшего этот метод.
Исключения:
UnsupportedOperationException - если этот StackWalker не сконфигурирован с Option.RETAIN_CLASS_REFERENCE.
IllegalCallerException - если нет кадра вызывающего метода, т.е. когда этот метод getCallerClass вызывается из метода, который является последним кадром стека.

© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/StackWalker.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API