1 /* 2 * Copyright (c) 2015, 2021, 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 */ getMonitors()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 */ getLocals()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 */ getStack()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 */ PrimitiveSlot()121 PrimitiveSlot() {} 122 123 /** 124 * Returns the size, in bytes, of the slot. 125 */ size()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 */ intValue()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 */ longValue()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 */ getStackWalker()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 */ getStackWalker(Set<StackWalker.Option> options)179 public static StackWalker getStackWalker(Set<StackWalker.Option> options) { 180 @SuppressWarnings("removal") 181 SecurityManager sm = System.getSecurityManager(); 182 if (sm != null) { 183 sm.checkPermission(new RuntimePermission("liveStackFrames")); 184 } 185 return StackWalker.newInstance(options, LOCALS_AND_OPERANDS); 186 } 187 } 188