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