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