Класс 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 |
Выполняет заданное действие для каждого элемента потока StackFrame текущего потока, проходя от верхнего кадра стека, который является методом, вызвавшим этот метод forEach. |
Class |
getCallerClass() |
Возвращает объект Class вызывающего, который вызвал метод, вызвавший getCallerClass. |
static StackWalker |
getInstance() |
Возвращает экземпляр StackWalker. |
static StackWalker |
getInstance |
Возвращает экземпляр StackWalker с заданным параметром, определяющим информацию о кадрах стека, к которой он имеет доступ. |
static StackWalker |
getInstance |
Возвращает экземпляр StackWalker с заданным options, определяющим информацию о кадрах стека, к которой он имеет доступ. |
static StackWalker |
getInstance |
Возвращает экземпляр StackWalker с заданным options, определяющим информацию о кадрах стека, к которой он имеет доступ. |
<T> T |
walk |
Применяет заданную функцию к потоку StackFrame для текущего потока, проходя от верхнего кадра стека, который является методом, вызвавшим этот метод walk. |
Подробное описание методов
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