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 }