This specification is not final and is subject to change. Use is subject to license terms.

Format Checking Cleanup

Changes to the Java® Virtual Machine Specification • Version 15-internal+0-adhoc.dlsmith.20200210

This document describes changes to the Java Virtual Machine Specification to clarify the constraints enforced by format checking as classes are loaded. In many cases, this leads to rephrasing assertions about class file structures to separate a format checking constraint from informative text about the purpose of the item.

Most of the changes in this document align the specification with the longstanding behavior of the reference implementation. However, three subtle changes to implementation behavior are proposed:

The resulting story for usage of the special method names <clinit> and <init> is as follows:

Changes are described with respect to existing sections of the JVM Specification. New text is indicated like this and deleted text is indicated like this. Explanation and discussion, as needed, is set aside in grey boxes.

Chapter 2: The Structure of the Java Virtual Machine

2.9 Special Methods

2.9.1 Instance Initialization Methods

A class has zero or more instance initialization methods, used to initialize instances of the class. each Each typically corresponding corresponds to a constructor written in the Java programming language.

If a class does not have an instance initialization method, its instances cannot be initialized or used.

A method is an instance initialization method if all of the following are true:

In a class, any non-void method named <init> is not an instance initialization method. In an interface, any method named <init> is not an instance initialization method. Such methods cannot be invoked by any Java Virtual Machine instruction (4.4.2, 4.9.2) and are rejected by format checking (4.6, 4.8).

An instance initialization method is declared with the special name <init>.

An instance initialization method may not be declared in an interface (4.6).

The declaration and use of an instance initialization method is constrained by the Java Virtual Machine. For the declaration, the method's access_flags item, descriptor, and code array are constrained (4.6, 4.9.2). For a use, an instance initialization method may be invoked only by the invokespecial instruction on an uninitialized class instance ([4.10.1.9]).

Because the name <init> is not a valid identifier in the Java programming language, it cannot be used directly in a program written in the Java programming language.

The previous presentation suggests that it's possible to use the name <init> for purposes other than declaring instance initialization methods. In older JVMs, this was the case, but since JDK 9 and JVMS 9, methods named <init> that are declared in interfaces or with a non-void return cause a ClassFormatError. It's confusing to present these malformed declarations as anything other than errors.

2.9.2 Class Initialization Methods

A class or interface has at most one class or interface initialization method and is initialized by the Java Virtual Machine invoking that method (5.5).

If a class or interface does not have a class or interface initialization method, initialization of the class or interface proceeds without executing any bytecode in the class or interface.

A method is a class or interface initialization method if all of the following are true:

Other methods named <clinit> in a class file are not class or interface initialization methods. They are never invoked by the Java Virtual Machine itself, cannot be invoked by any Java Virtual Machine instruction (4.9.1), and are rejected by format checking (4.6, 4.8).

An class or interface initialization method is declared with the special name <clinit>.

At the declaration of a class or interface initialization method, the access_flags item and descriptor are constrained by the Java Virtual Machine.

It is impossible to directly reference or invoke a class or interface initialization method (4.4.2).

Because the name <clinit> is not a valid identifier in the Java programming language, it cannot be used directly in a program written in the Java programming language.

Again, any corner-case support for methods named <clinit> that are not class or interface initialization methods was formally removed in JVMS 9. It's confusing to present these malformed declarations as anything other than errors.

2.11 Instruction Set Summary

2.11.8 Method Invocation and Return Instructions

The following five instructions invoke methods:

The method return instructions, which are distinguished by return type, are ireturn (used to return values of type boolean, byte, char, short, or int), lreturn, freturn, dreturn, and areturn. In addition, the return instruction is used to return from methods declared to be void, instance initialization methods, and class or interface initialization methods.

Initialization methods are "methods declared to be void".

Chapter 4: The class File Format

This chapter describes the class file format of the Java Virtual Machine. Each class file contains the definition of a single class, interface, or module. Although a class, interface, or module need not have an external representation literally contained in a file (for instance, because the class is generated by a class loader), we will colloquially refer to any valid representation of a class, interface, or module as being in the class file format.

A class file consists of a stream of 8-bit bytes. 16-bit and 32-bit quantities are constructed by reading in two and four consecutive 8-bit bytes, respectively. Multibyte data items are always stored in big-endian order, where the high bytes come first. This chapter defines the data types u1, u2, and u4 to represent an unsigned one-, two-, or four-byte quantity, respectively.

In the Java SE Platform API, the class file format is supported by interfaces java.io.DataInput and java.io.DataOutput and classes such as java.io.DataInputStream and java.io.DataOutputStream. For example, values of the types u1, u2, and u4 may be read by methods such as readUnsignedByte, readUnsignedShort, and readInt of the interface java.io.DataInput.

This chapter presents the class file format using pseudostructures written in a C-like structure notation. To avoid confusion with the fields of classes and class instances, etc., the contents of the structures describing the class file format are referred to as items. Successive items are stored in the class file sequentially, without padding or alignment.

Tables, consisting of zero or more variable-sized items, are used in several class file structures. Although we use C-like array syntax to refer to table items, the fact that tables are streams of varying-sized structures means that it is not possible to translate a table index directly to a byte offset into the table.

Where we refer to a data structure as an array, it consists of zero or more contiguous fixed-sized items and can be indexed like an array.

Reference to an ASCII character in this chapter should be interpreted to mean the Unicode code point corresponding to the ASCII character.

A valid class file is a stream of bytes that can be parsed according to the pseudostructure notation, has no extra bytes at the end, and conforms to all additional constraints described with the word "must" in sections 4.1, 4.4, 4.5, 4.6, and 4.7.

A constraint described with the word "should" communicates how certain items are intended to be used, but does not influence the validity of the class file.

4.1 The ClassFile Structure

A class file consists of a single ClassFile structure:

ClassFile {
    u4             magic;
    u2             minor_version;
    u2             major_version;
    u2             constant_pool_count;
    cp_info        constant_pool[constant_pool_count-1];
    u2             access_flags;
    u2             this_class;
    u2             super_class;
    u2             interfaces_count;
    u2             interfaces[interfaces_count];
    u2             fields_count;
    field_info     fields[fields_count];
    u2             methods_count;
    method_info    methods[methods_count];
    u2             attributes_count;
    attribute_info attributes[attributes_count];
}

The items in the ClassFile structure are as follows:

magic

The magic item supplies the magic number identifying the class file format; it has must have the value 0xCAFEBABE.

minor_version, major_version

The values of the minor_version and major_version items are the minor and major version numbers of this class file. Together, a major and a minor version number determine the version of the class file format. If a class file has major version number M and minor version number m, we denote the version of its class file format as M.m.

A Java Virtual Machine implementation which conforms to Java SE N must support exactly the major versions of the class file format specified for Java SE N in Table 4.1-A. The notation A .. B means major versions A through B inclusive. The column "Corresponding major version" denotes the major version introduced by each Java SE release, that is, the first release that could have accepted a class file containing that major_version item. For very early releases, the JDK version is shown instead of the Java SE release.

Table 4.1-A. class file format major versions

Java SE Corresponding major version Supported major versions
1.0.2 45 45
1.1 45 45
1.2 46 45 .. 46
1.3 47 45 .. 47
1.4 48 45 .. 48
5.0 49 45 .. 49
6 50 45 .. 50
7 51 45 .. 51
8 52 45 .. 52
9 53 45 .. 53
10 54 45 .. 54
11 55 45 .. 55
12 56 45 .. 56

For a class file whose major_version is 56 or above, the minor_version must be 0 or 65535.

For a class file whose major_version is between 45 and 55 inclusive, the minor_version may be any value.

A historical perspective on versions of the class file format is warranted. JDK 1.0.2 supported versions 45.0 through 45.3 inclusive. JDK 1.1 supported versions 45.0 through 45.65535 inclusive. When JDK 1.2 introduced support for major version 46, the only minor version supported under that major version was 0. Later JDKs continued the practice of introducing support for a new major version (47, 48, etc) but supporting only a minor version of 0 under the new major version. Finally, the introduction of preview features in Java SE 12 (see below) motivated a standard role for the minor version of the class file format, so JDK 12 supported minor versions of 0 and 65535 under major version 56. Subsequent JDKs introduce support for N.0 and N.65535 where N is the corresponding major version of the implemented Java SE Platform.

The Java SE Platform may define preview features. A Java Virtual Machine implementation which conforms to Java SE N (N 12) must support all the preview features of Java SE N, and none of the preview features of any other Java SE release. The implementation must by default disable the supported preview features, and must provide a way to enable all of them, and must not provide a way to enable only some of them.

A class file is said to depend on the preview features of Java SE N (N 12) if it has a major_version that corresponds to Java SE N (according to Table 4.1-A) and a minor_version of 65535.

A Java Virtual Machine implementation which conforms to Java SE N (N 12) must behave as follows:

  • A class file that depends on the preview features of Java SE N may be loaded only when the preview features of Java SE N are enabled.

  • A class file that depends on the preview features of another Java SE release must never be loaded.

  • A class file that does not depend on the preview features of any Java SE release may be loaded regardless of whether the preview features of Java SE N are enabled.

A class file must not depend on the preview features of Java SE N unless the Java Virtual Machine conforms to Java SE N and the preview features of Java SE N are enabled.

If the Java Virtual Machine conforms to some other version of Java SE, such as Java SE N+1, the class file is not valid.

A class file that does not depend on the preview features of any Java SE release may be valid regardless of whether the preview features of Java SE N are enabled.

This rule is rephrased to make it a clean "must" assertion and to avoid describing validity in terms of "may be loaded".

constant_pool_count

The value of the constant_pool_count item is equal to the number of entries in the constant_pool table plus one. A constant_pool index is considered valid if it is greater than zero and less than constant_pool_count, with the exception for constants of type long and double noted in 4.4.5.

constant_pool[]

The constant_pool is a table of structures (4.4) representing various string constants, class and interface names, field names, and other constants that are referred to within the ClassFile structure and its substructures. The format of each constant_pool table entry is indicated by its first "tag" byte.

The constant_pool table is indexed from 1 to constant_pool_count - 1.

access_flags

The value of the access_flags item is a mask of flags used to denote access permissions to and properties of this class or interface. The interpretation of each flag, when set, is specified in Table 4.1-B.

Table 4.1-B. Class access and property modifiers

Flag Name Value Interpretation
ACC_PUBLIC 0x0001 Declared public; may be accessed from outside its package.
ACC_FINAL 0x0010 Declared final; no subclasses allowed.
ACC_SUPER 0x0020 Treat superclass methods specially when invoked by the invokespecial instruction.
ACC_INTERFACE 0x0200 Is an interface, not a class.
ACC_ABSTRACT 0x0400 Declared abstract; must not be instantiated.
ACC_SYNTHETIC 0x1000 Declared synthetic; not present in the source code.
ACC_ANNOTATION 0x2000 Declared as an annotation type.
ACC_ENUM 0x4000 Declared as an enum type.
ACC_MODULE 0x8000 Is a module, not a class or interface.

The In a version 53.0 or later class file, the ACC_MODULE flag indicates that this class file defines a module, not a class or interface. If the ACC_MODULE flag is set in a version 53.0 or later class file, then special rules apply to the class file which are given at the end of this section. If the ACC_MODULE flag is not set, then the rules immediately below the current paragraph apply to the class file. no other flag in Table 4.1-B may be set.

The special rules have been dispersed to the appropriate parts of this section and 4.7, just as they are for interfaces.

Note that it's wrong to say that the version must be at least 53.0 if ACC_MODULE is set—rather, if the version is less than 53.0, the ACC_MODULE flag is ignored.

An interface is distinguished by the ACC_INTERFACE flag being set. If the ACC_INTERFACE flag is not set, this class file defines a class, not an interface or module.

The ACC_INTERFACE flag indicates that this class file defines an interface, not a module or class. If the ACC_INTERFACE flag is set, the ACC_ABSTRACT flag must also be set, and the ACC_FINAL, ACC_SUPER, ACC_ENUM, and ACC_MODULE flags set must not be set.

If the ACC_INTERFACE flag is not set and, in a version 53.0 or later class file, the ACC_MODULE flag is not set, this class file defines a class, not a module or interface. In this case, any of the other flags in Table 4.1-B may be set except ACC_ANNOTATION and ACC_MODULE. However, such a class file must not have both its ACC_FINAL and ACC_ABSTRACT flags set (JLS §8.1.1.2).

The ACC_FINAL flag indicates that this class cannot be extended by another class. If the ACC_FINAL flag is set, the ACC_ABSTRACT flag must not be set.

The ACC_SUPER flag indicates which of two alternative semantics is to be expressed by the invokespecial instruction (6.5.invokespecial) if it appears in this class or interface. Compilers to the instruction set of the Java Virtual Machine should set the ACC_SUPER flag. In Java SE 8 and above, the Java Virtual Machine considers the ACC_SUPER flag to be set in every class file, regardless of the actual value of the flag in the class file and the version of the class file.

The ACC_SUPER flag exists for backward compatibility with code compiled by older compilers for the Java programming language. Prior to JDK 1.0.2, the compiler generated access_flags in which the flag now representing ACC_SUPER had no assigned meaning, and Oracle's Java Virtual Machine implementation ignored the flag if it was set.

The ACC_SYNTHETIC flag indicates that this class or interface was generated by a compiler and does not appear in source code.

An annotation type (JLS §9.6) must have its ACC_ANNOTATION flag set. The ACC_ANNOTATION flag indicates that this interface is declared as an annotation type (JLS §9.6). If the ACC_ANNOTATION flag is set, the ACC_INTERFACE flag must also be set.

The ACC_ENUM flag indicates that this class or its superclass is declared as an enumerated type (JLS §8.9).

All bits of the access_flags item not assigned in Table 4.1-B are reserved for future use. They should be set to zero in generated class files and should be are ignored by Java Virtual Machine implementations.

this_class

The value of the this_class item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure (4.4.1) representing referencing a class or interface name.

For a module, the referenced name must be module-info.

For a class or interface, the this_class item represents the class or interface defined by this class file.

super_class

For a module or a class named java/lang/Object, the value of the super_class item must be 0.

For a class with any other name, the value of the super_class item either must be zero or must be a valid index into the constant_pool table. If the value of the super_class item is nonzero, the The constant_pool entry at that index must be a CONSTANT_Class_info structure representing the direct superclass of the class defined by this class file referencing a class or interface name.

Neither the direct superclass nor any of its superclasses may have the ACC_FINAL flag set in the access_flags item of its ClassFile structure.

This constraint on the superclass declaration is not part of format checking.

If the value of the super_class item is zero, then this class file must represent the class Object, the only class or interface without a direct superclass.

For an interface, the value of the super_class item must always be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure representing the class Object referencing the name java/lang/Object.

The super_class item represents the direct superclass of the class or interface defined by this class file.

The class Object has no direct superclass. Interfaces effectively have Object as their direct superclass.

interfaces_count

The value of the interfaces_count item gives the number of direct superinterfaces of this class or interface type.

For a module, interfaces_count must be 0.

interfaces[]

Each value in the interfaces array must be a valid index into the constant_pool table. The constant_pool entry at each value of interfaces[*i*], where 0 i < interfaces_count, must be a CONSTANT_Class_info structure representing referencing a class or interface name.

The interfaces array represents an each interface that is a direct superinterface of this class or interface type, in the left-to-right order given in the source for the type class or interface.

fields_count

The value of the fields_count item gives the number of field_info structures in the fields table. The field_info structures represent all fields, both class variables and instance variables, declared by this class or interface type.

For a module, fields_count must be 0.

fields[]

Each value in the fields table must be a field_info structure (4.5) giving a complete description of a field in this class or interface. The fields table includes only those fields that are declared by this class or interface. It does not include items representing fields that are inherited from superclasses or superinterfaces.

methods_count

The value of the methods_count item gives the number of method_info structures in the methods table.

For a module, methods_count must be 0.

methods[]

Each value in the methods table must be a method_info structure (4.6) giving a complete description of a method in this class or interface. If neither of the ACC_NATIVE and ACC_ABSTRACT flags are set in the access_flags item of a method_info structure, the Java Virtual Machine instructions implementing the method are also supplied.

This statement is redundant—better to leave it to 4.6 to describe exactly what a method_info structure requires.

The method_info structures represent all methods declared by this class or interface type, including instance methods, class methods, instance initialization methods (2.9.1), and any class or interface initialization method (2.9.2). The methods table does not include items representing methods that are inherited from superclasses or superinterfaces.

attributes_count

The value of the attributes_count item gives the number of attributes in the attributes table of this class.

attributes[]

Each value of the attributes table must be an attribute_info structure (4.7).

The attributes defined by this specification as appearing in the attributes table of a ClassFile structure are listed in Table 4.7-C.

The rules concerning attributes defined to appear in the attributes table of a ClassFile structure are given in 4.7.

The rules concerning non-predefined nonstandard attributes in the attributes table of a ClassFile structure are given in 4.7.1.

If the ACC_MODULE flag is set in the access_flags item, then no other flag in the access_flags item may be set, and the following rules apply to the rest of the ClassFile structure:

4.2 Names

4.2.1 Binary Class and Interface Names

Class and interface names that appear in class file structures are always represented in a fully qualified form known as binary names (JLS §13.1). Such names are always represented as CONSTANT_Utf8_info structures (4.4.7) and thus may be drawn, where not further constrained, from the entire Unicode codespace. Class and interface names are referenced from those CONSTANT_NameAndType_info structures (4.4.6) which have such names as part of their descriptor (4.3), and from all CONSTANT_Class_info structures (4.4.1). They may also appear in CONSTANT_Utf8_info structures that encode descriptors (4.3).

Not every CONSTANT_Class_info structure mentions a class name. (Some represent array types.)

CONSTANT_NameAndType_info is one of many contexts from which a descriptor string may be referenced. It would probably be more distracting than helpful to enumerate all of those contexts here.

For historical reasons, the syntax of binary names that appear in class file structures differs from the syntax of binary names documented in JLS §13.1. In this internal form, the ASCII periods (.) that normally separate the identifiers which make up the binary name are replaced by ASCII forward slashes (/). The identifiers themselves must be unqualified names (4.2.2).

For example, the normal binary name of class Thread is java.lang.Thread. In the internal form used in descriptors in the class file format, a reference to the name of class Thread is implemented using a CONSTANT_Utf8_info structure representing the string java/lang/Thread.

4.2.2 Unqualified Names

Names of methods, fields, local variables, and formal parameters are stored as unqualified names. An unqualified name must contain at least one Unicode code point and must not contain any of the ASCII characters . ; [ / (that is, period or semicolon or left square bracket or forward slash).

Method names are further constrained so that, with the exception of the special method names <init> and <clinit> (2.9), they must not contain the ASCII characters < or > (that is, left angle bracket or right angle bracket).

Note that a field name or interface method name may be <init> or <clinit>, but no method invocation instruction may reference <clinit> and only the invokespecial instruction (6.5.invokespecial) may reference <init>.

This doesn't seem like the right place to start a discussion about the JVM's treatment of initialization methods.

4.2.3 Module and Package Names

Module names referenced from the Module attribute are stored in CONSTANT_Module_info structures in the constant pool (4.4.11). A CONSTANT_Module_info structure wraps a CONSTANT_Utf8_info structure that denotes the module name. Module names are not encoded in "internal form" like class and interface names, that is, the ASCII periods (.) that separate the identifiers in a module name are not replaced by ASCII forward slashes (/).

Module names may be drawn from the entire Unicode codespace, subject to the following constraints:

Package names referenced from the Module attribute are stored in CONSTANT_Package_info structures in the constant pool (4.4.12). A CONSTANT_Package_info structure wraps a CONSTANT_Utf8_info structure that represents a package name encoded in internal form.

4.3 Descriptors

A descriptor is a string representing the type of a field or method. Descriptors are represented in the class file format using modified UTF-8 strings (4.4.7) and thus may be drawn, where not further constrained, from the entire Unicode codespace.

4.3.1 Grammar Notation

Descriptors are specified using a grammar. The grammar is a set of productions that describe how sequences of characters can form syntactically correct descriptors of various kinds. Terminal symbols of the grammar are shown in fixed width font. Nonterminal symbols are shown in italic type. The definition of a nonterminal is introduced by the name of the nonterminal being defined, followed by a colon. One or more alternative definitions for the nonterminal then follow on succeeding lines.

The syntax {x} on the right-hand side of a production denotes zero or more occurrences of x.

The phrase (one of) on the right-hand side of a production signifies that each of the terminal symbols on the following line or lines is an alternative definition.

4.3.2 Field Descriptors

A field descriptor represents the type of a class, instance, or local variable.

FieldDescriptor:
FieldType
FieldType:
BaseType
ObjectType
ArrayType
BaseType:
(one of)
B C D F I J S Z
ObjectType:
L ClassName ;
ArrayType:
[ ComponentType
ComponentType:
FieldType

The characters of BaseType, the L and ; of ObjectType, and the [ of ArrayType are all ASCII characters.

ClassName represents a binary class or interface name encoded in internal form (4.2.1).

The interpretation of field descriptors as types is shown in Table 4.3-A.

A field descriptor representing an array type is valid only if it represents a type with 255 or fewer dimensions.

Table 4.3-A. Interpretation of field descriptors

FieldType term Type Interpretation
B byte signed byte
C char Unicode character code point in the Basic Multilingual Plane, encoded with UTF-16
D double double-precision floating-point value
F float single-precision floating-point value
I int integer
J long long integer
L ClassName ; reference an instance of class ClassName
S short signed short
Z boolean true or false
[ reference one array dimension

The field descriptor of an instance variable of type int is simply I.

The field descriptor of an instance variable of type Object is Ljava/lang/Object;. Note that the internal form of the binary name for class Object is used.

The field descriptor of an instance variable of the multidimensional array type double[][][] is [[[D.

4.3.3 Method Descriptors

A method descriptor contains zero or more parameter descriptors, representing the types of parameters that the method takes, and a return descriptor, representing the type of the value (if any) that the method returns.

MethodDescriptor:
( {ParameterDescriptor} ) ReturnDescriptor
ParameterDescriptor:
FieldType
ReturnDescriptor:
FieldType
VoidDescriptor
VoidDescriptor:
V

The character V indicates that the method returns no value (its result is void).

The method descriptor for the method:

Object m(int i, double d, Thread t) {...}

is:

(IDLjava/lang/Thread;)Ljava/lang/Object;

Note that the internal forms of the binary names of Thread and Object are used.

A method descriptor is valid only if it represents method parameters with a total length of 255 or less, where that length includes the contribution for this in the case of instance or interface method invocations. The total length is calculated by summing the contributions of the individual parameters, where a parameter of type long or double contributes two units to the length and a parameter of any other type contributes one unit.

A method descriptor is the same whether the method it describes is a class method or an instance method. Although an instance method is passed this, a reference to the object on which the method is being invoked, in addition to its intended arguments, that fact is not reflected in the method descriptor. The reference to this is passed implicitly by the Java Virtual Machine instructions which invoke instance methods (2.6.1, 4.11).

4.4 The Constant Pool

Java Virtual Machine instructions do not rely on the run-time layout of classes, interfaces, class instances, or arrays. Instead, instructions refer to symbolic information in the constant_pool table.

All constant_pool table entries have the following general format:

cp_info {
    u1 tag;
    u1 info[];
}

Each entry in the constant_pool table must begin with a 1-byte tag indicating the kind of constant denoted by the entry. There are 17 kinds of constant, listed in Table 4.4-A with their corresponding tags, and ordered by their section number in this chapter. Each tag byte must be followed by two or more bytes giving information about the specific constant. The format of the additional information depends on the tag byte, that is, the content of the info array varies with the value of tag.

Table 4.4-A. Constant pool tags (by section)

Constant Kind Tag Section
CONSTANT_Class 7 4.4.1
CONSTANT_Fieldref 9 4.4.2
CONSTANT_Methodref 10 4.4.2
CONSTANT_InterfaceMethodref 11 4.4.2
CONSTANT_String 8 4.4.3
CONSTANT_Integer 3 4.4.4
CONSTANT_Float 4 4.4.4
CONSTANT_Long 5 4.4.5
CONSTANT_Double 6 4.4.5
CONSTANT_NameAndType 12 4.4.6
CONSTANT_Utf8 1 4.4.7
CONSTANT_MethodHandle 15 4.4.8
CONSTANT_MethodType 16 4.4.9
CONSTANT_Dynamic 17 4.4.10
CONSTANT_InvokeDynamic 18 4.4.10
CONSTANT_Module 19 4.4.11
CONSTANT_Package 20 4.4.12

If a ClassFile structure (4.1) does not represent a module, the tags for CONSTANT_Module and CONSTANT_Package must not be used.

This rule has been moved from 4.4.11 and 4.4.12.

In a class file whose version number is v, each entry in the constant_pool table must have a tag that was first defined in version v or earlier of the class file format (4.1). That is, each entry must denote a kind of constant that is approved for use in the class file. Table 4.4-B lists each tag with the first version of the class file format in which it was defined. Also shown is the version of the Java SE Platform which introduced that version of the class file format.

Table 4.4-B. Constant pool tags (by tag)

Constant Kind Tag class file format Java SE
CONSTANT_Utf8 1 45.3 1.0.2
CONSTANT_Integer 3 45.3 1.0.2
CONSTANT_Float 4 45.3 1.0.2
CONSTANT_Long 5 45.3 1.0.2
CONSTANT_Double 6 45.3 1.0.2
CONSTANT_Class 7 45.3 1.0.2
CONSTANT_String 8 45.3 1.0.2
CONSTANT_Fieldref 9 45.3 1.0.2
CONSTANT_Methodref 10 45.3 1.0.2
CONSTANT_InterfaceMethodref 11 45.3 1.0.2
CONSTANT_NameAndType 12 45.3 1.0.2
CONSTANT_MethodHandle 15 51.0 7
CONSTANT_MethodType 16 51.0 7
CONSTANT_Dynamic 17 55.0 11
CONSTANT_InvokeDynamic 18 51.0 7
CONSTANT_Module 19 53.0 9
CONSTANT_Package 20 53.0 9

Some entries in the constant_pool table are loadable because they represent entities that can be pushed onto the stack at run time to enable further computation. In a class file whose version number is v, an entry in the constant_pool table is loadable if it has a tag that was first deemed to be loadable in version v or earlier of the class file format. Table 4.4-C lists each tag with the first version of the class file format in which it was deemed to be loadable. Also shown is the version of the Java SE Platform which introduced that version of the class file format.

In every case except CONSTANT_Class, a tag was first deemed to be loadable in the same version of the class file format that first defined the tag.

Table 4.4-C. Loadable constant pool tags

Constant Kind Tag class file format Java SE
CONSTANT_Integer 3 45.3 1.0.2
CONSTANT_Float 4 45.3 1.0.2
CONSTANT_Long 5 45.3 1.0.2
CONSTANT_Double 6 45.3 1.0.2
CONSTANT_Class 7 49.0 5.0
CONSTANT_String 8 45.3 1.0.2
CONSTANT_MethodHandle 15 51.0 7
CONSTANT_MethodType 16 51.0 7
CONSTANT_Dynamic 17 55.0 11

4.4.1 The CONSTANT_Class_info Structure

The CONSTANT_Class_info structure is used to represent a class, or an interface, or an array type:

CONSTANT_Class_info {
    u1 tag;
    u2 name_index;
}

The items of the CONSTANT_Class_info structure are as follows:

tag

The tag item has the value CONSTANT_Class (7).

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) representing consisting of one of:

  • a valid binary class or interface name encoded in internal form (4.2.1). , or

  • an array type, encoded as a valid ArrayType descriptor (4.3.2).

Because arrays are objects, the opcodes anewarray and multianewarray - but not the opcode new - can reference array "classes" via CONSTANT_Class_info structures in the constant_pool table. For such array classes, the name of the class is the descriptor of the array type (4.3.2).

For example, the class name representing the two-dimensional array type int[][] is [[I, while the class name representing the type Thread[] is [Ljava/lang/Thread;.

For example, the name_index string representing the class String is java/lang/String. The name_index string representing the interface Runnable is java/lang/Runnable. The name_index string representing the array type Thread[] is [Ljava/lang/Thread;. The name_index string representing the array type int[][] is [[I.

Note that it is not supported to represent a primitive type with a CONSTANT_Class_info. For example, the name_index string D represents a class or interface named D, not the primitive type double.

An array type descriptor is valid only if it represents 255 or fewer dimensions.

This rule was already stated in 4.3.2.

4.4.2 The CONSTANT_Fieldref_info, CONSTANT_Methodref_info, and CONSTANT_InterfaceMethodref_info Structures

Fields References to fields, methods, and interface methods are represented by similar structures:

CONSTANT_Fieldref_info {
    u1 tag;
    u2 class_index;
    u2 name_and_type_index;
}

CONSTANT_Methodref_info {
    u1 tag;
    u2 class_index;
    u2 name_and_type_index;
}

CONSTANT_InterfaceMethodref_info {
    u1 tag;
    u2 class_index;
    u2 name_and_type_index;
}

The items of these structures are as follows:

tag

The tag item of a CONSTANT_Fieldref_info structure has the value CONSTANT_Fieldref (9).

The tag item of a CONSTANT_Methodref_info structure has the value CONSTANT_Methodref (10).

The tag item of a CONSTANT_InterfaceMethodref_info structure has the value CONSTANT_InterfaceMethodref (11).

class_index

The value of the class_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure (4.4.1).

representing The class_index item represents a class, or interface, or array type that has the field or method as a member.

In a CONSTANT_Fieldref_info structure, the class_index item may be either a class type or an interface type.

In a CONSTANT_Methodref_info structure, the class_index item must be should name a class or an array type, not an interface type.

In a CONSTANT_InterfaceMethodref_info structure, the class_index item must be should name an interface type, not a class or an array type.

name_and_type_index

The value of the name_and_type_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_NameAndType_info structure (4.4.6). This constant_pool entry indicates the name and descriptor of the field or method.

In a CONSTANT_Fieldref_info structure, the indicated descriptor must be a field descriptor (4.3.2). Otherwise, the indicated descriptor must be a method descriptor (4.3.3).

If the name of the method in a CONSTANT_Methodref_info structure begins with a '<' ('\u003c'), then the name must be the special name <init>, representing an instance initialization method (2.9.1). The return type of such a method must be void.

In a CONSTANT_Methodref_info or a CONSTANT_InterfaceMethoref_info structure, the indicated name must be a valid method name (4.2.1) and must not be <clinit>. The indicated descriptor must be a method descriptor (4.3.3). If the name is <init>, the return type of the method descriptor must be V.

Class initialization methods, which have the name <clinit> (2.9.2), cannot be referenced directly. They may only be invoked implicitly by the Java Virtual Machine (5.5).

4.4.3 The CONSTANT_String_info Structure

The CONSTANT_String_info structure is used to represent constant objects of the type String:

CONSTANT_String_info {
    u1 tag;
    u2 string_index;
}

The items of the CONSTANT_String_info structure are as follows:

tag

The tag item has the value CONSTANT_String (8).

string_index

The value of the string_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7).

representing The string_index item represents the sequence of Unicode code points to which the String object is to be initialized.

4.4.4 The CONSTANT_Integer_info and CONSTANT_Float_info Structures

The CONSTANT_Integer_info and CONSTANT_Float_info structures represent 4-byte numeric (int and float) constants:

CONSTANT_Integer_info {
    u1 tag;
    u4 bytes;
}

CONSTANT_Float_info {
    u1 tag;
    u4 bytes;
}

The items of these structures are as follows:

tag

The tag item of the CONSTANT_Integer_info structure has the value CONSTANT_Integer (3).

The tag item of the CONSTANT_Float_info structure has the value CONSTANT_Float (4).

bytes

The bytes item of the CONSTANT_Integer_info structure represents the value of the int constant. The bytes of the value are stored in big-endian (high byte first) order.

The bytes item of the CONSTANT_Float_info structure represents the value of the float constant in IEEE 754 floating-point single format (2.3.2). The bytes of the single format representation are stored in big-endian (high byte first) order.

The value represented by the CONSTANT_Float_info structure is determined as follows. The bytes of the value are first converted into an int constant bits. Then:

  • If bits is 0x7f800000, the float value will be positive infinity.

  • If bits is 0xff800000, the float value will be negative infinity.

  • If bits is in the range 0x7f800001 through 0x7fffffff or in the range 0xff800001 through 0xffffffff, the float value will be NaN.

  • In all other cases, let s, e, and m be three values that might be computed from bits:

    int s = ((*bits* >> 31) == 0) ? 1 : -1;
    int e = ((*bits* >> 23) & 0xff);
    int m = (e == 0) ?
              (*bits* & 0x7fffff) << 1 :
              (*bits* & 0x7fffff) | 0x800000;

Then the float value equals the result of the mathematical expression s · m · 2^e-150^.

4.4.5 The CONSTANT_Long_info and CONSTANT_Double_info Structures

The CONSTANT_Long_info and CONSTANT_Double_info represent 8-byte numeric (long and double) constants:

CONSTANT_Long_info {
    u1 tag;
    u4 high_bytes;
    u4 low_bytes;
}

CONSTANT_Double_info {
    u1 tag;
    u4 high_bytes;
    u4 low_bytes;
}

All 8-byte constants take up two entries in the constant_pool table of the class file. If a CONSTANT_Long_info or CONSTANT_Double_info structure is the entry at index n in the constant_pool table, then the next usable entry in the table is located at index n+2. The constant_pool index n+1 must be valid but is considered unusable.

In retrospect, making 8-byte constants take two constant pool entries was a poor choice.

The items of these structures are as follows:

tag

The tag item of the CONSTANT_Long_info structure has the value CONSTANT_Long (5).

The tag item of the CONSTANT_Double_info structure has the value CONSTANT_Double (6).

high_bytes, low_bytes

The unsigned high_bytes and low_bytes items of the CONSTANT_Long_info structure together represent the value of the long constant

((long) high_bytes << 32) + low_bytes

where the bytes of each of high_bytes and low_bytes are stored in big-endian (high byte first) order.

The high_bytes and low_bytes items of the CONSTANT_Double_info structure together represent the double value in IEEE 754 floating-point double format (2.3.2). The bytes of each item are stored in big-endian (high byte first) order.

The value represented by the CONSTANT_Double_info structure is determined as follows. The high_bytes and low_bytes items are converted into the long constant bits, which is equal to

((long) high_bytes << 32) + low_bytes

Then:

  • If bits is 0x7ff0000000000000L, the double value will be positive infinity.

  • If bits is 0xfff0000000000000L, the double value will be negative infinity.

  • If bits is in the range 0x7ff0000000000001L through 0x7fffffffffffffffL or in the range 0xfff0000000000001L through 0xffffffffffffffffL, the double value will be NaN.

  • In all other cases, let s, e, and m be three values that might be computed from bits:

    int s = ((*bits* >> 63) == 0) ? 1 : -1;
    int e = (int)((*bits* >> 52) & 0x7ffL);
    long m = (e == 0) ?
               (*bits* & 0xfffffffffffffL) << 1 :
               (*bits* & 0xfffffffffffffL) | 0x10000000000000L;

Then the floating-point value equals the double value of the mathematical expression s · m · 2^e-1075^.

4.4.6 The CONSTANT_NameAndType_info Structure

The CONSTANT_NameAndType_info structure is used to represent a field or method, without indicating which class or interface type it belongs to:

CONSTANT_NameAndType_info {
    u1 tag;
    u2 name_index;
    u2 descriptor_index;
}

The items of the CONSTANT_NameAndType_info structure are as follows:

tag

The tag item has the value CONSTANT_NameAndType (12).

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) representing either a valid unqualified name denoting a field or method (4.2.2), or the special method name <init> (2.9.1) a valid unqualified name (4.2.2).

descriptor_index

The value of the descriptor_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) representing a valid field descriptor or method descriptor (4.3.2, 4.3.3).

4.4.7 The CONSTANT_Utf8_info Structure

The CONSTANT_Utf8_info structure is used to represent constant string values:

CONSTANT_Utf8_info {
    u1 tag;
    u2 length;
    u1 bytes[length];
}

The items of the CONSTANT_Utf8_info structure are as follows:

tag

The tag item has the value CONSTANT_Utf8 (1).

length

The value of the length item gives the number of bytes in the bytes array (not the length of the resulting string).

bytes[]

The bytes array contains the bytes of the string.

No byte may have the value (byte)0.

No byte may lie in the range (byte)0xf0 to (byte)0xff.

String content is encoded in modified UTF-8. Modified UTF-8 strings are encoded so that code point sequences that contain only non-null ASCII characters can be represented using only 1 byte per code point, but all code points in the Unicode codespace can be represented. Modified UTF-8 strings are not null-terminated. The encoding is as follows:

The bytes of multibyte characters are stored in the class file in big-endian (high byte first) order.

There are two differences between this format and the "standard" UTF-8 format. First, the null character (char)0 is encoded using the 2-byte format rather than the 1-byte format, so that modified UTF-8 strings never have embedded nulls. Second, only the 1-byte, 2-byte, and 3-byte formats of standard UTF-8 are used. The Java Virtual Machine does not recognize the four-byte format of standard UTF-8; it uses its own two-times-three-byte format instead.

For more information regarding the standard UTF-8 format, see Section 3.9 Unicode Encoding Forms of The Unicode Standard, Version 11.0.0.

4.4.8 The CONSTANT_MethodHandle_info Structure

The CONSTANT_MethodHandle_info structure is used to represent a method handle:

CONSTANT_MethodHandle_info {
    u1 tag;
    u1 reference_kind;
    u2 reference_index;
}

The items of the CONSTANT_MethodHandle_info structure are the following:

tag

The tag item has the value CONSTANT_MethodHandle (15).

reference_kind

The value of the reference_kind item must be in the range 1 to 9. The value denotes the kind of this method handle, which characterizes its bytecode behavior (5.4.3.5).

reference_index

The value of the reference_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be as follows:

  • If the value of the reference_kind item is 1 (REF_getField), 2 (REF_getStatic), 3 (REF_putField), or 4 (REF_putStatic), then the constant_pool entry at that index must be a CONSTANT_Fieldref_info structure (4.4.2).

    representing The reference_index item represents a field for which a method handle is to be created.

  • If the value of the reference_kind item is 5 (REF_invokeVirtual) or 8 (REF_newInvokeSpecial), then the constant_pool entry at that index must be a CONSTANT_Methodref_info structure (4.4.2).

    representing The reference_index item represents a class's method or constructor (2.9.1) for which a method handle is to be created.

  • If the value of the reference_kind item is 6 (REF_invokeStatic) or 7 (REF_invokeSpecial), then if the class file version number is less than 52.0, the constant_pool entry at that index must be a CONSTANT_Methodref_info structure representing a class's method for which a method handle is to be created; if the class file version number is 52.0 or above, the constant_pool entry at that index must be either a CONSTANT_Methodref_info structure or a CONSTANT_InterfaceMethodref_info structure (4.4.2).

    representing The reference_index item represents a class's or interface's method for which a method handle is to be created.

  • If the value of the reference_kind item is 9 (REF_invokeInterface), then the constant_pool entry at that index must be a CONSTANT_InterfaceMethodref_info structure.

    representing The reference_index item represents an interface's method for which a method handle is to be created.

If the value of the reference_kind item is 5 (REF_invokeVirtual), 6 (REF_invokeStatic), 7 (REF_invokeSpecial), or 9 (REF_invokeInterface), the name of the method represented by a CONSTANT_Methodref_info structure or a CONSTANT_InterfaceMethodref_info structure must not be <init> or <clinit>.

If the value is 8 (REF_newInvokeSpecial), the name of the method represented by a CONSTANT_Methodref_info structure must be <init>.

In no case may the name be <clinit>, because Methodref and InterfaceMethodref structures that reference that name are already prohibited (4.4.2).

4.4.9 The CONSTANT_MethodType_info Structure

The CONSTANT_MethodType_info structure is used to represent a method type:

CONSTANT_MethodType_info {
    u1 tag;
    u2 descriptor_index;
}

The items of the CONSTANT_MethodType_info structure are as follows:

tag

The tag item has the value CONSTANT_MethodType (16).

descriptor_index

The value of the descriptor_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) representing a valid method descriptor (4.3.3).

4.4.10 The CONSTANT_Dynamic_info and CONSTANT_InvokeDynamic_info Structures

Most structures in the constant_pool table represent entities directly, by combining names, descriptors, and values recorded statically in the table. In contrast, the CONSTANT_Dynamic_info and CONSTANT_InvokeDynamic_info structures represent entities indirectly, by pointing to code which computes an entity dynamically. The code, called a bootstrap method, is invoked by the Java Virtual Machine during resolution of symbolic references derived from these structures (5.1, 5.4.3.6). Each structure specifies a bootstrap method as well as an auxiliary name and type that characterize the entity to be computed. In more detail:

CONSTANT_Dynamic_info {
    u1 tag;
    u2 bootstrap_method_attr_index;
    u2 name_and_type_index;
}

CONSTANT_InvokeDynamic_info {
    u1 tag;
    u2 bootstrap_method_attr_index;
    u2 name_and_type_index;
}

The items of these structures are as follows:

tag

The tag item of a CONSTANT_Dynamic_info structure has the value CONSTANT_Dynamic (17).

The tag item of a CONSTANT_InvokeDynamic_info structure has the value CONSTANT_InvokeDynamic (18).

bootstrap_method_attr_index

The value of the bootstrap_method_attr_index item must be a valid index into the bootstrap_methods array table of the bootstrap method table BootstrapMethods attribute of this class file ClassFile structure (4.7.23).

CONSTANT_Dynamic_info structures are unique in that they are syntactically allowed to refer to themselves via the bootstrap method table. Rather than mandating that such cycles are detected when classes are loaded (a potentially expensive check), we permit cycles initially but mandate a failure at resolution (5.4.3.6).

name_and_type_index

The value of the name_and_type_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_NameAndType_info structure (4.4.6). This constant_pool entry indicates a name and descriptor.

In a CONSTANT_Dynamic_info structure, the indicated descriptor must be a field descriptor (4.3.2).

In a CONSTANT_InvokeDynamic_info structure, the indicated name must be a valid method name (4.2.1) and must not be <clinit> or <init>. the The indicated descriptor must be a method descriptor (4.3.3).

This parallels the constraints imposed on the NameAndType of a Fieldref, Methodref, or InterfaceMethodref (4.4.2). An additional constraint prohibits using the name <init>, just as verification prohibits its use in an invokestatic instruction, etc.

In JDK 13, Hotspot allows a method named <init> if the descriptor is ()V, subsequently rejecting the method name at verification time. Since we already know this NameAndType is intended to be used by an invokedynamic, it doesn't make much sense to defer half of the check. (Compare the validation of MethodHandle structures (4.4.8), which also enforces verification-style constraints during format checking on use of the name <init>.)

4.4.11 The CONSTANT_Module_info Structure

The CONSTANT_Module_info structure is used to represent a module:

CONSTANT_Module_info {
    u1 tag;
    u2 name_index;
}

The items of the CONSTANT_Module_info structure are as follows:

tag

The tag item has the value CONSTANT_Module (19).

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) representing a valid module name (4.2.3).

A CONSTANT_Module_info structure is permitted only in the constant pool of a class file that declares a module, that is, a ClassFile structure where the access_flags item has the ACC_MODULE flag set. In all other class files, a CONSTANT_Module_info structure is illegal.

A CONSTANT_Module_info structure is permitted only in the constant pool of a class file that declares a module, that is, a ClassFile structure where the access_flags item has the ACC_MODULE flag set. In all other class files, a CONSTANT_Module_info structure is illegal (4.4).

It's useful to restate the rule in non-normative text, but the normative rule already appears in 4.4.

4.4.12 The CONSTANT_Package_info Structure

The CONSTANT_Package_info structure is used to represent a package exported or opened by a module:

CONSTANT_Package_info {
    u1 tag;
    u2 name_index;
}

The items of the CONSTANT_Package_info structure are as follows:

tag

The tag item has the value CONSTANT_Package (20).

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) representing a valid package name encoded in internal form (4.2.3).

A CONSTANT_Package_info structure is permitted only in the constant pool of a class file that declares a module, that is, a ClassFile structure where the access_flags item has the ACC_MODULE flag set. In all other class files, a CONSTANT_Package_info structure is illegal.

A CONSTANT_Package_info structure is permitted only in the constant pool of a class file that declares a module, that is, a ClassFile structure where the access_flags item has the ACC_MODULE flag set. In all other class files, a CONSTANT_Package_info structure is illegal (4.4).

It's useful to restate the rule in non-normative text, but the normative rule already appears in 4.4.

4.5 Fields

Each field is described by a field_info structure.

No two fields in one class file may have A ClassFile structure must not declare two fields with the same name and descriptor (4.3.2).

The structure has the following format:

field_info {
    u2             access_flags;
    u2             name_index;
    u2             descriptor_index;
    u2             attributes_count;
    attribute_info attributes[attributes_count];
}

The items of the field_info structure are as follows:

access_flags

The value of the access_flags item is a mask of flags used to denote access permission to and properties of this field. The interpretation of each flag, when set, is specified in Table 4.5-A.

Table 4.5-A. Field access and property flags

Flag Name Value Interpretation
ACC_PUBLIC 0x0001 Declared public; may be accessed from outside its package.
ACC_PRIVATE 0x0002 Declared private; accessible only within the defining class and other classes belonging to the same nest (5.4.4).
ACC_PROTECTED 0x0004 Declared protected; may be accessed within subclasses.
ACC_STATIC 0x0008 Declared static.
ACC_FINAL 0x0010 Declared final; never directly assigned to after object construction (JLS §17.5).
ACC_VOLATILE 0x0040 Declared volatile; cannot be cached.
ACC_TRANSIENT 0x0080 Declared transient; not written or read by a persistent object manager.
ACC_SYNTHETIC 0x1000 Declared synthetic; not present in the source code.
ACC_ENUM 0x4000 Declared as an element of an enum.

Fields of classes may set any of the flags in Table 4.5-A. However, each field of a class may must have at most one of its ACC_PUBLIC, ACC_PRIVATE, and ACC_PROTECTED flags set (JLS §8.3.1), and must not have both its ACC_FINAL and ACC_VOLATILE flags set (JLS §8.3.1.4).

Fields of interfaces must have their ACC_PUBLIC, ACC_STATIC, and ACC_FINAL flags set; they may have their ACC_SYNTHETIC flag set and must not have any of the other flags in Table 4.5-A set (JLS §9.3).

The ACC_SYNTHETIC flag indicates that this field was generated by a compiler and does not appear in source code.

The ACC_ENUM flag indicates that this field is used to hold an element of an enumerated type.

All bits of the access_flags item not assigned in Table 4.5-A are reserved for future use. They should be set to zero in generated class files and should be are ignored by Java Virtual Machine implementations.

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) which represents a valid unqualified name denoting a field (4.2.2).

descriptor_index

The value of the descriptor_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) which represents a valid field descriptor (4.3.2).

attributes_count

The value of the attributes_count item indicates the number of additional attributes of this field.

attributes[]

Each value of the attributes table must be an attribute_info structure (4.7).

A field can have any number of optional attributes associated with it.

A discussion about constraints on attributes is better left to 4.7.

The attributes defined by this specification as appearing in the attributes table of a field_info structure are listed in Table 4.7-C.

The rules concerning attributes defined to appear in the attributes table of a field_info structure are given in 4.7.

The rules concerning non-predefined nonstandard attributes in the attributes table of a field_info structure are given in 4.7.1.

4.6 Methods

Each method, including each instance initialization method (2.9.1) and the class or interface initialization method (2.9.2), is described by a method_info structure.

No two methods in one class file may have A ClassFile structure must not declare two methods with the same name and descriptor (4.3.3).

The structure has the following format:

method_info {
    u2             access_flags;
    u2             name_index;
    u2             descriptor_index;
    u2             attributes_count;
    attribute_info attributes[attributes_count];
}

The items of the method_info structure are as follows:

access_flags

The value of the access_flags item is a mask of flags used to denote access permission to and properties of this method. The interpretation of each flag, when set, is specified in Table 4.6-A.

Table 4.6-A. Method access and property flags

Flag Name Value Interpretation
ACC_PUBLIC 0x0001 Declared public; may be accessed from outside its package.
ACC_PRIVATE 0x0002 Declared private; accessible only within the defining class and other classes belonging to the same nest (5.4.4).
ACC_PROTECTED 0x0004 Declared protected; may be accessed within subclasses.
ACC_STATIC 0x0008 Declared static.
ACC_FINAL 0x0010 Declared final; must not be overridden (5.4.5).
ACC_SYNCHRONIZED 0x0020 Declared synchronized; invocation is wrapped by a monitor use.
ACC_BRIDGE 0x0040 A bridge method, generated by the compiler.
ACC_VARARGS 0x0080 Declared with variable number of arguments.
ACC_NATIVE 0x0100 Declared native; implemented in a language other than the Java programming language.
ACC_ABSTRACT 0x0400 Declared abstract; no implementation is provided.
ACC_STRICT 0x0800 Declared strictfp; floating-point mode is FP-strict.
ACC_SYNTHETIC 0x1000 Declared synthetic; not present in the source code.

A method named <init> (2.9.1) must have at most one of its ACC_PUBLIC, ACC_PRIVATE, and ACC_PROTECTED flags set, and may also have its ACC_VARARGS, ACC_STRICT, and ACC_SYNTHETIC flags set, but must not have any of the other flags in Table 4.6-A set.

A method named <clinit> (2.9.2) may have any of the flags in Table 4.6-A set, in any combination, but all flags except ACC_STATIC, ACC_STRICT, and ACC_SYNTHETIC are treated by the Java Virtual Machine as if they were not set. In a class file whose version number is 51.0 or greater, the ACC_STATIC flag must be set; in a class file whose version number is less than 51.0, the ACC_STATIC flag is treated by the Java Virtual Machine as if it were set.

Methods of classes with names other than <init> and <clinit> may have any of the flags in Table 4.6-A set. However, each such method of a class may must have at most one of its ACC_PUBLIC, ACC_PRIVATE, and ACC_PROTECTED flags set (JLS §8.4.3).

Methods of interfaces with names other than <clinit> may have any of the flags in Table 4.6-A set except must not have their ACC_PROTECTED, ACC_FINAL, ACC_SYNCHRONIZED, and ACC_NATIVE flags set (JLS §9.4); exactly one of the ACC_PUBLIC or ACC_PRIVATE flags must be set. They may have any of the other flags in Table 4.6-A set. In a class file whose version number is less than 52.0, each method of an interface with a name other than <clinit> must have its ACC_PUBLIC and ACC_ABSTRACT flags set; in a class file whose version number is 52.0 or above, each method of an interface must have exactly one of its ACC_PUBLIC and ACC_PRIVATE flags set.

If a method of a class or interface has its ACC_ABSTRACT flag set, it must not have any of its ACC_PRIVATE, ACC_STATIC, ACC_FINAL, ACC_SYNCHRONIZED, ACC_NATIVE, or ACC_STRICT flags set.

An instance initialization method (2.9.1) may have at most one of its ACC_PUBLIC, ACC_PRIVATE, and ACC_PROTECTED flags set, and may also have its ACC_VARARGS, ACC_STRICT, and ACC_SYNTHETIC flags set, but must not have any of the other flags in Table 4.6-A set.

In a class file whose version number is 51.0 or above, a method whose name is <clinit> must have its ACC_STATIC flag set.

A class or interface initialization method (2.9.2) is called implicitly by the Java Virtual Machine. The value of its access_flags item is ignored except for the setting of the ACC_STATIC and ACC_STRICT flags, and the method is exempt from the preceding rules about legal combinations of flags.

These rules have been reordered and rephrased to be more precise and to avoid saying things like "exempt from the preceding rules".

The ACC_BRIDGE flag is used to indicate a bridge method generated by a compiler for the Java programming language.

The ACC_VARARGS flag indicates that this method takes a variable number of arguments at the source code level. A method declared to take a variable number of arguments must be compiled with the ACC_VARARGS flag set to 1. All other methods must be compiled with the ACC_VARARGS flag set to 0.

That's how all flags work. No need to be so descriptive about this one flag.

The ACC_SYNTHETIC flag indicates that this method was generated by a compiler and does not appear in source code, unless it is and is not one of the methods named in 4.7.8.

All bits of the access_flags item not assigned in Table 4.6-A are reserved for future use. They should be set to zero in generated class files and should be are ignored by Java Virtual Machine implementations.

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) representing either a valid unqualified method name denoting a method (4.2.2), or (if this method is in a class rather than an interface) the special method name <init>, or the special method name <clinit>.

A method of an interface must not have the name <init>.

descriptor_index

The value of the descriptor_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure representing a valid method descriptor (4.3.3). Furthermore:

  • If this method is in a class rather than an interface, and the name of the method is <init>, then the descriptor must denote a void method.

  • If the name of the method is <clinit>, then the descriptor must denote a void method, and, in a class file whose version number is 51.0 or above, a method that takes no arguments.

A future edition of this specification may require that the last parameter descriptor of the method descriptor is an array type if the ACC_VARARGS flag is set in the access_flags item.

attributes_count

The value of the attributes_count item indicates the number of additional attributes of this method.

attributes[]

Each value of the attributes table must be an attribute_info structure (4.7).

A method can have any number of optional attributes associated with it.

A discussion about constraints on attributes is better left to 4.7.

The attributes defined by this specification as appearing in the attributes table of a method_info structure are listed in Table 4.7-C.

The rules concerning attributes defined to appear in the attributes table of a method_info structure are given in 4.7.

The rules concerning non-predefined nonstandard attributes in the attributes table of a method_info structure are given in 4.7.1.

4.7 Attributes

Attributes are used in the ClassFile, field_info, method_info, and Code_attribute structures of the class file format (4.1, 4.5, 4.6, 4.7.3).

All attributes have the following general format:

attribute_info {
    u2 attribute_name_index;
    u4 attribute_length;
    u1 info[attribute_length];
}

For all attributes, the attribute_name_index item must be a valid unsigned 16-bit index into the constant pool of the class. The constant_pool entry at attribute_name_index must be a CONSTANT_Utf8_info structure (4.4.7) representing which represents the name of the attribute. The value of the attribute_length item indicates the length of the subsequent information in bytes. The length does not include the initial six bytes that contain the attribute_name_index and attribute_length items.

28 attributes are predefined by this specification. They are listed three times, for ease of navigation:

Within the context of their use in this specification, that is, in the attributes tables of the class file structures the structures of appropriately-versioned class files in which they appear, the names of these predefined attributes are reserved.

Any conditions on the presence of a predefined attribute in an attributes table are specified explicitly in the section which describes the attribute. If no conditions are specified, then the attribute may appear any number of times in an attributes table.

The predefined attributes are categorized into three groups according to their purpose:

  1. Six Nine attributes are critical to correct interpretation of the class file by the Java Virtual Machine:

    • ConstantValue
    • Code
    • StackMapTable
    • BootstrapMethods
    • Module
    • ModulePackages
    • ModuleMainClass
    • NestHost
    • NestMembers

    In a class file whose version number is v, each of these attributes must be recognized and correctly read by an implementation of the Java Virtual Machine if the implementation supports version v of the class file format, and the attribute was first defined in version v or earlier of the class file format, and the attribute appears in a location where it is defined to appear.

    Module-related attributes are a special case, because module classses are never loaded (see 5.3.5). However, it makes sense to specify hard constraints on the module attributes, just as we specified constraints on the module class files in, e.g., 4.1. These constraints are presumably enforced by Java SE APIs.

  2. Nine Ten attributes are not critical to correct interpretation of the class file by the Java Virtual Machine, but are either critical to correct interpretation of the class file by the class libraries of the Java SE Platform, or are useful for tools (in which case the section that specifies an attribute describes it as "optional"):

    • Exceptions
    • InnerClasses
    • EnclosingMethod
    • Synthetic
    • Signature
    • SourceFile
    • LineNumberTable
    • LocalVariableTable
    • LocalVariableTypeTable
    • Deprecated

    In a class file whose version number is v, each of these attributes must be recognized and correctly read by an implementation of the Java Virtual Machine if the implementation supports version v of the class file format, and the attribute was first defined in version v or earlier of the class file format, and the attribute appears in a location where it is defined to appear.

    In JDK 13, Hotspot does not silently ignore the Deprecated attribute: it checks that the length is 0.

  3. Thirteen Nine attributes are not critical to correct interpretation of the class file by the Java Virtual Machine, but contain metadata about the class file that is either exposed by the class libraries of the Java SE Platform, or made available by tools (in which case the section that specifies an attribute describes it as "optional"):

    • SourceDebugExtension
    • Deprecated
    • RuntimeVisibleAnnotations
    • RuntimeInvisibleAnnotations
    • RuntimeVisibleParameterAnnotations
    • RuntimeInvisibleParameterAnnotations
    • RuntimeVisibleTypeAnnotations
    • RuntimeInvisibleTypeAnnotations
    • AnnotationDefault
    • MethodParameters
    • Module
    • ModulePackages
    • ModuleMainClass

    An implementation of the Java Virtual Machine may use the information that these attributes contain, or otherwise must silently ignore these attributes.

Table 4.7-A. Predefined class file attributes (by section)

Attribute Section class file Java SE
ConstantValue 4.7.2 45.3 1.0.2
Code 4.7.3 45.3 1.0.2
StackMapTable 4.7.4 50.0 6
Exceptions 4.7.5 45.3 1.0.2
InnerClasses 4.7.6 45.3 1.1
EnclosingMethod 4.7.7 49.0 5.0
Synthetic 4.7.8 45.3 1.1
Signature 4.7.9 49.0 5.0
SourceFile 4.7.10 45.3 1.0.2
SourceDebugExtension 4.7.11 49.0 5.0
LineNumberTable 4.7.12 45.3 1.0.2
LocalVariableTable 4.7.13 45.3 1.0.2
LocalVariableTypeTable 4.7.14 49.0 5.0
Deprecated 4.7.15 45.3 1.1
RuntimeVisibleAnnotations 4.7.16 49.0 5.0
RuntimeInvisibleAnnotations 4.7.17 49.0 5.0
RuntimeVisibleParameterAnnotations 4.7.18 49.0 5.0
RuntimeInvisibleParameterAnnotations 4.7.19 49.0 5.0
RuntimeVisibleTypeAnnotations 4.7.20 52.0 8
RuntimeInvisibleTypeAnnotations 4.7.21 52.0 8
AnnotationDefault 4.7.22 49.0 5.0
BootstrapMethods 4.7.23 51.0 7
MethodParameters 4.7.24 52.0 8
Module 4.7.25 53.0 9
ModulePackages 4.7.26 53.0 9
ModuleMainClass 4.7.27 53.0 9
NestHost 4.7.28 55.0 11
NestMembers 4.7.29 55.0 11

Table 4.7-B. Predefined class file attributes (by class file format)

Attribute class file Java SE Section
ConstantValue 45.3 1.0.2 4.7.2
Code 45.3 1.0.2 4.7.3
Exceptions 45.3 1.0.2 4.7.5
SourceFile 45.3 1.0.2 4.7.10
LineNumberTable 45.3 1.0.2 4.7.12
LocalVariableTable 45.3 1.0.2 4.7.13
InnerClasses 45.3 1.1 4.7.6
Synthetic 45.3 1.1 4.7.8
Deprecated 45.3 1.1 4.7.15
EnclosingMethod 49.0 5.0 4.7.7
Signature 49.0 5.0 4.7.9
SourceDebugExtension 49.0 5.0 4.7.11
LocalVariableTypeTable 49.0 5.0 4.7.14
RuntimeVisibleAnnotations 49.0 5.0 4.7.16
RuntimeInvisibleAnnotations 49.0 5.0 4.7.17
RuntimeVisibleParameterAnnotations 49.0 5.0 4.7.18
RuntimeInvisibleParameterAnnotations 49.0 5.0 4.7.19
AnnotationDefault 49.0 5.0 4.7.22
StackMapTable 50.0 6 4.7.4
BootstrapMethods 51.0 7 4.7.23
RuntimeVisibleTypeAnnotations 52.0 8 4.7.20
RuntimeInvisibleTypeAnnotations 52.0 8 4.7.21
MethodParameters 52.0 8 4.7.24
Module 53.0 9 4.7.25
ModulePackages 53.0 9 4.7.26
ModuleMainClass 53.0 9 4.7.27
NestHost 55.0 11 4.7.28
NestMembers 55.0 11 4.7.29

Table 4.7-C. Predefined class file attributes (by location)

Attribute Location class file
SourceFile ClassFile 45.3
InnerClasses ClassFile 45.3
EnclosingMethod ClassFile 49.0
SourceDebugExtension ClassFile 49.0
BootstrapMethods ClassFile 51.0
Module, ModulePackages, ModuleMainClass ClassFile 53.0
NestHost, NestMembers ClassFile 55.0
ConstantValue field_info 45.3
Code method_info 45.3
Exceptions method_info 45.3
RuntimeVisibleParameterAnnotations, RuntimeInvisibleParameterAnnotations method_info 49.0
AnnotationDefault method_info 49.0
MethodParameters method_info 52.0
Synthetic ClassFile, field_info, method_info 45.3
Deprecated ClassFile, field_info, method_info 45.3
Signature ClassFile, field_info, method_info 49.0
RuntimeVisibleAnnotations, RuntimeInvisibleAnnotations ClassFile, field_info, method_info 49.0
LineNumberTable Code 45.3
LocalVariableTable Code 45.3
LocalVariableTypeTable Code 49.0
StackMapTable Code 50.0
RuntimeVisibleTypeAnnotations, RuntimeInvisibleTypeAnnotations ClassFile, field_info, method_info, Code 52.0

4.7.1 Defining and Naming New Nonstandard Attributes

An attribute is nonstandard if one of the following are true:

Compilers are permitted to define and emit class files containing new nonstandard attributes in the attributes tables of class file structures, field_info structures, method_info structures, and Code attributes (4.7.3). Java Virtual Machine implementations are permitted to recognize and use new nonstandard attributes found in these attributes tables. However, any nonstandard attribute not defined as part of this specification must not affect the semantics of the class file, including determining whether the class file is valid (4). Java Virtual Machine implementations are required to must silently ignore attributes they do not recognize.

For instance, defining a new attribute to support vendor-specific debugging is permitted. Because Java Virtual Machine implementations are required to ignore attributes they do not recognize, class files intended for that particular Java Virtual Machine implementation will be usable by other implementations even if those implementations cannot make use of the additional debugging information that the class files contain.

Java Virtual Machine implementations are specifically prohibited from throwing an exception or otherwise refusing to use class files simply because of the presence of some new attribute. Of course, tools operating on class files may not run correctly if given class files that do not contain all the attributes they require.

Two attributes that are intended to be distinct, but that happen to use the same attribute name and are of the same length, will conflict on implementations that recognize either attribute. Attributes defined other than in this specification should have names chosen according to the package naming convention described in The Java Language Specification, Java SE 12 Edition (JLS §6.1).

For instance, defining a new attribute to support vendor-specific debugging is permitted. Because Java Virtual Machine implementations are required to ignore attributes they do not recognize, class files intended for that particular Java Virtual Machine implementation will be usable by other implementations even if those implementations cannot make use of the additional debugging information that the class files contain.

Java Virtual Machine implementations are specifically prohibited from throwing an exception or otherwise refusing to use class files simply because of the presence of some nonstandard attribute. Of course, tools operating on class files may not run correctly if given class files that do not contain all the attributes they require.

Two attributes that are intended to be distinct, but that happen to use the same attribute name and are of the same length, will conflict on implementations that recognize either attribute. Attributes defined other than in this specification should have names chosen according to the package naming convention described in The Java Language Specification, Java SE 12 Edition (JLS §6.1).

Future versions of this specification may define additional attributes.

4.7.2 The ConstantValue Attribute

The ConstantValue attribute is a fixed-length attribute in the attributes table of a field_info structure (4.5). A ConstantValue attribute represents the value of a constant expression (JLS §15.28), and is used as follows: . The field represented by the field_info structure is assigned the value represented by its ConstantValue attribute as part of the initialization of the class or interface declaring the field (5.5). This occurs prior to the invocation of the class or interface initialization method of that class or interface (2.9.2).

There may be at most one ConstantValue attribute in the attributes table of a field_info structure representing a static field. There must not be a ConstantValue attribute in the attributes table of a field_info structure representing a non-static field.

Current behavior is to treat the attribute as nonstandard if the field is not static. This is subtle and would need to appear in the discussions about predefined/nonstandard attributes in 4.7 and 4.7.1.

It's simpler and less error-prone to follow the lead of the Code attribute (4.7.3) and reject ConstantValue attributes appearing on non-static fields.

The ConstantValue attribute has must have the following format:

ConstantValue_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 constantvalue_index;
}

The items of the ConstantValue_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "ConstantValue".

attribute_length

The value of the attribute_length item must be two.

constantvalue_index

The value of the constantvalue_index item must be a valid index into the constant_pool table. The constant_pool entry at that index gives the value represented by this attribute. The constant_pool entry must be of a type appropriate to the field, as specified in Table 4.7.2-A. (If the field type is not listed in the table, no constant_pool entry type is appropriate.)

Table 4.7.2-A. Constant value attribute types

Field Type Entry Type
int, short, char, byte, boolean CONSTANT_Integer
float CONSTANT_Float
long CONSTANT_Long
double CONSTANT_Double
String CONSTANT_String

4.7.3 The Code Attribute

The Code attribute is a variable-length attribute in the attributes table of a method_info structure (4.6). A Code attribute contains the Java Virtual Machine instructions and auxiliary information for a method, including an instance initialization method and a class or interface initialization method (2.9.1, 2.9.2).

If the method is either native or abstract, and is not a class or interface initialization method, then its method_info structure must not have a Code attribute in its attributes table. Otherwise, its method_info structure must have exactly one Code attribute in its attributes table.

A class or interface initialization method is never native or abstract—those flags are "treated ... as if they were not set" (4.6). It's not practical to qualify "abstract" with "and not a class or interface initialization method" wherever the abstract flag is referenced, throughout JVMS.

The Code attribute has must have the following format:

Code_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 max_stack;
    u2 max_locals;
    u4 code_length;
    u1 code[code_length];
    u2 exception_table_length;
    {   u2 start_pc;
        u2 end_pc;
        u2 handler_pc;
        u2 catch_type;
    } exception_table[exception_table_length];
    u2 attributes_count;
    attribute_info attributes[attributes_count];
}

The items of the Code_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "Code".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

max_stack

The value of the max_stack item gives the maximum depth of the operand stack of this method (2.6.2) at any point during execution of the method.

max_locals

The value of the max_locals item gives the number of local variables in the local variable array allocated upon invocation of this method (2.6.1), including the local variables used to pass parameters to the method on its invocation.

The greatest local variable index for a value of type long or double is max_locals - 2. The greatest local variable index for a value of any other type is max_locals - 1.

code_length

The value of the code_length item gives the number of bytes in the code array for this method.

The value of code_length must be greater than zero (as the code array must not be empty) and less than 65536.

code[]

The code array gives the actual bytes of Java Virtual Machine code that implement the method.

When the code array is read into memory on a byte-addressable machine, if the first byte of the array is aligned on a 4-byte boundary, the tableswitch and lookupswitch 32-bit offsets will be 4-byte aligned. (Refer to the descriptions of those instructions for more information on the consequences of code array alignment.)

The detailed constraints on the contents of the code array are extensive and are given in a separate section (4.9).

exception_table_length

The value of the exception_table_length item gives the number of entries in the exception_table table.

exception_table[]

Each entry in the exception_table array describes one exception handler in the code array. The order of the handlers in the exception_table array is significant (2.10).

Each exception_table entry contains the following four items:

start_pc, end_pc

The values of the two items start_pc and end_pc indicate the ranges in the code array at which the exception handler is active. The value of start_pc must be a valid index into the code array of the opcode of an instruction. The value of end_pc either must be a valid index into the code array of the opcode of an instruction or must be equal to code_length, the length of the code array. The value of start_pc must be less than the value of end_pc.

The start_pc is inclusive and end_pc is exclusive; that is, the exception handler must be active while the program counter is within the interval [start_pc, end_pc).

The fact that end_pc is exclusive is a historical mistake in the design of the Java Virtual Machine: if the Java Virtual Machine code for a method is exactly 65535 bytes long and ends with an instruction that is 1 byte long, then that instruction cannot be protected by an exception handler. A compiler writer can work around this bug by limiting the maximum size of the generated Java Virtual Machine code for any method, instance initialization method, or static initializer (the size of any code array) to 65534 bytes.

handler_pc

The value of the handler_pc item indicates the start of the exception handler. The value of the item must be a valid index into the code array and must be the index of the opcode of an instruction.

catch_type

If the value of the catch_type item is nonzero, it must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure (4.4.1) representing a class of exceptions that this exception handler is designated to catch. The exception handler will be called only if the thrown exception is an instance of the given class or one of its subclasses.

The verifier checks that the class is Throwable or a subclass of Throwable (4.9.2).

If the value of the catch_type item is zero, this exception handler is called for all exceptions.

This is used to implement finally (3.13).

attributes_count

The value of the attributes_count item indicates the number of attributes of the Code attribute.

attributes[]

Each value of the attributes table must be an attribute_info structure (4.7).

A Code attribute can have any number of optional attributes associated with it.

A discussion about constraints on attributes is better left to 4.7.

The attributes defined by this specification as appearing in the attributes table of a Code attribute are listed in Table 4.7-C.

The rules concerning attributes defined to appear in the attributes table of a Code attribute are given in 4.7.

The rules concerning non-predefined nonstandard attributes in the attributes table of a Code attribute are given in 4.7.1.

4.7.4 The StackMapTable Attribute

The StackMapTable attribute is a variable-length attribute in the attributes table of a Code attribute (4.7.3) in a version 50.0 or later class file. A StackMapTable attribute is used during the process of verification by type checking (4.10.1).

There may be at most must be no more than one StackMapTable attribute in the attributes table of a Code attribute.

In a class file whose version number is 50.0 or above, if a method's Code attribute does not have a StackMapTable attribute, it has an implicit stack map attribute (4.10.1). This implicit stack map attribute is equivalent to a StackMapTable attribute with number_of_entries equal to zero.

The StackMapTable attribute has must have the following format:

StackMapTable_attribute {
    u2              attribute_name_index;
    u4              attribute_length;
    u2              number_of_entries;
    stack_map_frame entries[number_of_entries];
}

The items of the StackMapTable_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "StackMapTable".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

number_of_entries

The value of the number_of_entries item gives the number of stack_map_frame entries in the entries table.

entries[]

Each entry in the entries table describes one stack map frame of the method. The order of the stack map frames in the entries table is significant.

A stack map frame specifies (either explicitly or implicitly) the bytecode offset at which it applies, and the verification types of local variables and operand stack entries for that offset.

Each stack map frame described in the entries table relies on the previous frame for some of its semantics. The first stack map frame of a method is implicit, and computed from the method descriptor by the type checker ([4.10.1.6]). The stack_map_frame structure at entries[0] therefore describes the second stack map frame of the method.

The bytecode offset at which a stack map frame applies is calculated by taking the value offset_delta specified in the frame (either explicitly or implicitly), and adding offset_delta + 1 to the bytecode offset of the previous frame, unless the previous frame is the initial frame of the method. In that case, the bytecode offset at which the stack map frame applies is the value offset_delta specified in the frame.

By using an offset delta rather than storing the actual bytecode offset, we ensure, by definition, that stack map frames are in the correctly sorted order. Furthermore, by consistently using the formula offset_delta + 1 for all explicit frames (as opposed to the implicit first frame), we guarantee the absence of duplicates.

We say that an instruction in the bytecode has a corresponding stack map frame if the instruction starts at offset i in the code array of a Code attribute, and the Code attribute has a StackMapTable attribute whose entries array contains a stack map frame that applies at bytecode offset i.

A verification type specifies the type of either one or two locations, where a location is either a single local variable or a single operand stack entry. A verification type is represented by a discriminated union, verification_type_info, that consists of a one-byte tag, indicating which item of the union is in use, followed by zero or more bytes, giving more information about the tag.

union verification_type_info {
    Top_variable_info;
    Integer_variable_info;
    Float_variable_info;
    Long_variable_info;
    Double_variable_info;
    Null_variable_info;
    UninitializedThis_variable_info;
    Object_variable_info;
    Uninitialized_variable_info;
}

A verification type that specifies one location in the local variable array or in the operand stack is represented by the following items of the verification_type_info union:

A verification type that specifies two locations in the local variable array or in the operand stack is represented by the following items of the verification_type_info union:

...

4.7.5 The Exceptions Attribute

The Exceptions attribute is a variable-length attribute in the attributes table of a method_info structure (4.6). The Exceptions attribute indicates which checked exceptions a method may throw.

There may be at most must be no more than one Exceptions attribute in the attributes table of a method_info structure.

The Exceptions attribute has must have the following format:

Exceptions_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 number_of_exceptions;
    u2 exception_index_table[number_of_exceptions];
}

The items of the Exceptions_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be the is a CONSTANT_Utf8_info structure (4.4.7) representing the string "Exceptions".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

number_of_exceptions

The value of the number_of_exceptions item indicates the number of entries in the exception_index_table.

exception_index_table[]

Each value in the exception_index_table array must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure (4.4.1) representing a class type that this method is declared to throw.

A method should throw an exception only if at least one of the following three criteria is met:

These requirements are not enforced in the Java Virtual Machine; they are enforced only at compile time.

4.7.6 The InnerClasses Attribute

The InnerClasses attribute is a variable-length attribute in the attributes table of a ClassFile structure (4.1).

If the constant pool of a class or interface C contains at least one CONSTANT_Class_info entry (4.4.1) which represents a class or interface that is not a member of a package, then there must be exactly one InnerClasses attribute in the attributes table of the ClassFile structure for C.

The relationship to constant pool entries cannot be enforced by the JVM, and is presented as a recommendation below, in the description of the classes item.

There must be no more than one InnerClasses attribute in the attributes table of a ClassFile structure.

The InnerClasses attribute has must have the following format:

InnerClasses_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 number_of_classes;
    {   u2 inner_class_info_index;
        u2 outer_class_info_index;
        u2 inner_name_index;
        u2 inner_class_access_flags;
    } classes[number_of_classes];
}

The items of the InnerClasses_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "InnerClasses".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

number_of_classes

The value of the number_of_classes item indicates the number of entries in the classes array.

classes[]

Every CONSTANT_Class_info entry (4.4.1) in the constant_pool table which represents a class or interface C that is not a package member must should have exactly one corresponding entry in the classes array.

If a class or interface has members that are classes or interfaces, its constant_pool table (and hence its InnerClasses attribute) must should refer to each such member (JLS §13.1), even if that member is not otherwise mentioned by the class.

In addition, the constant_pool table of every nested class and nested interface must should refer to its enclosing class, so altogether, every nested class and nested interface will have InnerClasses information for each enclosing class and for each of its own nested classes and interfaces.

Each entry in the classes array contains the following four items:

inner_class_info_index

The value of the inner_class_info_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure representing C.

outer_class_info_index

If C is not a member of a class or an interface - that is, if C is a top-level class or interface (JLS §7.6) or a local class (JLS §14.3) or an anonymous class (JLS §15.9.5) - then the value of the outer_class_info_index item must be zero.

Otherwise, the value of the outer_class_info_index item must be a valid index into the constant_pool table, and the entry at that index must be a CONSTANT_Class_info structure representing the class or interface of which C is a member. The value of the outer_class_info_index item must not equal the the value of the inner_class_info_index item.

inner_name_index

If C is anonymous (JLS §15.9.5), the value of the inner_name_index item must be zero.

Otherwise, the value of the inner_name_index item must be a valid index into the constant_pool table, and the entry at that index must be a CONSTANT_Utf8_info structure that represents the original simple name of C, as given in the source code from which this class file was compiled.

inner_class_access_flags

The value of the inner_class_access_flags item is a mask of flags used to denote access permissions to and properties of class or interface C as declared in the source code from which this class file was compiled. It is used by a compiler to recover the original information when source code is not available. The flags are specified in Table 4.7.6-A.

Table 4.7.6-A. Nested class access and property flags

Flag Name Value Interpretation
ACC_PUBLIC 0x0001 Marked or implicitly public in source.
ACC_PRIVATE 0x0002 Marked private in source.
ACC_PROTECTED 0x0004 Marked protected in source.
ACC_STATIC 0x0008 Marked or implicitly static in source.
ACC_FINAL 0x0010 Marked or implicitly final in source.
ACC_INTERFACE 0x0200 Was an interface in source.
ACC_ABSTRACT 0x0400 Marked or implicitly abstract in source.
ACC_SYNTHETIC 0x1000 Declared synthetic; not present in the source code.
ACC_ANNOTATION 0x2000 Declared as an annotation type.
ACC_ENUM 0x4000 Declared as an enum type.

All bits of the inner_class_access_flags item not assigned in Table 4.7.6-A are reserved for future use. They should be set to zero in generated class files and should be ignored by Java Virtual Machine implementations.

If a class file has a version number that is 51.0 or above, and has an InnerClasses attribute in its attributes table, then for all entries in the classes array of the InnerClasses attribute, the value of the outer_class_info_index item must be zero if the value of the inner_name_index item is zero.

Oracle's Java Virtual Machine implementation The Java Virtual Machine does not check the consistency of an InnerClasses attribute against a class file representing a class or interface referenced by the attribute.

4.7.7 The EnclosingMethod Attribute

The EnclosingMethod attribute is a fixed-length attribute in the attributes table of a ClassFile structure (4.1) in a version 49.0 or later class file. A class or interface must should have an EnclosingMethod attribute if and only if it represents a local class or an anonymous class (JLS §14.3, JLS §15.9.5).

There may be at most must be no more than one EnclosingMethod attribute in the attributes table of a ClassFile structure representing a class or interface. There must not be an EnclosingMethod attribute in the attributes table of a ClassFile structure representing a module.

The EnclosingMethod attribute has must have the following format:

EnclosingMethod_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 class_index;
    u2 method_index;
}

The items of the EnclosingMethod_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "EnclosingMethod".

attribute_length

The value of the attribute_length item must be four.

class_index

The value of the class_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure (4.4.1) representing the innermost class that encloses the declaration of the current class.

method_index

If the current class is not immediately enclosed by a method or constructor, then the value of the method_index item must be zero.

In particular, method_index must be zero if the current class was immediately enclosed in source code by an instance initializer, static initializer, instance variable initializer, or class variable initializer. (The first two concern both local classes and anonymous classes, while the last two concern anonymous classes declared on the right hand side of a field assignment.)

Otherwise, the value of the method_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_NameAndType_info structure (4.4.6) representing the name and type of a method in the class referenced by the class_index attribute above.

It is the responsibility of a Java compiler to ensure that the method identified via the method_index is indeed the closest lexically enclosing method of the class that contains this EnclosingMethod attribute.

4.7.8 The Synthetic Attribute

The Synthetic attribute is a fixed-length attribute in the attributes table of a ClassFile, field_info, or method_info structure (4.1, 4.5, 4.6). A class member that does not appear in the source code must should be marked using a Synthetic attribute, or else it must should have its ACC_SYNTHETIC flag set. The only exceptions to this requirement are compiler-generated methods which are not considered implementation artifacts, namely the instance initialization method representing a default constructor of the Java programming language (2.9.1), the class or interface initialization method (2.9.2), and the Enum.values() and Enum.valueOf() methods.

The Synthetic attribute was introduced in JDK 1.1 to support nested classes and interfaces.

There must not be a Synthetic attribute in the attributes table of a ClassFile structure representing a module.

The Synthetic attribute has must have the following format:

Synthetic_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
}

The items of the Synthetic_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "Synthetic".

attribute_length

The value of the attribute_length item must be zero.

4.7.9 The Signature Attribute

The Signature attribute is a fixed-length attribute in the attributes table of a ClassFile, field_info, or method_info structure (4.1, 4.5, 4.6) in a version 49.0 or later class file. A Signature attribute records a signature (4.7.9.1) for a class, interface, constructor, method, or field whose declaration in the Java programming language uses type variables or parameterized types. See The Java Language Specification, Java SE 12 Edition for details about these constructs.

There may be at most must be no more than one Signature attribute in the attributes table of a ClassFile, field_info, or method_info structure. There must not be a Signature attribute in the attributes table of a ClassFile structure representing a module.

The Signature attribute has must have the following format:

Signature_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 signature_index;
}

The items of the Signature_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "Signature".

attribute_length

The value of the attribute_length item must be two.

signature_index

The value of the signature_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure (4.4.7) representing a class signature if this Signature attribute is an attribute of a ClassFile structure; a method signature if this Signature attribute is an attribute of a method_info structure; or a field signature otherwise.

Oracle's Java Virtual Machine implementation The Java Virtual Machine does not check the well-formedness of Signature attributes during class loading or linking. Instead, Signature attributes are checked by methods of the Java SE Platform class libraries which expose generic signatures of classes, interfaces, constructors, methods, and fields. Examples include getGenericSuperclass in Class and toGenericString in java.lang.reflect.Executable.

4.7.9.1 Signatures

Signatures encode declarations written in the Java programming language that use types outside the type system of the Java Virtual Machine. They support reflection and debugging, as well as compilation when only class files are available.

A Java compiler must should emit a signature for any class, interface, constructor, method, or field whose declaration uses type variables or parameterized types. Specifically, a Java compiler must should emit:

Signatures are specified using a grammar which follows the notation of 4.3.1. In addition to that notation:

The grammar includes the terminal symbol Identifier to denote the name of a type, field, method, formal parameter, local variable, or type variable, as generated by a Java compiler. Such a name must should not contain any of the ASCII characters . ; [ / < > : (that is, the characters forbidden in method names (4.2.2) and also colon) but may contain characters that must do not appear in an identifier in the Java programming language (JLS §3.8).

Signatures rely on a hierarchy of nonterminals known as type signatures:

A class signature encodes type information about a (possibly generic) class declaration. It describes any type parameters of the class, and lists its (possibly parameterized) direct superclass and direct superinterfaces, if any. A type parameter is described by its name, followed by any class bound and interface bounds.

ClassSignature:
[TypeParameters] SuperclassSignature {SuperinterfaceSignature}
TypeParameters:
< TypeParameter {TypeParameter} >
TypeParameter:
Identifier ClassBound {InterfaceBound}
ClassBound:
: [ReferenceTypeSignature]
InterfaceBound:
: ReferenceTypeSignature
SuperclassSignature:
ClassTypeSignature
SuperinterfaceSignature:
ClassTypeSignature

A method signature encodes type information about a (possibly generic) method declaration. It describes any type parameters of the method; the (possibly parameterized) types of any formal parameters; the (possibly parameterized) return type, if any; and the types of any exceptions declared in the method's throws clause.

MethodSignature:
[TypeParameters] ( {JavaTypeSignature} ) Result {ThrowsSignature}
Result:
JavaTypeSignature
VoidDescriptor
ThrowsSignature:
^ ClassTypeSignature
^ TypeVariableSignature

The following production from 4.3.3 is repeated here for convenience:

VoidDescriptor:
V

A method signature encoded by the Signature attribute may might not correspond exactly to the method descriptor in the method_info structure (4.3.3). In particular, there is no assurance that the number of formal parameter types in the method signature is the same as the number of parameter descriptors in the method descriptor. The numbers are the same for most methods, but certain constructors in the Java programming language have an implicitly declared parameter which a compiler represents with a parameter descriptor but may omit from the method signature. See the note in 4.7.18 for a similar situation involving parameter annotations.

A field signature encodes the (possibly parameterized) type of a field, formal parameter, or local variable declaration.

FieldSignature:
ReferenceTypeSignature

4.7.10 The SourceFile Attribute

The SourceFile attribute is an optional fixed-length attribute in the attributes table of a ClassFile structure (4.1).

There may be at most must be no more than one SourceFile attribute in the attributes table of a ClassFile structure.

The SourceFile attribute has must have the following format:

SourceFile_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 sourcefile_index;
}

The items of the SourceFile_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "SourceFile".

attribute_length

The value of the attribute_length item must be two.

sourcefile_index

The value of the sourcefile_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure representing a string.

The string referenced by the sourcefile_index item will be interpreted as indicating the name of the source file from which this class file was compiled. It will not be interpreted as indicating the name of a directory containing the file or an absolute path name for the file; such platform-specific additional information must should be supplied by the run-time interpreter or development tool at the time the file name is actually used.

4.7.11 The SourceDebugExtension Attribute

The SourceDebugExtension attribute is an optional attribute in the attributes table of a ClassFile structure (4.1) in a version 49.0 or later class file.

There may be at most must be no more than one SourceDebugExtension attribute in the attributes table of a ClassFile structure.

The SourceDebugExtension attribute has the following format:

SourceDebugExtension_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u1 debug_extension[attribute_length];
}

The items of the SourceDebugExtension_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "SourceDebugExtension".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

debug_extension[]

The debug_extension array holds extended debugging information which has no semantic effect on the Java Virtual Machine. The information is represented using a modified UTF-8 string (4.4.7) with no terminating zero byte.

Note that the debug_extension array may denote a string longer than that which can be represented with an instance of class String.

4.7.12 The LineNumberTable Attribute

The LineNumberTable attribute is an optional variable-length attribute in the attributes table of a Code attribute (4.7.3). It may be used by debuggers to determine which part of the code array corresponds to a given line number in the original source file.

If multiple LineNumberTable attributes are present in the attributes table of a Code attribute, then they may appear in any order.

There may be more than one LineNumberTable attribute per line of a source file in the attributes table of a Code attribute. That is, LineNumberTable attributes may together represent a given line of a source file, and need not be one-to-one with source lines.

Multiple LineNumberTable attributes may be present in the attributes table of a Code attribute, and may appear in any order. Multiple LineNumberTable attributes may together represent a given line of a source file, and need not be one-to-one with source lines.

The LineNumberTable attribute has must have the following format:

LineNumberTable_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 line_number_table_length;
    {   u2 start_pc;
        u2 line_number;
    } line_number_table[line_number_table_length];
}

The items of the LineNumberTable_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "LineNumberTable".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

line_number_table_length

The value of the line_number_table_length item indicates the number of entries in the line_number_table array.

line_number_table[]

Each entry in the line_number_table array indicates that the line number in the original source file changes at a given point in the code array. Each line_number_table entry must contain the following two items:

start_pc

The value of the start_pc item must be a valid index into the code array of this Code attribute. The item indicates the index into the code array at which the code for a new line in the original source file begins.

line_number

The value of the line_number item gives the corresponding line number in the original source file.

4.7.13 The LocalVariableTable Attribute

The LocalVariableTable attribute is an optional variable-length attribute in the attributes table of a Code attribute (4.7.3). It may be used by debuggers to determine the value of a given local variable during the execution of a method.

If multiple LocalVariableTable attributes are present in the attributes table of a Code attribute, then they may appear in any order.

There may be no more than one LocalVariableTable attribute per local variable in the attributes table of a Code attribute.

Multiple LocalVariableTable attributes may be present in the attributes table of a Code attribute, and they may appear in any order. Each local variable in the source code should appear at most once in one of the LocalVariableTable attributes.

The LocalVariableTable attribute has must have the following format:

LocalVariableTable_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 local_variable_table_length;
    {   u2 start_pc;
        u2 length;
        u2 name_index;
        u2 descriptor_index;
        u2 index;
    } local_variable_table[local_variable_table_length];
}

The items of the LocalVariableTable_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "LocalVariableTable".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

local_variable_table_length

The value of the local_variable_table_length item indicates the number of entries in the local_variable_table array.

local_variable_table[]

Each entry in the local_variable_table array indicates a range of code array offsets within which a local variable has a value, and indicates the index into the local variable array of the current frame at which that local variable can be found. Each entry must contain the following five items:

start_pc, length

The value of the start_pc item must be a valid index into the code array of this Code attribute and must be the index of the opcode of an instruction.

The value of start_pc + length must either be a valid index into the code array of this Code attribute and be the index of the opcode of an instruction, or it must be the first index beyond the end of that code array.

The start_pc and length items indicate that the given local variable has a value at indices into the code array in the interval [start_pc, start_pc + length), that is, between start_pc inclusive and start_pc + length exclusive.

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must contain a CONSTANT_Utf8_info structure representing a valid unqualified name denoting a local variable (4.2.2).

descriptor_index

The value of the descriptor_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must contain a CONSTANT_Utf8_info structure representing a field descriptor which encodes the type of a local variable in the source program (4.3.2).

index

The value of the index item must be a valid index into the local variable array of the current frame. The given local variable is at index in the local variable array of the current frame.

If the given local variable is of type double or long, it occupies both index and index + 1.

4.7.14 The LocalVariableTypeTable Attribute

The LocalVariableTypeTable attribute is an optional variable-length attribute in the attributes table of a Code attribute (4.7.3) in a version 49.0 or later class file. It may be used by debuggers to determine the value of a given local variable during the execution of a method.

If multiple LocalVariableTypeTable attributes are present in the attributes table of a given Code attribute, then they may appear in any order.

There may be no more than one LocalVariableTypeTable attribute per local variable in the attributes table of a Code attribute.

Multiple LocalVariableTypeTable attributes may be present in the attributes table of a Code attribute, and they may appear in any order. Each local variable in the source code should appear at most once in one of the LocalVariableTypeTable attributes.

The LocalVariableTypeTable attribute differs from the LocalVariableTable attribute (4.7.13) in that it provides signature information rather than descriptor information. This difference is only significant for variables whose type uses a type variable or parameterized type. Such variables will should appear in both tables, while variables of other types will might appear only in LocalVariableTable.

The LocalVariableTypeTable attribute has must have the following format:

LocalVariableTypeTable_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 local_variable_type_table_length;
    {   u2 start_pc;
        u2 length;
        u2 name_index;
        u2 signature_index;
        u2 index;
    } local_variable_type_table[local_variable_type_table_length];
}

The items of the LocalVariableTypeTable_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "LocalVariableTypeTable".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

local_variable_type_table_length

The value of the local_variable_type_table_length item indicates the number of entries in the local_variable_type_table array.

local_variable_type_table[]

Each entry in the local_variable_type_table array indicates a range of code array offsets within which a local variable has a value, and indicates the index into the local variable array of the current frame at which that local variable can be found. Each entry must contain the following five items:

start_pc, length

The value of the start_pc item must be a valid index into the code array of this Code attribute and must be the index of the opcode of an instruction.

The value of start_pc + length must either be a valid index into the code array of this Code attribute and be the index of the opcode of an instruction, or it must be the first index beyond the end of that code array.

The start_pc and length items indicate that the given local variable has a value at indices into the code array in the interval [start_pc, start_pc + length), that is, between start_pc inclusive and start_pc + length exclusive.

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must contain a CONSTANT_Utf8_info structure representing a valid unqualified name denoting a local variable (4.2.2).

signature_index

The value of the signature_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must contain a CONSTANT_Utf8_info structure representing a field signature which encodes the type of a local variable in the source program (4.7.9.1).

index

The value of the index item must be a valid index into the local variable array of the current frame. The given local variable is at index in the local variable array of the current frame.

If the given local variable is of type double or long, it occupies both index and index + 1.

4.7.15 The Deprecated Attribute

The Deprecated attribute is an optional fixed-length attribute in the attributes table of a ClassFile, field_info, or method_info structure (4.1, 4.5, 4.6). A class, interface, method, or field may be marked using a Deprecated attribute to indicate that the class, interface, method, or field has been superseded.

There must not be a Deprecated attribute in the attributes table of a ClassFile structure representing a module.

A run-time interpreter or tool that reads the class file format, such as a compiler, can use this marking to advise the user that a superseded class, interface, method, or field is being referred to. The presence of a Deprecated attribute does not alter the semantics of a class or interface.

The Deprecated attribute has must have the following format:

Deprecated_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
}

The items of the Deprecated_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "Deprecated".

attribute_length

The value of the attribute_length item must be zero.

4.7.16 The RuntimeVisibleAnnotations Attribute

The RuntimeVisibleAnnotations attribute is a variable-length attribute in the attributes table of a ClassFile, field_info, or method_info structure (4.1, 4.5, 4.6) in a version 49.0 or later class file. The RuntimeVisibleAnnotations attribute records run-time visible annotations on the declaration of the corresponding class, field, or method.

There may be at most must be no more than one RuntimeVisibleAnnotations attribute in the attributes table of a ClassFile, field_info, or method_info structure.

The RuntimeVisibleAnnotations attribute has should have the following format:

RuntimeVisibleAnnotations_attribute {
    u2         attribute_name_index;
    u4         attribute_length;
    u2         num_annotations;
    annotation annotations[num_annotations];
}

The items of the RuntimeVisibleAnnotations_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "RuntimeVisibleAnnotations".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

num_annotations

The value of the num_annotations item gives should give the number of run-time visible annotations represented by the structure.

annotations[]

Each entry in the annotations table represents should represent a single run-time visible annotation on a declaration. The annotation structure has the following format:

annotation {
    u2 type_index;
    u2 num_element_value_pairs;
    {   u2            element_name_index;
        element_value value;
    } element_value_pairs[num_element_value_pairs];
}

The items of the annotation structure are as follows:

type_index

The value of the type_index item must should be a valid index into the constant_pool table. The constant_pool entry at that index must should be a CONSTANT_Utf8_info structure (4.4.7) representing a field descriptor (4.3.2). The field descriptor denotes the type of the annotation represented by this annotation structure.

num_element_value_pairs

The value of the num_element_value_pairs item gives should give the number of element-value pairs of the annotation represented by this annotation structure.

element_value_pairs[]

Each value of the element_value_pairs table represents a single element-value pair in the annotation represented by this annotation structure. Each element_value_pairs entry contains should contain the following two items:

element_name_index

The value of the element_name_index item must should be a valid index into the constant_pool table. The constant_pool entry at that index must should be a CONSTANT_Utf8_info structure (4.4.7). The constant_pool entry denotes the name of the element of the element-value pair represented by this element_value_pairs entry.

In other words, the entry denotes an element of the annotation type specified by type_index.

value

The value of the value item represents the value of the element-value pair represented by this element_value_pairs entry.

4.7.16.1 The element_value structure

The element_value structure is a discriminated union representing the value of an element-value pair. It has the following format:

element_value {
    u1 tag;
    union {
        u2 const_value_index;

        {   u2 type_name_index;
            u2 const_name_index;
        } enum_const_value;

        u2 class_info_index;

        annotation annotation_value;

        {   u2            num_values;
            element_value values[num_values];
        } array_value;
    } value;
}

The tag item uses a single ASCII character to indicate the type of the value of the element-value pair. This determines which item of the value union is in use. Table 4.7.16.1-A shows the valid characters for the tag item, the type indicated by each character, and the item used in the value union for each character. The table's fourth column is used in the description below of one item of the value union.

Table 4.7.16.1-A. Interpretation of tag values as types

tag Item Type value Item Constant Type
B byte const_value_index CONSTANT_Integer
C char const_value_index CONSTANT_Integer
D double const_value_index CONSTANT_Double
F float const_value_index CONSTANT_Float
I int const_value_index CONSTANT_Integer
J long const_value_index CONSTANT_Long
S short const_value_index CONSTANT_Integer
Z boolean const_value_index CONSTANT_Integer
s String const_value_index CONSTANT_Utf8
e Enum type enum_const_value Not applicable
c Class class_info_index Not applicable
@ Annotation type annotation_value Not applicable
[ Array type array_value Not applicable

The value item represents the value of an element-value pair. The item is a union, whose own items are as follows:

const_value_index

The const_value_index item denotes either a primitive constant value or a String literal as the value of this element-value pair.

The value of the const_value_index item must should be a valid index into the constant_pool table. The constant_pool entry at that index must should be of a type appropriate to the tag item, as specified in the fourth column of Table 4.7.16.1-A.

enum_const_value

The enum_const_value item denotes an enum constant as the value of this element-value pair.

The enum_const_value item consists of the following two items:

type_name_index

The value of the type_name_index item must should be a valid index into the constant_pool table. The constant_pool entry at that index must should be a CONSTANT_Utf8_info structure (4.4.7) representing a field descriptor (4.3.2). The constant_pool entry gives the internal form of the binary name of the type of the enum constant represented by this element_value structure (4.2.1).

const_name_index

The value of the const_name_index item must should be a valid index into the constant_pool table. The constant_pool entry at that index must should be a CONSTANT_Utf8_info structure (4.4.7). The constant_pool entry gives the simple name of the enum constant represented by this element_value structure.

class_info_index

The class_info_index item denotes a class literal as the value of this element-value pair.

The class_info_index item must should be a valid index into the constant_pool table. The constant_pool entry at that index must should be a CONSTANT_Utf8_info structure (4.4.7) representing a return descriptor (4.3.3). The return descriptor gives the type corresponding to the class literal represented by this element_value structure. Types correspond to class literals as follows:

  • For a class literal C.class, where C is the name of a class, interface, or array type, the corresponding type is C. The return descriptor in the constant_pool will should be an ObjectType or an ArrayType.

  • For a class literal p.class, where p is the name of a primitive type, the corresponding type is p. The return descriptor in the constant_pool will should be a BaseType character.

  • For a class literal void.class, the corresponding type is void. The return descriptor in the constant_pool will should be V.

For example, the class literal Object.class corresponds to the type Object, so the constant_pool entry is Ljava/lang/Object;, whereas the class literal int.class corresponds to the type int, so the constant_pool entry is I.

The class literal void.class corresponds to void, so the constant_pool entry is V, whereas the class literal Void.class corresponds to the type Void, so the constant_pool entry is Ljava/lang/Void;.

annotation_value

The annotation_value item denotes a "nested" annotation as the value of this element-value pair.

The value of the annotation_value item is should be an annotation structure (4.7.16) that gives the annotation represented by this element_value structure.

array_value

The array_value item denotes an array as the value of this element-value pair.

The array_value item consists should consist of the following two items:

num_values

The value of the num_values item gives should give the number of elements in the array represented by this element_value structure.

values[]

Each value in the values table gives should give the corresponding element of the array represented by this element_value structure.

4.7.17 The RuntimeInvisibleAnnotations Attribute

The RuntimeInvisibleAnnotations attribute is a variable-length attribute in the attributes table of a ClassFile, field_info, or method_info structure (4.1, 4.5, 4.6) in a version 49.0 or later class file. The RuntimeInvisibleAnnotations attribute records run-time invisible annotations on the declaration of the corresponding class, method, or field.

There may be at most must be no more than one RuntimeInvisibleAnnotations attribute in the attributes table of a ClassFile, field_info, or method_info structure.

The RuntimeInvisibleAnnotations attribute is similar to the RuntimeVisibleAnnotations attribute (4.7.16), except that the annotations represented by a RuntimeInvisibleAnnotations attribute must not be are not made available for return by reflective APIs, unless the Java Virtual Machine has been instructed to retain these annotations via some implementation-specific mechanism such as a command line flag. In the absence of such instructions, the Java Virtual Machine ignores this attribute.

The RuntimeInvisibleAnnotations attribute has should have the following format:

RuntimeInvisibleAnnotations_attribute {
    u2         attribute_name_index;
    u4         attribute_length;
    u2         num_annotations;
    annotation annotations[num_annotations];
}

The items of the RuntimeInvisibleAnnotations_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "RuntimeInvisibleAnnotations".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

num_annotations

The value of the num_annotations item gives should give the number of run-time invisible annotations represented by the structure.

annotations[]

Each entry in the annotations table represents should represent a single run-time invisible annotation on a declaration. The annotation structure is specified in 4.7.16.

4.7.18 The RuntimeVisibleParameterAnnotations Attribute

The RuntimeVisibleParameterAnnotations attribute is a variable-length attribute in the attributes table of the method_info structure (4.6) in a version 49.0 or later class file. The RuntimeVisibleParameterAnnotations attribute records run-time visible annotations on the declarations of formal parameters of the corresponding method.

There may be at most must be no more than one RuntimeVisibleParameterAnnotations attribute in the attributes table of a method_info structure.

The RuntimeVisibleParameterAnnotations attribute has should have the following format:

RuntimeVisibleParameterAnnotations_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u1 num_parameters;
    {   u2         num_annotations;
        annotation annotations[num_annotations];
    } parameter_annotations[num_parameters];
}

The items of the RuntimeVisibleParameterAnnotations_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "RuntimeVisibleParameterAnnotations".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

num_parameters

The value of the num_parameters item gives should give the number of run-time visible parameter annotations represented by this structure.

There is no assurance that this number is the same as the number of parameter descriptors in the method descriptor.

parameter_annotations[]

Each entry in the parameter_annotations table represents should represent all of the run-time visible annotations on the declaration of a single formal parameter. Each parameter_annotations entry contains should contain the following two items:

num_annotations

The value of the num_annotations item indicates should indicate the number of run-time visible annotations on the declaration of the formal parameter corresponding to the parameter_annotations entry.

annotations[]

Each entry in the annotations table represents should represent a single run-time visible annotation on the declaration of the formal parameter corresponding to the parameter_annotations entry. The annotation structure is specified in 4.7.16.

The i'th entry in the parameter_annotations table may, but is not required to, correspond to the i'th parameter descriptor in the method descriptor (4.3.3).

For example, a compiler may choose to create entries in the table corresponding only to those parameter descriptors which represent explicitly declared parameters in source code. In the Java programming language, a constructor of an inner class is specified to have an implicitly declared parameter before its explicitly declared parameters (JLS §8.8.1), so the corresponding <init> method in a class file has a parameter descriptor representing the implicitly declared parameter before any parameter descriptors representing explicitly declared parameters. If the first explicitly declared parameter is annotated in source code, then a compiler may create parameter_annotations[0] to store annotations corresponding to the second parameter descriptor.

4.7.19 The RuntimeInvisibleParameterAnnotations Attribute

The RuntimeInvisibleParameterAnnotations attribute is a variable-length attribute in the attributes table of a method_info structure (4.6) in a version 49.0 or later class file. The RuntimeInvisibleParameterAnnotations attribute records run-time invisible annotations on the declarations of formal parameters of the corresponding method.

There may be at most must be no more than one RuntimeInvisibleParameterAnnotations attribute in the attributes table of a method_info structure.

The RuntimeInvisibleParameterAnnotations attribute is similar to the RuntimeVisibleParameterAnnotations attribute (4.7.18), except that the annotations represented by a RuntimeInvisibleParameterAnnotations attribute must not be are not made available for return by reflective APIs, unless the Java Virtual Machine has specifically been instructed to retain these annotations via some implementation-specific mechanism such as a command line flag. In the absence of such instructions, the Java Virtual Machine ignores this attribute.

The RuntimeInvisibleParameterAnnotations attribute has should have the following format:

RuntimeInvisibleParameterAnnotations_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u1 num_parameters;
    {   u2         num_annotations;
        annotation annotations[num_annotations];
    } parameter_annotations[num_parameters];
}

The items of the RuntimeInvisibleParameterAnnotations_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "RuntimeInvisibleParameterAnnotations".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

num_parameters

The value of the num_parameters item gives should give the number of run-time invisible parameter annotations represented by this structure.

There is no assurance that this number is the same as the number of parameter descriptors in the method descriptor.

parameter_annotations[]

Each entry in the parameter_annotations table represents should represent all of the run-time invisible annotations on the declaration of a single formal parameter. Each parameter_annotations entry contains should contain the following two items:

num_annotations

The value of the num_annotations item indicates should indicate the number of run-time invisible annotations on the declaration of the formal parameter corresponding to the parameter_annotations entry.

annotations[]

Each entry in the annotations table represents should represent a single run-time invisible annotation on the declaration of the formal parameter corresponding to the parameter_annotations entry. The annotation structure is specified in 4.7.16.

The i'th entry in the parameter_annotations table may, but is not required to, correspond to the i'th parameter descriptor in the method descriptor (4.3.3).

See the note in 4.7.18 for an example of when parameter_annotations[0] does not correspond to the first parameter descriptor in the method descriptor.

4.7.20 The RuntimeVisibleTypeAnnotations Attribute

The RuntimeVisibleTypeAnnotations attribute is an a variable-length attribute in the attributes table of a ClassFile, field_info, or method_info structure, or Code attribute (4.1, 4.5, 4.6, 4.7.3) in a version 52.0 or later class file. The RuntimeVisibleTypeAnnotations attribute records run-time visible annotations on types used in the declaration of the corresponding class, field, or method, or in an expression in the corresponding method body. The RuntimeVisibleTypeAnnotations attribute also records run-time visible annotations on type parameter declarations of generic classes, interfaces, methods, and constructors.

There may be at most must be no more than one RuntimeVisibleTypeAnnotations attribute in the attributes table of a ClassFile, field_info, or method_info structure, or Code attribute. There must not be a RuntimeVisibleTypeAnnotations attribute in the attributes table of a ClassFile structure representing a module.

An attributes table contains should contain a RuntimeVisibleTypeAnnotations attribute only if types are annotated in kinds of declaration or expression that correspond to the parent structure or attribute of the attributes table.

For example, all annotations on types in the implements clause of a class declaration are recorded in the RuntimeVisibleTypeAnnotations attribute of the class's ClassFile structure. Meanwhile, all annotations on the type in a field declaration are recorded in the RuntimeVisibleTypeAnnotations attribute of the field's field_info structure.

The RuntimeVisibleTypeAnnotations attribute has the following format:

RuntimeVisibleTypeAnnotations_attribute {
    u2              attribute_name_index;
    u4              attribute_length;
    u2              num_annotations;
    type_annotation annotations[num_annotations];
}

The items of the RuntimeVisibleTypeAnnotations_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure representing the string "RuntimeVisibleTypeAnnotations".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

num_annotations

The value of the num_annotations item gives should give the number of run-time visible type annotations represented by the structure.

annotations[]

Each entry in the annotations table represents a single run-time visible annotation on a type used in a declaration or expression. The type_annotation structure has should have the following format:

type_annotation {
    u1 target_type;
    union {
        type_parameter_target;
        supertype_target;
        type_parameter_bound_target;
        empty_target;
        formal_parameter_target;
        throws_target;
        localvar_target;
        catch_target;
        offset_target;
        type_argument_target;
    } target_info;
    type_path target_path;
    u2        type_index;
    u2        num_element_value_pairs;
    {   u2            element_name_index;
        element_value value;
    } element_value_pairs[num_element_value_pairs];
}

The first three items - target_type, target_info, and target_path - specify the precise location of the annotated type. The last three items - type_index, num_element_value_pairs, and element_value_pairs[] - specify the annotation's own type and element-value pairs.

The items of the type_annotation structure are as follows:

target_type

The value of the target_type item denotes should denote the kind of target on which the annotation appears. The various kinds of target correspond to the type contexts of the Java programming language where types are used in declarations and expressions (JLS §4.11).

The legal supported values of target_type are specified in Table 4.7.20-A and Table 4.7.20-B. Each value is a one-byte tag indicating which item of the target_info union follows the target_type item to give more information about the target.

The kinds of target in Table 4.7.20-A and Table 4.7.20-B correspond to the type contexts in JLS §4.11. Namely, target_type values 0x10-0x17 and 0x40-0x42 correspond to type contexts 1-10, while target_type values 0x43-0x4B correspond to type contexts 11-16.

The value of the target_type item determines whether the type_annotation structure appears should appear in a RuntimeVisibleTypeAnnotations attribute in a ClassFile structure, a field_info structure, a method_info structure, or a Code attribute. Table 4.7.20-C gives the location of the RuntimeVisibleTypeAnnotations attribute for a type_annotation structure with each legal supported target_type value.

target_info

The value of the target_info item denotes should denote precisely which type in a declaration or expression is annotated.

The items of the target_info union are specified in 4.7.20.1.

target_path

The value of the target_path item denotes should denote precisely which part of the type indicated by target_info is annotated.

The format of the type_path structure is specified in 4.7.20.2.

type_index, num_element_value_pairs, element_value_pairs[]

The meaning of these items in the type_annotation structure is the same as their meaning in the annotation structure (4.7.16).

Table 4.7.20-A. Interpretation of target_type values (Part 1)

Value Kind of target target_info item
0x00 type parameter declaration of generic class or interface type_parameter_target
0x01 type parameter declaration of generic method or constructor type_parameter_target
0x10 type in extends or implements clause of class declaration (including the direct superclass or direct superinterface of an anonymous class declaration), or in extends clause of interface declaration supertype_target
0x11 type in bound of type parameter declaration of generic class or interface type_parameter_bound_target
0x12 type in bound of type parameter declaration of generic method or constructor type_parameter_bound_target
0x13 type in field declaration empty_target
0x14 return type of method, or type of newly constructed object empty_target
0x15 receiver type of method or constructor empty_target
0x16 type in formal parameter declaration of method, constructor, or lambda expression formal_parameter_target
0x17 type in throws clause of method or constructor throws_target

Table 4.7.20-B. Interpretation of target_type values (Part 2)

Value Kind of target target_info item
0x40 type in local variable declaration localvar_target
0x41 type in resource variable declaration localvar_target
0x42 type in exception parameter declaration catch_target
0x43 type in instanceof expression offset_target
0x44 type in new expression offset_target
0x45 type in method reference expression using ::new offset_target
0x46 type in method reference expression using ::Identifier offset_target
0x47 type in cast expression type_argument_target
0x48 type argument for generic constructor in new expression or explicit constructor invocation statement type_argument_target
0x49 type argument for generic method in method invocation expression type_argument_target
0x4A type argument for generic constructor in method reference expression using ::new type_argument_target
0x4B type argument for generic method in method reference expression using ::Identifier type_argument_target

Table 4.7.20-C. Location of enclosing attribute for target_type values

Value Kind of target Location
0x00 type parameter declaration of generic class or interface ClassFile
0x01 type parameter declaration of generic method or constructor method_info
0x10 type in extends clause of class or interface declaration, or in implements clause of interface declaration ClassFile
0x11 type in bound of type parameter declaration of generic class or interface ClassFile
0x12 type in bound of type parameter declaration of generic method or constructor method_info
0x13 type in field declaration field_info
0x14 return type of method or constructor method_info
0x15 receiver type of method or constructor method_info
0x16 type in formal parameter declaration of method, constructor, or lambda expression method_info
0x17 type in throws clause of method or constructor method_info
0x40-0x4B types in local variable declarations, resource variable declarations, exception parameter declarations, expressions Code
4.7.20.1 The target_info union

The items of the target_info union (except for the first) specify precisely which type in a declaration or expression is annotated. The first item specifies not which type, but rather which declaration of a type parameter is annotated. The items are as follows:

4.7.20.2 The type_path structure

Wherever a type is used in a declaration or expression, the type_path structure identifies which part of the type is annotated. An annotation may appear on the type itself, but if the type is a reference type, then there are additional locations where an annotation may appear:

For example, consider the different parts of String[][] that are annotated in:

@Foo String[][]   // Annotates the class type String
String @Foo [][]  // Annotates the array type String[][]
String[] @Foo []  // Annotates the array type String[]

or the different parts of the nested type Outer.Middle.Inner that are annotated in:

@Foo Outer.Middle.Inner
Outer.@Foo Middle.Inner
Outer.Middle.@Foo Inner

or the different parts of the parameterized types Map<String,Object> and List<...> that are annotated in:

@Foo Map<String,Object>
Map<@Foo String,Object>
Map<String,@Foo Object>

List<@Foo ? extends String>
List<? extends @Foo String>

The type_path structure has the following format:

type_path {
    u1 path_length;
    {   u1 type_path_kind;
        u1 type_argument_index;
    } path[path_length];
}

The value of the path_length item gives the number of entries in the path array:

Table 4.7.20.2-B. type_path structures for @A Map<@B ? extends @C String, @D List<@E Object>>

Annotation path_length path
@A 0 []
@B 1 [{type_path_kind: 3; type_argument_index: 0}]
@C 2 [{type_path_kind: 3; type_argument_index: 0}, {type_path_kind: 2; type_argument_index: 0}]
@D 1 [{type_path_kind: 3; type_argument_index: 1}]
@E 2 [{type_path_kind: 3; type_argument_index: 1}, {type_path_kind: 3; type_argument_index: 0}]

Table 4.7.20.2-C. type_path structures for @I String @F [] @G [] @H []

Annotation path_length path
@F 0 []
@G 1 [{type_path_kind: 0; type_argument_index: 0}]
@H 2 [{type_path_kind: 0; type_argument_index: 0}, {type_path_kind: 0; type_argument_index: 0}]
@I 3 [{type_path_kind: 0; type_argument_index: 0}, {type_path_kind: 0; type_argument_index: 0}, {type_path_kind: 0; type_argument_index: 0}]

Table 4.7.20.2-D. type_path structures for @A List<@B Comparable<@F Object @C [] @D [] @E []>>

Annotation path_length path
@A 0 []
@B 1 [{type_path_kind: 3; type_argument_index: 0}]
@C 2 [{type_path_kind: 3; type_argument_index: 0}, {type_path_kind: 3; type_argument_index: 0}]
@D 3 [{type_path_kind: 3; type_argument_index: 0}, {type_path_kind: 3; type_argument_index: 0}, {type_path_kind: 0; type_argument_index: 0}]
@E 4 [{type_path_kind: 3; type_argument_index: 0}, {type_path_kind: 3; type_argument_index: 0}, {type_path_kind: 0; type_argument_index: 0}, {type_path_kind: 0; type_argument_index: 0}]
@F 5 [{type_path_kind: 3; type_argument_index: 0}, {type_path_kind: 3; type_argument_index: 0}, {type_path_kind: 0; type_argument_index: 0}, {type_path_kind: 0; type_argument_index: 0}, {type_path_kind: 0; type_argument_index: 0}]

Table 4.7.20.2-E. type_path structures for @A Outer . @B Middle . @C Inner

Assuming:

Annotation


path_length
class Outer { class Middle { class Inner {} } }
path
@A 0 []
@B 1 [{type_path_kind: 1; type_argument_index: 0}]
@C 2 [{type_path_kind: 1; type_argument_index: 0}, {type_path_kind: 1; type_argument_index: 0}]

Table 4.7.20.2-F. type_path structures for Outer . @A MiddleStatic . @B Inner

Assuming:

Annotation


path_length
class Outer { static class MiddleStatic { class Inner {} } }
path
@A 0 []
@B 1 [{type_path_kind: 1; type_argument_index: 0}]
In the type Outer . MiddleStatic . Inner, type annotations on the simple name Outer are not admissible because the type name to its right, MiddleStatic, does not refer to an inner class of Outer.

Table 4.7.20.2-G. type_path structures for Outer . MiddleStatic . @A InnerStatic

Assuming:

Annotation


path_length
class Outer { static class MiddleStatic { static class InnerStatic {} } }
path
@A 0 []
In the type Outer . MiddleStatic . InnerStatic, type annotations on the simple name Outer are not admissible because the type name to its right, MiddleStatic, does not refer to an inner class of Outer. Similarly, type annotations on the simple name MiddleStatic are not admissible because the type name to its right, InnerStatic, does not refer to an inner class of MiddleStatic.

Table 4.7.20.2-H. type_path structures for Outer . Middle<@A Foo . @B Bar> . Inner<@D String @C []>

Assuming:

Annotation


path_length
class Outer { class Middle<T> { class Inner<U> {} } }
path
@A 2 [{type_path_kind: 1; type_argument_index: 0}, {type_path_kind: 3; type_argument_index: 0}]
@B 3 [{type_path_kind: 1; type_argument_index: 0}, {type_path_kind: 3; type_argument_index: 0}, {type_path_kind: 1; type_argument_index: 0}]
@C 3 [{type_path_kind: 1; type_argument_index: 0}, {type_path_kind: 1; type_argument_index: 0}, {type_path_kind: 3; type_argument_index: 0}]
@D 4 [{type_path_kind: 1; type_argument_index: 0}, {type_path_kind: 1; type_argument_index: 0}, {type_path_kind: 3; type_argument_index: 0}, {type_path_kind: 0; type_argument_index: 0}]

4.7.21 The RuntimeInvisibleTypeAnnotations Attribute

The RuntimeInvisibleTypeAnnotations attribute is an a variable-length attribute in the attributes table of a ClassFile, field_info, or method_info structure, or Code attribute (4.1, 4.5, 4.6, 4.7.3) in a version 52.0 or later class file. The RuntimeInvisibleTypeAnnotations attribute records run-time invisible annotations on types used in the corresponding declaration of a class, field, or method, or in an expression in the corresponding method body. The RuntimeInvisibleTypeAnnotations attribute also records annotations on type parameter declarations of generic classes, interfaces, methods, and constructors.

There may be at most must be no more than one RuntimeInvisibleTypeAnnotations attribute in the attributes table of a ClassFile, field_info, or method_info structure, or Code attribute. There must not be a RuntimeInvisibleTypeAnnotations attribute in the attributes table of a ClassFile structure representing a module.

An attributes table contains should contain a RuntimeInvisibleTypeAnnotations attribute only if types are annotated in kinds of declaration or expression that correspond to the parent structure or attribute of the attributes table.

The RuntimeInvisibleTypeAnnotations attribute has should have the following format:

RuntimeInvisibleTypeAnnotations_attribute {
    u2              attribute_name_index;
    u4              attribute_length;
    u2              num_annotations;
    type_annotation annotations[num_annotations];
}

The items of the RuntimeInvisibleTypeAnnotations_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure representing the string "RuntimeInvisibleTypeAnnotations".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

num_annotations

The value of the num_annotations item gives should give the number of run-time invisible type annotations represented by the structure.

annotations[]

Each entry in the annotations table represents a single run-time invisible annotation on a type used in a declaration or expression. The type_annotation structure is specified in 4.7.20.

4.7.22 The AnnotationDefault Attribute

The AnnotationDefault attribute is a variable-length attribute in the attributes table of certain method_info structures (4.6), namely those representing elements of annotation types (JLS §9.6.1) a method_info structure (4.6) in a version 49.0 or later class file. The AnnotationDefault attribute records the default value (JLS §9.6.2) for the annotation element represented by the method_info structure.

There may be at most must be no more than one AnnotationDefault attribute in the attributes table of a method_info structure which represents an element of an annotation type.

It does not appear that these attributes have ever been prohibited or treated as nonstandard when they appear in non-annotation classes.

The AnnotationDefault attribute has should have the following format:

AnnotationDefault_attribute {
    u2            attribute_name_index;
    u4            attribute_length;
    element_value default_value;
}

The items of the AnnotationDefault_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "AnnotationDefault".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

default_value

The default_value item represents should represent the default value of the annotation type element represented by the method_info structure enclosing this AnnotationDefault attribute.

The element_value structure is specified in 4.7.16.1.

4.7.23 The BootstrapMethods Attribute

The BootstrapMethods attribute is a variable-length attribute in the attributes table of a ClassFile structure (4.1) in a version 51.0 or later class file. The BootstrapMethods attribute records bootstrap methods used to produce dynamically-computed constants and dynamically-computed call sites (4.4.10).

There must be exactly one BootstrapMethods attribute in the attributes table of a ClassFile structure if the constant_pool table of the ClassFile structure has at least one CONSTANT_Dynamic_info or CONSTANT_InvokeDynamic_info entry.

There may be at most must be no more than one BootstrapMethods attribute in the attributes table of a ClassFile structure representing a class or interface. There must not be a BootstrapMethods attribute in the attributes table of a ClassFile structure representing a module.

The BootstrapMethods attribute has must have the following format:

BootstrapMethods_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 num_bootstrap_methods;
    {   u2 bootstrap_method_ref;
        u2 num_bootstrap_arguments;
        u2 bootstrap_arguments[num_bootstrap_arguments];
    } bootstrap_methods[num_bootstrap_methods];
}

The items of the BootstrapMethods_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "BootstrapMethods".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

num_bootstrap_methods

The value of the num_bootstrap_methods item determines the number of bootstrap method specifiers in the bootstrap_methods array.

bootstrap_methods[]

Each entry in the bootstrap_methods table contains an index to a CONSTANT_MethodHandle_info structure which specifies a bootstrap method, and a sequence (perhaps empty) of indexes to static arguments for the bootstrap method.

Each bootstrap_methods entry must contain the following three items:

bootstrap_method_ref

The value of the bootstrap_method_ref item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_MethodHandle_info structure (4.4.8).

The method handle will be resolved during resolution of a dynamically-computed constant or call site (5.4.3.6), and then invoked as if by invocation of invokeWithArguments in java.lang.invoke.MethodHandle. The method handle must should be able to accept the array of arguments described in 5.4.3.6, or resolution will fail.

num_bootstrap_arguments

The value of the num_bootstrap_arguments item gives the number of items in the bootstrap_arguments array.

bootstrap_arguments[]

Each entry in the bootstrap_arguments array must be a valid index into the constant_pool table. The constant_pool entry at that index must be loadable (4.4).

4.7.24 The MethodParameters Attribute

The MethodParameters attribute is a variable-length attribute in the attributes table of a method_info structure (4.6) in a version 52.0 or later class file. A MethodParameters attribute records information about the formal parameters of a method, such as their names.

There may be at most must be no more than one MethodParameters attribute in the attributes table of a method_info structure.

The MethodParameters attribute has should have the following format:

MethodParameters_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u1 parameters_count;
    {   u2 name_index;
        u2 access_flags;
    } parameters[parameters_count];
}

The items of the MethodParameters_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "MethodParameters".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

parameters_count

The value of the parameters_count item indicates should indicate the number of parameter descriptors in the method descriptor (4.3.3) referenced by the descriptor_index of the attribute's enclosing method_info structure.

This is not a constraint which a Java Virtual Machine implementation must enforce during format checking (4.8). The task of matching parameter descriptors in a method descriptor against the items in the parameters array below is done by the reflection libraries of the Java SE Platform.

parameters[]

Each entry in the parameters array contains the following pair of items:

name_index

The value of the name_index item must should either be zero or a valid index into the constant_pool table.

If the value of the name_index item is zero, then this parameters element indicates a formal parameter with no name.

If the value of the name_index item is nonzero, the constant_pool entry at that index must should be a CONSTANT_Utf8_info structure representing a valid unqualified name denoting a formal parameter (4.2.2).

access_flags

The value of the access_flags item is should be a mask of flags, where the flags that are set are interpreted as follows:

0x0010 (ACC_FINAL)

Indicates that the formal parameter was declared final.

0x1000 (ACC_SYNTHETIC)

Indicates that the formal parameter was not explicitly or implicitly declared in source code, according to the specification of the language in which the source code was written (JLS §13.1). (The formal parameter is an implementation artifact of the compiler which produced this class file.)

0x8000 (ACC_MANDATED)

Indicates that the formal parameter was implicitly declared in source code, according to the specification of the language in which the source code was written (JLS §13.1). (The formal parameter is mandated by a language specification, so all compilers for the language must emit it.)

The i'th entry in the parameters array corresponds to the i'th parameter descriptor in the enclosing method's descriptor. (The parameters_count item is one byte because a method descriptor is limited to 255 parameters.) Effectively, this means the parameters array stores information for all the parameters of the method. One could imagine other schemes, where entries in the parameters array specify their corresponding parameter descriptors, but it would unduly complicate the MethodParameters attribute.

The i'th entry in the parameters array may or may not correspond to the i'th type in the enclosing method's Signature attribute (if present), or to the i'th annotation in the enclosing method's parameter annotations.

4.7.25 The Module Attribute

The Module attribute is a variable-length attribute in the attributes table of a ClassFile structure (4.1) in a version 53.0 or later class file. The Module attribute indicates the modules required by a module; the packages exported and opened by a module; and the services used and provided by a module.

There may be at most must be exactly one Module attribute in the attributes table of a ClassFile structure representing a module. There must not be a Module attribute in the attributes table of a ClassFile structure representing a class or interface.

The Module attribute has must have the following format:

Module_attribute {
    u2 attribute_name_index;
    u4 attribute_length;

    u2 module_name_index;
    u2 module_flags;
    u2 module_version_index;

    u2 requires_count;
    {   u2 requires_index;
        u2 requires_flags;
        u2 requires_version_index;
    } requires[requires_count];

    u2 exports_count;
    {   u2 exports_index;
        u2 exports_flags;
        u2 exports_to_count;
        u2 exports_to_index[exports_to_count];
    } exports[exports_count];

    u2 opens_count;
    {   u2 opens_index;
        u2 opens_flags;
        u2 opens_to_count;
        u2 opens_to_index[opens_to_count];
    } opens[opens_count];

    u2 uses_count;
    u2 uses_index[uses_count];

    u2 provides_count;
    {   u2 provides_index;
        u2 provides_with_count;
        u2 provides_with_index[provides_with_count];
    } provides[provides_count];
}

The items of the Module_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "Module".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

module_name_index

The value of the module_name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Module_info structure (4.4.11).

denoting The module_name_index item denotes the current module.

module_flags

The value of the module_flags item is a mask of flags, where the flags that are set are interpreted as follows:

0x0020 (ACC_OPEN)

Indicates that this module is open.

0x1000 (ACC_SYNTHETIC)

Indicates that this module was not explicitly or implicitly declared.

0x8000 (ACC_MANDATED)

Indicates that this module was implicitly declared.

module_version_index

The value of the module_version_index item must be either zero or a valid index into the constant_pool table. If the value of the item is zero, then no version information about the current module is present. If the value of the item is nonzero, then the constant_pool entry at that index must be a CONSTANT_Utf8_info structure.

representing The module_version_index item represents the version of the current module.

requires_count

The value of the requires_count item indicates the number of entries in the requires table.

If the current module is java.base, then requires_count must be zero.

If the current module is not java.base, then requires_count must be at least one.

requires[]

Each entry in the requires table specifies a dependence of the current module. The items in each entry are as follows:

requires_index

The value of the requires_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Module_info structure.

denoting The requires_index item denotes a module on which the current module depends.

At most one entry in the requires table may specify a module of a given name with its requires_index item.

requires_flags

The value of the requires_flags item is a mask of flags, where the flags that are set are interpreted as follows:

0x0020 (ACC_TRANSITIVE)

Indicates that any module which depends on the current module, implicitly declares a dependence on the module indicated by this entry.

0x0040 (ACC_STATIC_PHASE)

Indicates that this dependence is mandatory in the static phase, i.e., at compile time, but is optional in the dynamic phase, i.e., at run time.

0x1000 (ACC_SYNTHETIC)

Indicates that this dependence was not explicitly or implicitly declared in the source of the module declaration.

0x8000 (ACC_MANDATED)

Indicates that this dependence was implicitly declared in the source of the module declaration.

If the current module is not java.base, and the class file version number is 54.0 or above, then neither ACC_TRANSITIVE nor ACC_STATIC_PHASE may be set in requires_flags.

requires_version_index

The value of the requires_version_index item must be either zero or a valid index into the constant_pool table. If the value of the item is zero, then no version information about the dependence is present. If the value of the item is nonzero, then the constant_pool entry at that index must be a CONSTANT_Utf8_info structure.

representing The requires_version_index item represents the version of the module specified by requires_index.

Unless the current module is java.base, exactly one entry in the requires table must have both a requires_index item which indicates java.base and a requires_flags item which has the ACC_SYNTHETIC flag not set.

exports_count

The value of the exports_count item indicates the number of entries in the exports table.

exports[]

Each entry in the exports table specifies a package exported by the current module, such that public and protected types in the package, and their public and protected members, may be accessed from outside the current module, possibly from a limited set of "friend" modules.

The items in each entry are as follows:

exports_index

The value of the exports_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Package_info structure (4.4.12).

representing The exports_index item represents a package exported by the current module.

At most one entry in the exports table may specify a package of a given name with its exports_index item.

exports_flags

The value of the exports_flags item is a mask of flags, where the flags that are set are interpreted as follows:

0x1000 (ACC_SYNTHETIC)

Indicates that this export was not explicitly or implicitly declared in the source of the module declaration.

0x8000 (ACC_MANDATED)

Indicates that this export was implicitly declared in the source of the module declaration.

exports_to_count

The value of the exports_to_count indicates the number of entries in the exports_to_index table.

If exports_to_count is zero, then this package is exported by the current module in an unqualified fashion; code in any other module may access the types and members in the package.

If exports_to_count is nonzero, then this package is exported by the current module in a qualified fashion; only code in the modules listed in the exports_to_index table may access the types and members in the package.

exports_to_index[]

The value of each entry in the exports_to_index table must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Module_info structure.

denoting Each entry denotes a module whose code can access the types and members in this exported package.

For each entry in the exports table, at most one entry in its exports_to_index table may specify a module of a given name.

opens_count

The value of the opens_count item indicates the number of entries in the opens table.

opens_count must be zero if the current module is open.

opens[]

Each entry in the opens table specifies a package opened by the current module, such that all types in the package, and all their members, may be accessed from outside the current module via the reflection libraries of the Java SE Platform, possibly from a limited set of "friend" modules.

The items in each entry are as follows:

opens_index

The value of the opens_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Package_info structure.

representing The opens_index item represents a package opened by the current module.

At most one entry in the opens table may specify a package of a given name with its opens_index item.

opens_flags

The value of the opens_flags item is a mask of flags, where the flags that are set are interpreted as follows:

0x1000 (ACC_SYNTHETIC)

Indicates that this opening was not explicitly or implicitly declared in the source of the module declaration.

0x8000 (ACC_MANDATED)

Indicates that this opening was implicitly declared in the source of the module declaration.

opens_to_count

The value of the opens_to_count indicates the number of entries in the opens_to_index table.

If opens_to_count is zero, then this package is opened by the current module in an unqualified fashion; code in any other module may reflectively access the types and members in the package.

If opens_to_count is nonzero, then this package is opened by the current module in a qualified fashion; only code in the modules listed in the exports_to_index table may reflectively access the types and members in the package.

opens_to_index[]

The value of each entry in the opens_to_index table must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Module_info structure.

denoting Each entry denotes a module whose code can access the types and members in this opened package.

For each entry in the opens table, at most one entry in its opens_to_index table may specify a module of a given name.

uses_count

The value of the uses_count item indicates the number of entries in the uses_index table.

uses_index[]

The value of each entry in the uses_index table must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure (4.4.1).

representing Each entry represents a service interface which the current module may discover via java.util.ServiceLoader.

At most one entry in the uses_index table may specify a service interface of a given name.

provides_count

The value of the provides_count item indicates the number of entries in the provides table.

provides[]

Each entry in the provides table represents a service implementation for a given service interface.

The items in each entry are as follows:

provides_index

The value of the provides_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure.

representing The provides_index item represents a service interface for which the current module provides a service implementation.

At most one entry in the provides table may specify a service interface of a given name with its provides_index item.

provides_with_count

The value of the provides_with_count indicates the number of entries in the provides_with_index table.

provides_with_count must be nonzero.

provides_with_index[]

The value of each entry in the provides_with_index table must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure.

representing Each entry represents a service implementation for the service interface specified by provides_index.

For each entry in the provides table, at most one entry in its provides_with_index table may specify a service implementation of a given name.

4.7.26 The ModulePackages Attribute

The ModulePackages attribute is a variable-length attribute in the attributes table of a ClassFile structure (4.1) in a version 53.0 or later class file. The ModulePackages attribute indicates all the packages of a module that are exported or opened by the Module attribute, as well as all the packages of the service implementations recorded in the Module attribute. The ModulePackages attribute may also indicate packages in the module that are neither exported nor opened nor contain service implementations.

There may be at most must be no more than one ModulePackages attribute in the attributes table of a ClassFile structure representing a module. There must not be a ModulePackages attribute in the attributes table of a ClassFile structure representing a class or interface.

The ModulePackages attribute has must have the following format:

ModulePackages_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 package_count;
    u2 package_index[package_count];
}

The items of the ModulePackages_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "ModulePackages".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

package_count

The value of the package_count item indicates must indicate the number of entries in the package_index table.

package_index[]

The value of each entry in the package_index table must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Package_info structure (4.4.12).

representing Each entry represents a package in the current module.

At most one entry in the package_index table may specify a package of a given name.

4.7.27 The ModuleMainClass Attribute

The ModuleMainClass attribute is a fixed-length attribute in the attributes table of a ClassFile structure (4.1) in a version 53.0 or later class file. The ModuleMainClass attribute indicates the main class of a module.

There may be at most must be no more than one ModuleMainClass attribute in the attributes table of a ClassFile structure representing a module. There must not be a ModuleMainClass attribute in the attributes table of a ClassFile structure representing a class or interface.

The ModuleMainClass attribute has must have the following format:

ModuleMainClass_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 main_class_index;
}

The items of the ModuleMainClass_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "ModuleMainClass".

attribute_length

The value of the attribute_length item must be two.

main_class_index

The value of the main_class_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure (4.4.1).

representing The main_class_index item represents the main class of the current module.

4.7.28 The NestHost Attribute

The NestHost attribute is a fixed-length attribute in the attributes table of a ClassFile structure in a version 55.0 or later class file. The NestHost attribute records the nest host of the nest to which the current class or interface claims to belong (5.4.4).

There may be at most must be no more than one NestHost attribute in the attributes table of a ClassFile structure representing a class or interface. There must not be a NestHost attribute in the attributes table of a ClassFile structure representing a module.

The NestHost attribute has must have the following format:

NestHost_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 host_class_index;
}

The items of the NestHost_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "NestHost".

attribute_length

The value of the attribute_length item must be two.

host_class_index

The value of the host_class_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure (4.4.1).

representing The host_class_index item represents a class or interface which is the nest host for the current class or interface.

If the nest host cannot be loaded, or is not in the same run-time package as the current class or interface, or does not authorize nest membership for the current class or interface, then an error may occur during access control (5.4.4).

4.7.29 The NestMembers Attribute

The NestMembers attribute is a variable-length attribute in the attributes table of a ClassFile structure (4.1) in a version 55.0 or later class file. The NestMembers attribute records the classes and interfaces that are authorized to claim membership in the nest hosted by the current class or interface (5.4.4).

There may be at most must be no more than one NestMembers attribute in the attributes table of a ClassFile structure representing a class or interface. There must not be a NestMembers attribute in the attributes table of a ClassFile structure representing a module.

The attributes table of a ClassFile structure must not contain both a NestMembers attribute and a NestHost attribute.

This rule prevents a nest host from claiming membership in a different nest. It is implicitly a member of the nest that it hosts.

The NestMembers attribute has must have the following format:

NestMembers_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 number_of_classes;
    u2 classes[number_of_classes];
}

The items of the NestMembers_attribute structure are as follows:

attribute_name_index

The value of the attribute_name_index item must be a valid is an index into the constant_pool table. The constant_pool entry at that index must be is a CONSTANT_Utf8_info structure (4.4.7) representing the string "NestMembers".

attribute_length

The value of the attribute_length item indicates the length of the attribute, excluding the initial six bytes.

number_of_classes

The value of the number_of_classes item indicates must indicate the number of entries in the classes array.

classes[]

Each value entry in the classes array must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Class_info structure (4.4.1).

representing Each entry represents a class or interface which is a member of the nest hosted by the current class or interface.

The classes array is consulted by access control (5.4.4). It should consist of references to other classes and interfaces that are in the same run-time package and have NestHost attributes which reference the current class or interface. Array items that do not meet these criteria are ignored by access control.

4.8 Format Checking

When a prospective class file is loaded by the Java Virtual Machine (5.3), the Java Virtual Machine first ensures that the class file is valid (4)—that is, the file has the basic format of a class file (4.1). This process is known as format checking.

The checks are as follows:

This list is incomplete, and has been replaced with the definition of valid in 4.

These checks for basic class file integrity are necessary for any interpretation of the class file contents. Format checking is distinct from bytecode verification, although historically they have been confused because both are a form of integrity check.

After a class file has been loaded, it may be linked (5.4). Linking includes verification, which performs additional validation of Code and StackMapTable attributes, and resolution, which checks that referenced classes, interfaces, fields, and methods actually exist.

Historically, format checking and verification have sometimes been confused, because both are a form of integrity check, but they occur in distinctly-timed phases.

This section no longer serves much of a purpose, and what's left could be folded into 5.3.5. However, removing Section 4.8 would impact the rest of the chapter...

Chapter 5: Loading, Linking, and Initializing

5.3 Creation and Loading

5.3.5 Deriving a Class from a class File Representation

The following steps are used to derive a Class object for the nonarray class or interface C denoted by N using loader L from a purported representation in class file format.

  1. First, the Java Virtual Machine determines whether it has already recorded that L is an initiating loader of a class or interface denoted by N. If so, this creation attempt is invalid and loading throws a LinkageError.

  2. Otherwise, the Java Virtual Machine attempts to parse the purported representation. However, the purported representation may not in fact be a valid representation of C.

    This phase of loading must detect the following errors:

    • If the purported representation is not a ClassFile structure (4.1, 4.8) valid class file (4), loading throws an instance of ClassFormatError.

    • Otherwise, if the purported representation is not of a supported major or minor version (4.1), loading throws an instance of UnsupportedClassVersionError.

      UnsupportedClassVersionError, a subclass of ClassFormatError, was introduced to enable easy identification of a ClassFormatError caused by an attempt to load a class whose representation uses an unsupported version of the class file format. In JDK 1.1 and earlier, an instance of NoClassDefFoundError or ClassFormatError was thrown in case of an unsupported version, depending on whether the class was being loaded by the system class loader or a user-defined class loader.

    • Otherwise, if the purported representation does not actually represent a class named N, loading throws an instance of NoClassDefFoundError or an instance of one of its subclasses.

      This occurs when the purported representation has either a this_class item which specifies a name other than N, or an access_flags item which has the ACC_MODULE flag set.

  3. If C has a direct superclass, the symbolic reference from C to its direct superclass is resolved using the algorithm of 5.4.3.1. Note that if C is an interface it must have Object as its direct superclass, which must already have been loaded. Only Object has no direct superclass.

    Any exceptions that can be thrown due to class or interface resolution can be thrown as a result of this phase of loading. In addition, this phase of loading must detect the following errors:

    • If the class or interface named as the direct superclass of C is in fact an interface, loading throws an IncompatibleClassChangeError.

    • Otherwise, if any of the superclasses of C is C itself, loading throws a ClassCircularityError.

  4. If C has any direct superinterfaces, the symbolic references from C to its direct superinterfaces are resolved using the algorithm of 5.4.3.1.

    Any exceptions that can be thrown due to class or interface resolution can be thrown as a result of this phase of loading. In addition, this phase of loading must detect the following errors:

    • If any of the classes or interfaces named as direct superinterfaces of C is not in fact an interface, loading throws an IncompatibleClassChangeError.

    • Otherwise, if any of the superinterfaces of C is C itself, loading throws a ClassCircularityError.

  5. The Java Virtual Machine marks C as having L as its defining class loader and records that L is an initiating loader of C (5.3.4).