/*

 * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.lang;

import jdk.internal.reflect.CallerSensitive;

import java.util.*;

import java.util.function.Consumer;

import java.util.function.Function;

import java.util.stream.Stream;

/**

 * A stack walker.

 *

 * <p> The {@link StackWalker#walk walk} method opens a sequential stream

 * of {@link StackFrame StackFrame}s for the current thread and then applies

 * the given function to walk the {@code 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 {@code StackFrame} stream is closed when the {@code walk} method returns.

 * If an attempt is made to reuse the closed stream,

 * {@code IllegalStateException} will be thrown.

 *

 * <p> The {@linkplain Option <em>stack walking options</em>} of a

 * {@code StackWalker} determines the information of

 * {@link StackFrame StackFrame} objects to be returned.

 * By default, stack frames of the reflection API and implementation

 * classes are {@linkplain Option#SHOW_HIDDEN_FRAMES hidden}

 * and {@code StackFrame}s have the class name and method name

 * available but not the {@link StackFrame#getDeclaringClass() Class reference}.

 *

 * <p> {@code StackWalker} is thread-safe. Multiple threads can share

 * a single {@code StackWalker} object to traverse its own stack.

 * A permission check is performed when a {@code StackWalker} is created,

 * according to the options it requests.

 * No further permission check is done at stack walking time.

 *

 * @apiNote

 * Examples

 *

 * <p>1. To find the first caller filtering a known list of implementation class:

 * <pre>{@code

 *     StackWalker walker = StackWalker.getInstance(Option.RETAIN_CLASS_REFERENCE);

 *     Optional<Class<?>> callerClass = walker.walk(s ->

 *         s.map(StackFrame::getDeclaringClass)

 *          .filter(interestingClasses::contains)

 *          .findFirst());

 * }</pre>

 *

 * <p>2. To snapshot the top 10 stack frames of the current thread,

 * <pre>{@code

 *     List<StackFrame> stack = StackWalker.getInstance().walk(s ->

 *         s.limit(10).collect(Collectors.toList()));

 * }</pre>

 *

 * Unless otherwise noted, passing a {@code null} argument to a

 * constructor or method in this {@code StackWalker} class

 * will cause a {@link NullPointerException NullPointerException}

 * to be thrown.

 *

 * @since 9

 */

public final class StackWalker {

    /**

     * A {@code StackFrame} object represents a method invocation returned by

     * {@link StackWalker}.

     *

     * <p> The {@link #getDeclaringClass()} method may be unsupported as determined

     * by the {@linkplain Option stack walking options} of a {@linkplain

     * StackWalker stack walker}.

     *

     * @since 9

     * @jvms 2.6

     */

    public static interface StackFrame {

        /**

         * Gets the <a href="ClassLoader.html#name">binary name</a>

         * of the declaring class of the method represented by this stack frame.

         *

         * @return the binary name of the declaring class of the method

         *         represented by this stack frame

         *

         * @jls 13.1 The Form of a Binary

         */

        public String getClassName();

        /**

         * Gets the name of the method represented by this stack frame.

         * @return the name of the method represented by this stack frame

         */

        public String getMethodName();

        /**

         * Gets the declaring {@code Class} for the method represented by

         * this stack frame.

         *

         * @return the declaring {@code Class} of the method represented by

         * this stack frame

         *

         * @throws UnsupportedOperationException if this {@code StackWalker}

         *         is not configured with {@link Option#RETAIN_CLASS_REFERENCE

         *         Option.RETAIN_CLASS_REFERENCE}.

         */

        public Class<?> getDeclaringClass();

        /**

         * Returns the index to the code array of the {@code Code} attribute

         * containing the execution point represented by this stack frame.

         * The code array gives the actual bytes of Java Virtual Machine code

         * that implement the method.

         *

         * @return the index to the code array of the {@code Code} attribute

         *         containing the execution point represented by this stack frame,

         *         or a negative number if the method is native.

         *

         * @jvms 4.7.3 The {@code Code} Attribute

         */

        public int getByteCodeIndex();

        /**

         * Returns the name of the source file containing the execution point

         * represented by this stack frame.  Generally, this corresponds

         * to the {@code SourceFile} attribute of the relevant {@code class}

         * file as defined by <cite>The Java Virtual Machine Specification</cite>.

         * In some systems, the name may refer to some source code unit

         * other than a file, such as an entry in a source repository.

         *

         * @return the name of the file containing the execution point

         *         represented by this stack frame, or {@code null} if

         *         this information is unavailable.

         *

         * @jvms 4.7.10 The {@code SourceFile} Attribute

         */

        public String getFileName();

        /**

         * Returns the line number of the source line containing the execution

         * point represented by this stack frame.  Generally, this is

         * derived from the {@code LineNumberTable} attribute of the relevant

         * {@code class} file as defined by <cite>The Java Virtual Machine

         * Specification</cite>.

         *

         * @return the line number of the source line containing the execution

         *         point represented by this stack frame, or a negative number if

         *         this information is unavailable.

         *

         * @jvms 4.7.12 The {@code LineNumberTable} Attribute

         */

        public int getLineNumber();

        /**

         * Returns {@code true} if the method containing the execution point

         * represented by this stack frame is a native method.

         *

         * @return {@code true} if the method containing the execution point

         *         represented by this stack frame is a native method.

         */

        public boolean isNativeMethod();

        /**

         * Gets a {@code StackTraceElement} for this stack frame.

         *

         * @return {@code StackTraceElement} for this stack frame.

         */

        public StackTraceElement toStackTraceElement();

    }

    /**

     * Stack walker option to configure the {@linkplain StackFrame stack frame}

     * information obtained by a {@code StackWalker}.

     *

     * @since 9

     */

    public enum Option {

        /**

         * Retains {@code Class} object in {@code StackFrame}s

         * walked by this {@code StackWalker}.

         *

         * <p> A {@code StackWalker} configured with this option will support

         * {@link StackWalker#getCallerClass()} and

         * {@link StackFrame#getDeclaringClass() StackFrame.getDeclaringClass()}.

         */

        RETAIN_CLASS_REFERENCE,

        /**

         * Shows all reflection frames.

         *

         * <p>By default, reflection frames are hidden.  This includes the

         * {@link java.lang.reflect.Method#invoke} method

         * and the reflection implementation classes. A {@code StackWalker} with

         * this {@code SHOW_REFLECT_FRAMES} option will show all reflection frames.

         * The {@link #SHOW_HIDDEN_FRAMES} option can also be used to show all

         * reflection frames and it will also show other hidden frames that

         * are implementation-specific.

         */

        SHOW_REFLECT_FRAMES,

        /**

         * Shows all hidden frames.

         *

         * <p>A Java Virtual Machine implementation may hide implementation

         * specific frames in addition to {@linkplain #SHOW_REFLECT_FRAMES

         * reflection frames}. A {@code StackWalker} with this {@code SHOW_HIDDEN_FRAMES}

         * option will show all hidden frames (including reflection 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;

    /**

     * Returns a {@code StackWalker} instance.

     *

     * <p> This {@code StackWalker} is configured to skip all

     * {@linkplain Option#SHOW_HIDDEN_FRAMES hidden frames} and

     * no {@linkplain Option#RETAIN_CLASS_REFERENCE class reference} is retained.

     *

     * @return a {@code StackWalker} configured to skip all

     * {@linkplain Option#SHOW_HIDDEN_FRAMES hidden frames} and

     * no {@linkplain Option#RETAIN_CLASS_REFERENCE class reference} is retained.

     *

     */

    public static StackWalker getInstance() {

        // no permission check needed

        return DEFAULT_WALKER;

    }

    /**

     * Returns a {@code StackWalker} instance with the given option specifying

     * the stack frame information it can access.

     *

     * <p>

     * If a security manager is present and the given {@code option} is

     * {@link Option#RETAIN_CLASS_REFERENCE Option.RETAIN_CLASS_REFERENCE},

     * it calls its {@link SecurityManager#checkPermission checkPermission}

     * method for {@code StackFramePermission("retainClassReference")}.

     *

     * @param option {@link Option stack walking option}

     *

     * @return a {@code StackWalker} configured with the given option

     *

     * @throws SecurityException if a security manager exists and its

     *         {@code checkPermission} method denies access.

     */

    public static StackWalker getInstance(Option option) {

        return getInstance(EnumSet.of(Objects.requireNonNull(option)));

    }

    /**

     * Returns a {@code StackWalker} instance with the given {@code options} specifying

     * the stack frame information it can access.  If the given {@code options}

     * is empty, this {@code StackWalker} is configured to skip all

     * {@linkplain Option#SHOW_HIDDEN_FRAMES hidden frames} and no

     * {@linkplain Option#RETAIN_CLASS_REFERENCE class reference} is retained.

     *

     * <p>

     * If a security manager is present and the given {@code options} contains

     * {@link Option#RETAIN_CLASS_REFERENCE Option.RETAIN_CLASS_REFERENCE},

     * it calls its {@link SecurityManager#checkPermission checkPermission}

     * method for {@code StackFramePermission("retainClassReference")}.

     *

     * @param options {@link Option stack walking option}

     *

     * @return a {@code StackWalker} configured with the given options

     *

     * @throws SecurityException if a security manager exists and its

     *         {@code checkPermission} method denies access.

     */

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

        if (options.isEmpty()) {

            return DEFAULT_WALKER;

        }

        EnumSet<Option> optionSet = toEnumSet(options);

        checkPermission(optionSet);

        return new StackWalker(optionSet);

    }

    /**

     * Returns a {@code StackWalker} instance with the given {@code options} specifying

     * the stack frame information it can access. If the given {@code options}

     * is empty, this {@code StackWalker} is configured to skip all

     * {@linkplain Option#SHOW_HIDDEN_FRAMES hidden frames} and no

     * {@linkplain Option#RETAIN_CLASS_REFERENCE class reference} is retained.

     *

     * <p>

     * If a security manager is present and the given {@code options} contains

     * {@link Option#RETAIN_CLASS_REFERENCE Option.RETAIN_CLASS_REFERENCE},

     * it calls its {@link SecurityManager#checkPermission checkPermission}

     * method for {@code StackFramePermission("retainClassReference")}.

     *

     * <p>

     * The {@code estimateDepth} specifies the estimate number of stack frames

     * this {@code StackWalker} will traverse that the {@code StackWalker} could

     * use as a hint for the buffer size.

     *

     * @param options {@link Option stack walking options}

     * @param estimateDepth Estimate number of stack frames to be traversed.

     *

     * @return a {@code StackWalker} configured with the given options

     *

     * @throws IllegalArgumentException if {@code estimateDepth <= 0}

     * @throws SecurityException if a security manager exists and its

     *         {@code checkPermission} method denies access.

     */

    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 constructors ------

    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;

    }

    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 StackFramePermission("retainClassReference"));

            }

        }

    }

    /*

     * Returns a defensive copy

     */

    private static EnumSet<Option> toEnumSet(Set<Option> options) {

        Objects.requireNonNull(options);

        if (options.isEmpty()) {

            return DEFAULT_EMPTY_OPTION;

        } else {

            return EnumSet.copyOf(options);

        }

    }

    /**

     * Applies the given function to the stream of {@code StackFrame}s

     * for the current thread, traversing from the top frame of the stack,

     * which is the method calling this {@code walk} method.

     *

     * <p>The {@code StackFrame} stream will be closed when

     * this method returns.  When a closed {@code Stream<StackFrame>} object

     * is reused, {@code IllegalStateException} will be thrown.

     *

     * @apiNote

     * For example, to find the first 10 calling frames, first skipping those frames

     * whose declaring class is in package {@code com.foo}:

     * <blockquote>

     * <pre>{@code

     * List<StackFrame> frames = StackWalker.getInstance().walk(s ->

     *     s.dropWhile(f -> f.getClassName().startsWith("com.foo."))

     *      .limit(10)

     *      .collect(Collectors.toList()));

     * }</pre></blockquote>

     *

     * <p>This method takes a {@code Function} accepting a {@code Stream<StackFrame>},

     * rather than returning a {@code 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 {@code Function} parameter, this method

     * allows access to stack frames through a stable view of a thread's control

     * stack.

     *

     * <p>Parallel execution is effectively disabled and stream pipeline

     * execution will only occur on the current thread.

     *

     * @implNote 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, {@code IllegalStateException} will be thrown.

     *

     * @param function a function that takes a stream of

     *                 {@linkplain StackFrame stack frames} and returns a result.

     * @param <T> The type of the result of applying the function to the

     *            stream of {@linkplain StackFrame stack frame}.

     *

     * @return the result of applying the function to the stream of

     *         {@linkplain StackFrame stack frame}.

     */

    @CallerSensitive

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

        // Returning a Stream<StackFrame> would be unsafe, as the stream could

        // be used to access the stack frames in an uncontrolled manner.  For

        // example, a caller might pass a Spliterator of stack frames after one

        // or more frames had been traversed. There is no robust way to detect

        // whether the execution point when

        // Spliterator.tryAdvance(java.util.function.Consumer<? super T>) is

        // invoked is the exact same execution point where the stack frame

        // traversal is expected to resume.

        Objects.requireNonNull(function);

        return StackStreamFactory.makeStackTraverser(this, function)

                                 .walk();

    }

    /**

     * Performs the given action on each element of {@code StackFrame} stream

     * of the current thread, traversing from the top frame of the stack,

     * which is the method calling this {@code forEach} method.

     *

     * <p> This method is equivalent to calling

     * <blockquote>

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

     * </blockquote>

     *

     * @param action an action to be performed on each {@code StackFrame}

     *               of the stack of the current thread

     */

    @CallerSensitive

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

        Objects.requireNonNull(action);

        StackStreamFactory.makeStackTraverser(this, s -> {

            s.forEach(action);

            return null;

        }).walk();

    }

    /**

     * Gets the {@code Class} object of the caller invoking the method

     * that calls this {@code getCallerClass} method.

     *

     * <p> Reflection frames, {@link java.lang.invoke.MethodHandle}, and

     * hidden frames are filtered regardless of the

     * {@link Option#SHOW_REFLECT_FRAMES SHOW_REFLECT_FRAMES}

     * and {@link Option#SHOW_HIDDEN_FRAMES SHOW_HIDDEN_FRAMES} options

     * this {@code StackWalker} has been configured with.

     *

     * <p> This method throws {@code UnsupportedOperationException}

     * if this {@code StackWalker} is not configured with the

     * {@link Option#RETAIN_CLASS_REFERENCE RETAIN_CLASS_REFERENCE} option.

     * This method should be called when a caller frame is present.  If

     * it is called from the last frame on the stack,

     * {@code IllegalStateException} will be thrown.

     *

     * @apiNote

     * For example, {@code Util::getResourceBundle} loads a resource bundle

     * on behalf of the caller.  It calls this {@code getCallerClass} method

     * to find the method calling {@code Util::getResourceBundle} and uses the caller's

     * class loader to load the resource bundle. The caller class in this example

     * is the {@code MyTool} class.

     *

     * <pre>{@code

     * 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");

     *     }

     * }

     * }</pre>

     *

     * An equivalent way to find the caller class using the

     * {@link StackWalker#walk walk} method is as follows

     * (filtering the reflection frames, {@code MethodHandle} and hidden frames

     * not shown below):

     * <pre>{@code

     *     Optional<Class<?>> caller = walker.walk(s ->

     *         s.map(StackFrame::getDeclaringClass)

     *          .skip(2)

     *          .findFirst());

     * }</pre>

     *

     * When the {@code getCallerClass} method is called from a method that

     * is the last frame on the stack,

     * for example, {@code static public void main} method launched by the

     * {@code java} launcher, or a method invoked from a JNI attached thread,

     * {@code IllegalStateException} is thrown.