1 /*
  2  * Copyright (c) 2022, 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 /**
 27  * <h2>Classfile parsing, generation, and transformation</h2>
 28  * The {@code jdk.internal.classfile} package contains classes for reading, writing, and
 29  * modifying Java class files, as specified in Chapter 4 of the <a
 30  * href="https://docs.oracle.com/javase/specs/jvms/se17/html/index.html">Java
 31  * Java Virtual Machine Specification</a>.
 32  *
 33  * <h2>Reading classfiles</h2>
 34  * The main class for reading classfiles is {@link jdk.internal.classfile.ClassModel}; we
 35  * convert bytes into a {@link jdk.internal.classfile.ClassModel} with {@link
 36  * jdk.internal.classfile.Classfile#parse(byte[])}:
 37  * <p>
 38  * {@snippet lang=java :
 39  * ClassModel cm = Classfile.of().parse(bytes);
 40  * }
 41  * <p>
 42  * There are several additional overloads of {@code parse} that let you specify
 43  * various processing options.
 44  * <p>
 45  * A {@link jdk.internal.classfile.ClassModel} is an immutable description of a class
 46  * file.  It provides accessor methods to get at class metadata (e.g., {@link
 47  * jdk.internal.classfile.ClassModel#thisClass()}, {@link jdk.internal.classfile.ClassModel#flags()}),
 48  * as well as subordinate classfile entities ({@link jdk.internal.classfile.ClassModel#fields()},
 49  * {@link jdk.internal.classfile.ClassModel#attributes()}). A {@link
 50  * jdk.internal.classfile.ClassModel} is inflated lazily; most parts of the classfile are
 51  * not parsed until they are actually needed.
 52  * <p>
 53  * We can enumerate the names of the fields and methods in a class by:
 54  * {@snippet lang="java" class="PackageSnippets" region="enumerateFieldsMethods1"}
 55  * <p>
 56  * When we enumerate the methods, we get a {@link jdk.internal.classfile.MethodModel} for each method; like a
 57  * {@code ClassModel}, it gives us access to method metadata and
 58  * the ability to descend into subordinate entities such as the bytecodes of the
 59  * method body. In this way, a {@code ClassModel} is the root of a
 60  * tree, with children for fields, methods, and attributes, and {@code MethodModel} in
 61  * turn has its own children (attributes, {@code CodeModel}, etc.)
 62  * <p>
 63  * Methods like {@link jdk.internal.classfile.ClassModel#methods} allows us to traverse the class structure
 64  * explicitly, going straight to the parts we are interested in.  This is useful
 65  * for certain kinds of analysis, but if we wanted to process the whole
 66  * classfile, we may want something more organized.  A {@link
 67  * jdk.internal.classfile.ClassModel} also provides us with a view of the classfile as a
 68  * series of class <em>elements</em>, which may include methods, fields, attributes,
 69  * and more, and which can be distinguished with pattern matching.  We could
 70  * rewrite the above example as:
 71  * {@snippet lang="java" class="PackageSnippets" region="enumerateFieldsMethods2"}
 72  * <p>
 73  * The models returned as elements from traversing {@code ClassModel} can in
 74  * turn be sources of elements.  If we wanted to
 75  * traverse a classfile and enumerate all the classes for which we access fields
 76  * and methods, we can pick out the class elements that describe methods, then
 77  * in turn pick out the method elements that describe the code attribute, and
 78  * finally pick out the code elements that describe field access and invocation
 79  * instructions:
 80  * {@snippet lang="java" class="PackageSnippets" region="gatherDependencies1"}
 81  * <p>
 82  * This same query could alternately be processed as a stream pipeline over
 83  * class elements:
 84  * {@snippet lang="java" class="PackageSnippets" region="gatherDependencies2"}
 85  *
 86  * <h3>Models and elements</h3>
 87  * The view of classfiles presented by this API is framed in terms of
 88  * <em>models</em> and <em>elements</em>.  Models represent complex structures,
 89  * such as classes, methods, fields, record elements, or the code body of a
 90  * method.  Models can be explored either via random-access navigation (such as
 91  * the {@link jdk.internal.classfile.ClassModel#methods()} accessor) or as a linear
 92  * sequence of <em>elements</em>. (Elements can in turn also be models; a {@link
 93  * jdk.internal.classfile.FieldModel} is also an element of a class.) For each model type
 94  * (e.g., {@link jdk.internal.classfile.MethodModel}), there is a corresponding element
 95  * type ({@link jdk.internal.classfile.MethodElement}).  Models and elements are immutable
 96  * and are inflated lazily so creating a model does not necessarily require
 97  * processing its entire content.
 98  *
 99  * <h3>The constant pool</h3>
100  * Much of the interesting content in a classfile lives in the <em>constant
101  * pool</em>. {@link jdk.internal.classfile.ClassModel} provides a lazily-inflated,
102  * read-only view of the constant pool via {@link jdk.internal.classfile.ClassModel#constantPool()}.
103  * Descriptions of classfile content is often exposed in the form of various
104  * subtypes of {@link jdk.internal.classfile.constantpool.PoolEntry}, such as {@link
105  * jdk.internal.classfile.constantpool.ClassEntry} or {@link jdk.internal.classfile.constantpool.Utf8Entry}.
106  * <p>
107  * Constant pool entries are also exposed through models and elements; in the
108  * above traversal example, the {@link jdk.internal.classfile.instruction.InvokeInstruction}
109  * element exposed a method for {@code owner} that corresponds to a {@code
110  * Constant_Class_info} entry in the constant pool.
111  *
112  * <h3>Attributes</h3>
113  * Much of the contents of a classfile is stored in attributes; attributes are
114  * found on classes, methods, fields, record components, and on the {@code Code}
115  * attribute.  Most attributes are surfaced as elements; for example, {@link
116  * jdk.internal.classfile.attribute.SignatureAttribute} is a {@link
117  * jdk.internal.classfile.ClassElement}, {@link jdk.internal.classfile.MethodElement}, and {@link
118  * jdk.internal.classfile.FieldElement} since it can appear in all of those places, and is
119  * included when iterating the elements of the corresponding model.
120  * <p>
121  * Some attributes are not surfaced as elements; these are attributes that are
122  * tightly coupled to -- and logically part of -- other parts of the class file.
123  * These include the {@code BootstrapMethods}, {@code LineNumberTable}, {@code
124  * StackMapTable}, {@code LocalVariableTable}, and {@code
125  * LocalVariableTypeTable} attributes.  These are processed by the library and
126  * treated as part of the structure they are coupled to (the entries of the
127  * {@code BootstrapMethods} attribute are treated as part of the constant pool;
128  * line numbers and local variable metadata are modeled as elements of {@link
129  * jdk.internal.classfile.CodeModel}.)
130  * <p>
131  * The {@code Code} attribute, in addition to being modeled as a {@link
132  * jdk.internal.classfile.MethodElement}, is also a model in its own right ({@link
133  * jdk.internal.classfile.CodeModel}) due to its complex structure.
134  * <p>
135  * Each standard attribute has an interface (in {@code jdk.internal.classfile.attribute})
136  * which exposes the contents of the attribute and provides factories to
137  * construct the attribute.  For example, the {@code Signature} attribute is
138  * defined by the {@link jdk.internal.classfile.attribute.SignatureAttribute} class, and
139  * provides accessors for {@link jdk.internal.classfile.attribute.SignatureAttribute#signature()}
140  * as well as factories taking {@link jdk.internal.classfile.constantpool.Utf8Entry} or
141  * {@link java.lang.String}.
142  *
143  * <h3>Custom attributes</h3>
144  * Attributes are converted between their classfile form and their corresponding
145  * object form via an {@link jdk.internal.classfile.AttributeMapper}.  An {@code
146  * AttributeMapper} provides the
147  * {@link jdk.internal.classfile.AttributeMapper#readAttribute(AttributedElement,
148  * ClassReader, int)} method for mapping from the classfile format
149  * to an attribute instance, and the
150  * {@link jdk.internal.classfile.AttributeMapper#writeAttribute(jdk.internal.classfile.BufWriter,
151  * java.lang.Object)} method for mapping back to the classfile format.  It also
152  * contains metadata including the attribute name, the set of classfile entities
153  * where the attribute is applicable, and whether multiple attributes of the
154  * same kind are allowed on a single entity.
155  * <p>
156  * There are built-in attribute mappers (in {@link jdk.internal.classfile.Attributes}) for
157  * each of the attribute types defined in section {@jvms 4.7} of <cite>The Java Virtual
158  * Machine Specification</cite>, as well as several common nonstandard attributes used by the
159  * JDK such as {@code CharacterRangeTable}.
160  * <p>
161  * Unrecognized attributes are delivered as elements of type {@link
162  * jdk.internal.classfile.attribute.UnknownAttribute}, which provide access only to the
163  * {@code byte[]} contents of the attribute.
164  * <p>
165  * For nonstandard attributes, user-provided attribute mappers can be specified
166  * through the use of the {@link
167  * jdk.internal.classfile.Classfile.AttributeMapperOption#of(java.util.function.Function)}}
168  * classfile option.  Implementations of custom attributes should extend {@link
169  * jdk.internal.classfile.CustomAttribute}.
170  *
171  * <h3>Options</h3>
172  * <p>
173  * {@link jdk.internal.classfile.Classfile#of(jdk.internal.classfile.Classfile.Option[])}
174  * accepts a list of options.  {@link jdk.internal.classfile.Classfile.Option} is a base interface
175  * for some statically enumerated options, as well as factories for more complex options,
176  * including:
177  * <ul>
178  *   <li>{@link jdk.internal.classfile.Classfile.StackMapsOption}
179  * -- generate stackmaps (default is {@code STACK_MAPS_WHEN_REQUIRED})</li>
180  *   <li>{@link jdk.internal.classfile.Classfile.DebugElementsOption}
181  * -- processing of debug information, such as local variable metadata (default is {@code PASS_DEBUG}) </li>
182  *   <li>{@link jdk.internal.classfile.Classfile.LineNumbersOption}
183  * -- processing of line numbers (default is {@code PASS_LINE_NUMBERS}) </li>
184  *   <li>{@link jdk.internal.classfile.Classfile.UnknownAttributesOption}
185  * -- processing of unrecognized attributes (default is {@code PASS_UNKNOWN_ATTRIBUTES})</li>
186  *   <li>{@link jdk.internal.classfile.Classfile.ConstantPoolSharingOption}}
187  * -- share constant pool when transforming (default is {@code SHARED_POOL})</li>
188  *   <li>{@link jdk.internal.classfile.Classfile.ClassHierarchyResolverOption#of(jdk.internal.classfile.ClassHierarchyResolver)}
189  * -- specify a custom class hierarchy resolver used by stack map generation</li>
190  *   <li>{@link jdk.internal.classfile.Classfile.AttributeMapperOption#of(java.util.function.Function)}
191  * -- specify format of custom attributes</li>
192  * </ul>
193  * <p>
194  * Most options allow you to request that certain parts of the classfile be
195  * skipped during traversal, such as debug information or unrecognized
196  * attributes.  Some options allow you to suppress generation of portions of the
197  * classfile, such as stack maps.  Many of these options are to access
198  * performance tradeoffs; processing debug information and line numbers has a
199  * cost (both in writing and reading.)  If you don't need this information, you
200  * can suppress it with options to gain some performance.
201  *
202  * <h2>Writing classfiles</h2>
203  * Classfile generation is accomplished through <em>builders</em>.  For each
204  * entity type that has a model, there is also a corresponding builder type;
205  * classes are built through {@link jdk.internal.classfile.ClassBuilder}, methods through
206  * {@link jdk.internal.classfile.MethodBuilder}, etc.
207  * <p>
208  * Rather than creating builders directly, builders are provided as an argument
209  * to a user-provided lambda.  To generate the familiar "hello world" program,
210  * we ask for a class builder, and use that class builder to create method
211  * builders for the constructor and {@code main} method, and in turn use the
212  * method builders to create a {@code Code} attribute and use the code builders
213  * to generate the instructions:
214  * {@snippet lang="java" class="PackageSnippets" region="helloWorld1"}
215  * <p>
216  * The convenience methods {@code ClassBuilder.buildMethodBody} allows us to ask
217  * {@link ClassBuilder} to create code builders to build method bodies directly,
218  * skipping the method builder custom lambda:
219  * {@snippet lang="java" class="PackageSnippets" region="helloWorld2"}
220  * <p>
221  * Builders often support multiple ways of expressing the same entity at
222  * different levels of abstraction.  For example, the {@code invokevirtual}
223  * instruction invoking {@code println} could have been generated with {@link
224  * jdk.internal.classfile.CodeBuilder#invokevirtual(java.lang.constant.ClassDesc,
225  * java.lang.String, java.lang.constant.MethodTypeDesc) CodeBuilder.invokevirtual}, {@link
226  * jdk.internal.classfile.CodeBuilder#invokeInstruction(jdk.internal.classfile.Opcode,
227  * java.lang.constant.ClassDesc, java.lang.String, java.lang.constant.MethodTypeDesc,
228  * boolean) CodeBuilder.invokeInstruction}, or {@link
229  * jdk.internal.classfile.CodeBuilder#with(jdk.internal.classfile.ClassfileElement)
230  * CodeBuilder.with}.
231  * <p>
232  * The convenience method {@code CodeBuilder.invokevirtual} behaves as if it calls
233  * the convenience method {@code CodeBuilder.invokeInstruction}, which in turn behaves
234  * as if it calls method {@code CodeBuilder.with}. This composing of method calls on the
235  * builder enables the composing of transforms (as described later).
236  *
237  * <h3>Symbolic information</h3>
238  * To describe symbolic information for classes and types, the API uses the
239  * nominal descriptor abstractions from {@code java.lang.constant} such as {@link
240  * java.lang.constant.ClassDesc} and {@link java.lang.constant.MethodTypeDesc},
241  * which is less error-prone than using raw strings.
242  * <p>
243  * If a constant pool entry has a nominal representation then it provides a
244  * method returning the corresponding nominal descriptor type e.g.
245  * method {@link jdk.internal.classfile.constantpool.ClassEntry#asSymbol} returns
246  * {@code ClassDesc}.
247  * <p>
248  * Where appropriate builders provide two methods for building an element with
249  * symbolic information, one accepting nominal descriptors, and the other
250  * accepting constant pool entries.
251  *
252  * <h2>Transforming classfiles</h2>
253  * Classfile Processing APIs are most frequently used to combine reading and
254  * writing into transformation, where a classfile is read, localized changes are
255  * made, but much of the classfile is passed through unchanged.  For each kind
256  * of builder, {@code XxxBuilder} has a method {@code with(XxxElement)} so that
257  * elements that we wish to pass through unchanged can be handed directly back
258  * to the builder.
259  * <p>
260  * If we wanted to strip out methods whose names starts with "debug", we could
261  * get an existing {@link jdk.internal.classfile.ClassModel}, build a new classfile that
262  * provides a {@link jdk.internal.classfile.ClassBuilder}, iterate the elements of the
263  * original {@link jdk.internal.classfile.ClassModel}, and pass through all of them to
264  * the builder except the methods we want to drop:
265  * {@snippet lang="java" class="PackageSnippets" region="stripDebugMethods1"}
266  * <p>
267  * This hands every class element, except for those corresponding to methods
268  * whose names start with {@code debug}, back to the builder.  Transformations
269  * can of course be more complicated, diving into method bodies and instructions
270  * and transforming those as well, but the same structure is repeated at every
271  * level, since every entity has corresponding model, builder, and element
272  * abstractions.
273  * <p>
274  * Transformation can be viewed as a "flatMap" operation on the sequence of
275  * elements; for every element, we could pass it through unchanged, drop it, or
276  * replace it with one or more elements.  Because transformation is such a
277  * common operation on classfiles, each model type has a corresponding {@code
278  * XxxTransform} type (which describes a transform on a sequence of {@code
279  * XxxElement}) and each builder type has {@code transformYyy} methods for transforming
280  * its child models.  A transform is simply a functional interface that takes a
281  * builder and an element, and an implementation "flatMap"s elements
282  * into the builder.  We could express the above as:
283  * {@snippet lang="java" class="PackageSnippets" region="stripDebugMethods2"}
284  * <p>
285  * {@code ClassTransform.dropping} convenience method allow us to simplify the same
286  * transformation construction and express the above as:
287  * {@snippet lang="java" class="PackageSnippets" region="stripDebugMethods3"}
288  *
289  * <h3>Lifting transforms</h3>
290  * While the example using transformations are only slightly shorter, the
291  * advantage of expressing transformation in this way is that the transform
292  * operations can be more easily combined.  Suppose we want to redirect
293  * invocations of static methods on {@code Foo} to the corresponding method on
294  * {@code Bar} instead.  We could express this as a transformation on {@link
295  * jdk.internal.classfile.CodeElement}:
296  * {@snippet lang="java" class="PackageSnippets" region="fooToBarTransform"}
297  * <p>
298  * We can then <em>lift</em> this transformation on code elements into a
299  * transformation on method elements.  This intercepts method elements that
300  * correspond to a {@code Code} attribute, dives into its code elements, and
301  * applies the code transform to them, and passes other method elements through
302  * unchanged:
303  * {@snippet lang=java :
304  * MethodTransform mt = MethodTransform.transformingCode(fooToBar);
305  * }
306  * <p>
307  * and further lift the transform on method elements into one on class
308  * elements:
309  * {@snippet lang=java :
310  * ClassTransform ct = ClassTransform.transformingMethods(mt);
311  * }
312  * <p>
313  * or lift the code transform into the class transform directly:
314  * {@snippet lang=java :
315  * ClassTransform ct = ClassTransform.transformingMethodBodiess(fooToBar);
316  * }
317  * <p>
318  * and then transform the classfile:
319  * {@snippet lang=java :
320  * var cc = Classfile.of();
321  * byte[] newBytes = cc.transform(cc.parse(bytes), ct);
322  * }
323  * <p>
324  * This is much more concise (and less error-prone) than the equivalent
325  * expressed by traversing the classfile structure directly:
326  * {@snippet lang="java" class="PackageSnippets" region="fooToBarUnrolled"}
327  *
328  * <h3>Composing transforms</h3>
329  * Transforms on the same type of element can be composed in sequence, where the
330  * output of the first is fed to the input of the second.  Suppose we want to
331  * instrument all method calls, where we print the name of a method before
332  * calling it:
333  * {@snippet lang="java" class="PackageSnippets" region="instrumentCallsTransform"}
334  * <p>
335  * Then we can compose {@code fooToBar} and {@code instrumentCalls} with {@link
336  * jdk.internal.classfile.CodeTransform#andThen(jdk.internal.classfile.CodeTransform)}:
337  * <p>
338  * {@snippet lang=java :
339  * var cc = Classfile.of();
340  * byte[] newBytes = cc.transform(cc.parse(bytes),
341  *                                ClassTransform.transformingMethods(
342  *                                    MethodTransform.transformingCode(
343  *                                        fooToBar.andThen(instrumentCalls))));
344  * }
345  *
346  * Transform {@code instrumentCalls} will receive all code elements produced by
347  * transform {@code forToBar}, either those code elements from the original classfile
348  * or replacements (replacing static invocations to {@code Foo} with those to {@code Bar}).
349  *
350  * <h3>Constant pool sharing</h3>
351  * Transformation doesn't merely handle the logistics of reading, transforming
352  * elements, and writing.  Most of the time when we are transforming a
353  * classfile, we are making relatively minor changes.  To optimize such cases,
354  * transformation seeds the new classfile with a copy of the constant pool from
355  * the original classfile; this enables significant optimizations (methods and
356  * attributes that are not transformed can be processed by bulk-copying their
357  * bytes, rather than parsing them and regenerating their contents.)  If
358  * constant pool sharing is not desired it can be suppressed
359  * with the {@link jdk.internal.classfile.Classfile.ConstantPoolSharingOption} option.
360  * Such suppression may be beneficial when transformation removes many elements,
361  * resulting in many unreferenced constant pool entries.
362  *
363  * <h2>API conventions</h2>
364  * <p>
365  * The API is largely derived from a <a href="#data_model"><em>data model</em></a>
366  * for the classfile format, which defines each element kind (which includes models and
367  * attributes) and its properties.  For each element kind, there is a
368  * corresponding interface to describe that element, and factory methods to
369  * create that element.  Some element kinds also have convenience methods on the
370  * corresponding builder (e.g., {@link
371  * jdk.internal.classfile.CodeBuilder#invokevirtual(java.lang.constant.ClassDesc,
372  * java.lang.String, java.lang.constant.MethodTypeDesc)}).
373  * <p>
374  * Most symbolic information in elements is represented by constant pool entries
375  * (for example, the owner of a field is represented by a {@link
376  * jdk.internal.classfile.constantpool.ClassEntry}.) Factories and builders also
377  * accept nominal descriptors from {@code java.lang.constant} (e.g., {@link
378  * java.lang.constant.ClassDesc}.)
379  *
380  * <h2><a id="data_model"></a>Data model</h2>
381  * We define each kind of element by its name, an optional arity indicator (zero
382  * or more, zero or one, exactly one), and a list of components.  The elements
383  * of a class are fields, methods, and the attributes that can appear on
384  * classes:
385  * <p>
386  * {@snippet lang="text" :
387  * ClassElement =
388  *     FieldModel*(UtfEntry name, Utf8Entry descriptor)
389  *     | MethodModel*(UtfEntry name, Utf8Entry descriptor)
390  *     | ModuleAttribute?(int flags, ModuleEntry moduleName, UtfEntry moduleVersion,
391  *                        List<ModuleRequireInfo> requires, List<ModuleOpenInfo> opens,
392  *                        List<ModuleExportInfo> exports, List<ModuleProvidesInfo> provides,
393  *                        List<ClassEntry> uses)
394  *     | ModulePackagesAttribute?(List<PackageEntry> packages)
395  *     | ModuleTargetAttribute?(Utf8Entry targetPlatform)
396  *     | ModuleHashesAttribute?(Utf8Entry algorithm, List<HashInfo> hashes)
397  *     | ModuleResolutionAttribute?(int resolutionFlags)
398  *     | SourceFileAttribute?(Utf8Entry sourceFile)
399  *     | SourceDebugExtensionsAttribute?(byte[] contents)
400  *     | CompilationIDAttribute?(Utf8Entry compilationId)
401  *     | SourceIDAttribute?(Utf8Entry sourceId)
402  *     | NestHostAttribute?(ClassEntry nestHost)
403  *     | NestMembersAttribute?(List<ClassEntry> nestMembers)
404  *     | RecordAttribute?(List<RecordComponent> components)
405  *     | EnclosingMethodAttribute?(ClassEntry className, NameAndTypeEntry method)
406  *     | InnerClassesAttribute?(List<InnerClassInfo> classes)
407  *     | PermittedSubclassesAttribute?(List<ClassEntry> permittedSubclasses)
408  *     | PreloadAttribute?(List<ClassEntry> preloads)
409  *     | DeclarationElement*
410  * }
411  *<p>
412  * where {@code DeclarationElement} are the elements that are common to all declarations
413  * (classes,  methods, fields) and so are factored out:
414  *
415  * {@snippet lang="text" :
416  * DeclarationElement =
417  *     SignatureAttribute?(Utf8Entry signature)
418  *     | SyntheticAttribute?()
419  *     | DeprecatedAttribute?()
420  *     | RuntimeInvisibleAnnotationsAttribute?(List<Annotation> annotations)
421  *     | RuntimeVisibleAnnotationsAttribute?(List<Annotation> annotations)
422  *     | CustomAttribute*
423  *     | UnknownAttribute*
424  * }
425  *
426  * Fields and methods are models with their own elements.  The elements of fields
427  * and methods are fairly simple; most of the complexity of methods lives in the
428  * {@link jdk.internal.classfile.CodeModel} (which models the {@code Code} attribute
429  * along with the code-related attributes: stack map table, local variable table,
430  * line number table, etc.)
431  *
432  * {@snippet lang="text" :
433  * FieldElement =
434  *     DeclarationElement
435  *     | ConstantValueAttribute?(ConstantValueEntry constant)
436  *
437  * MethodElement =
438  *     DeclarationElement
439  *     | CodeModel?()
440  *     | AnnotationDefaultAttribute?(ElementValue defaultValue)
441  *     | MethodParametersAttribute?(List<MethodParameterInfo> parameters)
442  *     | ExceptionsAttribute?(List<ClassEntry> exceptions)
443  * }
444  *
445  * {@link jdk.internal.classfile.CodeModel} is unique in that its elements are <em>ordered</em>.
446  * Elements of {@code Code} include ordinary bytecodes, as well as a number of pseudo-instructions
447  * representing branch targets, line number metadata, local variable metadata, and
448  * catch blocks.
449  *
450  * {@snippet lang="text" :
451  * CodeElement = Instruction | PseudoInstruction
452  *
453  * Instruction =
454  *     LoadInstruction(TypeKind type, int slot)
455  *     | StoreInstruction(TypeKind type, int slot)
456  *     | IncrementInstruction(int slot, int constant)
457  *     | BranchInstruction(Opcode opcode, Label target)
458  *     | LookupSwitchInstruction(Label defaultTarget, List<SwitchCase> cases)
459  *     | TableSwitchInstruction(Label defaultTarget, int low, int high,
460  *                              List<SwitchCase> cases)
461  *     | ReturnInstruction(TypeKind kind)
462  *     | ThrowInstruction()
463  *     | FieldInstruction(Opcode opcode, FieldRefEntry field)
464  *     | InvokeInstruction(Opcode opcode, MemberRefEntry method, boolean isInterface)
465  *     | InvokeDynamicInstruction(InvokeDynamicEntry invokedynamic)
466  *     | NewObjectInstruction(ClassEntry className)
467  *     | NewReferenceArrayInstruction(ClassEntry componentType)
468  *     | NewPrimitiveArrayInstruction(TypeKind typeKind)
469  *     | NewMultiArrayInstruction(ClassEntry componentType, int dims)
470  *     | ArrayLoadInstruction(Opcode opcode)
471  *     | ArrayStoreInstruction(Opcode opcode)
472  *     | TypeCheckInstruction(Opcode opcode, ClassEntry className)
473  *     | ConvertInstruction(TypeKind from, TypeKind to)
474  *     | OperatorInstruction(Opcode opcode)
475  *     | ConstantInstruction(ConstantDesc constant)
476  *     | StackInstruction(Opcode opcode)
477  *     | MonitorInstruction(Opcode opcode)
478  *     | NopInstruction()
479  *
480  * PseudoInstruction =
481  *     | LabelTarget(Label label)
482  *     | LineNumber(int line)
483  *     | ExceptionCatch(Label tryStart, Label tryEnd, Label handler, ClassEntry exception)
484  *     | LocalVariable(int slot, UtfEntry name, Utf8Entry type, Label startScope, Label endScope)
485  *     | LocalVariableType(int slot, Utf8Entry name, Utf8Entry type, Label startScope, Label endScope)
486  *     | CharacterRange(int rangeStart, int rangeEnd, int flags, Label startScope, Label endScope)
487  * }
488  */
489 package jdk.internal.classfile;