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 import java.util.EnumSet;
29 import java.util.Set;
30
31 import static java.lang.StackWalker.ExtendedOption.LOCALS_AND_OPERANDS;
32
33 /**
34 * <em>UNSUPPORTED</em> This interface is intended to be package-private
35 * or move to an internal package.<p>
36 *
37 * {@code LiveStackFrame} represents a frame storing data and partial results.
38 * Each frame has its own array of local variables (JVMS section 2.6.1),
39 * its own operand stack (JVMS section 2.6.2) for a method invocation.
40 *
41 * @jvms 2.6 Frames
42 */
43 /* package-private */
44 interface LiveStackFrame extends StackFrame {
45 /**
46 * Return the monitors held by this stack frame. This method returns
47 * an empty array if no monitor is held by this stack frame.
48 *
49 * @return the monitors held by this stack frames
50 */
51 public Object[] getMonitors();
52
53 /**
54 * Gets the local variable array of this stack frame.
55 *
56 * <p>A single local variable can hold a value of type boolean, byte, char,
57 * short, int, float, reference or returnAddress. A pair of local variables
58 * can hold a value of type long or double. In other words,
59 * a value of type long or type double occupies two consecutive local
60 * variables. For a value of primitive type, the element in the
61 * local variable array is an {@link PrimitiveValue} object;
62 * otherwise, the element is an {@code Object}.
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 * @return the operand stack of this stack frame.
82 */
83 public Object[] getStack();
84
85 /**
86 * <em>UNSUPPORTED</em> This interface is intended to be package-private
87 * or move to an internal package.<p>
88 *
89 * Represents a local variable or an entry on the operand whose value is
90 * of primitive type.
91 */
92 public abstract class PrimitiveValue {
93 /**
94 * Returns the base type of this primitive value, one of
95 * {@code B, D, C, F, I, J, S, Z}.
96 *
97 * @return Name of a base type
98 * @jvms table 4.3-A
99 */
100 abstract char type();
101
102 /**
103 * Returns the boolean value if this primitive value is of type boolean.
104 * @return the boolean value if this primitive value is of type boolean.
105 *
106 * @throws UnsupportedOperationException if this primitive value is not
107 * of type boolean.
108 */
109 public boolean booleanValue() {
110 throw new UnsupportedOperationException("this primitive of type " + type());
111 }
112
113 /**
114 * Returns the int value if this primitive value is of type int.
115 * @return the int value if this primitive value is of type int.
116 *
117 * @throws UnsupportedOperationException if this primitive value is not
118 * of type int.
119 */
120 public int intValue() {
121 throw new UnsupportedOperationException("this primitive of type " + type());
122 }
123
124 /**
125 * Returns the long value if this primitive value is of type long.
126 * @return the long value if this primitive value is of type long.
127 *
128 * @throws UnsupportedOperationException if this primitive value is not
129 * of type long.
130 */
131 public long longValue() {
132 throw new UnsupportedOperationException("this primitive of type " + type());
133 }
134
135 /**
136 * Returns the char value if this primitive value is of type char.
137 * @return the char value if this primitive value is of type char.
138 *
139 * @throws UnsupportedOperationException if this primitive value is not
140 * of type char.
141 */
142 public char charValue() {
143 throw new UnsupportedOperationException("this primitive of type " + type());
144 }
145
146 /**
147 * Returns the byte value if this primitive value is of type byte.
148 * @return the byte value if this primitive value is of type byte.
149 *
150 * @throws UnsupportedOperationException if this primitive value is not
151 * of type byte.
152 */
153 public byte byteValue() {
154 throw new UnsupportedOperationException("this primitive of type " + type());
155 }
156
157 /**
158 * Returns the short value if this primitive value is of type short.
159 * @return the short value if this primitive value is of type short.
160 *
161 * @throws UnsupportedOperationException if this primitive value is not
162 * of type short.
163 */
164 public short shortValue() {
165 throw new UnsupportedOperationException("this primitive of type " + type());
166 }
167
168 /**
169 * Returns the float value if this primitive value is of type float.
170 * @return the float value if this primitive value is of type float.
171 *
172 * @throws UnsupportedOperationException if this primitive value is not
173 * of type float.
174 */
175 public float floatValue() {
176 throw new UnsupportedOperationException("this primitive of type " + type());
177 }
178
179 /**
180 * Returns the double value if this primitive value is of type double.
181 * @return the double value if this primitive value is of type double.
182 *
183 * @throws UnsupportedOperationException if this primitive value is not
184 * of type double.
185 */
186 public double doubleValue() {
187 throw new UnsupportedOperationException("this primitive of type " + type());
188 }
189 }
190
191
192 /**
193 * Gets {@code StackWalker} that can get locals and operands.
194 *
195 * @throws SecurityException if the security manager is present and
196 * denies access to {@code RuntimePermission("liveStackFrames")}
197 */
198 public static StackWalker getStackWalker() {
199 return getStackWalker(EnumSet.noneOf(StackWalker.Option.class));
200 }
201
202 /**
203 * Gets a {@code StackWalker} instance with the given options specifying
204 * the stack frame information it can access, and which will traverse at most
205 * the given {@code maxDepth} number of stack frames. If no option is
206 * specified, this {@code StackWalker} obtains the method name and
207 * the class name with all
208 * {@linkplain StackWalker.Option#SHOW_HIDDEN_FRAMES hidden frames} skipped.
209 * The returned {@code StackWalker} can get locals and operands.
210 *
211 * @param options stack walk {@link StackWalker.Option options}
212 *
213 * @throws SecurityException if the security manager is present and
214 * it denies access to {@code RuntimePermission("liveStackFrames")}; or
215 * or if the given {@code options} contains
216 * {@link StackWalker.Option#RETAIN_CLASS_REFERENCE Option.RETAIN_CLASS_REFERENCE}
217 * and it denies access to {@code StackFramePermission("retainClassReference")}.
218 */
219 public static StackWalker getStackWalker(Set<StackWalker.Option> options) {
220 SecurityManager sm = System.getSecurityManager();
221 if (sm != null) {
222 sm.checkPermission(new RuntimePermission("liveStackFrames"));
223 }
224 return StackWalker.newInstance(options, LOCALS_AND_OPERANDS);
225 }
226 }