Added in [API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Nested Classes](https://developer.android.com/reference/java/lang/StackWalker#nestedclasses) \| [Methods](https://developer.android.com/reference/java/lang/StackWalker#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/java/lang/StackWalker#inhmethods)
# StackWalker
` public final class StackWalker `
` extends https://developer.android.com/reference/java/lang/Object ` ` `
|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | java.lang.StackWalker |
*** ** * ** ***
A stack walker.
The `https://developer.android.com/reference/java/lang/StackWalker#walk(java.util.function.Function,?%20extends%20T>)` method opens a sequential stream of `https://developer.android.com/reference/java/lang/StackWalker.StackFrame`s 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 top most 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.
The [*stack walking options*](https://developer.android.com/reference/java/lang/StackWalker.Option) of a `StackWalker` determines the information of `https://developer.android.com/reference/java/lang/StackWalker.StackFrame` objects to be returned. By default, stack frames of the reflection API and implementation classes are [hidden](https://developer.android.com/reference/java/lang/StackWalker.Option#SHOW_HIDDEN_FRAMES) and `StackFrame`s have the class name and method name available but not the `https://developer.android.com/reference/java/lang/StackWalker.StackFrame#getDeclaringClass()`.
`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 ||
|---|---|
| ` interface` | `https://developer.android.com/reference/java/lang/StackWalker.StackFrame` A `StackFrame` object represents a method invocation returned by `https://developer.android.com/reference/java/lang/StackWalker`. |
| ### Public methods ||
|---|---|
| ` void` | ` https://developer.android.com/reference/java/lang/StackWalker#forEach(java.util.function.Consumer)(https://developer.android.com/reference/java/util/function/Consumer action) ` Performs the given action on each element of `StackFrame` stream of the current thread, traversing from the top frame of the stack, which is the method calling this `forEach` method. |
| ` https://developer.android.com/reference/java/lang/Class` | ` https://developer.android.com/reference/java/lang/StackWalker#getCallerClass()() ` Gets the `Class` object of the caller who invoked the method that invoked `getCallerClass`. |
| ` static https://developer.android.com/reference/java/lang/StackWalker` | ` https://developer.android.com/reference/java/lang/StackWalker#getInstance(java.util.Set)(https://developer.android.com/reference/java/util/Set options) ` Returns a `StackWalker` instance with the given `options` specifying the stack frame information it can access. |
| ` static https://developer.android.com/reference/java/lang/StackWalker` | ` https://developer.android.com/reference/java/lang/StackWalker#getInstance()() ` Returns a `StackWalker` instance. |
| ` static https://developer.android.com/reference/java/lang/StackWalker` | ` https://developer.android.com/reference/java/lang/StackWalker#getInstance(java.util.Set,%20int)(https://developer.android.com/reference/java/util/Set options, int estimateDepth) ` Returns a `StackWalker` instance with the given `options` specifying the stack frame information it can access. |
| ` static https://developer.android.com/reference/java/lang/StackWalker` | ` https://developer.android.com/reference/java/lang/StackWalker#getInstance(java.lang.StackWalker.Option)(https://developer.android.com/reference/java/lang/StackWalker.Option option) ` Returns a `StackWalker` instance with the given option specifying the stack frame information it can access. |
| ` T` | ` https://developer.android.com/reference/java/lang/StackWalker#walk(java.util.function.Function,?%20extends%20T>)(https://developer.android.com/reference/java/util/function/Function, ? extends T> function) ` Applies the given function to the stream of `StackFrame`s for the current thread, traversing from the top frame of the stack, which is the method calling this `walk` method. |
### Inherited methods
From class ` https://developer.android.com/reference/java/lang/Object ` ` https://developer.android.com/reference/java/lang/Object` ` https://developer.android.com/reference/java/lang/Object#clone()() `
Creates and returns a copy of this object.
` boolean` ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) `
Indicates whether some other object is "equal to" this one.
` void` ` https://developer.android.com/reference/java/lang/Object#finalize()() `
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
` final https://developer.android.com/reference/java/lang/Class` ` https://developer.android.com/reference/java/lang/Object#getClass()() `
Returns the runtime class of this `Object`.
` int` ` https://developer.android.com/reference/java/lang/Object#hashCode()() `
Returns a hash code value for the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#notify()() `
Wakes up a single thread that is waiting on this object's monitor.
` final void` ` https://developer.android.com/reference/java/lang/Object#notifyAll()() `
Wakes up all threads that are waiting on this object's monitor.
` https://developer.android.com/reference/java/lang/String` ` https://developer.android.com/reference/java/lang/Object#toString()() `
Returns a string representation of the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait()() `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*.
## Public methods
### forEach
Added in [API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void forEach (Consumer action)
```
Performs the given action on each element of `StackFrame` stream of the current thread, traversing from the top frame 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`: an action to be performed on each `StackFrame` of the stack of the current thread
|
### getCallerClass
Added in [API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Class getCallerClass ()
```
Gets the `Class` object of the caller who invoked the method that invoked `getCallerClass`.
This method filters [reflection frames](https://developer.android.com/reference/java/lang/StackWalker.Option#SHOW_REFLECT_FRAMES), `https://developer.android.com/reference/java/lang/invoke/MethodHandle`, and [hidden frames](https://developer.android.com/reference/java/lang/StackWalker.Option#SHOW_HIDDEN_FRAMES) regardless of the `https://developer.android.com/reference/java/lang/StackWalker.Option#SHOW_REFLECT_FRAMES` and `https://developer.android.com/reference/java/lang/StackWalker.Option#SHOW_HIDDEN_FRAMES` options this `StackWalker` has been configured with.
This method should be called when a caller frame is present. If it is called from the bottom most frame on the stack, `IllegalCallerException` will be thrown.
This method throws `UnsupportedOperationException` if this `StackWalker` is not configured with the `https://developer.android.com/reference/java/lang/StackWalker.Option#RETAIN_CLASS_REFERENCE` option.
##### 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 `https://developer.android.com/reference/java/lang/StackWalker#walk(java.util.function.Function,?%20extends%20T>)` method is as follows (filtering the reflection frames, `MethodHandle` and hidden frames not shown below):
Optional> 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 ||
|---|---|
| `https://developer.android.com/reference/java/lang/Class` | `Class` object of the caller's caller invoking this method.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/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. |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if this `StackWalker` is not configured with `https://developer.android.com/reference/java/lang/StackWalker.Option#RETAIN_CLASS_REFERENCE`. |
### getInstance
Added in [API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static StackWalker getInstance (Set options)
```
Returns a `StackWalker` instance with the given `options` specifying the stack frame information it can access. If the given `options` is empty, this `StackWalker` is configured to skip all [hidden frames](https://developer.android.com/reference/java/lang/StackWalker.Option#SHOW_HIDDEN_FRAMES) and no [class reference](https://developer.android.com/reference/java/lang/StackWalker.Option#RETAIN_CLASS_REFERENCE) is retained.
If a security manager is present and the given `options` contains `https://developer.android.com/reference/java/lang/StackWalker.Option#RETAIN_CLASS_REFERENCE`, it calls its `https://developer.android.com/reference/java/lang/SecurityManager#checkPermission(java.security.Permission)` method for `RuntimePermission("getStackWalkerWithClassReference")`.
| Parameters ||
|---|---|
| `options` | `Set`: `https://developer.android.com/reference/java/lang/StackWalker.Option`
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/lang/StackWalker` | a `StackWalker` configured with the given options
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/SecurityException` | if a security manager exists and its `checkPermission` method denies access. |
### getInstance
Added in [API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static StackWalker getInstance ()
```
Returns a `StackWalker` instance.
This `StackWalker` is configured to skip all [hidden frames](https://developer.android.com/reference/java/lang/StackWalker.Option#SHOW_HIDDEN_FRAMES) and no [class reference](https://developer.android.com/reference/java/lang/StackWalker.Option#RETAIN_CLASS_REFERENCE) is retained.
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/lang/StackWalker` | a `StackWalker` configured to skip all [hidden frames](https://developer.android.com/reference/java/lang/StackWalker.Option#SHOW_HIDDEN_FRAMES) and no [class reference](https://developer.android.com/reference/java/lang/StackWalker.Option#RETAIN_CLASS_REFERENCE) is retained.
|
### getInstance
Added in [API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static StackWalker getInstance (Set options,
int estimateDepth)
```
Returns a `StackWalker` instance with the given `options` specifying the stack frame information it can access. If the given `options` is empty, this `StackWalker` is configured to skip all [hidden frames](https://developer.android.com/reference/java/lang/StackWalker.Option#SHOW_HIDDEN_FRAMES) and no [class reference](https://developer.android.com/reference/java/lang/StackWalker.Option#RETAIN_CLASS_REFERENCE) is retained.
If a security manager is present and the given `options` contains `https://developer.android.com/reference/java/lang/StackWalker.Option#RETAIN_CLASS_REFERENCE`, it calls its `https://developer.android.com/reference/java/lang/SecurityManager#checkPermission(java.security.Permission)` method for `RuntimePermission("getStackWalkerWithClassReference")`.
The `estimateDepth` specifies the estimate number of stack frames this `StackWalker` will traverse that the `StackWalker` could use as a hint for the buffer size.
| Parameters ||
|---|---|
| `options` | `Set`: `https://developer.android.com/reference/java/lang/StackWalker.Option`
|
| `estimateDepth` | `int`: Estimate number of stack frames to be traversed.
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/lang/StackWalker` | a `StackWalker` configured with the given options
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if `estimateDepth <= 0` |
| `https://developer.android.com/reference/java/lang/SecurityException` | if a security manager exists and its `checkPermission` method denies access. |
### getInstance
Added in [API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static StackWalker getInstance (StackWalker.Option option)
```
Returns a `StackWalker` instance with the given option specifying the stack frame information it can access.
If a security manager is present and the given `option` is `https://developer.android.com/reference/java/lang/StackWalker.Option#RETAIN_CLASS_REFERENCE`, it calls its `https://developer.android.com/reference/java/lang/SecurityManager#checkPermission(java.security.Permission)` method for `RuntimePermission("getStackWalkerWithClassReference")`.
| Parameters ||
|---|---|
| `option` | `StackWalker.Option`: `https://developer.android.com/reference/java/lang/StackWalker.Option`
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/lang/StackWalker` | a `StackWalker` configured with the given option
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/SecurityException` | if a security manager exists and its `checkPermission` method denies access. |
### walk
Added in [API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public T walk (Function, ? extends T> function)
```
Applies the given function to the stream of `StackFrame`s for the current thread, traversing from the top frame 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` object is reused, `IllegalStateException` will be thrown.
##### API Note:
- For example, to find the first 10 calling frames, first skipping those frames whose declaring class is in package `com.foo`:
>
> List 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`, rather than returning a `Stream` 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.
| Parameters ||
|---|---|
| `function` | `Function`: a function that takes a stream of [stack frames](https://developer.android.com/reference/java/lang/StackWalker.StackFrame) and returns a result.
|
| Returns ||
|---|---|
| `T` | the result of applying the function to the stream of [stack frame](https://developer.android.com/reference/java/lang/StackWalker.StackFrame).
|