1 /*
  2  * Copyright (c) 2023, 2025, 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 
 26 package java.lang.classfile.attribute;
 27 
 28 import java.lang.classfile.ClassFile;
 29 import java.lang.classfile.Label;
 30 import java.lang.classfile.Opcode;
 31 import java.lang.classfile.constantpool.ClassEntry;
 32 import java.lang.classfile.instruction.BranchInstruction;
 33 import java.lang.constant.ClassDesc;
 34 import java.util.List;
 35 
 36 import jdk.internal.classfile.impl.StackMapDecoder;
 37 import jdk.internal.classfile.impl.StackMapGenerator;
 38 import jdk.internal.classfile.impl.TemporaryConstantPool;
 39 
 40 /**
 41  * Models a stack map frame in a {@link StackMapTableAttribute StackMapTable}
 42  * attribute (JVMS {@jvms 4.7.4}).  A stack map frame must appear at the
 43  * beginning of each basic block in a method (JVMS {@jvms 4.10.1}).
 44  *
 45  * @apiNote
 46  * In general, a stack map frame should be defined for each target of a
 47  * {@link BranchInstruction}, or unreachable code right after an unconditional
 48  * branch instruction like {@link Opcode#GOTO goto}.  The automatic stack map
 49  * generation cannot handle unreachable code right after an unconditional jump;
 50  * The {@link ClassFile.DeadCodeOption} allows substituting such code, or
 51  * advanced users can provide their own stack maps for dead code.
 52  *
 53  * @see StackMapTableAttribute#entries()
 54  * @jvms 4.7.4 The {@code StackMapTable} Attribute
 55  * @jvms 4.10.1 Verification by Type Checking
 56  * @since 24
 57  */
 58 public sealed interface StackMapFrameInfo
 59             permits StackMapDecoder.StackMapFrameImpl {
 60 
 61     /**
 62      * {@return the raw {@code u1 frame_type}}
 63      */
 64     int frameType();
 65 
 66     /**
 67      * {@return the frame target label}
 68      */
 69     Label target();
 70 
 71     /**
 72      * {@return the expanded local variable types}
 73      */
 74     List<VerificationTypeInfo> locals();
 75 
 76     /**
 77      * {@return the expanded operand stack types}
 78      */
 79     List<VerificationTypeInfo> stack();
 80 
 81     /**
 82      * {@return a new stack map frame}
 83      *
 84      * @param target the location of the frame
 85      * @param locals the complete list of frame locals
 86      * @param stack the complete frame stack
 87      * @throws IllegalArgumentException if the number of types in {@code locals}
 88      *         or {@code stack} exceeds the limit of {@link java.lang.classfile##u2 u2}
 89      */
 90     public static StackMapFrameInfo of(Label target,
 91             List<VerificationTypeInfo> locals,
 92             List<VerificationTypeInfo> stack) {
 93         return new StackMapDecoder.StackMapFrameImpl(255, target, locals, stack);
 94     }
 95 
 96     /**
 97      * The type of a stack or local variable value.
 98      *
 99      * @see #locals()
100      * @see #stack()
101      * @jvms 4.7.4 The {@code StackMapTable} Attribute
102      * @since 24
103      */
104     sealed interface VerificationTypeInfo {
105 
106         /** The {@link #tag() tag} for verification type info {@link SimpleVerificationTypeInfo#TOP TOP}. */
107         int ITEM_TOP = StackMapGenerator.ITEM_TOP;
108 
109         /** The {@link #tag() tag} for verification type info {@link SimpleVerificationTypeInfo#INTEGER INTEGER}. */
110         int ITEM_INTEGER = StackMapGenerator.ITEM_INTEGER;
111 
112         /** The {@link #tag() tag} for verification type info {@link SimpleVerificationTypeInfo#FLOAT FLOAT}. */
113         int ITEM_FLOAT = StackMapGenerator.ITEM_FLOAT;
114 
115         /** The {@link #tag() tag} for verification type info {@link SimpleVerificationTypeInfo#DOUBLE DOUBLE}. */
116         int ITEM_DOUBLE = StackMapGenerator.ITEM_DOUBLE;
117 
118         /** The {@link #tag() tag} for verification type info {@link SimpleVerificationTypeInfo#LONG LONG}. */
119         int ITEM_LONG = StackMapGenerator.ITEM_LONG;
120 
121         /** The {@link #tag() tag} for verification type info {@link SimpleVerificationTypeInfo#NULL NULL}. */
122         int ITEM_NULL = StackMapGenerator.ITEM_NULL;
123 
124         /** The {@link #tag() tag} for verification type info {@link SimpleVerificationTypeInfo#UNINITIALIZED_THIS UNINITIALIZED_THIS}. */
125         int ITEM_UNINITIALIZED_THIS = StackMapGenerator.ITEM_UNINITIALIZED_THIS;
126 
127         /** The {@link #tag() tag} for verification type info {@link ObjectVerificationTypeInfo OBJECT}. */
128         int ITEM_OBJECT = StackMapGenerator.ITEM_OBJECT;
129 
130         /** The {@link #tag() tag} for verification type info {@link UninitializedVerificationTypeInfo UNINITIALIZED}. */
131         int ITEM_UNINITIALIZED = StackMapGenerator.ITEM_UNINITIALIZED;
132 
133         /**
134          * {@return the tag of the type info}
135          *
136          * @apiNote
137          * {@code ITEM_}-prefixed constants in this class, such as {@link #ITEM_TOP}, describe the
138          * possible return values of this method.
139          */
140         int tag();
141     }
142 
143     /**
144      * A simple stack value.
145      *
146      * @since 24
147      */
148     public enum SimpleVerificationTypeInfo implements VerificationTypeInfo {
149 
150         /** Verification type top. */
151         TOP(ITEM_TOP),
152 
153         /** Verification type int. */
154         INTEGER(ITEM_INTEGER),
155 
156         /** Verification type float. */
157         FLOAT(ITEM_FLOAT),
158 
159         /** Verification type double. */
160         DOUBLE(ITEM_DOUBLE),
161 
162         /** Verification type long. */
163         LONG(ITEM_LONG),
164 
165         /** Verification type null. */
166         NULL(ITEM_NULL),
167 
168         /** Verification type uninitializedThis. */
169         UNINITIALIZED_THIS(ITEM_UNINITIALIZED_THIS);
170 
171 
172         private final int tag;
173 
174         SimpleVerificationTypeInfo(int tag) {
175             this.tag = tag;
176         }
177 
178         @Override
179         public int tag() {
180             return tag;
181         }
182     }
183 
184     /**
185      * A stack value for an object type. Its {@link #tag() tag} is {@value #ITEM_OBJECT}.
186      *
187      * @jvms 4.7.4 The {@code StackMapTable} Attribute
188      * @since 24
189      */
190     sealed interface ObjectVerificationTypeInfo extends VerificationTypeInfo
191             permits StackMapDecoder.ObjectVerificationTypeInfoImpl {
192 
193         /**
194          * {@return a new object verification type info}
195          * @param className the class of the object
196          */
197         public static ObjectVerificationTypeInfo of(ClassEntry className) {
198             return new StackMapDecoder.ObjectVerificationTypeInfoImpl(className);
199         }
200 
201         /**
202          * {@return a new object verification type info}
203          * @param classDesc the class of the object
204          * @throws IllegalArgumentException if {@code classDesc} represents a primitive type
205          */
206         public static ObjectVerificationTypeInfo of(ClassDesc classDesc) {
207             return of(TemporaryConstantPool.INSTANCE.classEntry(classDesc));
208         }
209 
210         /**
211          * {@return the class of the object}
212          */
213         ClassEntry className();
214 
215         /**
216          * {@return the class of the object, as a symbolic descriptor}
217          */
218         default ClassDesc classSymbol() {
219             return className().asSymbol();
220         }
221     }
222 
223     /**
224      * An uninitialized stack value. Its {@link #tag() tag} is {@value #ITEM_UNINITIALIZED}.
225      *
226      * @jvms 4.7.4 The {@code StackMapTable} Attribute
227      * @since 24
228      */
229     sealed interface UninitializedVerificationTypeInfo extends VerificationTypeInfo
230             permits StackMapDecoder.UninitializedVerificationTypeInfoImpl {
231 
232         /**
233          * {@return the label immediately before the {@link Opcode#NEW new}
234          * instruction that creates this uninitialized object}
235          */
236         Label newTarget();
237 
238         /**
239          * {@return an uninitialized verification type info}
240          * @param newTarget the label immediately before the {@link Opcode#NEW new}
241          *                  instruction that creates this uninitialized object
242          */
243         public static UninitializedVerificationTypeInfo of(Label newTarget) {
244             return new StackMapDecoder.UninitializedVerificationTypeInfoImpl(newTarget);
245         }
246     }
247 }