Format Checking Cleanup

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.

Two subtle changes to implementation behavior are proposed: rejecting class or interface declarations with Module, ModulePackages, or ModuleMainClass attributes (4.7.25, 4.7.26, 4.7.27), and rejecting non-static field declarations with ConstantValue attributes (4.7.2).

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 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 in the fourth column of Table 4.1-A, "Supported majors". The notation A .. B means major versions A through B, inclusive of both A and B. The third column, "Major", shows 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	Released	Major	Supported majors
1.0.2	May 1996	45	45
1.1	February 1997	45	45
1.2	December 1998	46	45 .. 46
1.3	May 2000	47	45 .. 47
1.4	February 2002	48	45 .. 48
5.0	September 2004	49	45 .. 49
6	December 2006	50	45 .. 50
7	July 2011	51	45 .. 51
8	March 2014	52	45 .. 52
9	September 2017	53	45 .. 53
10	March 2018	54	45 .. 54
11	September 2018	55	45 .. 55
12	March 2019	56	45 .. 56
13	September 2019	57	45 .. 57
14	March 2020	58	45 .. 58
15	September 2020	59	45 .. 59
16	March 2021	60	45 .. 60

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 is warranted on JDK support for class file format versions. 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. For example, JDK 13 supports 57.0 and 57.65535.

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 is 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 class file with major version 53 or later, the ACC_MODULE flag indicates that this class file defines a module, not a class or interface. In a class file with major version less than 53, the 0x8000 bit is ignored, and the ACC_MODULE flag is considered not to be set. If the ACC_MODULE flag is set, then special rules apply to the class file which are given at the end of this section no other flag in Table 4.1-B may be set. If the ACC_MODULE flag is not set, then the rules immediately below the current paragraph apply to the class file.

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 neither the ACC_INTERFACE flag nor 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 interface (JLS §9.6) must have its ACC_ANNOTATION flag set. The ACC_ANNOTATION flag indicates that this interface is declared as an annotation interface (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 enum class (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.

Historically, the value 0x0020 was used to indicate ACC_SUPER, which affected the semantics of any invokespecial instructions (6.5.invokespecial) appearing in the class or interface. In Java SE 8, the ACC_SUPER semantics became mandatory, regardless of the setting of ACC_SUPER or the class file version number, and the flag no longer had any effect.

The specification of ACC_SUPER is "dead code": because the JVM must ignore the flag setting, it's meaningless, and there's no reason to continue to define it.

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.

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).

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.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.

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

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.

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.

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.

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.

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.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>.

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:

• The CONSTANT_Dynamic_info structure is used to represent a dynamically-computed constant, an arbitrary value that is produced by invocation of a bootstrap method in the course of an ldc instruction (6.5.ldc), among others. The auxiliary type specified by the structure constrains the type of the dynamically-computed constant.

• The CONSTANT_InvokeDynamic_info structure is used to represent a dynamically-computed call site, an instance of java.lang.invoke.CallSite that is produced by invocation of a bootstrap method in the course of an invokedynamic instruction (6.5.invokedynamic). The auxiliary type specified by the structure constrains the method type of the dynamically-computed call site.

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 descriptor must be a method descriptor (4.3.3).

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).

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).

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 class.

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 enum class (JLS §8.9).

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.

Methods of classes may have any of the flags in Table 4.6-A set. However, each 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 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 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 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.

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.

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 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>.

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, Code_attribute, and record_component_info structures of the class file format (4.1, 4.5, 4.6, 4.7.3, 4.7.30).

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.

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

• Table 4.7-A is ordered by the attributes' section numbers in this chapter. Each attribute is shown 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 (4.1).

• Table 4.7-B is ordered by the first version of the class file format in which each attribute was defined.

• Table 4.7-C is ordered by the location in a class file where each attribute is defined to appear.

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. 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
   • Record
   • SourceFile
   • LineNumberTable
   • LocalVariableTable
   • LocalVariableTypeTable

   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.

3. Thirteen Ten 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.

4.7.1 Defining and Naming New Nonstandard Attributes

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.

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).

• If the ACC_STATIC flag in the access_flags item of the field_info structure is set, then 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).

• Otherwise, the Java Virtual Machine must silently ignore the attribute.

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.

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.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.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.

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.

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 the attempt to derive a class or interface named N for class loader L is invalid. If so, loading throws a LinkageError.

   An attempt to derive a class or interface named N for class loader L is invalid if one of the following are true:

   • L has already been recorded as as an initiating loader of a class or interface named N.

   • L is not the bootstrap class loader (5.3) and N is the reserved name java/lang/Object.

   The second case, combined with restrictions in 4.1, ensures that there is only one root of the class hierarchy, and the name java/lang/Object can reliably be used to refer to it.

   The Java SE API enforces additional security restrictions that prevent unauthorized attempts to load classes in certain packages, including java.*.

   In practice, the security restrictions make it impossible to test the Object rule—a SecurityException will happen before the JVM can perform this check. But for internal consistency, it seems important to state.

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), loading throws an instance of ClassFormatError.

     It doesn't make sense to try to parse a class file before determining that the version number is supported. The version check has to happen first.

   • Otherwise, if If the purported representation is not of a supported major or minor version (4.1) provides a major and minor version number in its 5th through 8th bytes (4.1), but the version number is not supported by this Java Virtual Machine implementation, 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 is not a valid class file (4), loading throws an instance of ClassFormatError.

   • Otherwise, if the purported representation does not actually represent a class or interface 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.

   Note that if C is an interface, its direct superclass is the class Object (4.1). The symbolic reference to Object is resolved just like a reference to any other class.

   In fact, Object may not have been loaded yet, if the initial class or interface of a program ([5.2]) is an interface.

   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 superclasses of C is C itself, loading throws a ClassCircularityError.

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

   • Otherwise, if C is a class and some instance method declared in C can override (5.4.5) a final instance method declared in a superclass of C, loading throws an IncompatibleClassChangeError.

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 superinterfaces of C is C itself, loading throws a ClassCircularityError.

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

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).

Chapter 6: The Java Virtual Machine Instruction Set

6.5 Instructions

invokespecial

Operation

Invoke instance method; direct invocation of instance initialization methods and methods of the current class and its supertypes

Format

invokespecial
indexbyte1
indexbyte2

Forms

invokespecial = 183 (0xb7)

Operand Stack

..., objectref, [arg1, [arg2 ...]] →

...

Description

The unsigned indexbyte1 and indexbyte2 are used to construct an index into the run-time constant pool of the current class (2.6), where the value of the index is (indexbyte1 << 8) | indexbyte2. The run-time constant pool entry at the index must be a symbolic reference to a method or an interface method (5.1), which gives the name and descriptor (4.3.3) of the method or interface method as well as a symbolic reference to the class or interface in which the method or interface method is to be found. The named method is resolved (5.4.3.3, 5.4.3.4).

If all of the following are true, let C be the direct superclass of the current class:

• The resolved method is not an instance initialization method (2.9.1).

• The symbolic reference names a class (not an interface), and that class is a superclass of the current class.

• The ACC_SUPER flag is set for the class file (4.1).

If the symbolic reference names a class (not an interface), and the resolved method is not an instance initialization method (2.9.1), let C be the direct superclass of the current class. Otherwise, let C be the class or interface named by the symbolic reference.

The ACC_SUPER flag is always considered to be set. A referenced class must always be a superclass of the current class, per 4.9.2.

The actual method to be invoked is selected by the following lookup procedure:

1. If C contains a declaration for an instance method with the same name and descriptor as the resolved method, then it is the method to be invoked.

2. Otherwise, if C is a class and has a superclass, a search for a declaration of an instance method with the same name and descriptor as the resolved method is performed, starting with the direct superclass of C and continuing with the direct superclass of that class, and so forth, until a match is found or no further superclasses exist. If a match is found, then it is the method to be invoked.

3. Otherwise, if C is an interface and the class Object contains a declaration of a public instance method with the same name and descriptor as the resolved method, then it is the method to be invoked.

4. Otherwise, if there is exactly one maximally-specific method (5.4.3.3) in the superinterfaces of C that matches the resolved method's name and descriptor and is not abstract, then it is the method to be invoked.

The objectref must be of type reference and must be followed on the operand stack by nargs argument values, where the number, type, and order of the values must be consistent with the descriptor of the selected instance method.

If the method is synchronized, the monitor associated with objectref is entered or reentered as if by execution of a monitorenter instruction (6.5.monitorenter) in the current thread.

If the method is not native, the nargs argument values and objectref are popped from the operand stack. A new frame is created on the Java Virtual Machine stack for the method being invoked. The objectref and the argument values are consecutively made the values of local variables of the new frame, with objectref in local variable 0, arg1 in local variable 1 (or, if arg1 is of type long or double, in local variables 1 and 2), and so on. Any argument value that is of a floating-point type undergoes value set conversion (2.8.3) prior to being stored in a local variable. The new frame is then made current, and the Java Virtual Machine pc is set to the opcode of the first instruction of the method to be invoked. Execution continues with the first instruction of the method.

If the method is native and the platform-dependent code that implements it has not yet been bound (5.6) into the Java Virtual Machine, that is done. The nargs argument values and objectref are popped from the operand stack and are passed as parameters to the code that implements the method. Any argument value that is of a floating-point type undergoes value set conversion (2.8.3) prior to being passed as a parameter. The parameters are passed and the code is invoked in an implementation-dependent manner. When the platform-dependent code returns, the following take place:

• If the native method is synchronized, the monitor associated with objectref is updated and possibly exited as if by execution of a monitorexit instruction (6.5.monitorexit) in the current thread.

• If the native method returns a value, the return value of the platform-dependent code is converted in an implementation-dependent way to the return type of the native method and pushed onto the operand stack.

Linking Exceptions

During resolution of the symbolic reference to the method, any of the exceptions pertaining to method resolution (5.4.3.3) can be thrown.

Otherwise, if the resolved method is an instance initialization method, and the class in which it is declared is not the class symbolically referenced by the instruction, a NoSuchMethodError is thrown.

Otherwise, if the resolved method is a class (static) method, the invokespecial instruction throws an IncompatibleClassChangeError.

Run-time Exceptions

Otherwise, if objectref is null, the invokespecial instruction throws a NullPointerException.

Otherwise, if step 1, step 2, or step 3 of the lookup procedure selects an abstract method, invokespecial throws an AbstractMethodError.

Otherwise, if step 1, step 2, or step 3 of the lookup procedure selects a native method and the code that implements the method cannot be bound, invokespecial throws an UnsatisfiedLinkError.

Otherwise, if step 4 of the lookup procedure determines there are multiple maximally-specific superinterface methods of C that match the resolved method's name and descriptor and are not abstract, invokespecial throws an IncompatibleClassChangeError

Otherwise, if step 4 of the lookup procedure determines there are no maximally-specific superinterface methods of C that match the resolved method's name and descriptor and are not abstract, invokespecial throws an AbstractMethodError.

Notes

The difference between the invokespecial instruction and the invokevirtual instruction (6.5.invokevirtual) is that invokevirtual invokes a method based on the class of the object. The invokespecial instruction is used to directly invoke instance initialization methods (2.9.1) as well as methods of the current class and its supertypes.

The invokespecial instruction was named invokenonvirtual prior to JDK release 1.0.2.

The nargs argument values and objectref are not one-to-one with the first nargs+1 local variables. Argument values of types long and double must be stored in two consecutive local variables, thus more than nargs local variables may be required to pass nargs argument values to the invoked method.

The invokespecial instruction handles invocation of a non-abstract interface method, referenced either via a direct superinterface or via a superclass. In these cases, the rules for selection are essentially the same as those for invokeinterface (except that the search starts from a different class).