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 import jdk.internal.vm.Continuation;
 31 import jdk.internal.vm.ContinuationScope;
 32 
 33 import static java.lang.StackWalker.ExtendedOption.LOCALS_AND_OPERANDS;
 34 
 35 /**
 36  * <em>UNSUPPORTED</em> This interface is intended to be package-private
 37  * or move to an internal package.<p>
 38  *
 39  * {@code LiveStackFrame} represents a frame storing data and partial results.
 40  * Each frame has its own array of local variables (JVMS section 2.6.1),
 41  * its own operand stack (JVMS section 2.6.2) for a method invocation.
 42  *
 43  * @jvms 2.6 Frames
 44  */
 45 /* package-private */
 46 interface LiveStackFrame extends StackFrame {
 47     /**
 48      * Return the monitors held by this stack frame. This method returns
 49      * an empty array if no monitor is held by this stack frame.
 50      *
 51      * @return the monitors held by this stack frames
 52      */
 53     public Object[] getMonitors();
 54 
 55     /**
 56      * Gets the local variable array of this stack frame.
 57      *
 58      * <p>A single local variable can hold a value of type boolean, byte, char,
 59      * short, int, float, reference or returnAddress.  A pair of local variables
 60      * can hold a value of type long or double (JVMS section 2.6.1).  Primitive
 61      * locals are represented in the returned array as {@code PrimitiveSlot}s,
 62      * with longs and doubles occupying a pair of consecutive
 63      * {@code PrimitiveSlot}s.
 64      *
 65      * <p>The current VM implementation does not provide specific type
 66      * information for primitive locals.  This method simply returns the raw
 67      * contents of the VM's primitive locals on a best-effort basis, without
 68      * indicating a specific type.
 69      *
 70      * <p>The returned array may contain null entries for local variables that
 71      * are not live.
 72      *
 73      * @implNote
 74      * <p> The specific subclass of {@code PrimitiveSlot} will reflect the
 75      * underlying architecture, and will be either {@code PrimitiveSlot32} or
 76      * {@code PrimitiveSlot64}.
 77      *
 78      * <p>How a long or double value is stored in the pair of
 79      * {@code PrimitiveSlot}s can vary based on the underlying architecture and
 80      * VM implementation.  On 32-bit architectures, long/double values are split
 81      * between the two {@code PrimitiveSlot32}s.
 82      * On 64-bit architectures, the entire value may be stored in one of the
 83      * {@code PrimitiveSlot64}s, with the other {@code PrimitiveSlot64} being
 84      * unused.
 85      *
 86      * <p>The contents of the unused, high-order portion of a
 87      * {@code PrimitiveSlot64} (when storing a primitive other than a long or
 88      * double) is unspecified.  In particular, the unused bits are not
 89      * necessarily zeroed out.
 90      *
 91      * @return  the local variable array of this stack frame.
 92      */
 93     public Object[] getLocals();
 94 
 95     /**
 96      * Gets the operand stack of this stack frame.
 97      *
 98      * <p>
 99      * The 0-th element of the returned array represents the top of the operand stack.
100      * This method returns an empty array if the operand stack is empty.
101      *
102      * <p>Each entry on the operand stack can hold a value of any Java Virtual
103      * Machine Type.
104      * For a value of primitive type, the element in the returned array is
105      * a {@link PrimitiveSlot} object; otherwise, the element is the {@code Object}
106      * on the operand stack.
107      *
108      * @return the operand stack of this stack frame.
109      */
110     public Object[] getStack();
111 
112     /**
113      * <em>UNSUPPORTED</em> This interface is intended to be package-private
114      * or moved to an internal package.<p>
115      *
116      * Represents a local variable or an entry on the operand stack whose value is
117      * of primitive type.
118      */
119     public abstract class PrimitiveSlot {
120         /**
121          * Constructor.
122          */
123         PrimitiveSlot() {}
124 
125         /**
126          * Returns the size, in bytes, of the slot.
127          */
128         public abstract int size();
129 
130         /**
131          * Returns the int value if this primitive value is of size 4
132          * @return the int value if this primitive value is of size 4
133          *
134          * @throws UnsupportedOperationException if this primitive value is not
135          * of size 4.
136          */
137         public int intValue() {
138             throw new UnsupportedOperationException("this " + size() + "-byte primitive");
139         }
140 
141         /**
142          * Returns the long value if this primitive value is of size 8
143          * @return the long value if this primitive value is of size 8
144          *
145          * @throws UnsupportedOperationException if this primitive value is not
146          * of size 8.
147          */
148         public long longValue() {
149             throw new UnsupportedOperationException("this " + size() + "-byte primitive");
150         }
151     }
152 
153 
154     /**
155      * Gets {@code StackWalker} that can get locals and operands.
156      *
157      * @throws SecurityException if the security manager is present and
158      * denies access to {@code RuntimePermission("liveStackFrames")}
159      */
160     public static StackWalker getStackWalker() {
161         return getStackWalker(EnumSet.noneOf(StackWalker.Option.class));
162     }
163 
164     /**
165      * Gets a {@code StackWalker} instance with the given options specifying
166      * the stack frame information it can access, and which will traverse at most
167      * the given {@code maxDepth} number of stack frames.  If no option is
168      * specified, this {@code StackWalker} obtains the method name and
169      * the class name with all
170      * {@linkplain StackWalker.Option#SHOW_HIDDEN_FRAMES hidden frames} skipped.
171      * The returned {@code StackWalker} can get locals and operands.
172      *
173      * @param options stack walk {@link StackWalker.Option options}
174      *
175      * @throws SecurityException if the security manager is present and
176      * it denies access to {@code RuntimePermission("liveStackFrames")};
177      * or if the given {@code options} contains
178      * {@link StackWalker.Option#RETAIN_CLASS_REFERENCE Option.RETAIN_CLASS_REFERENCE}
179      * and it denies access to {@code RuntimePermission("getStackWalkerWithClassReference")}.
180      */
181     public static StackWalker getStackWalker(Set<StackWalker.Option> options) {
182         return getStackWalker(options, null);
183     }
184 
185     /**
186      * Gets a {@code StackWalker} instance with the given options specifying
187      * the stack frame information it can access, and which will traverse at most
188      * the given {@code maxDepth} number of stack frames.  If no option is
189      * specified, this {@code StackWalker} obtains the method name and
190      * the class name with all
191      * {@linkplain StackWalker.Option#SHOW_HIDDEN_FRAMES hidden frames} skipped.
192      * The returned {@code StackWalker} can get locals and operands.
193      *
194      * @param options stack walk {@link StackWalker.Option options}
195      * @param contScope the continuation scope up to which (inclusive) to walk the stack
196      *
197      * @throws SecurityException if the security manager is present and
198      * it denies access to {@code RuntimePermission("liveStackFrames")}; or
199      * or if the given {@code options} contains
200      * {@link StackWalker.Option#RETAIN_CLASS_REFERENCE Option.RETAIN_CLASS_REFERENCE}
201      * and it denies access to {@code RuntimePermission("getStackWalkerWithClassReference")}.
202      */
203     public static StackWalker getStackWalker(Set<StackWalker.Option> options, ContinuationScope contScope) {
204         @SuppressWarnings("removal")
205         SecurityManager sm = System.getSecurityManager();
206         if (sm != null) {
207             sm.checkPermission(new RuntimePermission("liveStackFrames"));
208         }
209         return StackWalker.newInstance(options, LOCALS_AND_OPERANDS, contScope);
210     }
211 
212     /**
213      * Gets {@code StackWalker} of the given unmounted continuation, that can get locals and operands.
214      *
215      * @param continuation the continuation to walk
216      * 
217      * @throws SecurityException if the security manager is present and
218      * denies access to {@code RuntimePermission("liveStackFrames")}
219      */
220     public static StackWalker getStackWalker(Continuation continuation) {
221         return getStackWalker(EnumSet.noneOf(StackWalker.Option.class), continuation.getScope(), continuation);
222     }
223 
224     /**
225      * Gets a {@code StackWalker} instance with the given options specifying
226      * the stack frame information it can access, and which will traverse at most
227      * the given {@code maxDepth} number of stack frames.  If no option is
228      * specified, this {@code StackWalker} obtains the method name and
229      * the class name with all
230      * {@linkplain StackWalker.Option#SHOW_HIDDEN_FRAMES hidden frames} skipped.
231      * The returned {@code StackWalker} can get locals and operands.
232      *
233      * @param options stack walk {@link StackWalker.Option options}
234      * @param continuation the continuation to walk
235      *
236      * @throws SecurityException if the security manager is present and
237      * it denies access to {@code RuntimePermission("liveStackFrames")}; or
238      * or if the given {@code options} contains
239      * {@link StackWalker.Option#RETAIN_CLASS_REFERENCE Option.RETAIN_CLASS_REFERENCE}
240      * and it denies access to {@code RuntimePermission("getStackWalkerWithClassReference")}.
241      */
242     public static StackWalker getStackWalker(Set<StackWalker.Option> options,
243                                              ContinuationScope contScope,
244                                              Continuation continuation) {
245         @SuppressWarnings("removal")
246         SecurityManager sm = System.getSecurityManager();
247         if (sm != null) {
248             sm.checkPermission(new RuntimePermission("liveStackFrames"));
249         }
250         return StackWalker.newInstance(options, LOCALS_AND_OPERANDS, contScope, continuation);
251     }
252 }