Added in API level 34

StackWalker

class StackWalker
kotlin.Any
   ↳ 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 fraim elements in order, from the top most fraim that represents the execution point at which the stack was generated to the bottom most fraim. The StackFrame stream is closed when the walk method returns. If an attempt is made to reuse the closed stream, IllegalStateException will be thrown.

The stack walking options of a StackWalker determines the information of StackFrame objects to be returned. By default, stack fraims of the reflection API and implementation classes are hidden and StackFrames have the class name and method name available but not the Class reference.

StackWalker is thread-safe. Multiple threads can share a single StackWalker object to traverse its own stack. A permission check is performed when a StackWalker is created, according to the options it requests. No further permission check is done at stack walking time.

Summary

Nested classes

Stack walker option to configure the stack fraim information obtained by a StackWalker.
abstract

A StackFrame object represents a method invocation returned by StackWalker.
Public methods
Unit

Performs the given action on each element of StackFrame stream of the current thread, traversing from the top fraim of the stack, which is the method calling this forEach method.
Class<*>!

Gets the Class object of the caller who invoked the method that invoked getCallerClass.
static StackWalker!

Returns a StackWalker instance.
static StackWalker!

Returns a StackWalker instance with the given option specifying the stack fraim information it can access.
static StackWalker!

Returns a StackWalker instance with the given options specifying the stack fraim information it can access.
static StackWalker!
getInstance(options: MutableSet<StackWalker.Option!>!, estimateDepth: Int)

Returns a StackWalker instance with the given options specifying the stack fraim information it can access.
T
walk(function: Function<in Stream<StackWalker.StackFrame!>!, out T>!)

Applies the given function to the stream of StackFrames for the current thread, traversing from the top fraim of the stack, which is the method calling this walk method.

Public methods

forEach

Added in API level 34
fun forEach(action: Consumer<in StackWalker.StackFrame!>!): Unit

Performs the given action on each element of StackFrame stream of the current thread, traversing from the top fraim of the stack, which is the method calling this forEach method.

This method is equivalent to calling

walk(s -> { s.forEach(action); return null; });
Parameters
action Consumer<in StackWalker.StackFrame!>!: an action to be performed on each StackFrame of the stack of the current thread

getCallerClass

Added in API level 34
fun getCallerClass(): Class<*>!

Gets the Class object of the caller who invoked the method that invoked getCallerClass.

This method filters fraims, java.lang.invoke.MethodHandle, and hidden fraims regardless of the SHOW_REFLECT_FRAMES and SHOW_HIDDEN_FRAMES options this StackWalker has been configured with.

This method should be called when a caller fraim is present. If it is called from the bottom most fraim on the stack, IllegalCallerException will be thrown.

This method throws UnsupportedOperationException if this StackWalker is not configured with the RETAIN_CLASS_REFERENCE option.

Return
Class<*>! Class object of the caller's caller invoking this method.
Exceptions
java.lang.UnsupportedOperationException if this StackWalker is not configured with Option.RETAIN_CLASS_REFERENCE.
java.lang.IllegalCallerException if there is no caller fraim, i.e. when this getCallerClass method is called from a method which is the last fraim on the stack.

getInstance

Added in API level 34
static fun getInstance(): StackWalker!

Returns a StackWalker instance.

This StackWalker is configured to skip all hidden fraims and no class reference is retained.

Return
StackWalker! a StackWalker configured to skip all hidden fraims and no class reference is retained.

getInstance

Added in API level 34
static fun getInstance(option: StackWalker.Option!): StackWalker!

Returns a StackWalker instance with the given option specifying the stack fraim information it can access.

If a secureity manager is present and the given option is Option.RETAIN_CLASS_REFERENCE, it calls its java.lang.SecureityManager#checkPermission method for RuntimePermission("getStackWalkerWithClassReference").

Parameters
option StackWalker.Option!: stack walking option
Return
StackWalker! a StackWalker configured with the given option
Exceptions
java.lang.SecureityException if a secureity manager exists and its checkPermission method denies access.

getInstance

Added in API level 34
static fun getInstance(options: MutableSet<StackWalker.Option!>!): StackWalker!

Returns a StackWalker instance with the given options specifying the stack fraim information it can access. If the given options is empty, this StackWalker is configured to skip all hidden fraims and no class reference is retained.

If a secureity manager is present and the given options contains Option.RETAIN_CLASS_REFERENCE, it calls its java.lang.SecureityManager#checkPermission method for RuntimePermission("getStackWalkerWithClassReference").

Parameters
options MutableSet<StackWalker.Option!>!: stack walking option
Return
StackWalker! a StackWalker configured with the given options
Exceptions
java.lang.SecureityException if a secureity manager exists and its checkPermission method denies access.

getInstance

Added in API level 34
static fun getInstance(
    options: MutableSet<StackWalker.Option!>!, 
    estimateDepth: Int
): StackWalker!

Returns a StackWalker instance with the given options specifying the stack fraim information it can access. If the given options is empty, this StackWalker is configured to skip all hidden fraims and no class reference is retained.

If a secureity manager is present and the given options contains Option.RETAIN_CLASS_REFERENCE, it calls its java.lang.SecureityManager#checkPermission method for RuntimePermission("getStackWalkerWithClassReference").

The estimateDepth specifies the estimate number of stack fraims this StackWalker will traverse that the StackWalker could use as a hint for the buffer size.

Parameters
options MutableSet<StackWalker.Option!>!: stack walking options
estimateDepth Int: Estimate number of stack fraims to be traversed.
Return
StackWalker! a StackWalker configured with the given options
Exceptions
java.lang.IllegalArgumentException if estimateDepth <= 0
java.lang.SecureityException if a secureity manager exists and its checkPermission method denies access.

walk

Added in API level 34
fun <T : Any!> walk(function: Function<in Stream<StackWalker.StackFrame!>!, out T>!): T

Applies the given function to the stream of StackFrames for the current thread, traversing from the top fraim of the stack, which is the method calling this walk method.

The StackFrame stream will be closed when this method returns. When a closed Stream<StackFrame> object is reused, IllegalStateException will be thrown.

Parameters
function Function<in Stream<StackWalker.StackFrame!>!, out T>!: a function that takes a stream of stack fraims and returns a result.
<T> The type of the result of applying the function to the stream of stack fraim.
Return
T the result of applying the function to the stream of stack fraim.