64 * <p>1. To find the first caller filtering a known list of implementation class:
65 * <pre>{@code
66 * StackWalker walker = StackWalker.getInstance(Option.RETAIN_CLASS_REFERENCE);
67 * Optional<Class<?>> callerClass = walker.walk(s ->
68 * s.map(StackFrame::getDeclaringClass)
69 * .filter(interestingClasses::contains)
70 * .findFirst());
71 * }</pre>
72 *
73 * <p>2. To snapshot the top 10 stack frames of the current thread,
74 * <pre>{@code
75 * List<StackFrame> stack = StackWalker.getInstance().walk(s ->
76 * s.limit(10).collect(Collectors.toList()));
77 * }</pre>
78 *
79 * Unless otherwise noted, passing a {@code null} argument to a
80 * constructor or method in this {@code StackWalker} class
81 * will cause a {@link NullPointerException NullPointerException}
82 * to be thrown.
83 *
84 * @since 1.9
85 */
86 public final class StackWalker {
87 /**
88 * A {@code StackFrame} object represents a method invocation returned by
89 * {@link StackWalker}.
90 *
91 * <p> The {@link #getDeclaringClass()} method may be unsupported as determined
92 * by the {@linkplain Option stack walking options} of a {@linkplain
93 * StackWalker stack walker}.
94 *
95 * @since 1.9
96 * @jvms 2.6
97 */
98 public static interface StackFrame {
99 /**
100 * Gets the <a href="ClassLoader.html#name">binary name</a>
101 * of the declaring class of the method represented by this stack frame.
102 *
103 * @return the binary name of the declaring class of the method
104 * represented by this stack frame
105 *
106 * @jls 13.1 The Form of a Binary
107 */
108 public String getClassName();
109
110 /**
111 * Gets the name of the method represented by this stack frame.
112 * @return the name of the method represented by this stack frame
113 */
114 public String getMethodName();
115
168
169 /**
170 * Gets a {@code StackTraceElement} for this stack frame.
171 *
172 * @return {@code StackTraceElement} for this stack frame.
173 *
174 * */
175 public default StackTraceElement toStackTraceElement() {
176 int lineNumber = isNativeMethod() ? -2
177 : getLineNumber().orElse(-1);
178 return new StackTraceElement(getClassName(), getMethodName(),
179 getFileName().orElse(null),
180 lineNumber);
181 }
182 }
183
184 /**
185 * Stack walker option to configure the {@linkplain StackFrame stack frame}
186 * information obtained by a {@code StackWalker}.
187 *
188 * @since 1.9
189 */
190 public enum Option {
191 /**
192 * Retains {@code Class} object in {@code StackFrame}s
193 * walked by this {@code StackWalker}.
194 *
195 * <p> A {@code StackWalker} configured with this option will support
196 * {@link StackWalker#getCallerClass()} and
197 * {@link StackFrame#getDeclaringClass() StackFrame.getDeclaringClass()}.
198 */
199 RETAIN_CLASS_REFERENCE,
200 /**
201 * Shows all reflection frames.
202 *
203 * <p>By default, reflection frames are hidden. This includes the
204 * {@link java.lang.reflect.Method#invoke} method
205 * and the reflection implementation classes. A {@code StackWalker} with
206 * this {@code SHOW_REFLECT_FRAMES} option will show all reflection frames.
207 * The {@link #SHOW_HIDDEN_FRAMES} option can also be used to show all
208 * reflection frames and it will also show other hidden frames that
|
64 * <p>1. To find the first caller filtering a known list of implementation class:
65 * <pre>{@code
66 * StackWalker walker = StackWalker.getInstance(Option.RETAIN_CLASS_REFERENCE);
67 * Optional<Class<?>> callerClass = walker.walk(s ->
68 * s.map(StackFrame::getDeclaringClass)
69 * .filter(interestingClasses::contains)
70 * .findFirst());
71 * }</pre>
72 *
73 * <p>2. To snapshot the top 10 stack frames of the current thread,
74 * <pre>{@code
75 * List<StackFrame> stack = StackWalker.getInstance().walk(s ->
76 * s.limit(10).collect(Collectors.toList()));
77 * }</pre>
78 *
79 * Unless otherwise noted, passing a {@code null} argument to a
80 * constructor or method in this {@code StackWalker} class
81 * will cause a {@link NullPointerException NullPointerException}
82 * to be thrown.
83 *
84 * @since 9
85 */
86 public final class StackWalker {
87 /**
88 * A {@code StackFrame} object represents a method invocation returned by
89 * {@link StackWalker}.
90 *
91 * <p> The {@link #getDeclaringClass()} method may be unsupported as determined
92 * by the {@linkplain Option stack walking options} of a {@linkplain
93 * StackWalker stack walker}.
94 *
95 * @since 9
96 * @jvms 2.6
97 */
98 public static interface StackFrame {
99 /**
100 * Gets the <a href="ClassLoader.html#name">binary name</a>
101 * of the declaring class of the method represented by this stack frame.
102 *
103 * @return the binary name of the declaring class of the method
104 * represented by this stack frame
105 *
106 * @jls 13.1 The Form of a Binary
107 */
108 public String getClassName();
109
110 /**
111 * Gets the name of the method represented by this stack frame.
112 * @return the name of the method represented by this stack frame
113 */
114 public String getMethodName();
115
168
169 /**
170 * Gets a {@code StackTraceElement} for this stack frame.
171 *
172 * @return {@code StackTraceElement} for this stack frame.
173 *
174 * */
175 public default StackTraceElement toStackTraceElement() {
176 int lineNumber = isNativeMethod() ? -2
177 : getLineNumber().orElse(-1);
178 return new StackTraceElement(getClassName(), getMethodName(),
179 getFileName().orElse(null),
180 lineNumber);
181 }
182 }
183
184 /**
185 * Stack walker option to configure the {@linkplain StackFrame stack frame}
186 * information obtained by a {@code StackWalker}.
187 *
188 * @since 9
189 */
190 public enum Option {
191 /**
192 * Retains {@code Class} object in {@code StackFrame}s
193 * walked by this {@code StackWalker}.
194 *
195 * <p> A {@code StackWalker} configured with this option will support
196 * {@link StackWalker#getCallerClass()} and
197 * {@link StackFrame#getDeclaringClass() StackFrame.getDeclaringClass()}.
198 */
199 RETAIN_CLASS_REFERENCE,
200 /**
201 * Shows all reflection frames.
202 *
203 * <p>By default, reflection frames are hidden. This includes the
204 * {@link java.lang.reflect.Method#invoke} method
205 * and the reflection implementation classes. A {@code StackWalker} with
206 * this {@code SHOW_REFLECT_FRAMES} option will show all reflection frames.
207 * The {@link #SHOW_HIDDEN_FRAMES} option can also be used to show all
208 * reflection frames and it will also show other hidden frames that
|