1 /*
2 * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package java.lang;
26
27 import java.lang.StackWalker.StackFrame;
28
29 /**
30 * <em>UNSUPPORTED</em> This interface is intended to be package-private
31 * or move to an internal package.<p>
32 *
33 * {@code LiveStackFrame} represents a frame storing data and partial results.
34 * Each frame has its own array of local variables (JVMS section 2.6.1),
35 * its own operand stack (JVMS section 2.6.2) for a method invocation.
36 *
37 * @jvms 2.6 Frames
38 */
39 /* package-private */
40 interface LiveStackFrame extends StackFrame {
41 /**
42 * Return the monitors held by this stack frame. This method returns
43 * an empty array if no monitor is held by this stack frame.
44 *
45 * @return the monitors held by this stack frames
46 */
47 public Object[] getMonitors();
48
49 /**
50 * Gets the local variable array of this stack frame.
51 *
52 * <p>A single local variable can hold a value of type boolean, byte, char,
53 * short, int, float, reference or returnAddress. A pair of local variables
54 * can hold a value of type long or double. In other words,
55 * a value of type long or type double occupies two consecutive local
56 * variables. For a value of primitive type, the element in the
57 * local variable array is an {@link PrimitiveValue} object;
58 * otherwise, the element is an {@code Object}.
59 *
60 * <p>A value of type long or double will be represented by
61 * a {@code PrimitiveValue} object containing the value in the elements
62 * at index <em>n</em> and <em>n</em>+1 in the local variable array.
63 *
64 * @return the local variable array of this stack frame.
65 */
66 public Object[] getLocals();
67
68 /**
69 * Gets the operand stack of this stack frame.
70 *
71 * <p>
72 * The 0-th element of the returned array represents the top of the operand stack.
73 * This method returns an empty array if the operand stack is empty.
74 *
75 * <p>Each entry on the operand stack can hold a value of any Java Virtual
76 * Machine Type.
77 * For a value of primitive type, the element in the returned array is
78 * an {@link PrimitiveValue} object; otherwise, the element is the {@code Object}
79 * on the operand stack.
80 *
81 * <p>A value of type long or double contributes two elements
82 * of the returned array and a value of any other type contributes one element;
83 * i.e. a value of type long or double at index
84 * <em>i</em>, the elements at <em>i</em> and <em>i</em>+1 in the returned
85 * array are both the same {@code PrimitiveValue} object containing the value.
86 *
87 * @return the operand stack of this stack frame.
88 */
89 public Object[] getStack();
90
91 /**
92 * <em>UNSUPPORTED</em> This interface is intended to be package-private
93 * or move to an internal package.<p>
94 *
95 * Represents a local variable or an entry on the operand whose value is
96 * of primitive type.
97 */
98 public interface PrimitiveValue {
99 /**
100 * Returns the base type of this primitive value, one of
101 * {@code B, D, C, F, I, J, S, Z}.
102 *
103 * @return Name of a base type
104 * @jvms table 4.3-A
105 */
106 char type();
107
108 /**
109 * Returns the boolean value if this primitive value is of type boolean.
110 * @return the boolean value if this primitive value is of type boolean.
111 *
112 * @throws UnsupportedOperationException if this primitive value is not
113 * of type boolean.
114 */
115 default boolean booleanValue() {
116 throw new UnsupportedOperationException("this primitive of type " + type());
117 }
118
119 /**
120 * Returns the int value if this primitive value is of type int.
121 * @return the int value if this primitive value is of type int.
122 *
123 * @throws UnsupportedOperationException if this primitive value is not
124 * of type int.
125 */
126 default int intValue() {
127 throw new UnsupportedOperationException("this primitive of type " + type());
128 }
129
130 /**
131 * Returns the long value if this primitive value is of type long.
132 * @return the long value if this primitive value is of type long.
133 *
134 * @throws UnsupportedOperationException if this primitive value is not
135 * of type long.
136 */
137 default long longValue() {
138 throw new UnsupportedOperationException("this primitive of type " + type());
139 }
140
141 /**
142 * Returns the char value if this primitive value is of type char.
143 * @return the char value if this primitive value is of type char.
144 *
145 * @throws UnsupportedOperationException if this primitive value is not
146 * of type char.
147 */
148 default char charValue() {
149 throw new UnsupportedOperationException("this primitive of type " + type());
150 }
151
152 /**
153 * Returns the byte value if this primitive value is of type byte.
154 * @return the byte value if this primitive value is of type byte.
155 *
156 * @throws UnsupportedOperationException if this primitive value is not
157 * of type byte.
158 */
159 default byte byteValue() {
160 throw new UnsupportedOperationException("this primitive of type " + type());
161 }
162
163 /**
164 * Returns the short value if this primitive value is of type short.
165 * @return the short value if this primitive value is of type short.
166 *
167 * @throws UnsupportedOperationException if this primitive value is not
168 * of type short.
169 */
170 default short shortValue() {
171 throw new UnsupportedOperationException("this primitive of type " + type());
172 }
173
174 /**
175 * Returns the float value if this primitive value is of type float.
176 * @return the float value if this primitive value is of type float.
177 *
178 * @throws UnsupportedOperationException if this primitive value is not
179 * of type float.
180 */
181 default float floatValue() {
182 throw new UnsupportedOperationException("this primitive of type " + type());
183 }
184
185 /**
186 * Returns the double value if this primitive value is of type double.
187 * @return the double value if this primitive value is of type double.
188 *
189 * @throws UnsupportedOperationException if this primitive value is not
190 * of type double.
191 */
192 default double doubleValue() {
193 throw new UnsupportedOperationException("this primitive of type " + type());
194 }
195 }
196 }