StackWalker class in Java

java.lang.StackWalker

A stack walker.

The walk method opens a sequential stream of StackFrames for the current thread and then applies the given function to walk the StackFrame stream. The stream reports stack frame elements in order, from the topmost frame that represents the execution point at which the stack was generated to the bottom-most frame.

The StackFrame stream is closed when the walk method returns. If an attempt is made to reuse the closed stream, IllegalStateException will be thrown.

Declaration

public final class StackWalker {

    public interface StackFrame {

        public String getClassName();

        public String getMethodName();

        public Class<?> getDeclaringClass();

        public default MethodType getMethodType() {
            throw new UnsupportedOperationException();
        }

        public default String getDescriptor() {
            throw new UnsupportedOperationException();
        }

        public int getByteCodeIndex();

        public String getFileName();

        public int getLineNumber();

        public boolean isNativeMethod();

        public StackTraceElement toStackTraceElement();
    }

    public enum Option {

        RETAIN_CLASS_REFERENCE,

        SHOW_REFLECT_FRAMES,

        SHOW_HIDDEN_FRAMES;
    }

    enum ExtendedOption {
        /**
         * Obtain monitors, locals and operands.
         */
        LOCALS_AND_OPERANDS
    };

    static final EnumSet<Option> DEFAULT_EMPTY_OPTION = EnumSet.noneOf(Option.class);

    private final static StackWalker DEFAULT_WALKER = new StackWalker(DEFAULT_EMPTY_OPTION);

    private final Set<Option> options;
    private final ExtendedOption extendedOption;
    private final int estimateDepth;
    final boolean retainClassRef; // cached for performance

    public static StackWalker getInstance() {
        // no permission check needed
        return DEFAULT_WALKER;
    }

    public static StackWalker getInstance(Option option) {
        return getInstance(EnumSet.of(Objects.requireNonNull(option)));
    }

    public static StackWalker getInstance(Set<Option> options) {
        if (options.isEmpty()) {
            return DEFAULT_WALKER;
        }

        EnumSet<Option> optionSet = toEnumSet(options);
        checkPermission(optionSet);
        return new StackWalker(optionSet);
    }

    public static StackWalker getInstance(Set<Option> options, int estimateDepth) {
        if (estimateDepth <= 0) {
            throw new IllegalArgumentException("estimateDepth must be > 0");
        }
        EnumSet<Option> optionSet = toEnumSet(options);
        checkPermission(optionSet);
        return new StackWalker(optionSet, estimateDepth);
    }

    private StackWalker(EnumSet<Option> options) {
        this(options, 0, null);
    }

    private StackWalker(EnumSet<Option> options, int estimateDepth) {
        this(options, estimateDepth, null);
    }

    private StackWalker(EnumSet<Option> options, int estimateDepth, ExtendedOption extendedOption) {
        this.options = options;
        this.estimateDepth = estimateDepth;
        this.extendedOption = extendedOption;
        this.retainClassRef = hasOption(Option.RETAIN_CLASS_REFERENCE);
    }

    private static void checkPermission(Set<Option> options) {
        Objects.requireNonNull(options);
        SecurityManager sm = System.getSecurityManager();
        if (sm != null) {
            if (options.contains(Option.RETAIN_CLASS_REFERENCE)) {
                sm.checkPermission(new RuntimePermission("getStackWalkerWithClassReference"));
            }
        }
    }

    private static EnumSet<Option> toEnumSet(Set<Option> options) {
        Objects.requireNonNull(options);
        if (options.isEmpty()) {
            return DEFAULT_EMPTY_OPTION;
        } else {
            return EnumSet.copyOf(options);
        }
    }

    @CallerSensitive
    public <T> T walk(Function<? super Stream<StackFrame>, ? extends T> function) {

        Objects.requireNonNull(function);
        return StackStreamFactory.makeStackTraverser(this, function).walk();
    }

    @CallerSensitive
    public void forEach(Consumer<? super StackFrame> action) {
        Objects.requireNonNull(action);
        StackStreamFactory.makeStackTraverser(this, s -> {
            s.forEach(action);
            return null;
        }).walk();
    }

    @CallerSensitive
    public Class<?> getCallerClass() {
        if (!retainClassRef) {
            throw new UnsupportedOperationException(
                    "This stack walker " + "does not have RETAIN_CLASS_REFERENCE access");
        }

        return StackStreamFactory.makeCallerFinder(this).findCaller();
    }

    static StackWalker newInstance(Set<Option> options, ExtendedOption extendedOption) {
        EnumSet<Option> optionSet = toEnumSet(options);
        checkPermission(optionSet);
        return new StackWalker(optionSet, 0, extendedOption);
    }

    int estimateDepth() {
        return estimateDepth;
    }

    boolean hasOption(Option option) {
        return options.contains(option);
    }

    boolean hasLocalsOperandsOption() {
        return extendedOption == ExtendedOption.LOCALS_AND_OPERANDS;
    }
}

Some methods of StackWalker class

forEach(Consumer): This method performs the given action on each element of the StackFrame stream of the current thread, traversing from the top frame of the stack, which is the method calling this forEach method.

getCallerClass(): This method gets the Class object of the caller who invoked the method that invoked getCallerClass.

StackWalker.getInstance(): This method returns a StackWalker instance.

StackWalker.getInstance(Set): This method returns a StackWalker instance with the given options specifying the stack frame information it can access.

StackWalker.getInstance(Option): This method returns a StackWalker instance with the given option specifying the stack frame information it can access.

StackWalker.getInstance(Set, int): This method returns a StackWalker instance with the given options specifying the stack frame information it can access.

walk(Function): This method applies the given function to the stream of StackFramesfor the current thread, traversing from the top frame of the stack, which is the method calling this walk method.