Class StackWalker

Methods

getInstance

public static StackWalker getInstance()

Returns:

a StackWalker configured to skip all hidden frames and no class reference is retained.

getInstance

public static StackWalker getInstance(StackWalker.Option option)

Parameters:

option - stack walking option

Returns:

a StackWalker configured with the given option

Throws:

SecurityException - if a security manager exists and its checkPermission method denies access.

getInstance

public static StackWalker getInstance(Set<StackWalker.Option> options)

Parameters:

options - stack walking option

Returns:

a StackWalker configured with the given options

Throws:

SecurityException - if a security manager exists and its checkPermission method denies access.

getInstance

public static StackWalker getInstance(Set<StackWalker.Option> options,
                                      int estimateDepth)

Parameters:

options - stack walking options

estimateDepth - Estimate number of stack frames to be traversed.

Returns:

a StackWalker configured with the given options

Throws:

IllegalArgumentException - if estimateDepth <= 0

SecurityException - if a security manager exists and its checkPermission method denies access.

walk

public <T> T walk(Function<? super Stream<StackWalker.StackFrame>,​? extends T> function)

API Note:

For example, to find the first 10 calling frames, first skipping those frames whose declaring class is in package com.foo:

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

This method takes a Function accepting a Stream<StackFrame>, rather than returning a Stream<StackFrame> and allowing the caller to directly manipulate the stream. The Java virtual machine is free to reorganize a thread's control stack, for example, via deoptimization. By taking a Function parameter, this method allows access to stack frames through a stable view of a thread's control stack.

Parallel execution is effectively disabled and stream pipeline execution will only occur on the current thread.

Implementation Note:

The implementation stabilizes the stack by anchoring a frame specific to the stack walking and ensures that the stack walking is performed above the anchored frame. When the stream object is closed or being reused, IllegalStateException will be thrown.

Type Parameters:

T - The type of the result of applying the function to the stream of stack frame.

Parameters:

function - a function that takes a stream of stack frames and returns a result.

Returns:

the result of applying the function to the stream of stack frame.

forEach

public void forEach(Consumer<? super StackWalker.StackFrame> action)

walk(s -> { s.forEach(action); return null; });

Parameters:

action - an action to be performed on each StackFrame of the stack of the current thread

getCallerClass

public Class<?> getCallerClass()

API Note:

For example, Util::getResourceBundle loads a resource bundle on behalf of the caller. It invokes getCallerClass to identify the class whose method called Util::getResourceBundle. Then, it obtains the class loader of that class, and uses the class loader to load the resource bundle. The caller class in this example is 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");
     }
 }

An equivalent way to find the caller class using the walk method is as follows (filtering the reflection frames, MethodHandle and hidden frames not shown below):

Optional<Class<?>> caller = walker.walk(s ->
         s.map(StackFrame::getDeclaringClass)
          .skip(2)
          .findFirst());

When the getCallerClass method is called from a method that is the bottom most frame on the stack, for example, static public void main method launched by the java launcher, or a method invoked from a JNI attached thread, IllegalCallerException is thrown.

Returns:

Class object of the caller's caller invoking this method.

Throws:

UnsupportedOperationException - if this StackWalker is not configured with Option.RETAIN_CLASS_REFERENCE.

IllegalCallerException - if there is no caller frame, i.e. when this getCallerClass method is called from a method which is the last frame on the stack.