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:
Eliminating checks on
CONSTANT_NameAndType
structures involving restricted method names (names that include<
or>
) and name/descriptor coordination (4.4.6). These checks should only occur when the constant is referenced from a context that requires a method.Ensuring that a
CONSTANT_InvokeDynamic
structure never uses method name<init>
(4.4.10), rather than delaying the check until aninvokedynamic
instruction is verified.Rejecting class or interface declarations with
Module
,ModulePackages
, orModuleMainClass
attributes (4.7.25, 4.7.26, 4.7.27), and non-static
field declarations withConstantValue
attributes (4.7.2).
The resulting story for usage of the special method names <clinit>
and <init>
is as follows:
A valid method name is a valid unqualified name that either i) does not contain the characters
<
or>
, or ii) is one of the special names<clinit>
or<init>
(4.2.2). (Note that field and class names are not subject to these restrictions—a field can be named<init>
or even>_<
.)A method declaration must have a valid method name, and if it has a special method name, is subject to additional constraints on the descriptor, flags, etc. (4.6).
A
CONSTANT_NameAndType
structure may refer to any valid unqualified name, paired with any valid field or method descriptor (4.4.6).A
CONSTANT_Methodref
orCONSTANT_InterfaceMethodref
structure must refer to aNameAndType
with a valid method name and a valid method descriptor (4.4.2). The method name must not be<clinit>
. If the method name is<init>
, the descriptor must have avoid
return.A
CONSTANT_InvokeDynamic
structure must refer to aNameAndType
with a valid method name and a valid method descriptor (4.4.10). The method name must not be<clinit>
or<init>
.A
CONSTANT_MethodHandle
structure of kind 5 (REF_invokeVirtual
), 6 (REF_invokeStatic
), 7 (REF_invokeSpecial
), or 9 (REF_invokeInterface
) must not reference a method named<init>
, while a structure of kind 8 (REF_newInvokeSpecial
) must reference a method named<init>
(4.4.8).At verification time, an
invokevirtual
,invokeinterface
, orinvokestatic
instruction must not reference a method named<init>
(4.9.1).
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:
It is defined in a class (not an interface).It has the special name<init>
.It isvoid
(4.3.3).
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:
It has the special name<clinit>
.It isvoid
(4.3.3).In aclass
file whose version number is 51.0 or above, the method has itsACC_STATIC
flag set and takes no arguments (4.6).The requirement forACC_STATIC
was introduced in Java SE 7, and for taking no arguments in Java SE 9. In a class file whose version number is 50.0 or below, a method named<clinit>
that isvoid
is considered the class or interface initialization method regardless of the setting of itsACC_STATIC
flag or whether it takes arguments.These details are better left to 4.6.
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:
invokevirtual invokes an instance method of an object, dispatching on the (virtual) type of the object. This is the normal method dispatch in the Java programming language.
invokeinterface invokes an interface method, searching the methods implemented by the particular run-time object to find the appropriate method.
invokespecial invokes an instance method requiring special handling, either an instance initialization method (2.9.1) or a method of the current class or its supertypes.
invokestatic invokes a class (
static
) method in a named class.invokedynamic invokes the method which is the target of the call site object bound to the invokedynamic instruction. The call site object was bound to a specific lexical occurrence of the invokedynamic instruction by the Java Virtual Machine as a result of running a bootstrap method before the first execution of the instruction. Therefore, each occurrence of an invokedynamic instruction has a unique linkage state, unlike the other instructions which 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 interfacesjava.io.DataInput
andjava.io.DataOutput
and classes such asjava.io.DataInputStream
andjava.io.DataOutputStream
. For example, values of the typesu1
,u2
, andu4
may be read by methods such asreadUnsignedByte
,readUnsignedShort
, andreadInt
of the interfacejava.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 theclass
file format; ithasmust have the value0xCAFEBABE
.- minor_version, major_version
The values of the
minor_version
andmajor_version
items are the minor and major version numbers of thisclass
file. Together, a major and a minor version number determine the version of theclass
file format. If aclass
file has major version number M and minor version number m, we denote the version of itsclass
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 aclass
file containing thatmajor_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 versionsJava 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 whosemajor_version
is 56 or above, theminor_version
must be 0 or 65535.For a
class
file whosemajor_version
is between 45 and 55 inclusive, theminor_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 theclass
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 amajor_version
that corresponds to Java SE N (according to Table 4.1-A) and aminor_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 theconstant_pool
table plus one. Aconstant_pool
index is considered valid if it is greater than zero and less thanconstant_pool_count
, with the exception for constants of typelong
anddouble
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 theClassFile
structure and its substructures. The format of eachconstant_pool
table entry is indicated by its first "tag" byte.The
constant_pool
table is indexed from 1 toconstant_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. TheIn a version 53.0 or laterclass
file, theACC_MODULE
flag indicates that thisclass
file defines a module, not a class or interface. If theACC_MODULE
flag is set in a version 53.0 or laterclass
file, thenspecial rules apply to theno other flag in Table 4.1-B may be set.class
file which are given at the end of this section. If theACC_MODULE
flag is not set, then the rules immediately below the current paragraph apply to theclass
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, theACC_MODULE
flag is ignored.An interface is distinguished by theACC_INTERFACE
flag being set. If theACC_INTERFACE
flag is not set, thisclass
file defines a class, not an interface or module.The
ACC_INTERFACE
flag indicates that thisclass
file defines an interface, not a module or class. If theACC_INTERFACE
flag is set, theACC_ABSTRACT
flag must also be set, and theACC_FINAL
,ACC_SUPER
,ACC_ENUM
, andACC_MODULE
flagssetmust not be set.If the
ACC_INTERFACE
flag is not set and, in a version 53.0 or laterclass
file, theACC_MODULE
flag is not set, thisclass
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 exceptACC_ANNOTATION
and.ACC_MODULE
However, such aclass
file must not have both itsACC_FINAL
andACC_ABSTRACT
flags set (JLS §8.1.1.2).The
ACC_FINAL
flag indicates that this class cannot be extended by another class. If theACC_FINAL
flag is set, theACC_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 theACC_SUPER
flag. In Java SE 8 and above, the Java Virtual Machine considers theACC_SUPER
flag to be set in everyclass
file, regardless of the actual value of the flag in theclass
file and the version of theclass
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 generatedaccess_flags
in which the flag now representingACC_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 itsTheACC_ANNOTATION
flag set.ACC_ANNOTATION
flag indicates that this interface is declared as an annotation type (JLS §9.6). If theACC_ANNOTATION
flag is set, theACC_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 generatedclass
files andshould beare ignored by Java Virtual Machine implementations.- this_class
The value of the
this_class
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Class_info
structure (4.4.1)representingreferencing 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 thisclass
file.- super_class
For a module or a class named
java/lang/Object
, the value of thesuper_class
item must be 0.For a class with any other name, the value of the
super_class
itemeither must be zero ormust be a valid index into theconstant_pool
table.If the value of theThesuper_class
item is nonzero, theconstant_pool
entry at that index must be aCONSTANT_Class_info
structurerepresenting the direct superclass of the class defined by thisreferencing a class or interface name.class
fileNeither the direct superclass nor any of its superclasses may have theACC_FINAL
flag set in theaccess_flags
item of itsClassFile
structure.This constraint on the superclass declaration is not part of format checking.
If the value of thesuper_class
item is zero, then thisclass
file must represent the classObject
, the only class or interface without a direct superclass.For an interface, the value of the
super_class
item mustalwaysbe a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Class_info
structurerepresenting the classreferencing the nameObject
java/lang/Object
.The
super_class
item represents the direct superclass of the class or interface defined by thisclass
file.The class
Object
has no direct superclass. Interfaces effectively haveObject
as their direct superclass.- interfaces_count
The value of the
interfaces_count
item gives the number of direct superinterfaces of this class or interfacetype.For a module,
interfaces_count
must be 0.- interfaces[]
Each value in the
interfaces
array must be a valid index into theconstant_pool
table. Theconstant_pool
entry at each value ofinterfaces[*i*]
, where 0 ≤ i <interfaces_count
, must be aCONSTANT_Class_info
structurerepresentingreferencing a class or interface name.The
interfaces
array representsaneach interface that is a direct superinterface of this class or interfacetype, in the left-to-right order given in the source for thetypeclass or interface.- fields_count
The value of the
fields_count
item gives the number offield_info
structures in thefields
table. Thefield_info
structures represent all fields, both class variables and instance variables, declared by this class or interfacetype.For a module,
fields_count
must be 0.- fields[]
Each value in the
fields
table must be afield_info
structure (4.5) giving a complete description of a field in this class or interface. Thefields
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 ofmethod_info
structures in themethods
table.For a module,
methods_count
must be 0.- methods[]
Each value in the
methods
table must be amethod_info
structure (4.6) giving a complete description of a method in this class or interface.If neither of theACC_NATIVE
andACC_ABSTRACT
flags are set in theaccess_flags
item of amethod_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 interfacetype, including instance methods, class methods, instance initialization methods (2.9.1), and any class or interface initialization method (2.9.2). Themethods
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 theattributes
table of this class.- attributes[]
Each value of the
attributes
table must be anattribute_info
structure (4.7).The attributes defined by this specification as appearing in the
attributes
table of aClassFile
structure are listed in Table 4.7-C.The rules concerning attributes defined to appear in the
attributes
table of aClassFile
structure are given in 4.7.The rules concerning
non-predefinednonstandard attributes in theattributes
table of aClassFile
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:
major_version
,minor_version
: ≥ 53.0 (i.e., Java SE 9 and above)this_class
:module-info
super_class
,interfaces_count
,fields_count
,methods_count
: zeroattributes
: OneModule
attribute must be present. Except forModule
,ModulePackages
,ModuleMainClass
,InnerClasses
,SourceFile
,SourceDebugExtension
,RuntimeVisibleAnnotations
, andRuntimeInvisibleAnnotations
, none of the pre-defined attributes (4.7) may appear.
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 allCONSTANT_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
isjava.lang.Thread
. In the internal form used in descriptors in theclass
file format, a reference to the name of classThread
is implemented using aCONSTANT_Utf8_info
structure representing the stringjava/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:
A module name must not contain any code point in the range '
\u0000
' to '\u001F
' inclusive.The ASCII backslash (
\
) is reserved for use as an escape character in module names. It must not appear in a module name unless it is followed by an ASCII backslash, an ASCII colon (:
), or an ASCII at-sign (@
). The ASCII character sequence\\
may be used to encode a backslash in a module name.The ASCII colon (
:
) and at-sign (@
) are reserved for future use in module names. They must not appear in module names unless they are escaped. The ASCII character sequences\:
and\@
may be used to encode a colon and an at-sign in a module name.
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 simplyI
.The field descriptor of an instance variable of type
Object
isLjava/lang/Object;
. Note that the internal form of the binary name for classObject
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
andObject
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.
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 theclass
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 valueCONSTANT_Class
(7).- name_index
The value of the
name_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure (4.4.7)representingconsisting of one of:
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 typeint[][]
is[[I
, while the class name representing the typeThread[]
is[Ljava/lang/Thread;
.
For example, the
name_index
string representing the classString
isjava/lang/String
. Thename_index
string representing the interfaceRunnable
isjava/lang/Runnable
. Thename_index
string representing the array typeThread[]
is[Ljava/lang/Thread;
. Thename_index
string representing the array typeint[][]
is[[I
.
Note that it is not supported to represent a primitive type with a
CONSTANT_Class_info
. For example, thename_index
stringD
represents a class or interface namedD
, not the primitive typedouble
.
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 aCONSTANT_Fieldref_info
structure has the valueCONSTANT_Fieldref
(9).The
tag
item of aCONSTANT_Methodref_info
structure has the valueCONSTANT_Methodref
(10).The
tag
item of aCONSTANT_InterfaceMethodref_info
structure has the valueCONSTANT_InterfaceMethodref
(11).- class_index
The value of the
class_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Class_info
structure (4.4.1).representingTheclass_index
item represents a class,orinterface, or array type that has the field or method as a member.In aCONSTANT_Fieldref_info
structure, theclass_index
item may be either a class type or an interface type.In a
CONSTANT_Methodref_info
structure, theclass_index
itemmust beshould name a class or an array type, not an interfacetype.In a
CONSTANT_InterfaceMethodref_info
structure, theclass_index
itemmust beshould name an interfacetype, 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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_NameAndType_info
structure (4.4.6). Thisconstant_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 aCONSTANT_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 bevoid
.In a
CONSTANT_Methodref_info
or aCONSTANT_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 beV
.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 valueCONSTANT_String
(8).- string_index
The value of the
string_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure (4.4.7).representingThestring_index
item represents the sequence of Unicode code points to which theString
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 theCONSTANT_Integer_info
structure has the valueCONSTANT_Integer
(3).The
tag
item of theCONSTANT_Float_info
structure has the valueCONSTANT_Float
(4).- bytes
The
bytes
item of theCONSTANT_Integer_info
structure represents the value of theint
constant. The bytes of the value are stored in big-endian (high byte first) order.The
bytes
item of theCONSTANT_Float_info
structure represents the value of thefloat
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 anint
constant bits. Then:If bits is
0x7f800000
, thefloat
value will be positive infinity.If bits is
0xff800000
, thefloat
value will be negative infinity.If bits is in the range
0x7f800001
through0x7fffffff
or in the range0xff800001
through0xffffffff
, thefloat
value will be NaN.In all other cases, let
s
,e
, andm
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 expressions · 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 theCONSTANT_Long_info
structure has the valueCONSTANT_Long
(5).The
tag
item of theCONSTANT_Double_info
structure has the valueCONSTANT_Double
(6).- high_bytes, low_bytes
The unsigned
high_bytes
andlow_bytes
items of theCONSTANT_Long_info
structure together represent the value of thelong
constant((long) high_bytes << 32) + low_bytes
where the bytes of each of
high_bytes
andlow_bytes
are stored in big-endian (high byte first) order.The
high_bytes
andlow_bytes
items of theCONSTANT_Double_info
structure together represent thedouble
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. Thehigh_bytes
andlow_bytes
items are converted into thelong
constant bits, which is equal to((long) high_bytes << 32) + low_bytes
Then:
If bits is
0x7ff0000000000000L
, thedouble
value will be positive infinity.If bits is
0xfff0000000000000L
, thedouble
value will be negative infinity.If bits is in the range
0x7ff0000000000001L
through0x7fffffffffffffffL
or in the range0xfff0000000000001L
through0xffffffffffffffffL
, the double value will be NaN.In all other cases, let
s
,e
, andm
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 expressions · 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 valueCONSTANT_NameAndType
(12).- name_index
The value of the
name_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure (4.4.7) representingeither a valid unqualified name denoting a field or method (4.2.2), or the special method namea valid unqualified name (4.2.2).<init>
(2.9.1)- descriptor_index
The value of the
descriptor_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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 valueCONSTANT_Utf8
(1).- length
The value of the
length
item gives the number of bytes in thebytes
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:
Code points in the range '
\u0001
' to '\u007F
' are represented by a single byte:0 bits 6-0 The 7 bits of data in the byte give the value of the code point represented.
The null code point ('
\u0000
') and code points in the range '\u0080
' to '\u07FF
' are represented by a pair of bytesx
andy
:x
:1 | 1 | 0 | bits 10-6 y
:1 | 0 | bits 5-0 The two bytes represent the code point with the value:
((x & 0x1f) << 6) + (y & 0x3f)
Code points in the range '
\u0800
' to '\uFFFF
' are represented by 3 bytesx
,y
, andz
:x
:1 | 1 | 1 | 0 | bits 15-12 y
:1 | 0 | bits 11-6 z
:1 | 0 | bits 5-0 The three bytes represent the code point with the value:
((x & 0xf) << 12) + ((y & 0x3f) << 6) + (z & 0x3f)
Characters with code points above U+FFFF (so-called supplementary characters) are represented by separately encoding the two surrogate code units of their UTF-16 representation. Each of the surrogate code units is represented by three bytes. This means supplementary characters are represented by six bytes,
u
,v
,w
,x
,y
, andz
:u
:1 | 1 | 1 | 0 | 1 | 1 | 0 | 1 v
:1 | 0 | 1 | 0 | (bits 20-16)-1 w
:1 | 0 | bits 15-10 x
:1 | 1 | 1 | 0 | 1 | 1 | 0 | 1 y
:1 | 0 | 1 | 1 | bits 9-6 z
:1 | 0 | bits 5-0 The six bytes represent the code point with the value:
0x10000 + ((v & 0x0f) << 16) + ((w & 0x3f) << 10) + ((y & 0x0f) << 6) + (z & 0x3f)
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 valueCONSTANT_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 theconstant_pool
table. Theconstant_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 theconstant_pool
entry at that index must be aCONSTANT_Fieldref_info
structure (4.4.2).representingThereference_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 theconstant_pool
entry at that index must be aCONSTANT_Methodref_info
structure (4.4.2).representingThereference_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 theclass
file version number is less than 52.0, theconstant_pool
entry at that index must be aCONSTANT_Methodref_info
structurerepresenting a class's method for which a method handle is to be created; if theclass
file version number is 52.0 or above, theconstant_pool
entry at that index must be either aCONSTANT_Methodref_info
structure or aCONSTANT_InterfaceMethodref_info
structure (4.4.2).representingThereference_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 theconstant_pool
entry at that index must be aCONSTANT_InterfaceMethodref_info
structure.representingThereference_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 aCONSTANT_Methodref_info
structure or aCONSTANT_InterfaceMethodref_info
structure must not be<init>
or.<clinit>
If the value is 8 (
REF_newInvokeSpecial
), the name of the method represented by aCONSTANT_Methodref_info
structure must be<init>
.In no case may the name be
<clinit>
, becauseMethodref
andInterfaceMethodref
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 valueCONSTANT_MethodType
(16).- descriptor_index
The value of the
descriptor_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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 ofjava.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 aCONSTANT_Dynamic_info
structure has the valueCONSTANT_Dynamic
(17).The
tag
item of aCONSTANT_InvokeDynamic_info
structure has the valueCONSTANT_InvokeDynamic
(18).- bootstrap_method_attr_index
The value of the
bootstrap_method_attr_index
item must be a valid index into thebootstrap_methods
arraytable of thebootstrap method tableBootstrapMethods
attribute of thisclass
fileClassFile
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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_NameAndType_info
structure (4.4.6). Thisconstant_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>
.theThe indicated descriptor must be a method descriptor (4.3.3).This parallels the constraints imposed on the
NameAndType
of aFieldref
,Methodref
, orInterfaceMethodref
(4.4.2). An additional constraint prohibits using the name<init>
, just as verification prohibits its use in aninvokestatic
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 thisNameAndType
is intended to be used by aninvokedynamic
, it doesn't make much sense to defer half of the check. (Compare the validation ofMethodHandle
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 valueCONSTANT_Module
(19).- name_index
The value of the
name_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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 aclass
file that declares a module, that is, aClassFile
structure where theaccess_flags
item has theACC_MODULE
flag set. In all otherclass
files, aCONSTANT_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 valueCONSTANT_Package
(20).- name_index
The value of the
name_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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 aclass
file that declares a module, that is, aClassFile
structure where theaccess_flags
item has theACC_MODULE
flag set. In all otherclass
files, aCONSTANT_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 A class
file may haveClassFile
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
maymust have at most one of itsACC_PUBLIC
,ACC_PRIVATE
, andACC_PROTECTED
flags set (JLS §8.3.1), and must not have both itsACC_FINAL
andACC_VOLATILE
flags set (JLS §8.3.1.4).Fields of interfaces must have their
ACC_PUBLIC
,ACC_STATIC
, andACC_FINAL
flags set; they may have theirACC_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 generatedclass
files andshould beare ignored by Java Virtual Machine implementations.- name_index
The value of the
name_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure (4.4.7) which represents a valid unqualified namedenoting a field(4.2.2).- descriptor_index
The value of the
descriptor_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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 anattribute_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 afield_info
structure are listed in Table 4.7-C.The rules concerning attributes defined to appear in the
attributes
table of afield_info
structure are given in 4.7.The rules concerning
non-predefinednonstandard attributes in theattributes
table of afield_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 A class
file may haveClassFile
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 itsACC_PUBLIC
,ACC_PRIVATE
, andACC_PROTECTED
flags set, and may also have itsACC_VARARGS
,ACC_STRICT
, andACC_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 exceptACC_STATIC
,ACC_STRICT
, andACC_SYNTHETIC
are treated by the Java Virtual Machine as if they were not set. In aclass
file whose version number is 51.0 or greater, theACC_STATIC
flag must be set; in aclass
file whose version number is less than 51.0, theACC_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 methodof a class maymust have at most one of itsACC_PUBLIC
,ACC_PRIVATE
, andACC_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 exceptmust not have theirACC_PROTECTED
,ACC_FINAL
,ACC_SYNCHRONIZED
, andACC_NATIVE
flags set (JLS §9.4); exactly one of theACC_PUBLIC
orACC_PRIVATE
flags must be set. They may have any of the other flags in Table 4.6-A set. In aclass
file whose version number is less than 52.0, each method of an interface with a name other than<clinit>
must have itsACC_PUBLIC
andACC_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 itsACC_PUBLIC
andACC_PRIVATE
flags setIf a method of a class or interface has its
ACC_ABSTRACT
flag set, it must not have any of itsACC_PRIVATE
,ACC_STATIC
,ACC_FINAL
,ACC_SYNCHRONIZED
,ACC_NATIVE
, orACC_STRICT
flags set.An instance initialization method (2.9.1) may have at most one of itsACC_PUBLIC
,ACC_PRIVATE
, andACC_PROTECTED
flags set, and may also have itsACC_VARARGS
,ACC_STRICT
, andACC_SYNTHETIC
flags set, but must not have any of the other flags in Table 4.6-A set.In aclass
file whose version number is 51.0 or above, a method whose name is<clinit>
must have itsACC_STATIC
flag set.A class or interface initialization method (2.9.2) is called implicitly by the Java Virtual Machine. The value of itsaccess_flags
item is ignored except for the setting of theACC_STATIC
andACC_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 theACC_VARARGS
flag set to 1. All other methods must be compiled with theACC_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 isand 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 generatedclass
files andshould beare ignored by Java Virtual Machine implementations.- name_index
The value of the
name_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure (4.4.7) representingeithera valid unqualified method namedenoting 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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure representing a valid method descriptor (4.3.3). Furthermore:If
this method is in a class rather than an interface, andthe name of the method is<init>
, then the descriptor must denote avoid
method.If the name of the method is
<clinit>
, then the descriptor must denote avoid
method, and, in aclass
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 theaccess_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 anattribute_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 amethod_info
structure are listed in Table 4.7-C.The rules concerning attributes defined to appear in the
attributes
table of amethod_info
structure are given in 4.7.The rules concerning
non-predefinednonstandard attributes in theattributes
table of amethod_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:
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 theclass
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 the structures of appropriately-versioned class
file structuresclass
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:
SixNine attributes are critical to correct interpretation of theclass
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 theclass
file format, and the attribute was first defined in version v or earlier of theclass
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.
NineTen attributes are not critical to correct interpretation of theclass
file by the Java Virtual Machine, but are either critical to correct interpretation of theclass
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 theclass
file format, and the attribute was first defined in version v or earlier of theclass
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.ThirteenNine attributes are not critical to correct interpretation of theclass
file by the Java Virtual Machine, but contain metadata about theclass
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:
The attribute's name is not one of the predefined attribute names (see Table 4.7-A).
The attribute appears in a class file whose version number is v, and the predefined attribute of the same name was first defined in a
class
file version later than v (see Table 4.7-B).The attribute appears in a location other than where the predefined attribute of the same name is defined to appear (see Table 4.7-C).
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 theclass
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 onclass
files may not run correctly if givenclass
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).
If theACC_STATIC
flag in theaccess_flags
item of thefield_info
structure is set, then the field represented by thefield_info
structure is assigned the value represented by itsConstantValue
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 the attribute has no effect.
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index gives the value represented by this attribute. Theconstant_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, noconstant_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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
ordouble
ismax_locals - 2
. The greatest local variable index for a value of any other type ismax_locals - 1
.- code_length
The value of the
code_length
item gives the number of bytes in thecode
array for this method.The value of
code_length
must be greater than zero (as thecode
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 ofcode
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 theexception_table
table.- exception_table[]
Each entry in the
exception_table
array describes one exception handler in thecode
array. The order of the handlers in theexception_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
andend_pc
indicate the ranges in thecode
array at which the exception handler is active. The value ofstart_pc
must be a valid index into thecode
array of the opcode of an instruction. The value ofend_pc
either must be a valid index into thecode
array of the opcode of an instruction or must be equal tocode_length
, the length of thecode
array. The value ofstart_pc
must be less than the value ofend_pc
.The
start_pc
is inclusive andend_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 thecode
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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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 ofThrowable
(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 theCode
attribute.- attributes[]
Each value of the
attributes
table must be anattribute_info
structure (4.7).ACode
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 aCode
attribute are listed in Table 4.7-C.The rules concerning attributes defined to appear in the
attributes
table of aCode
attribute are given in 4.7.The rules concerning
non-predefinednonstandard attributes in theattributes
table of aCode
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 ofstack_map_frame
entries in theentries
table.- entries[]
Each entry in the
entries
table describes one stack map frame of the method. The order of the stack map frames in theentries
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:
The
Top_variable_info
item indicates that the local variable has the verification typetop
.Top_variable_info { u1 tag = ITEM_Top; /* 0 */ }
The
Integer_variable_info
item indicates that the location has the verification typeint
.Integer_variable_info { u1 tag = ITEM_Integer; /* 1 */ }
The
Float_variable_info
item indicates that the location has the verification typefloat
.Float_variable_info { u1 tag = ITEM_Float; /* 2 */ }
The
Null_variable_info
type indicates that the location has the verification typenull
.Null_variable_info { u1 tag = ITEM_Null; /* 5 */ }
The
UninitializedThis_variable_info
item indicates that the location has the verification typeuninitializedThis
.UninitializedThis_variable_info { u1 tag = ITEM_UninitializedThis; /* 6 */ }
The
Object_variable_info
item indicates that the location has the verification type which is the class, interface, or array type represented by theCONSTANT_Class_info
structure (4.4.1) found in theconstant_pool
table at the index given bycpool_index
.Object_variable_info { u1 tag = ITEM_Object; /* 7 */ u2 cpool_index; }
The
Uninitialized_variable_info
item indicates that the location has the verification typeuninitialized(Offset)
. TheOffset
item indicates the offset, in thecode
array of theCode
attribute that contains thisStackMapTable
attribute, of the new instruction ([6.5.new]) that created the object being stored in the location.Uninitialized_variable_info { u1 tag = ITEM_Uninitialized; /* 8 */ u2 offset; }
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:
The
Long_variable_info
item indicates that the first of two locations has the verification typelong
.Long_variable_info { u1 tag = ITEM_Long; /* 4 */ }
The
Double_variable_info
item indicates that the first of two locations has the verification typedouble
.Double_variable_info { u1 tag = ITEM_Double; /* 3 */ }
The
Long_variable_info
andDouble_variable_info
items indicate the verification type of the second of two locations as follows:If the first of the two locations is a local variable, then:
It must not be the local variable with the highest index.
The next higher numbered local variable has the verification type
top
.
If the first of the two locations is an operand stack entry, then:
It must not be the topmost location of the operand stack.
The next location closer to the top of the operand stack has the verification type
top
.
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust be theis aCONSTANT_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 theexception_index_table
.- exception_index_table[]
Each value in the
exception_index_table
array must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Class_info
structure (4.4.1) representing a classtypethat this method is declared to throw.
A method should throw an exception only if at least one of the following three criteria is met:
The exception is an instance of
RuntimeException
or one of its subclasses.The exception is an instance of
Error
or one of its subclasses.The exception is an instance of one of the exception classes specified in the
exception_index_table
just described, or one of their subclasses.
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 theclasses
array.- classes[]
Every
CONSTANT_Class_info
entry (4.4.1) in theconstant_pool
table which represents a class or interface C that is not a package membermustshould have exactly one corresponding entry in theclasses
array.If a class or interface has members that are classes or interfaces, its
constant_pool
table (and hence itsInnerClasses
attribute)mustshould 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 interfacemustshould refer to its enclosing class, so altogether, every nested class and nested interface will haveInnerClasses
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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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 theconstant_pool
table, and the entry at that index must be aCONSTANT_Class_info
structure representing the class or interface of which C is a member. The value of theouter_class_info_index
item must not equal the the value of theinner_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 theconstant_pool
table, and the entry at that index must be aCONSTANT_Utf8_info
structure that represents the original simple name of C, as given in the source code from which thisclass
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 thisclass
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 generatedclass
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 anInnerClasses
attribute in itsattributes
table, then for all entries in theclasses
array of theInnerClasses
attribute, the value of theouter_class_info_index
item must be zero if the value of theinner_name_index
item is zero.
Oracle's Java Virtual Machine implementationThe Java Virtual Machine does not check the consistency of anInnerClasses
attribute against aclass
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_NameAndType_info
structure (4.4.6) representing the name and type of a method in the class referenced by theclass_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 thisEnclosingMethod
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure (4.4.7) representing a class signature if thisSignature
attribute is an attribute of aClassFile
structure; a method signature if thisSignature
attribute is an attribute of amethod_info
structure; or a field signature otherwise.
Oracle's Java Virtual Machine implementationThe Java Virtual Machine does not check the well-formedness ofSignature
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 includegetGenericSuperclass
inClass
andtoGenericString
injava.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:
A class signature for any class or interface declaration which is either generic, or has a parameterized type as a superclass or superinterface, or both.
A method signature for any method or constructor declaration which is either generic, or has a type variable or parameterized type as the return type or a formal parameter type, or has a type variable in a
throws
clause, or any combination thereof.If the
throws
clause of a method or constructor declaration does not involve type variables, then a compiler may treat the declaration as having nothrows
clause for the purpose of emitting a method signature.A field signature for any field, formal parameter, or local variable declaration whose type uses a type variable or a parameterized type.
Signatures are specified using a grammar which follows the notation of 4.3.1. In addition to that notation:
The syntax [x] on the right-hand side of a production denotes zero or one occurrences of x. That is, x is an optional symbol. The alternative which contains the optional symbol actually defines two alternatives: one that omits the optional symbol and one that includes it.
A very long right-hand side may be continued on a second line by clearly indenting the second line.
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 Java type signature represents either a reference type or a primitive type of the Java programming language.
- JavaTypeSignature:
- ReferenceTypeSignature
- BaseType
The following production from 4.3.2 is repeated here for convenience:
- BaseType:
- (one of)
B
C
D
F
I
J
S
Z
A reference type signature represents a reference type of the Java programming language, that is, a class or interface type, a type variable, or an array type.
A class type signature represents a (possibly parameterized) class or interface type. A class type signature
mustshould be formulated such that it can be reliably mapped to the binary name of the class it denotes by erasing any type arguments and converting each.
character to a$
character.A type variable signature represents a type variable.
An array type signature represents one dimension of an array type.
- ReferenceTypeSignature:
- ClassTypeSignature
- TypeVariableSignature
- ArrayTypeSignature
- ClassTypeSignature:
L
[PackageSpecifier]
SimpleClassTypeSignature {ClassTypeSignatureSuffix};
- PackageSpecifier:
- Identifier
/
{PackageSpecifier} - SimpleClassTypeSignature:
- Identifier [TypeArguments]
- TypeArguments:
<
TypeArgument {TypeArgument}>
- TypeArgument:
- [WildcardIndicator] ReferenceTypeSignature
*
- WildcardIndicator:
+
-
- ClassTypeSignatureSuffix:
.
SimpleClassTypeSignature- TypeVariableSignature:
T
Identifier;
- ArrayTypeSignature:
[
JavaTypeSignature
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
attributemaymight not correspond exactly to the method descriptor in themethod_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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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 thisclass
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 informationmustshould 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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 classString
.
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 theattributes
table of aCode
attribute, and may appear in any order. MultipleLineNumberTable
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 theline_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 thecode
array. Eachline_number_table
entry must contain the following two items:- start_pc
The value of the
start_pc
item must be a valid index into thecode
array of thisCode
attribute. The item indicates the index into thecode
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 theattributes
table of aCode
attribute, and they may appear in any order. Each local variable in the source code should appear at most once in one of theLocalVariableTable
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 thelocal_variable_table
array.- local_variable_table[]
Each entry in the
local_variable_table
array indicates a range ofcode
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 thecode
array of thisCode
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 thecode
array of thisCode
attribute and be the index of the opcode of an instruction, or it must be the first index beyond the end of thatcode
array.The
start_pc
andlength
items indicate that the given local variable has a value at indices into thecode
array in the interval [start_pc
,start_pc + length
), that is, betweenstart_pc
inclusive andstart_pc + length
exclusive.- name_index
The value of the
name_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must contain aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index must contain aCONSTANT_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 atindex
in the local variable array of the current frame.If the given local variable is of type
double
orlong
, it occupies bothindex
andindex + 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 theattributes
table of aCode
attribute, and they may appear in any order. Each local variable in the source code should appear at most once in one of theLocalVariableTypeTable
attributes.
The
LocalVariableTypeTable
attribute differs from theLocalVariableTable
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 variableswillshould appear in both tables, while variables of other typeswillmight appear only inLocalVariableTable
.
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 thelocal_variable_type_table
array.- local_variable_type_table[]
Each entry in the
local_variable_type_table
array indicates a range ofcode
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 thecode
array of thisCode
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 thecode
array of thisCode
attribute and be the index of the opcode of an instruction, or it must be the first index beyond the end of thatcode
array.The
start_pc
andlength
items indicate that the given local variable has a value at indices into thecode
array in the interval [start_pc
,start_pc + length
), that is, betweenstart_pc
inclusive andstart_pc + length
exclusive.- name_index
The value of the
name_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must contain aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index must contain aCONSTANT_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 atindex
in the local variable array of the current frame.If the given local variable is of type
double
orlong
, it occupies bothindex
andindex + 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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemgivesshould give the number of run-time visible annotations represented by the structure.- annotations[]
Each entry in the
annotations
tablerepresentsshould represent a single run-time visible annotation on a declaration. Theannotation
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
itemmustshould be a valid index into theconstant_pool
table. Theconstant_pool
entry at that indexmustshould be aCONSTANT_Utf8_info
structure (4.4.7) representing a field descriptor (4.3.2). The field descriptor denotes the type of the annotation represented by thisannotation
structure.- num_element_value_pairs
The value of the
num_element_value_pairs
itemgivesshould give the number of element-value pairs of the annotation represented by thisannotation
structure.- element_value_pairs[]
Each value of the
element_value_pairs
table represents a single element-value pair in the annotation represented by thisannotation
structure. Eachelement_value_pairs
entrycontainsshould contain the following two items:- element_name_index
The value of the
element_name_index
itemmustshould be a valid index into theconstant_pool
table. Theconstant_pool
entry at that indexmustshould be aCONSTANT_Utf8_info
structure (4.4.7). Theconstant_pool
entry denotes the name of the element of the element-value pair represented by thiselement_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 thiselement_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 aString
literal as the value of this element-value pair.The value of the
const_value_index
itemmustshould be a valid index into theconstant_pool
table. Theconstant_pool
entry at that indexmustshould be of a type appropriate to thetag
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
itemmustshould be a valid index into theconstant_pool
table. Theconstant_pool
entry at that indexmustshould be aCONSTANT_Utf8_info
structure (4.4.7) representing a field descriptor (4.3.2). Theconstant_pool
entry gives the internal form of the binary name of the type of the enum constant represented by thiselement_value
structure (4.2.1).- const_name_index
The value of the
const_name_index
itemmustshould be a valid index into theconstant_pool
table. Theconstant_pool
entry at that indexmustshould be aCONSTANT_Utf8_info
structure (4.4.7). Theconstant_pool
entry gives the simple name of the enum constant represented by thiselement_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
itemmustshould be a valid index into theconstant_pool
table. Theconstant_pool
entry at that indexmustshould be aCONSTANT_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 thiselement_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 theconstant_pool
willshould 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 theconstant_pool
willshould be a BaseType character.For a class literal
void.class
, the corresponding type isvoid
. The return descriptor in theconstant_pool
willshould be V.
For example, the class literal
Object.class
corresponds to the typeObject
, so theconstant_pool
entry isLjava/lang/Object;
, whereas the class literalint.class
corresponds to the typeint
, so theconstant_pool
entry isI
.The class literal
void.class
corresponds tovoid
, so theconstant_pool
entry is V, whereas the class literalVoid.class
corresponds to the typeVoid
, so theconstant_pool
entry isLjava/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
itemisshould be anannotation
structure (4.7.16) that gives the annotation represented by thiselement_value
structure.- array_value
The
array_value
item denotes an array as the value of this element-value pair.The
array_value
itemconsistsshould consist of the following two items:- num_values
The value of the
num_values
itemgivesshould give the number of elements in the array represented by thiselement_value
structure.- values[]
Each value in the
values
tablegivesshould give the corresponding element of the array represented by thiselement_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 theRuntimeVisibleAnnotations
attribute (4.7.16), except that the annotations represented by aRuntimeInvisibleAnnotations
attributemust not beare 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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemgivesshould give the number of run-time invisible annotations represented by the structure.- annotations[]
Each entry in the
annotations
tablerepresentsshould represent a single run-time invisible annotation on a declaration. Theannotation
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemgivesshould 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
tablerepresentsshould represent all of the run-time visible annotations on the declaration of a single formal parameter. Eachparameter_annotations
entrycontainsshould contain the following two items:- num_annotations
The value of the
num_annotations
itemindicatesshould indicate the number of run-time visible annotations on the declaration of the formal parameter corresponding to theparameter_annotations
entry.- annotations[]
Each entry in the
annotations
tablerepresentsshould represent a single run-time visible annotation on the declaration of the formal parameter corresponding to theparameter_annotations
entry. Theannotation
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 aclass
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 createparameter_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 theRuntimeVisibleParameterAnnotations
attribute (4.7.18), except that the annotations represented by aRuntimeInvisibleParameterAnnotations
attributemust not beare 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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemgivesshould 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
tablerepresentsshould represent all of the run-time invisible annotations on the declaration of a single formal parameter. Eachparameter_annotations
entrycontainsshould contain the following two items:- num_annotations
The value of the
num_annotations
itemindicatesshould indicate the number of run-time invisible annotations on the declaration of the formal parameter corresponding to theparameter_annotations
entry.- annotations[]
Each entry in the
annotations
tablerepresentsshould represent a single run-time invisible annotation on the declaration of the formal parameter corresponding to theparameter_annotations
entry. Theannotation
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 theRuntimeVisibleTypeAnnotations
attribute of the class'sClassFile
structure. Meanwhile, all annotations on the type in a field declaration are recorded in theRuntimeVisibleTypeAnnotations
attribute of the field'sfield_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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemgivesshould 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. Thetype_annotation
structurehasshould 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
, andtarget_path
- specify the precise location of the annotated type. The last three items -type_index
,num_element_value_pairs
, andelement_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
itemdenotesshould 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
legalsupported values oftarget_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 thetarget_info
union follows thetarget_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, whiletarget_type
values 0x43-0x4B correspond to type contexts 11-16.The value of the
target_type
item determines whether thetype_annotation
structureappearsshould appear in aRuntimeVisibleTypeAnnotations
attribute in aClassFile
structure, afield_info
structure, amethod_info
structure, or aCode
attribute. Table 4.7.20-C gives the location of theRuntimeVisibleTypeAnnotations
attribute for atype_annotation
structure with eachlegalsupportedtarget_type
value.- target_info
The value of the
target_info
itemdenotesshould 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
itemdenotesshould denote precisely which part of the type indicated bytarget_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 theannotation
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:
The
type_parameter_target
item indicates that an annotation appears on the declaration of the i'th type parameter of a generic class, generic interface, generic method, or generic constructor.type_parameter_target { u1 type_parameter_index; }
The value of the
type_parameter_index
item specifies which type parameter declaration is annotated. Atype_parameter_index
value of0
specifies the first type parameter declaration.The
supertype_target
item indicates that an annotation appears on a type in theextends
orimplements
clause of a class or interface declaration.supertype_target { u2 supertype_index; }
A
supertype_index
value of 65535 specifies that the annotation appears on the superclass in anextends
clause of a class declaration.Any other
supertype_index
value is an index into theinterfaces
array of the enclosingClassFile
structure, and specifies that the annotation appears on that superinterface in either theimplements
clause of a class declaration or theextends
clause of an interface declaration.The
type_parameter_bound_target
item indicates that an annotation appears on the i'th bound of the j'th type parameter declaration of a generic class, interface, method, or constructor.type_parameter_bound_target { u1 type_parameter_index; u1 bound_index; }
The value of the of
type_parameter_index
item specifies which type parameter declaration has an annotated bound. Atype_parameter_index
value of0
specifies the first type parameter declaration.The value of the
bound_index
item specifies which bound of the type parameter declaration indicated bytype_parameter_index
is annotated. Abound_index
value of0
specifies the first bound of a type parameter declaration.The
type_parameter_bound_target
item records that a bound is annotated, but does not record the type which constitutes the bound. The type may be found by inspecting the class signature or method signature stored in the appropriateSignature
attribute.The
empty_target
item indicates that an annotation appears on either the type in a field declaration, the return type of a method, the type of a newly constructed object, or the receiver type of a method or constructor.empty_target { }
Only one type appears in each of these locations, so there is no per-type information to represent in the
target_info
union.The
formal_parameter_target
item indicates that an annotation appears on the type in a formal parameter declaration of a method, constructor, or lambda expression.formal_parameter_target { u1 formal_parameter_index; }
The value of the
formal_parameter_index
item specifies which formal parameter declaration has an annotated type. Aformal_parameter_index
value of i may, but is not required to, correspond to the i'th parameter descriptor in the method descriptor (4.3.3).The
formal_parameter_target
item records that a formal parameter's type is annotated, but does not record the type itself. The type may be found by inspecting the method descriptor, although aformal_parameter_index
value of0
does not always indicate the first parameter descriptor in the method descriptor; see the note in 4.7.18 for a similar situation involving theparameter_annotations
table.The
throws_target
item indicates that an annotation appears on the i'th type in thethrows
clause of a method or constructor declaration.throws_target { u2 throws_type_index; }
The value of the
throws_type_index
itemisshould be an index into theexception_index_table
array of theExceptions
attribute of themethod_info
structure enclosing theRuntimeVisibleTypeAnnotations
attribute.The
localvar_target
item indicates that an annotation appears on the type in a local variable declaration, including a variable declared as a resource in atry
-with-resources statement.localvar_target { u2 table_length; { u2 start_pc; u2 length; u2 index; } table[table_length]; }
The value of the
table_length
itemgivesshould give the number of entries in thetable
array. Each entryindicatesshould indicate a range ofcode
array offsets within which a local variable has a value. Italso indicatesshould also indicate the index into the local variable array of the current frame at which that local variable can be found. Each entry contains the following three items:- start_pc, length
The given local variable has a value at indices into the
code
array in the interval [start_pc
,start_pc + length
), that is, betweenstart_pc
inclusive andstart_pc + length
exclusive.- index
The given local variable
must beshould be atindex
in the local variable array of the current frame.If the local variable at
index
is of typedouble
orlong
, it occupies bothindex
andindex + 1
.
A table is needed to fully specify the local variable whose type is annotated, because a single local variable may be represented with different local variable indices over multiple live ranges. The
start_pc
,length
, andindex
items in each table entry specify the same information as aLocalVariableTable
attribute.The
localvar_target
item records that a local variable's type is annotated, but does not record the type itself. The type may be found by inspecting the appropriateLocalVariableTable
attribute.The
catch_target
item indicates that an annotation appears on the i'th type in an exception parameter declaration.catch_target { u2 exception_table_index; }
The value of the
exception_table_index
itemisshould be an index into theexception_table
array of theCode
attribute enclosing theRuntimeVisibleTypeAnnotations
attribute.The possibility of more than one type in an exception parameter declaration arises from the multi-
catch
clause of thetry
statement, where the type of the exception parameter is a union of types (JLS §14.20). A compiler usually creates oneexception_table
entry for each type in the union, which allows thecatch_target
item to distinguish them. This preserves the correspondence between a type and its annotations.The
offset_target
item indicates that an annotation appears on either the type in an instanceof expression or a new expression, or the type before the::
in a method reference expression.offset_target { u2 offset; }
The value of the
offset
itemspecifiesshould specify thecode
array offset of either the bytecode instruction corresponding to the instanceof expression, the new bytecode instruction corresponding to the new expression, or the bytecode instruction corresponding to the method reference expression.The
type_argument_target
item indicates that an annotation appears either on the i'th type in a cast expression, or on the i'th type argument in the explicit type argument list for any of the following: a new expression, an explicit constructor invocation statement, a method invocation expression, or a method reference expression.type_argument_target { u2 offset; u1 type_argument_index; }
The value of the
offset
itemspecifiesshould specify thecode
array offset of either the bytecode instruction corresponding to the cast expression, the new bytecode instruction corresponding to the new expression, the bytecode instruction corresponding to the explicit constructor invocation statement, the bytecode instruction corresponding to the method invocation expression, or the bytecode instruction corresponding to the method reference expression.For a cast expression, the value of the
type_argument_index
itemspecifiesshould specify which type in the cast operator is annotated. Atype_argument_index
value of0
specifies the first (or only) type in the cast operator.The possibility of more than one type in a cast expression arises from a cast to an intersection type.
For an explicit type argument list, the value of the
type_argument_index
item specifies which type argument is annotated. Atype_argument_index
value of0
specifies the first type argument.
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:
If an array type T
[]
is used in a declaration or expression, then an annotation may appear on any component type of the array type, including the element type.If a nested type T1
.
T2 is used in a declaration or expression, then an annotation may appear on the name of the innermost member type and any enclosing type for which a type annotation is admissible (JLS §9.7.4).If a parameterized type T
<
A>
or T<
? extends A>
or T<
? super A>
is used in a declaration or expression, then an annotation may appear on any type argument or on the bound of any wildcard type argument.
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>
andList<...>
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:
If the value of
path_length
is0
, and the type being annotated is a nested type, then the annotation applies to the outermost part of the type for which a type annotation is admissible.If the value of
path_length
is0
, and the type being annotated is not a nested type, then the annotation appears directly on the type itself.If the value of
path_length
is non-zero, then each entry in thepath
array represents an iterative, left-to-right step towards the precise location of the annotation in an array type, nested type, or parameterized type. (In an array type, the iteration visits the array type itself, then its component type, then the component type of that component type, and so on, until the element type is reached.) Each entry contains the following two items:- type_path_kind
The
legalsupported values for thetype_path_kind
item are listed in Table 4.7.20.2-A.Table 4.7.20.2-A. Interpretation of
type_path_kind
valuesValue Interpretation 0
Annotation is deeper in an array type 1
Annotation is deeper in a nested type 2
Annotation is on the bound of a wildcard type argument of a parameterized type 3
Annotation is on a type argument of a parameterized type - type_argument_index
If the value of the
type_path_kind
item is0
,1
, or2
, then the value of thetype_argument_index
itemisshould be0
.If the value of the
type_path_kind
item is3
, then the value of thetype_argument_index
item specifies which type argument of a parameterized type is annotated, where0
indicates the first type argument of a parameterized type.
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 forOuter . @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 nameOuter
are not admissible because the type name to its right,MiddleStatic
, does not refer to an inner class ofOuter
.Table 4.7.20.2-G.
type_path
structures forOuter . 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 nameOuter
are not admissible because the type name to its right,MiddleStatic
, does not refer to an inner class ofOuter
. Similarly, type annotations on the simple nameMiddleStatic
are not admissible because the type name to its right,InnerStatic
, does not refer to an inner class ofMiddleStatic
.Table 4.7.20.2-H.
type_path
structures forOuter . 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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemgivesshould 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. Thetype_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 a method_info
structures (4.6), namely those representing elements of annotation types (JLS §9.6.1)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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemrepresentsshould represent the default value of the annotation type element represented by themethod_info
structure enclosing thisAnnotationDefault
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 thebootstrap_methods
array.- bootstrap_methods[]
Each entry in the
bootstrap_methods
table contains an index to aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_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
injava.lang.invoke.MethodHandle
. The method handlemustshould 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 thebootstrap_arguments
array.- bootstrap_arguments[]
Each entry in the
bootstrap_arguments
array must be a valid index into theconstant_pool
table. Theconstant_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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemindicatesshould indicate the number of parameter descriptors in the method descriptor (4.3.3) referenced by thedescriptor_index
of the attribute's enclosingmethod_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 theparameters
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
itemmustshould either be zero or a valid index into theconstant_pool
table.If the value of the
name_index
item is zero, then thisparameters
element indicates a formal parameter with no name.If the value of the
name_index
item is nonzero, theconstant_pool
entry at that indexmustshould be aCONSTANT_Utf8_info
structure representing a valid unqualified name denoting a formal parameter (4.2.2).- access_flags
The value of the
access_flags
itemisshould 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.)
- 0x0010 (
The i'th entry in the
parameters
array corresponds to the i'th parameter descriptor in the enclosing method's descriptor. (Theparameters_count
item is one byte because a method descriptor is limited to 255 parameters.) Effectively, this means theparameters
array stores information for all the parameters of the method. One could imagine other schemes, where entries in theparameters
array specify their corresponding parameter descriptors, but it would unduly complicate theMethodParameters
attribute.
The i'th entry in the
parameters
array may or may not correspond to the i'th type in the enclosing method'sSignature
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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Module_info
structure (4.4.11).denotingThemodule_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.
- 0x0020 (
- module_version_index
The value of the
module_version_index
item must be either zero or a valid index into theconstant_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 theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure.representingThemodule_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 therequires
table.If the current module is
java.base
, thenrequires_count
must be zero.If the current module is not
java.base
, thenrequires_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Module_info
structure.denotingTherequires_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 itsrequires_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 theclass
file version number is 54.0 or above, then neitherACC_TRANSITIVE
norACC_STATIC_PHASE
may be set inrequires_flags
.- 0x0020 (
- requires_version_index
The value of the
requires_version_index
item must be either zero or a valid index into theconstant_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 theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure.representingTherequires_version_index
item represents the version of the module specified byrequires_index
.
Unless the current module is
java.base
, exactly one entry in therequires
table must have both arequires_index
item which indicatesjava.base
and arequires_flags
item which has theACC_SYNTHETIC
flag not set.- exports_count
The value of the
exports_count
item indicates the number of entries in theexports
table.- exports[]
Each entry in the
exports
table specifies a package exported by the current module, such thatpublic
andprotected
types in the package, and theirpublic
andprotected
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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Package_info
structure (4.4.12).representingTheexports_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 itsexports_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.
- 0x1000 (
- exports_to_count
The value of the
exports_to_count
indicates the number of entries in theexports_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 theexports_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Module_info
structure.denotingEach 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 itsexports_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 theopens
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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Package_info
structure.representingTheopens_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 itsopens_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.
- 0x1000 (
- opens_to_count
The value of the
opens_to_count
indicates the number of entries in theopens_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 theexports_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Module_info
structure.denotingEach 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 itsopens_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 theuses_index
table.- uses_index[]
The value of each entry in the
uses_index
table must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Class_info
structure (4.4.1).representingEach entry represents a service interface which the current module may discover viajava.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 theprovides
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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Class_info
structure.representingTheprovides_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 itsprovides_index
item.- provides_with_count
The value of the
provides_with_count
indicates the number of entries in theprovides_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Class_info
structure.representingEach entry represents a service implementation for the service interface specified byprovides_index
.For each entry in the
provides
table, at most one entry in itsprovides_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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemindicatesmust indicate the number of entries in thepackage_index
table.- package_index[]
The value of each entry in the
package_index
table must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Package_info
structure (4.4.12).representingEach 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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Class_info
structure (4.4.1).representingThemain_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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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 theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Class_info
structure (4.4.1).representingThehost_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
itemmust be a validis an index into theconstant_pool
table. Theconstant_pool
entry at that indexmust beis aCONSTANT_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
itemindicatesmust indicate the number of entries in theclasses
array.- classes[]
Each
valueentry in theclasses
array must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Class_info
structure (4.4.1).representingEach 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 haveNestHost
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:
The first four bytes must contain the right magic number.
All predefined attributes (4.7) must be of the proper length, except for
StackMapTable
,RuntimeVisibleAnnotations
,RuntimeInvisibleAnnotations
,RuntimeVisibleParameterAnnotations
,RuntimeInvisibleParameterAnnotations
,RuntimeVisibleTypeAnnotations
,RuntimeInvisibleTypeAnnotations
, andAnnotationDefault
.The
class
file must not be truncated or have extra bytes at the end.The constant pool must satisfy the constraints documented throughout 4.4.
For example, each
CONSTANT_Class_info
structure in the constant pool must contain in itsname_index
item a valid constant pool index for aCONSTANT_Utf8_info
structure.All field references and method references in the constant pool must have valid names, valid classes, and valid descriptors (4.3).
Format checking does not ensure that the given field or method actually exists in the given class, nor that the descriptors given refer to real classes. Format checking ensures only that these items are well formed. More detailed checking is performed when the bytecodes themselves are verified, and during resolution.
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.
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
.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
validClassFile
structure (4.1, 4.8)class
file (4), loading throws an instance ofClassFormatError
.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 ofClassFormatError
, was introduced to enable easy identification of aClassFormatError
caused by an attempt to load a class whose representation uses an unsupported version of theclass
file format. In JDK 1.1 and earlier, an instance ofNoClassDefFoundError
orClassFormatError
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 anaccess_flags
item which has theACC_MODULE
flag set.
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. OnlyObject
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
.
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
.
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).