模块  java.base
软件包  java.lang

Class StackWalker


  • public final class StackWalker
    extends Object
    堆栈助行器。

    walk方法为当前线程打开顺序流StackFrame ,然后应用给定函数来遍历StackFrame流。 流按顺序报告堆栈帧元素,从表示生成堆栈的执行点的最顶部帧到最底部的帧。 walk方法返回时, StackFrame流将关闭。 如果尝试重新使用已关闭的流,则将抛出IllegalStateException

    StackWalkerStackWalker确定要返回的StackFrame对象的信息。 默认情况下,反射API和实现类的堆栈帧是hiddenStackFrame可以使用类名和方法名,但不能使用Class reference

    StackWalker是线程安全的。 多个线程可以共享一个StackWalker对象来遍历自己的堆栈。 根据请求的选项,在创建StackWalker时执行权限检查。 在堆栈步行时间没有进一步的权限检查。

    API Note:
    例子

    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
    • 方法详细信息

      • getInstance

        public static StackWalker getInstance​(Set<StackWalker.Option> options,
                                              int estimateDepth)
        返回StackWalker实例,其中给定的options指定了它可以访问的堆栈帧信息。 如果给定的options为空,则此StackWalker配置为跳过所有hidden frames,并且不保留class reference

        如果存在安全管理器且给定的options包含Option.RETAIN_CLASS_REFERENCE ,则会将其checkPermission方法调用为RuntimePermission("getStackWalkerWithClassReference")

        estimateDepth指定StackWalker将遍历的堆栈帧的估计数, StackWalker StackWalker缓冲区大小的提示。

        参数
        options - stack walking options
        estimateDepth - 估计要遍历的堆栈帧数。
        结果
        a 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 Note:
        例如,要查找前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参数,此方法允许通过线程控制堆栈的稳定视图访问堆栈帧。

        并行执行被有效禁用,流管道执行只会在当前线程上发生。

        Implementation Note:
        该实现通过锚定特定于堆栈行走的帧来稳定堆栈,并确保在锚定帧上方执行堆栈行走。 当流对象关闭或被重用时,将抛出IllegalStateException
        参数类型
        T - 将函数应用于stack frame流的结果的类型。
        参数
        function - 一个获取stack frames流并返回结果的函数。
        结果
        将函数应用于stack frame的流的结果
      • forEach

        public void forEach​(Consumer<? super StackWalker.StackFrame> action)
        对当前线程的StackFrame流的每个元素执行给定操作,从堆栈的顶部帧遍历,这是调用此forEach方法的方法。

        这种方法相当于调用

        walk(s -> { s.forEach(action); return null; });
        参数
        action - 要对当前线程的堆栈的每个 StackFrame执行的操作
      • getCallerClass

        public <?> getCallerClass()
        获取调用者调用getCallerClass的方法的对象。

        该方法过滤reflection framesMethodHandle ,和hidden frames不管SHOW_REFLECT_FRAMESSHOW_HIDDEN_FRAMES这个选项StackWalker已配置。

        当存在调用者帧时,应该调用此方法。 如果从堆栈的最底部框架调用它,则将抛出IllegalCallerException

        如果此StackWalker未配置RETAIN_CLASS_REFERENCE选项,则此方法将引发UnsupportedOperationException

        API Note:
        例如, 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被抛出。
        结果
        调用者调用此方法的调用者的对象。
        异常
        UnsupportedOperationException - 如果 StackWalker未配置 Option.RETAIN_CLASS_REFERENCE
        IllegalCallerException - 如果没有调用者帧,即从堆栈中最后一帧的方法调用此 getCallerClass方法时。