Spec-Zone.ru › OpenJDK 21

Класс 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 , настроенный на пропуск всех скрытых кадров стека и не сохраняющий ссылку на класс.

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.

Поток 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, 2023, 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/21/docs/api/java.base/java/lang/StackWalker.html

Spec-Zone.ru

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