/*
 * Copyright (c) 2015, 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;

/**
 * <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.
     *
     * @return the monitors held by this stack frames
     */
    public Object[] getMonitors();

    /**
     * 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.  In other words,
     * a value of type long or type double occupies two consecutive local
     * variables.  For a value of primitive type, the element in the
     * local variable array is an {@link PrimitiveValue} object;
     * otherwise, the element is an {@code Object}.
     *
     * <p>A value of type long or double will be represented by
     * a {@code PrimitiveValue} object containing the value in the elements
     * at index <em>n</em> and <em>n</em>+1 in the local variable array.
     *
     * @return  the local variable array of this stack frame.
     */
    public Object[] getLocals();

    /**
     * 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
     * an {@link PrimitiveValue} object; otherwise, the element is the {@code Object}
     * on the operand stack.
     *
     * <p>A value of type long or double contributes two elements
     * of the returned array and a value of any other type contributes one element;
     * i.e. a value of type long or double at index
     * <em>i</em>, the elements at <em>i</em> and <em>i</em>+1 in the returned
     * array are both the same {@code PrimitiveValue} object containing the value.
     *
     * @return the operand stack of this stack frame.
     */
    public Object[] getStack();

    /**
     * <em>UNSUPPORTED</em> This interface is intended to be package-private
     * or move to an internal package.<p>
     *
     * Represents a local variable or an entry on the operand whose value is
     * of primitive type.
     */
    public interface PrimitiveValue {
        /**
         * Returns the base type of this primitive value, one of
         * {@code B, D, C, F, I, J, S, Z}.
         *
         * @return Name of a base type
         * @jvms table 4.3-A
         */
        char type();

        /**
         * Returns the boolean value if this primitive value is of type boolean.
         * @return the boolean value if this primitive value is of type boolean.
         *
         * @throws UnsupportedOperationException if this primitive value is not
         * of type boolean.
         */
        default boolean booleanValue() {
            throw new UnsupportedOperationException("this primitive of type " + type());
        }

        /**
         * Returns the int value if this primitive value is of type int.
         * @return the int value if this primitive value is of type int.
         *
         * @throws UnsupportedOperationException if this primitive value is not
         * of type int.
         */
        default int intValue() {
            throw new UnsupportedOperationException("this primitive of type " + type());
        }

        /**
         * Returns the long value if this primitive value is of type long.
         * @return the long value if this primitive value is of type long.
         *
         * @throws UnsupportedOperationException if this primitive value is not
         * of type long.
         */
        default long longValue() {
            throw new UnsupportedOperationException("this primitive of type " + type());
        }

        /**
         * Returns the char value if this primitive value is of type char.
         * @return the char value if this primitive value is of type char.
         *
         * @throws UnsupportedOperationException if this primitive value is not
         * of type char.
         */
        default char charValue() {
            throw new UnsupportedOperationException("this primitive of type " + type());
        }

        /**
         * Returns the byte value if this primitive value is of type byte.
         * @return the byte value if this primitive value is of type byte.
         *
         * @throws UnsupportedOperationException if this primitive value is not
         * of type byte.
         */
        default byte byteValue() {
            throw new UnsupportedOperationException("this primitive of type " + type());
        }

        /**
         * Returns the short value if this primitive value is of type short.
         * @return the short value if this primitive value is of type short.
         *
         * @throws UnsupportedOperationException if this primitive value is not
         * of type short.
         */
        default short shortValue() {
            throw new UnsupportedOperationException("this primitive of type " + type());
        }

        /**
         * Returns the float value if this primitive value is of type float.
         * @return the float value if this primitive value is of type float.
         *
         * @throws UnsupportedOperationException if this primitive value is not
         * of type float.
         */
        default float floatValue() {
            throw new UnsupportedOperationException("this primitive of type " + type());
        }

        /**
         * Returns the double value if this primitive value is of type double.
         * @return the double value if this primitive value is of type double.
         *
         * @throws UnsupportedOperationException if this primitive value is not
         * of type double.
         */
        default double doubleValue() {
            throw new UnsupportedOperationException("this primitive of type " + type());
        }
    }
}