https://openjdk.java.net/ 
/*
 * Copyright (c) 2015, 2017, 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 java.lang.StackWalker.StackFrame;
import java.util.EnumSet;
import java.util.Set;

import static java.lang.StackWalker.ExtendedOption.LOCALS_AND_OPERANDS;


UNSUPPORTED This interface is intended to be package-private
or move to an internal package.
 LiveStackFrame represents a frame storing data and partial results. Each frame has its own array of local variables (JVMS section 2.6.1), its own operand stack (JVMS section 2.6.2) for a method invocation. 
@jvms2.6 Frames
/**
 * <em>UNSUPPORTED</em> This interface is intended to be package-private
 * or move to an internal package.<p>
 *
 * {@code LiveStackFrame} represents a frame storing data and partial results.
 * Each frame has its own array of local variables (JVMS section 2.6.1),
 * its own operand stack (JVMS section 2.6.2) for a method invocation.
 *
 * @jvms 2.6 Frames
 */
/* package-private */
interface LiveStackFrame extends StackFrame {
    
Return the monitors held by this stack frame. This method returns
an empty array if no monitor is held by this stack frame.

Returns:the monitors held by this stack frames
/**
     * Return the monitors held by this stack frame. This method returns
     * an empty array if no monitor is held by this stack frame.
     *
     * @return the monitors held by this stack frames
     */
    public Object[] getMonitors();

    
Gets the local variable array of this stack frame.

A single local variable can hold a value of type boolean, byte, char, short, int, float, reference or returnAddress. A pair of local variables can hold a value of type long or double (JVMS section 2.6.1). Primitive locals are represented in the returned array as PrimitiveSlots, with longs and doubles occupying a pair of consecutive PrimitiveSlots. 
The current VM implementation does not provide specific type
information for primitive locals.  This method simply returns the raw
contents of the VM's primitive locals on a best-effort basis, without
indicating a specific type.

The returned array may contain null entries for local variables that
are not live.

Implementation Note:

 The specific subclass of PrimitiveSlot will reflect the underlying architecture, and will be either PrimitiveSlot32 or PrimitiveSlot64. 
How a long or double value is stored in the pair of PrimitiveSlots can vary based on the underlying architecture and VM implementation. On 32-bit architectures, long/double values are split between the two PrimitiveSlot32s. On 64-bit architectures, the entire value may be stored in one of the PrimitiveSlot64s, with the other PrimitiveSlot64 being unused. 
The contents of the unused, high-order portion of a PrimitiveSlot64 (when storing a primitive other than a long or double) is unspecified. In particular, the unused bits are not necessarily zeroed out.
Returns: the local variable array of this stack frame.
/**
     * Gets the local variable array of this stack frame.
     *
     * <p>A single local variable can hold a value of type boolean, byte, char,
     * short, int, float, reference or returnAddress.  A pair of local variables
     * can hold a value of type long or double (JVMS section 2.6.1).  Primitive
     * locals are represented in the returned array as {@code PrimitiveSlot}s,
     * with longs and doubles occupying a pair of consecutive
     * {@code PrimitiveSlot}s.
     *
     * <p>The current VM implementation does not provide specific type
     * information for primitive locals.  This method simply returns the raw
     * contents of the VM's primitive locals on a best-effort basis, without
     * indicating a specific type.
     *
     * <p>The returned array may contain null entries for local variables that
     * are not live.
     *
     * @implNote
     * <p> The specific subclass of {@code PrimitiveSlot} will reflect the
     * underlying architecture, and will be either {@code PrimitiveSlot32} or
     * {@code PrimitiveSlot64}.
     *
     * <p>How a long or double value is stored in the pair of
     * {@code PrimitiveSlot}s can vary based on the underlying architecture and
     * VM implementation.  On 32-bit architectures, long/double values are split
     * between the two {@code PrimitiveSlot32}s.
     * On 64-bit architectures, the entire value may be stored in one of the
     * {@code PrimitiveSlot64}s, with the other {@code PrimitiveSlot64} being
     * unused.
     *
     * <p>The contents of the unused, high-order portion of a
     * {@code PrimitiveSlot64} (when storing a primitive other than a long or
     * double) is unspecified.  In particular, the unused bits are not
     * necessarily zeroed out.
     *
     * @return  the local variable array of this stack frame.
     */
    public Object[] getLocals();

    
Gets the operand stack of this stack frame.


The 0-th element of the returned array represents the top of the operand stack.
This method returns an empty array if the operand stack is empty.

Each entry on the operand stack can hold a value of any Java Virtual Machine Type. For a value of primitive type, the element in the returned array is a PrimitiveSlot object; otherwise, the element is the Object on the operand stack. 
Returns:the operand stack of this stack frame.
/**
     * Gets the operand stack of this stack frame.
     *
     * <p>
     * The 0-th element of the returned array represents the top of the operand stack.
     * This method returns an empty array if the operand stack is empty.
     *
     * <p>Each entry on the operand stack can hold a value of any Java Virtual
     * Machine Type.
     * For a value of primitive type, the element in the returned array is
     * a {@link PrimitiveSlot} object; otherwise, the element is the {@code Object}
     * on the operand stack.
     *
     * @return the operand stack of this stack frame.
     */
    public Object[] getStack();

    
UNSUPPORTED This interface is intended to be package-private
or moved to an internal package.

Represents a local variable or an entry on the operand stack whose value is
of primitive type.

/**
     * <em>UNSUPPORTED</em> This interface is intended to be package-private
     * or moved to an internal package.<p>
     *
     * Represents a local variable or an entry on the operand stack whose value is
     * of primitive type.
     */
    public abstract class PrimitiveSlot {
        
Returns the size, in bytes, of the slot.

/**
         * Returns the size, in bytes, of the slot.
         */
        public abstract int size();

        
Returns the int value if this primitive value is of size 4

Throws:
Returns:the int value if this primitive value is of size 4
/**
         * Returns the int value if this primitive value is of size 4
         * @return the int value if this primitive value is of size 4
         *
         * @throws UnsupportedOperationException if this primitive value is not
         * of size 4.
         */
        public int intValue() {
            throw new UnsupportedOperationException("this " + size() + "-byte primitive");
        }

        
Returns the long value if this primitive value is of size 8

Throws:
Returns:the long value if this primitive value is of size 8
/**
         * Returns the long value if this primitive value is of size 8
         * @return the long value if this primitive value is of size 8
         *
         * @throws UnsupportedOperationException if this primitive value is not
         * of size 8.
         */
        public long longValue() {
            throw new UnsupportedOperationException("this " + size() + "-byte primitive");
        }
    }


    
Gets StackWalker that can get locals and operands. 
Throws:
  • SecurityException – if the security manager is present and denies access to RuntimePermission("liveStackFrames")
/**
     * Gets {@code StackWalker} that can get locals and operands.
     *
     * @throws SecurityException if the security manager is present and
     * denies access to {@code RuntimePermission("liveStackFrames")}
     */
    public static StackWalker getStackWalker() {
        return getStackWalker(EnumSet.noneOf(StackWalker.Option.class));
    }

    
Gets a StackWalker instance with the given options specifying the stack frame information it can access, and which will traverse at most the given maxDepth number of stack frames. If no option is specified, this StackWalker obtains the method name and the class name with all hidden frames skipped. The returned StackWalker can get locals and operands. 
Params:
Throws:
  • SecurityException – if the security manager is present and it denies access to RuntimePermission("liveStackFrames"); or or if the given options contains Option.RETAIN_CLASS_REFERENCE and it denies access to RuntimePermission("getStackWalkerWithClassReference").
/**
     * Gets a {@code StackWalker} instance with the given options specifying
     * the stack frame information it can access, and which will traverse at most
     * the given {@code maxDepth} number of stack frames.  If no option is
     * specified, this {@code StackWalker} obtains the method name and
     * the class name with all
     * {@linkplain StackWalker.Option#SHOW_HIDDEN_FRAMES hidden frames} skipped.
     * The returned {@code StackWalker} can get locals and operands.
     *
     * @param options stack walk {@link StackWalker.Option options}
     *
     * @throws SecurityException if the security manager is present and
     * it denies access to {@code RuntimePermission("liveStackFrames")}; or
     * or if the given {@code options} contains
     * {@link StackWalker.Option#RETAIN_CLASS_REFERENCE Option.RETAIN_CLASS_REFERENCE}
     * and it denies access to {@code RuntimePermission("getStackWalkerWithClassReference")}.
     */
    public static StackWalker getStackWalker(Set<StackWalker.Option> options) {
        SecurityManager sm = System.getSecurityManager();
        if (sm != null) {
            sm.checkPermission(new RuntimePermission("liveStackFrames"));
        }
        return StackWalker.newInstance(options, LOCALS_AND_OPERANDS);
    }
}