1 /*
2 * Copyright (c) 2015, 2019, 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 (JVMS section 2.6.1). Primitive
59 * locals are represented in the returned array as {@code PrimitiveSlot}s,
60 * with longs and doubles occupying a pair of consecutive
61 * {@code PrimitiveSlot}s.
62 *
63 * <p>The current VM implementation does not provide specific type
64 * information for primitive locals. This method simply returns the raw
65 * contents of the VM's primitive locals on a best-effort basis, without
66 * indicating a specific type.
67 *
68 * <p>The returned array may contain null entries for local variables that
69 * are not live.
70 *
71 * @implNote
72 * <p> The specific subclass of {@code PrimitiveSlot} will reflect the
73 * underlying architecture, and will be either {@code PrimitiveSlot32} or
74 * {@code PrimitiveSlot64}.
75 *
76 * <p>How a long or double value is stored in the pair of
77 * {@code PrimitiveSlot}s can vary based on the underlying architecture and
78 * VM implementation. On 32-bit architectures, long/double values are split
79 * between the two {@code PrimitiveSlot32}s.
80 * On 64-bit architectures, the entire value may be stored in one of the
81 * {@code PrimitiveSlot64}s, with the other {@code PrimitiveSlot64} being
82 * unused.
83 *
84 * <p>The contents of the unused, high-order portion of a
85 * {@code PrimitiveSlot64} (when storing a primitive other than a long or
86 * double) is unspecified. In particular, the unused bits are not
87 * necessarily zeroed out.
88 *
89 * @return the local variable array of this stack frame.
90 */
91 public Object[] getLocals();
92
93 /**
94 * Gets the operand stack of this stack frame.
95 *
96 * <p>
97 * The 0-th element of the returned array represents the top of the operand stack.
98 * This method returns an empty array if the operand stack is empty.
99 *
100 * <p>Each entry on the operand stack can hold a value of any Java Virtual
101 * Machine Type.
102 * For a value of primitive type, the element in the returned array is
103 * a {@link PrimitiveSlot} object; otherwise, the element is the {@code Object}
104 * on the operand stack.
105 *
106 * @return the operand stack of this stack frame.
107 */
108 public Object[] getStack();
109
110 /**
111 * <em>UNSUPPORTED</em> This interface is intended to be package-private
112 * or moved to an internal package.<p>
113 *
114 * Represents a local variable or an entry on the operand stack whose value is
115 * of primitive type.
116 */
117 public abstract class PrimitiveSlot {
118 /**
119 * Constructor.
120 */
121 PrimitiveSlot() {}
122
123 /**
124 * Returns the size, in bytes, of the slot.
125 */
126 public abstract int size();
127
128 /**
129 * Returns the int value if this primitive value is of size 4
130 * @return the int value if this primitive value is of size 4
131 *
132 * @throws UnsupportedOperationException if this primitive value is not
133 * of size 4.
134 */
135 public int intValue() {
136 throw new UnsupportedOperationException("this " + size() + "-byte primitive");
137 }
138
139 /**
140 * Returns the long value if this primitive value is of size 8
141 * @return the long value if this primitive value is of size 8
142 *
143 * @throws UnsupportedOperationException if this primitive value is not
144 * of size 8.
145 */
146 public long longValue() {
147 throw new UnsupportedOperationException("this " + size() + "-byte primitive");
148 }
149 }
150
151
152 /**
153 * Gets {@code StackWalker} that can get locals and operands.
154 *
155 * @throws SecurityException if the security manager is present and
156 * denies access to {@code RuntimePermission("liveStackFrames")}
157 */
158 public static StackWalker getStackWalker() {
159 return getStackWalker(EnumSet.noneOf(StackWalker.Option.class));
160 }
161
162 /**
163 * Gets a {@code StackWalker} instance with the given options specifying
164 * the stack frame information it can access, and which will traverse at most
165 * the given {@code maxDepth} number of stack frames. If no option is
166 * specified, this {@code StackWalker} obtains the method name and
167 * the class name with all
168 * {@linkplain StackWalker.Option#SHOW_HIDDEN_FRAMES hidden frames} skipped.
169 * The returned {@code StackWalker} can get locals and operands.
170 *
171 * @param options stack walk {@link StackWalker.Option options}
172 *
173 * @throws SecurityException if the security manager is present and
174 * it denies access to {@code RuntimePermission("liveStackFrames")};
175 * or if the given {@code options} contains
176 * {@link StackWalker.Option#RETAIN_CLASS_REFERENCE Option.RETAIN_CLASS_REFERENCE}
177 * and it denies access to {@code RuntimePermission("getStackWalkerWithClassReference")}.
178 */
179 public static StackWalker getStackWalker(Set<StackWalker.Option> options) {
180 SecurityManager sm = System.getSecurityManager();
181 if (sm != null) {
182 sm.checkPermission(new RuntimePermission("liveStackFrames"));
183 }
184 return StackWalker.newInstance(options, LOCALS_AND_OPERANDS);
185 }
186 }