模块  java.base
软件包  java.lang

Class StackWalker

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

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

    StackWalker的StackWalker确定要返回的StackFrame对象的信息。 默认情况下，反射API和实现类的堆栈帧是hidden和StackFrame可以使用类名和方法名，但不能使用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 frames ， MethodHandle ，和hidden frames不管SHOW_REFLECT_FRAMES个SHOW_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方法时。