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      */
 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         @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 }