Table of Contents
ClassFile
Structure
CONSTANT_Class_info
Structure
CONSTANT_Fieldref_info
, CONSTANT_Methodref_info
, and CONSTANT_InterfaceMethodref_info
Structures
CONSTANT_String_info
Structure
CONSTANT_Integer_info
and CONSTANT_Float_info
Structures CONSTANT_Long_info
and CONSTANT_Double_info
StructuresCONSTANT_NameAndType_info
Structure
CONSTANT_Utf8_info
Structure
CONSTANT_MethodHandle_info
Structure
CONSTANT_MethodType_info
Structure
CONSTANT_InvokeDynamic_info
Structure
ConstantValue
Attribute
Code
AttributeStackMapTable
Attribute
Exceptions
Attribute
InnerClasses
Attribute
EnclosingMethod
Attribute
Synthetic
Attribute
Signature
Attribute
SourceFile
Attribute
SourceDebugExtension
Attribute
LineNumberTable
Attribute
LocalVariableTable
Attribute
LocalVariableTypeTable
Attribute
Deprecated
Attribute
RuntimeVisibleAnnotations
Attribute
RuntimeInvisibleAnnotations
Attribute
RuntimeVisibleParameterAnnotations
Attribute
RuntimeInvisibleParameterAnnotations
Attribute
RuntimeVisibleTypeAnnotations
Attribute
RuntimeInvisibleTypeAnnotations
Attribute
AnnotationDefault
Attribute
BootstrapMethods
Attribute
MethodParameters
Attribute
class
Filesprotected
Members
This chapter describes the
class
file format of the Java Virtual Machine. Each class
file contains the
definition of a single class or interface. Although a class or
interface 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 or interface as being in the class
file format.
A class
file consists of a
stream of 8-bit bytes. All 16-bit, 32-bit, and 64-bit quantities are
constructed by reading in two, four, and eight consecutive 8-bit
bytes, respectively. Multibyte data items are always stored in
big-endian order, where the high bytes come first. In the Java SE platform,
this format is supported by
interfaces java.io.DataInput
and java.io.DataOutput
and classes such as
java.io.DataInputStream
and java.io.DataOutputStream
.
This chapter defines its own set
of data types representing class
file data: The
types u1
, u2
,
and u4
represent an unsigned one-, two-, or
four-byte quantity, respectively. In the Java SE platform, these types may
be read by methods such as readUnsignedByte
,
readUnsignedShort
, and readInt
of the interface java.io.DataInput
.
This chapter presents the
class
file format using pseudostructures written in a C-like
structure notation. To avoid confusion with the fields of classes and
class instances, etc., the contents of the structures describing the
class
file format are referred to as items.
Successive items are stored in the class
file sequentially, without
padding or alignment.
Tables,
consisting of zero or more variable-sized items, are used in several
class
file structures. Although we use C-like array syntax to refer
to table items, the fact that tables are streams of varying-sized
structures means that it is not possible to translate a table index
directly to a byte offset into the table.
Where we refer to a data structure as an array, it consists of zero or more contiguous fixed-sized items and can be indexed like an array.
Reference to an ASCII character in this chapter should be interpreted to mean the Unicode code point corresponding to the ASCII character.
A 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:
The magic
item supplies the magic number
identifying the class
file format; it has the
value 0xCAFEBABE
.
The values of the minor_version
and major_version
items are the minor and
major version numbers of this class
file. Together, a major
and a minor version number determine the version of the
class
file format. If a class
file has
major version
number M and minor version number m, we denote the version of
its class
file format as M.m. Thus, class
file format
versions may be ordered lexicographically, for example, 1.5
< 2.0 < 2.1.
A Java Virtual Machine implementation can support a class
file
format of
version v if and only if v lies in some contiguous range Mi.0
≤ v ≤ Mj.m. The release
level of the Java SE platform to
which a Java Virtual Machine implementation conforms is responsible for
determining the range.
Oracle's Java Virtual Machine implementation in JDK release
1.0.2 supports class
file format versions 45.0 through 45.3
inclusive. JDK releases 1.1.* support class
file format
versions in the range 45.0 through 45.65535 inclusive. For k
≥ 2, JDK release 1.k supports class
file format
versions in the range 45.0 through 44+k.0 inclusive.
The value of the constant_pool_count
item
is equal to the number of entries in the constant_pool
table
plus one. A constant_pool
index is considered valid if it is
greater than zero and less
than constant_pool_count
, with the
exception for constants of type long
and double
noted in
§4.4.5.
The constant_pool
is a table of structures
(§4.4)
representing various string
constants, class and interface names, field names, and other
constants that are referred to within the ClassFile
structure and its substructures. The format of each
constant_pool
table entry is indicated by its first "tag"
byte.
The constant_pool
table is indexed from 1
to constant_pool_count
- 1.
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-A.
Table 4.1-A. 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.
|
An interface is distinguished by the ACC_INTERFACE
flag
being set. If the ACC_INTERFACE
flag is not set, this
class
file defines a class, not an interface.
If the ACC_INTERFACE
flag is set, the ACC_ABSTRACT
flag
must also be set, and the ACC_FINAL
, ACC_SUPER
,
and
ACC_ENUM
flags set must not be set.
If the ACC_INTERFACE
flag is not set, any of the other flags
in Table 4.1-A
may be set except
ACC_ANNOTATION
. However, such a class
file must not have
both its ACC_FINAL
and ACC_ABSTRACT
flags set (JLS
§<IP_ADDRESS>).
The ACC_SUPER
flag indicates which of two alternative
semantics is to be expressed by the invokespecial
instruction (§invokespecial) if it
appears in this class or interface. Compilers to the
instruction set of the Java Virtual Machine should set the ACC_SUPER
flag. In Java SE 8 and above, the Java Virtual Machine considers the
ACC_SUPER
flag to be set in every class
file, regardless
of the actual value of the flag in the class
file and the
version of the class
file.
The ACC_SUPER
flag exists for backward
compatibility with code compiled by older compilers for the
Java programming language. In JDK releases prior to 1.0.2, the compiler
generated access_flags
in which the flag now representing
ACC_SUPER
had no assigned meaning, and Oracle's Java Virtual
Machine
implementation ignored the flag if it was set.
The ACC_SYNTHETIC
flag indicates that this class or
interface was generated by a compiler and does not appear in
source code.
An annotation type must have its ACC_ANNOTATION
flag set. If
the ACC_ANNOTATION
flag is set, the ACC_INTERFACE
flag
must also be set.
The ACC_ENUM
flag indicates that this class or its
superclass is declared as an enumerated type.
All bits of the access_flags
item not assigned in
Table 4.1-A are
reserved for future
use. They should be set to zero in generated class
files and
should be ignored by Java Virtual Machine implementations.
The value of the this_class
item must be a
valid index into the constant_pool
table. The
constant_pool
entry at that index must be a
CONSTANT_Class_info
structure (§4.4.1)
representing the class or interface defined by this class
file.
For a class, the value of the super_class
item either must be zero or must be a valid index into the
constant_pool
table. If the value of
the super_class
item is nonzero, the
constant_pool
entry at that index must be a
CONSTANT_Class_info
structure representing the direct
superclass of the class defined by this class
file. Neither
the direct superclass nor any of its superclasses may have the
ACC_FINAL
flag set in the access_flags
item of its
ClassFile
structure.
If the value of the super_class
item is
zero, then this class
file must represent the class
Object
, the only class or interface without a direct
superclass.
For an interface, the value of the
super_class
item must always be a valid
index into the constant_pool
table. The constant_pool
entry at that index must be a CONSTANT_Class_info
structure
representing the class Object
.
The value of the interfaces_count
item
gives the number of direct superinterfaces of this class or
interface type.
Each value in the interfaces
array must be
a valid index into the constant_pool
table. The
constant_pool
entry at each value of
interfaces[i]
, where 0 ≤ i
< interfaces_count
, must be a
CONSTANT_Class_info
structure representing an interface that
is a direct superinterface of this class or interface type, in
the left-to-right order given in the source for the
type.
The value of the fields_count
item gives
the number of field_info
structures in
the fields
table. The field_info
structures represent all fields, both class variables and
instance variables, declared by this class or interface
type.
Each value in the fields
table must be a
field_info
structure (§4.5)
giving a
complete description of a field in this class or
interface. The fields
table includes only
those fields that are declared by this class or interface. It
does not include items representing fields that are inherited
from superclasses or superinterfaces.
The value of the methods_count
item gives
the number of method_info
structures in
the methods
table.
Each value in the methods
table must be a
method_info
structure (§4.6)
giving a
complete description of a method in this class or
interface. If neither of the ACC_NATIVE
and ACC_ABSTRACT
flags are set in the access_flags
item of a method_info
structure, the Java Virtual Machine instructions implementing the method are
also supplied.
The method_info
structures represent all methods declared by
this class or interface type, including instance methods,
class methods, instance initialization methods
(§2.9),
and any class or interface
initialization method (§2.9). The
methods
table does not include items
representing methods that are inherited from superclasses or
superinterfaces.
The value of the attributes_count
item
gives the number of attributes in the attributes
table of
this class.
Each value of the attributes
table must be an
attribute_info
structure
(§4.7).
The attributes defined by this specification as appearing in
the attributes
table of a ClassFile
structure are listed
in Table 4.7-C.
The rules concerning attributes defined to appear in the
attributes
table of a ClassFile
structure are given in
§4.7.
The rules concerning non-predefined attributes in the
attributes
table of a ClassFile
structure are given in
§4.7.1.
Class and interface names
that appear in class
file structures are always represented in a
fully qualified form known as binary names (JLS
§13.1). Such names are always represented as CONSTANT_Utf8_info
structures (§4.4.7) and thus may be
drawn, where
not further constrained, from the entire Unicode codespace. Class and
interface names are referenced from those CONSTANT_NameAndType_info
structures (§4.4.6) which have
such names as
part of their descriptor (§4.3),
and from all
CONSTANT_Class_info
structures
(§4.4.1).
For historical reasons, the
syntax of binary names that appear in class
file structures differs
from the syntax of binary names documented in JLS §13.1. In this
internal form, the ASCII periods (.
) that normally separate the
identifiers which make up the binary name are replaced by ASCII
forward slashes (/
). The identifiers themselves must be
unqualified names (§4.2.2).
For example, the normal binary name of class
Thread
is java.lang.Thread
. In the internal
form
used in descriptors in the class
file format, a reference to the
name of class Thread
is implemented using a CONSTANT_Utf8_info
structure representing the
string java/lang/Thread
.
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
(§invokespecial) may reference <init>
.
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.
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.
A field descriptor represents the type of a class, instance, or local variable.
The characters
of BaseType, the L
and ;
of ObjectType, and the [
of ArrayType are all ASCII characters.
ClassName represents a binary class or interface name encoded in internal form (§4.2.1).
The interpretation of field descriptors as types is shown in Table 4.3-A.
A field descriptor representing an array type is valid only if it represents a type with 255 or fewer dimensions.
Table 4.3-A. Interpretation of field descriptors
| FieldType term | Type | Interpretation |
|---|---|---|
B |
byte |
signed byte |
C |
char |
Unicode character code point in the Basic Multilingual Plane, encoded with UTF-16 |
D |
double |
double-precision floating-point value |
F |
float |
single-precision floating-point value |
I |
int |
integer |
J |
long |
long integer |
L ClassName ; |
reference |
an instance of class ClassName |
S |
short |
signed short |
Z |
boolean |
true or false |
[ |
reference |
one array dimension |
The field descriptor of an instance variable of type
int
is simply I
.
The field descriptor of an instance variable of type
Object
is Ljava/lang/Object;
. Note that
the
internal form of the binary name for class Object
is used.
The field descriptor of an instance variable of the
multidimensional array type double[][][]
is [[[D
.
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.
The
character V
indicates that the method returns no
value (its result is void
).
The method descriptor for the method:
Object m(int i, double d, Thread t) {...}
is:
(IDLjava/lang/Thread;)Ljava/lang/Object;
Note that the internal forms of the binary names of
Thread
and Object
are used.
A method
descriptor is valid only if it represents method parameters with a
total length of 255 or less, where that length includes the
contribution for this
in the case of instance or interface method
invocations. The total length is calculated by summing the
contributions of the individual parameters, where a parameter of type
long
or double
contributes two units to the
length and a parameter
of any other type contributes one unit.
A method
descriptor is the same whether the method it describes is a class
method or an instance method. Although an instance method is passed
this
, a reference to the object on which the method is being
invoked, in addition to its intended arguments, that fact is not
reflected in the method descriptor. The reference to this
is passed
implicitly by the Java Virtual Machine instructions which invoke instance methods
(§2.6.1, §4.11).
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 item in the
constant_pool
table must begin with a 1-byte tag indicating the kind
of cp_info
entry. The contents of
the info
array vary with the value
of tag
. The valid tags and their values are listed
in Table 4.4-A.
Each tag byte must be followed by
two or more bytes giving information about the specific constant. The
format of the additional information varies with the tag value.
Table 4.4-A. Constant pool tags
| Constant Type | Value |
|---|---|
CONSTANT_Class |
7 |
CONSTANT_Fieldref |
9 |
CONSTANT_Methodref |
10 |
CONSTANT_InterfaceMethodref |
11 |
CONSTANT_String |
8 |
CONSTANT_Integer |
3 |
CONSTANT_Float |
4 |
CONSTANT_Long |
5 |
CONSTANT_Double |
6 |
CONSTANT_NameAndType |
12 |
CONSTANT_Utf8 |
1 |
CONSTANT_MethodHandle |
15 |
CONSTANT_MethodType |
16 |
CONSTANT_InvokeDynamic |
18 |
The CONSTANT_Class_info
structure is used to represent a class or an interface:
CONSTANT_Class_info { u1 tag; u2 name_index; }
The items of the
CONSTANT_Class_info
structure are as follows:
Because arrays are objects,
the opcodes anewarray and multianewarray
- but not the opcode
new - can reference array "classes" via CONSTANT_Class_info
structures in the constant_pool
table. For such array classes, the
name of the class is the descriptor of the array type
(§4.3.2).
For example, the class name representing the
two-dimensional array type int[][]
is [[I
, while the class name representing the
type Thread[]
is [Ljava/lang/Thread;
.
An array type descriptor is valid only if it represents 255 or fewer dimensions.
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:
The tag
item of
a CONSTANT_Fieldref_info
structure has the
value CONSTANT_Fieldref
(9).
The tag
item of
a CONSTANT_Methodref_info
structure has the
value CONSTANT_Methodref
(10).
The tag
item of
a CONSTANT_InterfaceMethodref_info
structure has the value
CONSTANT_InterfaceMethodref
(11).
The value of the class_index
item must be a
valid index into the constant_pool
table. The
constant_pool
entry at that index must be a
CONSTANT_Class_info
structure (§4.4.1)
representing a class or interface type that has the field or
method as a member.
The class_index
item of a
CONSTANT_Methodref_info
structure must be a class type, not
an interface type.
The class_index
item of a
CONSTANT_InterfaceMethodref_info
structure must be an
interface type.
The class_index
item of a
CONSTANT_Fieldref_info
structure may be either a class type
or an interface type.
The value of the name_and_type_index
item
must be a valid index into the constant_pool
table. The
constant_pool
entry at that index must be a
CONSTANT_NameAndType_info
structure
(§4.4.6). This constant_pool
entry
indicates the name and descriptor of the field or
method.
In a CONSTANT_Fieldref_info
, 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 of a CONSTANT_Methodref_info
structure begins with a '<
'
('\u003c
'), then the name must be the
special name <init>
, representing an instance
initialization
method (§2.9).
The return type of such a
method must be void
.
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:
The tag
item of
the CONSTANT_String_info
structure has the value
CONSTANT_String
(8).
The value of
the string_index
item must be a valid index
into the constant_pool
table. The constant_pool
entry at
that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
sequence of
Unicode code points to which the String
object is to be
initialized.
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:
The tag
item of
the CONSTANT_Integer_info
structure has the value
CONSTANT_Integer
(3).
The tag
item of
the CONSTANT_Float_info
structure has the value
CONSTANT_Float
(4).
The bytes
item of
the CONSTANT_Integer_info
structure represents the value of
the int
constant. The bytes of the value are stored in
big-endian (high byte first) order.
The bytes
item of
the CONSTANT_Float_info
structure represents the value of the
float
constant in IEEE 754 floating-point single format
(§2.3.2). The
bytes of the single format
representation are stored in big-endian (high byte first)
order.
The value
represented by the CONSTANT_Float_info
structure is determined
as follows. The bytes of the value are first converted into an
int
constant bits. Then:
If bits
is 0x7f800000
, the float
value will be
positive infinity.
If bits
is 0xff800000
, the float
value will be
negative infinity.
If bits
is in the range 0x7f800001
through
0x7fffffff
or in the
range 0xff800001
through 0xffffffff
, the float
value
will be NaN.
In all other
cases, let s
, e
,
and m
be three values that might be
computed from bits:
int s = ((bits >> 31) == 0) ? 1 : -1; int e = ((bits >> 23) & 0xff); int m = (e == 0) ? (bits & 0x7fffff) << 1 : (bits & 0x7fffff) | 0x800000;
Then the float
value equals the result of the mathematical
expression s · m ·
2e-150
.
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 item
in the constant_pool
table at index n, then the next usable
item in the pool 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:
The tag
item of
the CONSTANT_Long_info
structure has the value CONSTANT_Long
(5).
The tag
item of
the CONSTANT_Double_info
structure has the value
CONSTANT_Double
(6).
The
unsigned high_bytes
and low_bytes
items of the
CONSTANT_Long_info
structure together represent the value of
the long
constant
((long) high_bytes << 32) + low_bytes
where the bytes of
each of high_bytes
and low_bytes
are stored in big-endian (high
byte first) order.
The high_bytes
and low_bytes
items of the
CONSTANT_Double_info
structure together represent the double
value in IEEE 754 floating-point double format
(§2.3.2). The
bytes of each item are
stored in big-endian (high byte first) order.
The value
represented by the CONSTANT_Double_info
structure is
determined as follows. The high_bytes
and low_bytes
items are converted into the
long
constant bits,
which is equal
to
((long) high_bytes << 32) + low_bytes
If bits
is 0x7ff0000000000000L
, the double
value will be positive infinity.
If bits
is 0xfff0000000000000L
, the double
value will be negative infinity.
If bits
is in the range 0x7ff0000000000001L
through
0x7fffffffffffffffL
or in the
range 0xfff0000000000001L
through 0xffffffffffffffffL
, the double
value will be NaN.
In all other
cases, let s
, e
,
and m
be three values that might be
computed from bits:
int s = ((bits >> 63) == 0) ? 1 : -1; int e = (int)((bits >> 52) & 0x7ffL); long m = (e == 0) ? (bits & 0xfffffffffffffL) << 1 : (bits & 0xfffffffffffffL) | 0x10000000000000L;
Then the
floating-point value equals the double
value of the
mathematical expression s · m ·
2e-1075
.
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:
The tag
item of
the CONSTANT_NameAndType_info
structure has the value
CONSTANT_NameAndType
(12).
The value of
the name_index
item must be a valid index
into the constant_pool
table. The constant_pool
entry at
that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing
either the special
method name <init>
(§2.9)
or a valid
unqualified name denoting a field or method
(§4.2.2).
The value of
the descriptor_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing a
valid field
descriptor or method descriptor (§4.3.2,
§4.3.3).
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:
The tag
item of the CONSTANT_Utf8_info
structure has the
value CONSTANT_Utf8
(1).
The value of the length
item gives the
number of bytes in the bytes
array (not the
length of the resulting string).
The bytes
array contains the bytes of the
string.
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:
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
bytes x
and y
:
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
bytes x
, y
,
and z
:
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
, and z
:
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 6.0.0.
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:
The tag
item of the CONSTANT_MethodHandle_info
structure
has the value CONSTANT_MethodHandle
(15).
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
(§<IP_ADDRESS>).
The value of the reference_index
item must
be a valid index into the constant_pool
table. The
constant_pool
entry at that index must be as follows:
If the value of the reference_kind
item
is 1 (REF_getField
), 2 (REF_getStatic
),
3
(REF_putField
), or 4 (REF_putStatic
),
then the
constant_pool
entry at that index must be a
CONSTANT_Fieldref_info
(§4.4.2)
structure representing a field for which a method handle
is to be created.
If the value of the reference_kind
item
is 5 (REF_invokeVirtual
) or 8 (REF_newInvokeSpecial
),
then the constant_pool
entry at that index must be
a
CONSTANT_Methodref_info
structure
(§4.4.2)
representing a class's
method or constructor (§2.9) for
which a method handle is to be created.
If the value of the reference_kind
item
is 6 (REF_invokeStatic
) or 7 (REF_invokeSpecial
), then
if the class
file version number is less than 52.0,
the
constant_pool
entry at that index must be a
CONSTANT_Methodref_info
structure representing a
class's
method for which a method handle is to be created; if the
class
file version number is 52.0 or above, the
constant_pool
entry at that index must be either a
CONSTANT_Methodref_info
structure or a
CONSTANT_InterfaceMethodref_info
structure
(§4.4.2)
representing a class's or
interface's method for which a method handle is to be
created.
If the value of the reference_kind
item
is 9 (REF_invokeInterface
), then the constant_pool
entry at that index must be a
CONSTANT_InterfaceMethodref_info
structure
representing
an interface's method for which a method handle is to be
created.
If the value of the reference_kind
item is
5 (REF_invokeVirtual
), 6 (REF_invokeStatic
),
7
(REF_invokeSpecial
), or 9 (REF_invokeInterface
),
the name
of the method represented by a CONSTANT_Methodref_info
structure or a CONSTANT_InterfaceMethodref_info
structure
must not be <init>
or <clinit>
.
If the value is 8 (REF_newInvokeSpecial
), the name of the
method represented by a CONSTANT_Methodref_info
structure
must be <init>
.
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:
The tag
item of
the CONSTANT_MethodType_info
structure has the value
CONSTANT_MethodType
(16).
The value of
the descriptor_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing a
method descriptor
(§4.3.3).
The
CONSTANT_InvokeDynamic_info
structure is used by an invokedynamic
instruction (§invokedynamic) to specify a
bootstrap method, the dynamic invocation name, the argument and return
types of the call, and optionally, a sequence of additional constants
called static arguments to the bootstrap
method.
CONSTANT_InvokeDynamic_info { u1 tag; u2 bootstrap_method_attr_index; u2 name_and_type_index; }
The items of the
CONSTANT_InvokeDynamic_info
structure are as follows:
The tag
item of
the CONSTANT_InvokeDynamic_info
structure has the value
CONSTANT_InvokeDynamic
(18).
The value of the
bootstrap_method_attr_index
item must be a
valid index into the bootstrap_methods
array
of the bootstrap method table (§4.7.23)
of
this class
file.
The value of the name_and_type_index
item
must be a valid index into the constant_pool
table. The
constant_pool
entry at that index must be a
CONSTANT_NameAndType_info
structure
(§4.4.6)
representing a method name and
method descriptor (§4.3.3).
Each field is described by a
field_info
structure.
No two fields in one class
file may have 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:
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 ; usable only within the defining
class.
|
ACC_PROTECTED |
0x0004 | Declared protected ; may be accessed within
subclasses.
|
ACC_STATIC |
0x0008 | Declared static .
|
ACC_FINAL |
0x0010 | Declared final ; never directly assigned to
after object construction (JLS §17.5).
|
ACC_VOLATILE |
0x0040 | Declared volatile ; cannot be cached.
|
ACC_TRANSIENT |
0x0080 | Declared transient ; not written or read by a
persistent object manager.
|
ACC_SYNTHETIC |
0x1000 | Declared synthetic; not present in the source code. |
ACC_ENUM |
0x4000 | Declared as an element of an enum .
|
Fields of classes may set any of the flags in
Table 4.5-A. However,
each field of a
class may have at most one of its ACC_PUBLIC
, ACC_PRIVATE
,
and ACC_PROTECTED
flags set (JLS §8.3.1), and must not have
both its ACC_FINAL
and ACC_VOLATILE
flags set (JLS
§<IP_ADDRESS>).
Fields of interfaces must have their ACC_PUBLIC
,
ACC_STATIC
, and ACC_FINAL
flags set;
they may have their
ACC_SYNTHETIC
flag set and must not have any of the other
flags in Table 4.5-A
set (JLS
§9.3).
The ACC_SYNTHETIC
flag indicates that this field was
generated by a compiler and does not appear in source
code.
The ACC_ENUM
flag indicates that this field is used to hold
an element of an enumerated type.
All bits of the access_flags
item not assigned in
Table 4.5-A are
reserved for future
use. They should be set to zero in generated class
files and
should be ignored by Java Virtual Machine implementations.
The value of the
name_index
item must be a valid index into
the constant_pool
table. The constant_pool
entry at that
index must be a CONSTANT_Utf8_info
structure
(§4.4.7) which represents a
valid
unqualified name denoting a field
(§4.2.2).
The value of the
descriptor_index
item must be a valid index
into the constant_pool
table. The constant_pool
entry at
that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) which represents a
valid field
descriptor (§4.3.2).
The value of the
attributes_count
item indicates the number of
additional attributes of this field.
Each value of the
attributes
table must be an attribute_info
structure
(§4.7).
A field can have any number of optional attributes associated with it.
The attributes defined by this specification as appearing in
the attributes
table of a field_info
structure are listed
in Table 4.7-C.
The rules concerning attributes defined to appear in the
attributes
table of a field_info
structure are given in
§4.7.
The rules concerning non-predefined attributes in the
attributes
table of a field_info
structure are given in
§4.7.1.
Each method, including each
instance initialization method (§2.9) and the
class or interface initialization method (§2.9),
is described by a method_info
structure.
No two methods in one class
file may have 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:
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.
|
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 Java.
|
ACC_ABSTRACT |
0x0400 | Declared abstract ; no implementation is
provided.
|
ACC_STRICT |
0x0800 | Declared strictfp ; floating-point mode is
FP-strict.
|
ACC_SYNTHETIC |
0x1000 | Declared synthetic; not present in the source code. |
Methods of classes may have any of the flags in
Table 4.6-A set.
However, each method
of a class may have at most one of its ACC_PUBLIC
,
ACC_PRIVATE
, and ACC_PROTECTED
flags
set (JLS
§8.4.3).
Methods of interfaces may have any of the flags in
Table 4.6-A set
except ACC_PROTECTED
,
ACC_FINAL
, ACC_SYNCHRONIZED
, and ACC_NATIVE
(JLS
§9.4). In a class
file whose version number is less than
52.0, each method of an interface must have its ACC_PUBLIC
and ACC_ABSTRACT
flags set; in a class
file whose version
number is 52.0 or above, each method of an interface must have
exactly one of its ACC_PUBLIC
and ACC_PRIVATE
flags
set.
If a method of a class or interface has its ACC_ABSTRACT
flag set, it must not have any of its ACC_PRIVATE
,
ACC_STATIC
, ACC_FINAL
, ACC_SYNCHRONIZED
, ACC_NATIVE
, or
ACC_STRICT
flags set.
Each instance initialization method
(§2.9)
may have at most one of its
ACC_PUBLIC
, ACC_PRIVATE
, and ACC_PROTECTED
flags set,
and may also have its ACC_VARARGS
, ACC_STRICT
, and
ACC_SYNTHETIC
flags set, but must not have any of the other
flags in Table 4.6-A
set.
Class and interface initialization methods are called
implicitly by the Java Virtual Machine. The value of their access_flags
item is ignored except for the setting of the ACC_STRICT
flag.
The ACC_BRIDGE
flag is used to indicate a bridge method
generated by a compiler for the Java programming language.
The ACC_VARARGS
flag indicates that this method takes a
variable number of arguments at the source code level. A
method declared to take a variable number of arguments must be
compiled with the ACC_VARARGS
flag set to 1. All other
methods must be compiled with the ACC_VARARGS
flag set to
0.
The ACC_SYNTHETIC
flag indicates that this method was
generated by a compiler and does not appear in source code,
unless it is one of the methods named in
§4.7.8.
All bits of the access_flags
item not assigned in
Table 4.6-A are
reserved for future
use. They should be set to zero in generated class
files and
should be ignored by Java Virtual Machine implementations.
The value of the
name_index
item must be a valid index into
the constant_pool
table. The constant_pool
entry at that
index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing either
one of the
special method names <init>
or <clinit>
(§2.9),
or a valid unqualified name
denoting a method (§4.2.2).
The value of the
descriptor_index
item must be a valid index
into the constant_pool
table. The constant_pool
entry at
that index must be a CONSTANT_Utf8_info
structure representing
a valid method descriptor (§4.3.3).
A future edition of this specification may
require that the last parameter descriptor of the method
descriptor is an array type if the ACC_VARARGS
flag is set in
the access_flags
item.
The value of the
attributes_count
item indicates the number of
additional attributes of this method.
Each value of the
attributes
table must be an attribute_info
structure
(§4.7).
A method can have any number of optional attributes associated with it.
The attributes defined by this specification as appearing in
the attributes
table of a method_info
structure are listed
in Table 4.7-C.
The rules concerning attributes defined to appear in the
attributes
table of a method_info
structure are given in
§4.7.
The rules concerning non-predefined attributes in the
attributes
table of a method_info
structure are given in
§4.7.1.
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
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 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.
23 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 accompanied
by the first version of the class
file format in which it was
defined, and the corresponding version of the Java SE platform. (For
old class
file versions, the JDK release is used instead of
the Java SE platform version).
Table 4.7-B
is orderd by the first version of
the class
file format in which each attribute was
defined.
Table 4.7-C
is ordered by the location in a
class
file where each attribute is defined to appear.
Within the context of their
use in this specification, that is, in the attributes
tables of the
class
file structures 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:
Five attributes are critical to correct interpretation of the
class
file by the Java Virtual Machine:
In a class
file of version V, each of
these attributes must
be recognized and correctly read by an implementation of the
Java Virtual Machine if the implementation recognizes class
files
of version
V, and V is at least the version where the
attribute was
first defined, and the attribute appears in a location where it
is defined to appear.
Twelve attributes are critical to correct interpretation of the
class
file by the class libraries of the Java SE platform:
Each of these attributes in a class
file of version V must
be recognized and correctly read by an implementation of the
class libraries of the Java SE platform if the implementation
recognizes class
files of version V, and
V is at least the
version where the attribute was first defined, and the attribute
appears in a location where it is defined to appear.
Six attributes are not critical to correct interpretation of the
class
file by either the Java Virtual Machine or the class
libraries of the
Java SE platform, but are useful for tools:
Use of these attributes by an implementation of the Java Virtual Machine or the class libraries of the Java SE platform is optional. An implementation 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 |
Table 4.7-B. Predefined class
file attributes (by
class
file version)
| 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 |
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 |
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 |
Compilers are permitted to define
and emit class
files containing new 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 attributes found in these attributes
tables. However, any attribute not defined as part of the class
file
specification must not affect the semantics of the class
file. Java Virtual
Machine implementations are required to
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 must have names chosen according to the package naming convention described in The Java Language Specification, Java SE 8 Edition (JLS §6.1).
Future versions of this specification may define additional attributes.
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:
If the ACC_STATIC
flag in the access_flags
item of the field_info
structure is
set, then the field represented by the
field_info
structure is assigned the value represented by its
ConstantValue
attribute as part of the initialization of the
class or interface declaring the field
(§5.5).
This occurs prior to the
invocation of the class or interface initialization method of
that class or interface (§2.9).
Otherwise, the Java Virtual Machine must silently ignore the attribute.
There may be at most one
ConstantValue
attribute in the attributes
table of a field_info
structure.
The ConstantValue
attribute has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"ConstantValue
".
The value of
the attribute_length
item of a
ConstantValue_attribute
structure must be
two.
The value of the
constantvalue_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index gives the constant value represented by this
attribute. The constant_pool
entry must be of a type
appropriate to the field, as specified in
Table 4.7.2-A.
Table 4.7.2-A. Constant value attribute types
| Field Type | Entry Type |
|---|---|
long |
CONSTANT_Long |
float |
CONSTANT_Float |
double |
CONSTANT_Double |
int , short , char , byte , boolean |
CONSTANT_Integer |
String |
CONSTANT_String |
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 or a class or interface
initialization method (§2.9).
If the method is either
native
or abstract
, 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.
The Code
attribute has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"Code
".
The value of the
attribute_length
item indicates the length of
the attribute, excluding the initial six bytes.
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.
The value of the
max_locals
item gives the number of local
variables in the local variable array allocated upon invocation
of this method (§2.6.1), including the
local variables used to pass parameters to the method on its
invocation.
The greatest local
variable index for a value of type long
or double
is
max_locals - 2
. The greatest local variable
index for a value of any other type is max_locals -
1
.
The value of the
code_length
item gives the number of bytes
in the code
array for this method.
The
value of code_length
must be greater than
zero (as the code
array must not be empty) and less than
65536.
The code
array
gives the actual bytes of Java Virtual Machine code that implement the
method.
When
the code
array is read into memory on a
byte-addressable machine, if the first byte of the array is
aligned on a 4-byte boundary, the tableswitch and
lookupswitch 32-bit offsets will be 4-byte aligned.
(Refer to
the descriptions of those instructions for more information on
the consequences of code
array
alignment.)
The detailed
constraints on the contents of the code
array
are extensive and are given in a separate section
(§4.9).
The value of the
exception_table_length
item gives the number
of entries in the exception_table
table.
Each entry in the
exception_table
array describes one exception
handler in the code
array. The order of the handlers in
the exception_table
array is significant
(§2.10).
Each
exception_table
entry contains the following
four items:
The values
of the two items start_pc
and end_pc
indicate the ranges in the
code
array at which the exception handler is
active. The
value of start_pc
must be a valid index
into the code
array of the opcode of an
instruction. The
value of end_pc
either must be a valid
index into the code
array of the opcode of an
instruction or must be equal
to code_length
, the length of the
code
array. The value of start_pc
must be less than the value
of end_pc
.
The
start_pc
is inclusive
and end_pc
is exclusive; that is, the
exception handler must be active while the program counter
is within the interval
[start_pc
, end_pc
).
The fact that end_pc
is exclusive is a historical mistake in the design of the
Java Virtual Machine: if the Java Virtual Machine code for a method is exactly
65535
bytes long and ends with an instruction that is 1 byte
long, then that instruction cannot be protected by an
exception handler. A compiler writer can work around this
bug by limiting the maximum size of the generated Java Virtual Machine
code for any method, instance initialization method, or
static initializer (the size of any code array) to 65534
bytes.
The value
of the handler_pc
item indicates the
start of the exception handler. The value of the item must
be a valid index into the code
array and must be
the
index of the opcode of an instruction.
If the
value of the catch_type
item is
nonzero, it must be a valid index into the
constant_pool
table. The constant_pool
entry at that
index must be a CONSTANT_Class_info
structure
(§4.4.1)
representing a class of
exceptions that this exception handler is designated to
catch. The exception handler will be called only if the
thrown exception is an instance of the given class or
one of its subclasses.
The verifier checks that the class is
Throwable
or a subclass of Throwable
(§4.9.2).
If the
value of the catch_type
item is zero,
this exception handler is called for all
exceptions.
This is used to implement finally
(§3.13).
The value of the
attributes_count
item indicates the number of
attributes of the Code
attribute.
Each value of the
attributes
table must be an attribute_info
structure
(§4.7).
A Code
attribute
can have any number of optional attributes associated with
it.
The attributes defined by this specification as appearing in
the attributes
table of a Code
attribute are listed in
Table 4.7-C.
The rules concerning attributes defined to appear in the
attributes
table of a Code
attribute are given in
§4.7.
The rules concerning non-predefined attributes in the
attributes
table of a Code
attribute are given in
§4.7.1.
The StackMapTable
attribute is a variable-length attribute in the attributes
table of
a Code
attribute (§4.7.3).
A StackMapTable
attribute is used during the process of verification by type checking
(§4.10.1).
There may be at most 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 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"StackMapTable
".
The value of the
attribute_length
item indicates the length of
the attribute, excluding the initial six bytes.
The value of the
number_of_entries
item gives the number of
stack_map_frame
entries in
the entries
table.
Each entry in
the entries
table describes one stack map
frame of the method. The order of the stack map frames in
the entries
table is significant.
A stack map frame specifies (either explicitly or implicitly) the bytecode offset at which it applies, and the verification types of local variables and operand stack entries for that offset.
Each stack map frame
described in the entries
table relies on the
previous frame for some of its semantics. The first stack map frame of
a method is implicit, and computed from the method descriptor by the
type checker (§<IP_ADDRESS>). 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 type top
.
Top_variable_info { u1 tag = ITEM_Top; /* 0 */ }
The
Integer_variable_info
item indicates that the location has the
verification type int
.
Integer_variable_info { u1 tag = ITEM_Integer; /* 1 */ }
The
Float_variable_info
item indicates that the location has the
verification type float
.
Float_variable_info { u1 tag = ITEM_Float; /* 2 */ }
The
Null_variable_info
type indicates that the location has the
verification type null
.
Null_variable_info { u1 tag = ITEM_Null; /* 5 */ }
The
UninitializedThis_variable_info
item indicates that the
location has the verification type uninitializedThis
.
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 represented by the
CONSTANT_Class_info
structure (§4.4.1)
found in the constant_pool
table at the index given by
cpool_index
.
Object_variable_info { u1 tag = ITEM_Object; /* 7 */ u2 cpool_index; }
The
Uninitialized_variable_info
item indicates that the location
has the verification type uninitialized(Offset)
.
The Offset
item indicates the offset, in the
code
array of the Code
attribute
that contains this
StackMapTable
attribute, of the new instruction
(§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 type long
.
Long_variable_info { u1 tag = ITEM_Long; /* 4 */ }
The
Double_variable_info
item indicates that the first of two
locations has the verification type double
.
Double_variable_info { u1 tag = ITEM_Double; /* 3 */ }
The
Long_variable_info
and Double_variable_info
items indicate
the verification type of the second of two locations as
follows:
A stack map frame is
represented by a discriminated union,
stack_map_frame
, which 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 stack_map_frame { same_frame; same_locals_1_stack_item_frame; same_locals_1_stack_item_frame_extended; chop_frame; same_frame_extended; append_frame; full_frame; }
The tag indicates the frame type of the stack map frame:
The frame type
same_frame
is represented by tags in the range [0-63]. This
frame type indicates that the frame has exactly the same local
variables as the previous frame and that the operand stack is
empty. The offset_delta
value for the frame is the value of
the tag item, frame_type
.
same_frame { u1 frame_type = SAME; /* 0-63 */ }
The frame type
same_locals_1_stack_item_frame
is represented by tags in the
range [64, 127]. This frame type indicates that the frame has
exactly the same local variables as the previous frame and that
the operand stack has one entry. The offset_delta
value for
the frame is given by the formula frame_type -
64
. The verification type of the one stack entry
appears after the frame type.
same_locals_1_stack_item_frame { u1 frame_type = SAME_LOCALS_1_STACK_ITEM; /* 64-127 */ verification_type_info stack[1]; }
The frame type
same_locals_1_stack_item_frame_extended
is represented by the
tag 247. This frame type indicates that the frame has exactly
the same local variables as the previous frame and that the
operand stack has one entry. The offset_delta
value for the
frame is given explicitly, unlike in the frame type
same_locals_1_stack_item_frame
. The verification type of the
one stack entry appears after offset_delta
.
same_locals_1_stack_item_frame_extended { u1 frame_type = SAME_LOCALS_1_STACK_ITEM_EXTENDED; /* 247 */ u2 offset_delta; verification_type_info stack[1]; }
The frame type
chop_frame
is represented by tags in the range [248-250]. This
frame type indicates that the frame has the same local variables
as the previous frame except that the last k local
variables are absent, and that the operand stack is empty. The
value of k is given by the formula 251 -
frame_type
. The offset_delta
value for the frame is
given explicitly.
chop_frame { u1 frame_type = CHOP; /* 248-250 */ u2 offset_delta; }
Assume the verification types of local variables in the previous
frame are given by locals
, an array
structured as in the full_frame
frame type.
If locals[M-1]
in the previous frame
represented local variable X and locals[M]
represented local variable Y, then the effect of removing one
local variable is that locals[M-1]
in the new
frame represents local variable X and
locals[M]
is undefined.
It is an error if k is larger than the number of
local variables
in locals
for the previous frame, that is, if
the number of local variables in the new frame would be less
than zero.
The frame type
same_frame_extended
is represented by the tag 251. This frame
type indicates that the frame has exactly the same local variables
as the previous frame and that the operand stack is empty. The
offset_delta
value for the frame is given explicitly, unlike in
the frame type same_frame
.
same_frame_extended { u1 frame_type = SAME_FRAME_EXTENDED; /* 251 */ u2 offset_delta; }
The frame type
append_frame
is represented by tags in the range
[252-254]. This frame type indicates that the frame has the same
locals as the previous frame except that k additional
locals are defined, and that the operand stack is empty. The
value of k is given by the formula frame_type -
251
. The offset_delta
value for the frame is given
explicitly.
append_frame { u1 frame_type = APPEND; /* 252-254 */ u2 offset_delta; verification_type_info locals[frame_type - 251]; }
The 0th entry in
locals
represents the verification type of
the first additional local
variable. If locals[M]
represents local
variable N
, then:
locals[M+1]
represents local variable N+1
if locals[M]
is one of
Top_variable_info
, Integer_variable_info
,
Float_variable_info
, Null_variable_info
,
UninitializedThis_variable_info
, Object_variable_info
,
or Uninitialized_variable_info
; and
locals[M+1]
represents local variable N+2
if locals[M]
is either
Long_variable_info
or Double_variable_info
.
It
is an error if, for any index i,
locals[i]
represents a
local variable
whose index is greater than the maximum number of local
variables for the method.
The frame type
full_frame
is represented by the tag 255. The offset_delta
value for the frame is given explicitly.
full_frame { u1 frame_type = FULL_FRAME; /* 255 */ u2 offset_delta; u2 number_of_locals; verification_type_info locals[number_of_locals]; u2 number_of_stack_items; verification_type_info stack[number_of_stack_items]; }
The 0th entry in
locals
represents the verification type of
local variable 0. If locals[M]
represents local
variable N
, then:
locals[M+1]
represents local variable N+1
if locals[M]
is one of
Top_variable_info
, Integer_variable_info
,
Float_variable_info
, Null_variable_info
,
UninitializedThis_variable_info
, Object_variable_info
,
or Uninitialized_variable_info
; and
locals[M+1]
represents local variable N+2
if locals[M]
is either
Long_variable_info
or Double_variable_info
.
It
is an error if, for any index i,
locals[i]
represents a
local variable
whose index is greater than the maximum number of local
variables for the method.
The 0th entry in
stack
represents the verification type of the
bottom of the operand stack, and subsequent entries
in stack
represent the verification types of
stack entries closer to the top of the operand stack. We refer
to the bottom of the operand stack as stack entry 0, and to
subsequent entries of the operand stack as stack entry 1, 2,
etc. If stack[M]
represents stack
entry N
, then:
stack[M+1]
represents stack
entry N+1
if
stack[M]
is one of Top_variable_info
,
Integer_variable_info
, Float_variable_info
,
Null_variable_info
, UninitializedThis_variable_info
,
Object_variable_info
, or Uninitialized_variable_info
;
and
stack[M+1]
represents stack entry N+2
if stack[M]
is either
Long_variable_info
or Double_variable_info
.
It
is an error if, for any index i,
stack[i]
represents a
stack entry whose
index is greater than the maximum operand stack size for the
method.
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 one
Exceptions
attribute in the attributes
table
of a method_info
structure.
The Exceptions
attribute
has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be the CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"Exceptions
".
The value of
the attribute_length
item indicates the
attribute length, excluding the initial six bytes.
The value of the
number_of_exceptions
item indicates the
number of entries in
the exception_index_table
.
Each value in
the exception_index_table
array must be a
valid index into the constant_pool
table. The constant_pool
entry at that index must be a CONSTANT_Class_info
structure
(§4.4.1) representing a
class type that
this method is declared to throw.
A method should throw an exception only if at least one of the following three criteria is met:
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.
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 InnerClasses
attribute
has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"InnerClasses
".
The value of
the attribute_length
item indicates the
length of the attribute, excluding the initial six bytes.
The value of the
number_of_classes
item indicates the number
of entries in the classes
array.
Every
CONSTANT_Class_info
entry in the constant_pool
table which
represents a class or interface C that is not a package
member must have exactly one corresponding entry in
the classes
array.
If a class or interface has members that are
classes or interfaces, its constant_pool
table (and hence
its InnerClasses
attribute) must refer to each such member
(JLS §13.1), even if that member is not otherwise mentioned by
the class.
In addition, the constant_pool
table of every nested class and nested interface must refer to
its enclosing class, so altogether, every nested class and
nested interface will have InnerClasses
information for each
enclosing class and for each of its own nested classes and
interfaces.
Each entry in
the classes
array contains the following
four items:
The value
of the inner_class_info_index
item must
be a valid index into the constant_pool
table. The
constant_pool
entry at that index must be a
CONSTANT_Class_info
structure representing C. The
remaining items in the classes
array
entry give information about C.
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)),
the value of the outer_class_info_index
item must be zero.
Otherwise, the value of
the outer_class_info_index
item must be
a valid index into the constant_pool
table, and the
entry at that index must be a CONSTANT_Class_info
structure representing the class or interface of which C
is a member.
If C is
anonymous (JLS §15.9.5), the value of
the inner_name_index
item must be
zero.
Otherwise, the value of
the inner_name_index
item must be a
valid index into the constant_pool
table, and the
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) that
represents the
original simple name of C, as given in the source code
from which this class
file was compiled.
The value
of the inner_class_access_flags
item is
a mask of flags used to denote access permissions to and
properties of class or interface C as declared in the
source code from which this class
file was
compiled. It
is used by a compiler to recover the original information
when source code is not available. The flags are specified
in Table 4.7.6-A.
Table 4.7.6-A. Nested class access and property flags
| Flag Name | Value | Interpretation |
|---|---|---|
ACC_PUBLIC |
0x0001 | Marked or implicitly public in
source.
|
ACC_PRIVATE |
0x0002 | Marked private in source.
|
ACC_PROTECTED |
0x0004 | Marked protected in source.
|
ACC_STATIC |
0x0008 | Marked or implicitly static in
source.
|
ACC_FINAL |
0x0010 | Marked final in source.
|
ACC_INTERFACE |
0x0200 | Was an interface in source.
|
ACC_ABSTRACT |
0x0400 | Marked or implicitly abstract in
source.
|
ACC_SYNTHETIC |
0x1000 | Declared synthetic; not present in the source code. |
ACC_ANNOTATION |
0x2000 | Declared as an annotation type. |
ACC_ENUM |
0x4000 | Declared as an enum type.
|
All bits
of the inner_class_access_flags
item
not assigned in Table 4.7.6-A
are
reserved for future use. They should be set to zero in
generated class
files and should be ignored by Java
Virtual Machine
implementations.
If a class
file has a version number that is 51.0 or above,
and has an InnerClasses
attribute in its attributes
table,
then for all entries in the classes
array
of the InnerClasses
attribute, the value of the
outer_class_info_index
item must be zero if
the value of the inner_name_index
item is
zero.
Oracle's Java Virtual Machine implementation does not check the
consistency of an InnerClasses
attribute against a class
file
representing a class or interface referenced by the attribute.
The EnclosingMethod
attribute is
a fixed-length attribute in the attributes
table of a ClassFile
structure (§4.1).
A class must 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 one
EnclosingMethod
attribute in the attributes
table of a ClassFile
structure.
The EnclosingMethod
attribute has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"EnclosingMethod
".
The value of the class_index
item must be a
valid index into the constant_pool
table. The
constant_pool
entry at that index must be a
CONSTANT_Class_info
structure (§4.4.1)
representing the innermost class that encloses the declaration
of the current class.
If the current class
is not immediately enclosed by a method or constructor, then
the value of the method_index
item must be
zero.
In
particular, method_index
must be zero if
the current class was immediately enclosed in source code by
an instance initializer, static initializer, instance variable
initializer, or class variable initializer. (The first two
concern both local classes and anonymous classes, while the
last two concern anonymous classes declared on the right hand
side of a field assignment.)
Otherwise, the
value of the method_index
item must be a
valid index into the constant_pool
table. The
constant_pool
entry at that index must be a
CONSTANT_NameAndType_info
structure
(§4.4.6)
representing the name and type
of a method in the class referenced by
the class_index
attribute above.
It is the responsibility of a Java compiler to
ensure that the method identified via
the method_index
is indeed the closest
lexically enclosing method of the class that contains this
EnclosingMethod
attribute.
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 be marked using a
Synthetic
attribute, or else it must 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), the class
initialization
method (§2.9),
and
the Enum.values()
and Enum.valueOf()
methods.
The Synthetic
attribute was introduced in JDK 1.1
to support nested classes and interfaces.
The Synthetic
attribute
has the following format:
Synthetic_attribute { u2 attribute_name_index; u4 attribute_length; }
The items of
the Synthetic_attribute
structure are as
follows:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"Synthetic
".
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).
A Signature
attribute records a signature (§<IP_ADDRESS>) 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 8 Edition
for details about these types.
The Signature
attribute
has 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:
The value of
the attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"Signature
".
The value of the
attribute_length
item of a
Signature_attribute
structure must be
two.
The value of the
signature_index
item must be a valid index
into the constant_pool
table. The constant_pool
entry at
that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing a
class signature if
this Signature
attribute is an attribute of a ClassFile
structure; a method signature if this Signature
attribute is
an attribute of a method_info
structure; or a field signature
otherwise.
Oracle's Java Virtual Machine implementation does not check the
well-formedness of Signature
attributes during class loading or
linking. Instead, Signature
attributes are checked by methods of the
Java SE platform class libraries which expose generic signatures of classes,
interfaces, constructors, methods, and fields. Examples
include getGenericSuperclass
in Class
and toGenericString
in java.lang.reflect.Executable
.
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 emit a signature for any class, interface, constructor, method, or field whose declaration uses type variables or parameterized types. Specifically, a Java compiler must 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 no throws
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 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 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.
The following production from §4.3.2 is repeated here for convenience:
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 must 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.
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.
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.
The following production from §4.3.3 is repeated here for convenience:
Due to compiler-generated artifacts, the method signature of a method may not correspond exactly to the method descriptor of the method (§4.3.3). In particular, the number of formal parameter types in the method signature may be less than the number of parameter descriptors in the method descriptor.
A field signature encodes the (possibly parameterized) type of a field, formal parameter, or local variable declaration.
The SourceFile
attribute
is an optional fixed-length attribute in the attributes
table of a
ClassFile
structure (§4.1).
There may be at most one
SourceFile
attribute in the attributes
table
of a ClassFile
structure.
The SourceFile
attribute
has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"SourceFile
".
The value of
the attribute_length
item of
a SourceFile_attribute
structure must be
two.
The value of the
sourcefile_index
item must be a valid index
into the constant_pool
table. The constant_pool
entry at
that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing a
string.
The string referenced by
the sourcefile_index
item will be
interpreted as indicating the name of the source file from
which this class
file was compiled. It will not be
interpreted as indicating the name of a directory containing
the file or an absolute path name for the file; such
platform-specific additional information must be supplied by
the run-time interpreter or development tool at the time the
file name is actually used.
The SourceDebugExtension
attribute is an optional attribute in the attributes
table of a
ClassFile
structure (§4.1).
There may be at most 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"SourceDebugExtension
".
The value of the
attribute_length
item indicates the length of
the attribute, excluding the initial six bytes.
The debug_extension
array holds extended debugging information which has no semantic
effect on the Java Virtual Machine. The information is represented using a
modified UTF-8 string (§4.4.7)
with no
terminating zero byte.
Note that
the debug_extension
array may denote a string
longer than that which can be represented with an instance of
class String
.
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.
The LineNumberTable
attribute has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"LineNumberTable
".
The value of the
attribute_length
item indicates the length of
the attribute, excluding the initial six bytes.
The value of the
line_number_table_length
item indicates the
number of entries in the line_number_table
array.
Each entry in the
line_number_table
array indicates that the
line number in the original source file changes at a given point
in the code
array. Each line_number_table
entry must contain the following two items:
The value
of the start_pc
item must indicate the
index into the code
array at which the code for a
new
line in the original source file begins.
The value
of start_pc
must be less than the value
of the code_length
item of the Code
attribute of which this LineNumberTable
is an
attribute.
The value
of the line_number
item must give the
corresponding line number in the original source
file.
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.
The LocalVariableTable
attribute has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"LocalVariableTable
".
The value of the
attribute_length
item indicates the length of
the attribute, excluding the initial six bytes.
The value of the
local_variable_table_length
item indicates
the number of entries in
the local_variable_table
array.
Each entry in the
local_variable_table
array indicates a range
of code
array offsets within which a local variable has a
value. It also 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:
The given
local variable must have a value at indices into the
code
array in the interval
[start_pc
, start_pc +
length
), that is,
between start_pc
inclusive
and start_pc + length
exclusive.
The value
of start_pc
must be a valid index into
the code
array of this Code
attribute and must be the
index of the opcode of an instruction.
The value of
start_pc + length
must either be a
valid index into the code
array of this Code
attribute
and be the index of the opcode of an instruction, or it
must be the first index beyond the end of that code
array.
The value
of the name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry at that index must contain a CONSTANT_Utf8_info
structure (§4.4.7)
representing a
valid unqualified name denoting a local variable
(§4.2.2).
The value
of the descriptor_index
item must be a
valid index into the constant_pool
table. The
constant_pool
entry at that index must contain a
CONSTANT_Utf8_info
structure
(§4.4.7)
representing a field
descriptor which encodes the type of a local variable in
the source program (§4.3.2).
The given
local variable must be at index
in the
local variable array of the current frame.
If the
local variable at index
is of type
double
or long
, it
occupies
both index
and index +
1
.
The
LocalVariableTypeTable
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
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.
The LocalVariableTypeTable
attribute differs from
the LocalVariableTable
attribute (§4.7.13)
in
that it provides signature information rather than descriptor
information. This difference is only significant for variables whose
type uses a type variable or parameterized type. Such variables will
appear in both tables, while variables of other types will appear only
in LocalVariableTable
.
The
LocalVariableTypeTable
attribute has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"LocalVariableTypeTable
".
The value of the
attribute_length
item indicates the length of
the attribute, excluding the initial six bytes.
The value of the
local_variable_type_table_length
item
indicates the number of entries in
the local_variable_type_table
array.
Each entry in the
local_variable_type_table
array indicates a
range of code
array offsets within which a local variable has
a value. It also 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:
The given
local variable must have a value at indices into the
code
array in the interval
[start_pc
, start_pc +
length
), that is,
between start_pc
inclusive
and start_pc + length
exclusive.
The value
of start_pc
must be a valid index into
the code
array of this Code
attribute and must be the
index of the opcode of an instruction.
The value
of start_pc + length
must either be a
valid index into the code
array of this Code
attribute
and be the index of the opcode of an instruction, or it
must be the first index beyond the end of that code
array.
The value
of the name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry at that index must contain a CONSTANT_Utf8_info
structure (§4.4.7)
representing a
valid unqualified name denoting a local variable
(§4.2.2).
The value
of the signature_index
item must be a
valid index into the constant_pool
table. The
constant_pool
entry at that index must contain a
CONSTANT_Utf8_info
structure
(§4.4.7)
representing a field
signature which encodes the type of a local variable in
the source program
(§<IP_ADDRESS>).
The given
local variable must be at index
in the
local variable array of the current frame.
If the
local variable at index
is of type
double
or long
, it
occupies
both index
and index +
1
.
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.
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 the following format:
Deprecated_attribute { u2 attribute_name_index; u4 attribute_length; }
The items of
the Deprecated_attribute
structure are as
follows:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"Deprecated
".
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).
The
RuntimeVisibleAnnotations
attribute records run-time visible
annotations on the declaration of the corresponding class, field, or
method. The Java Virtual Machine must make these annotations available so they can be
returned by the appropriate reflective APIs.
There may be at most one
RuntimeVisibleAnnotations
attribute in the attributes
table of a
ClassFile
, field_info
, or method_info
structure.
The
RuntimeVisibleAnnotations
attribute has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"RuntimeVisibleAnnotations
".
The value of the
attribute_length
item indicates the length
of the attribute, excluding the initial six bytes.
The value of the
num_annotations
item gives the number of
run-time visible annotations represented by the
structure.
Each entry in the
annotations
table represents a single
run-time visible annotation on a
declaration. The annotation
structure has
the following format:
annotation { u2 type_index; u2 num_element_value_pairs; { u2 element_name_index; element_value value; } element_value_pairs[num_element_value_pairs]; }
The items of the
annotation
structure are as follows:
The value
of the type_index
item must be a
valid index into the constant_pool
table. The
constant_pool
entry at that index must be a
CONSTANT_Utf8_info
structure
(§4.4.7)
representing a field
descriptor (§4.3.2). The field
descriptor denotes the type of the annotation
represented by this annotation
structure.
The value
of the num_element_value_pairs
item
gives the number of element-value pairs of the annotation
represented by this annotation
structure.
Each
value of the element_value_pairs
table
represents a single element-value pair in the annotation
represented by this annotation
structure. Each element_value_pairs
entry contains the following two items:
The value of the
element_name_index
item must be
a valid index into the constant_pool
table. The
constant_pool
entry at that index must
be a
CONSTANT_Utf8_info
structure
(§4.4.7).
The
constant_pool
entry denotes the name of
the
element of the element-value pair represented by
this element_value_pairs
entry.
In other words, the entry denotes
an element of the annotation type specified
by type_index
.
The value of
the value
item represents the
value of the element-value pair represented by this
element_value_pairs
entry.
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 <IP_ADDRESS>-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 <IP_ADDRESS>-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:
The const_value_index
item denotes either a
primitive constant value or a String
literal as the value
of
this element-value pair.
The value of the const_value_index
item
must be a valid index into the constant_pool
table. The
constant_pool
entry at that index must be of a type
appropriate to the tag
item, as specified in the fourth
column of Table <IP_ADDRESS>-A.
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:
The value of the type_name_index
item
must be a valid index into the constant_pool
table. The constant_pool
entry at that index
must be a
CONSTANT_Utf8_info
structure
(§4.4.7)
representing a field
descriptor (§4.3.2). The
constant_pool
entry gives the internal form of
the
binary name of the type of the enum constant represented
by this element_value
structure
(§4.2.1).
The value of the const_name_index
item must be a valid index into the constant_pool
table. The constant_pool
entry at that index
must be a
CONSTANT_Utf8_info
structure
(§4.4.7).
The constant_pool
entry gives the simple name of the enum constant
represented by this element_value
structure.
The class_info_index
item denotes a class
literal as the value of this element-value pair.
The
class_info_index
item must be a valid index
into the constant_pool
table. The constant_pool
entry at
that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing a
return
descriptor (§4.3.3). The return
descriptor gives the type corresponding to the class literal
represented by this element_value
structure. Types correspond to class literals as
follows:
For a class literal C.
class
, where
C is the name
of a class, interface, or array type, the corresponding
type is C. The return descriptor in the constant_pool
will be an ObjectType or
an ArrayType.
For a class literal p.
class
,
where p is the name of a primitive type, the
corresponding type is p. The return
descriptor in the constant_pool
will be
a BaseType character.
For a class literal void
.
class
, the
corresponding
type is void
. The return descriptor in the
constant_pool
will be V.
For example, the class literal
Object.class
corresponds to the type
Object
, so the constant_pool
entry
is Ljava/lang/Object;
, whereas the class
literal int.class
corresponds to the type
int
, so the constant_pool
entry is I
.
The class literal
void.class
corresponds to void
,
so the
constant_pool
entry is V, whereas the
class literal Void.class
corresponds to the
type Void
, so the constant_pool
entry
is Ljava/lang/Void;
.
The annotation_value
item denotes a
"nested" annotation as the value of this element-value
pair.
The value of the annotation_value
item is an
annotation
structure
(§4.7.16) that
gives the annotation
represented by this element_value
structure.
The array_value
item denotes an array as
the value of this element-value pair.
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).
The
RuntimeInvisibleAnnotations
attribute records run-time invisible
annotations on the declaration of the corresponding class, method, or
field.
There may be at most one
RuntimeInvisibleAnnotations
attribute in the attributes
table of a
ClassFile
, field_info
, or method_info
structure.
The RuntimeInvisibleAnnotations
attribute is
similar to the RuntimeVisibleAnnotations
attribute
(§4.7.16), except that the
annotations
represented by a RuntimeInvisibleAnnotations
attribute must not be
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 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"RuntimeInvisibleAnnotations
".
The value of the
attribute_length
item indicates the length of
the attribute, excluding the initial six bytes.
The value of the
num_annotations
item gives the number of
run-time invisible annotations represented by the
structure.
Each entry in the
annotations
table represents a single
run-time invisible annotation on a
declaration. The annotation
structure is
specified in §4.7.16.
The
RuntimeVisibleParameterAnnotations
attribute is a variable-length
attribute in the attributes
table of the method_info
structure
(§4.6). The RuntimeVisibleParameterAnnotations
attribute records run-time visible annotations on the declarations of
formal parameters of the corresponding method. The Java Virtual Machine must make
these annotations available so they can be returned by the appropriate
reflective APIs.
There may be at most one
RuntimeVisibleParameterAnnotations
attribute in the attributes
table of a method_info
structure.
The
RuntimeVisibleParameterAnnotations
attribute has 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"RuntimeVisibleParameterAnnotations
".
The value of the
attribute_length
item indicates the length
of the attribute, excluding the initial six bytes.
The value of the
num_parameters
item gives the number of
formal parameters of the method represented by the
method_info
structure on which the annotation occurs.
This duplicates information that could be extracted from the method descriptor.
Each entry in the
parameter_annotations
table represents all
of the run-time visible annotations on the declaration of a
single formal parameter. The i'th entry in the table
corresponds to the i'th formal parameter in the
method
descriptor (§4.3.3). Each
parameter_annotations
entry contains the
following two items:
The value
of the num_annotations
item indicates
the number of run-time visible annotations on the
declaration of the formal parameter corresponding to the
parameter_annotations
entry.
Each entry
in the annotations
table represents a
single run-time visible annotation on the declaration of
the formal parameter corresponding to
the parameter_annotations
entry. The annotation
structure is
specified in §4.7.16.
The
RuntimeInvisibleParameterAnnotations
attribute is a variable-length
attribute in the attributes
table of a method_info
structure
(§4.6). The
RuntimeInvisibleParameterAnnotations
attribute records run-time
invisible annotations on the declarations of formal parameters of the
corresponding method.
There may be at most one
RuntimeInvisibleParameterAnnotations
attribute in the attributes
table of a method_info
structure.
The RuntimeInvisibleParameterAnnotations
attribute
is similar to the RuntimeVisibleParameterAnnotations
attribute
(§4.7.18), except that
the annotations
represented by a RuntimeInvisibleParameterAnnotations
attribute must
not be 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 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:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry
at that index must be a CONSTANT_Utf8_info
structure
(§4.4.7) representing the
string
"RuntimeInvisibleParameterAnnotations
".
The value of the
attribute_length
item indicates the length
of the attribute, excluding the initial six bytes.
The value of the
num_parameters
item gives the number of
formal parameters of the method represented by the
method_info
structure on which the annotation occurs.
This duplicates information that could be extracted from the method descriptor.
Each entry in the
parameter_annotations
table represents all
of the run-time invisible annotations on the declaration of a
single formal parameter. The i'th entry in the table
corresponds to the i'th formal parameter in the
method
descriptor (§4.3.3). Each
parameter_annotations
entry contains the
following two items:
The value
of the num_annotations
item indicates
the number of run-time invisible annotations on the
declaration of the formal parameter corresponding to the
parameter_annotations
entry.
Each entry
in the annotations
table represents a
single run-time invisible annotation on the declaration
of the formal parameter corresponding to the
parameter_annotations
entry. The annotation
structure is
specified in §4.7.16.
The
RuntimeVisibleTypeAnnotations
attribute is an 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).
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. The Java Virtual Machine must
make these annotations available so they can be returned by the
appropriate reflective APIs.
There may be at most one
RuntimeVisibleTypeAnnotations
attribute in the attributes
table of
a ClassFile
, field_info
, or method_info
structure, or Code
attribute.
An attributes
table
contains a RuntimeVisibleTypeAnnotations
attribute only if types are
annotated in kinds of declaration or expression that correspond to the
parent structure or attribute of the attributes
table.
For example, all annotations on types in the
implements
clause of a class declaration are recorded in the
RuntimeVisibleTypeAnnotations
attribute of the class's ClassFile
structure. Meanwhile, all annotations on the type in a field
declaration are recorded in the RuntimeVisibleTypeAnnotations
attribute of the field's field_info
structure.
The
RuntimeVisibleTypeAnnotations
attribute has the following
format:
RuntimeVisibleTypeAnnotations_attribute { u2 attribute_name_index; u4 attribute_length; u2 num_annotations; type_annotation annotations[num_annotations]; }
The items of
the RuntimeVisibleTypeAnnotations_attribute
structure are as follows:
The value of the
attribute_name_index
item must be a valid
index into the constant_pool
table. The constant_pool
entry at that index must be a CONSTANT_Utf8_info
structure
representing the string "RuntimeVisibleTypeAnnotations
".
The value of the attribute_length
item
indicates the length of the attribute, excluding the initial
six bytes.
The value of the num_annotations
item gives
the number of run-time visible type annotations represented by
the structure.
Each entry in the annotations
table
represents a single run-time visible annotation on a type used
in a declaration or expression. The
type_annotation
structure has the following
format:
type_annotation { u1 target_type; union { type_parameter_target; supertype_target; type_parameter_bound_target; empty_target; method_formal_parameter_target; throws_target; localvar_target; catch_target; offset_target; type_argument_target; } target_info; type_path target_path; u2 type_index; u2 num_element_value_pairs; { u2 element_name_index; element_value value; } element_value_pairs[num_element_value_pairs]; }
The first three items - target_type
, target_info
,
and target_path
- specify the precise
location of the annotated type. The last three items
- type_index
,
num_element_value_pairs
,
and element_value_pairs[]
- specify the
annotation's own type and element-value pairs.
The items of the type_annotation
structure
are as follows:
The value of the target_type
item denotes the kind
of
target on which the annotation appears. The various
kinds of target correspond to the type
contexts of the Java programming language where types are
used in declarations and expressions (JLS §4.11).
The legal values of target_type
are specified in
Table 4.7.20-A
and
Table 4.7.20-B.
Each value is a
one-byte tag indicating which item of the target_info
union follows the target_type
item to give more
information about the target.
The kinds of target in
Table 4.7.20-A
and
Table 4.7.20-B
correspond to the type
contexts in JLS §4.11. Namely, target_type
values
0x10-0x17 and 0x40-0x42 correspond to type contexts
1-10, while target_type
values 0x43-0x4B correspond
to
type contexts 11-16.
The value of the target_type
item determines
whether
the type_annotation
structure appears
in a RuntimeVisibleTypeAnnotations
attribute in a
ClassFile
structure, a field_info
structure, a
method_info
structure, or a Code
attribute. Table 4.7.20-C
gives the
location of the RuntimeVisibleTypeAnnotations
attribute for a type_annotation
structure with each legal target_type
value.
The value
of the target_info
item denotes precisely which
type
in a declaration or expression is annotated.
The
items of the target_info
union are specified in
§<IP_ADDRESS>.
The value
of the target_path
item denotes
precisely which part of the type indicated by
target_info
is annotated.
The
format of the type_path
structure is specified in
§<IP_ADDRESS>.
The
meaning of these items in
the type_annotation
structure is the
same as their meaning in
the annotation
structure
(§4.7.16).
Table 4.7.20-A. Interpretation of target_type
values (Part 1)
| Value | Kind of target | target_info item
|
|---|---|---|
| 0x00 | type parameter declaration of generic class or interface | type_parameter_target |
| 0x01 | type parameter declaration of generic method or constructor | type_parameter_target |
| 0x10 | type in extends or implements
clause of class
declaration (including the direct superclass or direct
superinterface of an anonymous class declaration), or in
extends clause of interface declaration
|
supertype_target |
| 0x11 | type in bound of type parameter declaration of generic class or interface | type_parameter_bound_target |
| 0x12 | type in bound of type parameter declaration of generic method or constructor | type_parameter_bound_target |
| 0x13 | type in field declaration | empty_target |
| 0x14 | return type of method, or type of newly constructed object | empty_target |
| 0x15 | receiver type of method or constructor | empty_target |
| 0x16 | type in formal parameter declaration of method, constructor, or lambda expression | formal_parameter_target |
| 0x17 | type in throws clause of method or
constructor
|
throws_target |
Table 4.7.20-B. Interpretation of target_type
values (Part 2)
| Value | Kind of target | target_info item
|
|---|---|---|
| 0x40 | type in local variable declaration | localvar_target |
| 0x41 | type in resource variable declaration | localvar_target |
| 0x42 | type in exception parameter declaration | catch_target |
| 0x43 | type in instanceof expression | offset_target |
| 0x44 | type in new expression | offset_target |
| 0x45 | type in method reference expression using :: new |
offset_target |
| 0x46 | type in method reference expression using :: Identifier |
offset_target |
| 0x47 | type in cast expression | type_argument_target |
| 0x48 | type argument for generic constructor in new expression or explicit constructor invocation statement | type_argument_target |
| 0x49 | type argument for generic method in method invocation expression | type_argument_target |
| 0x4A | type argument for generic constructor in method
reference expression using :: new |
type_argument_target |
| 0x4B | type argument for generic method in method reference
expression using :: Identifier |
type_argument_target |
Table 4.7.20-C. Location of enclosing attribute for target_type
values
| Value | Kind of target | Location |
|---|---|---|
| 0x00 | type parameter declaration of generic class or interface | ClassFile |
| 0x01 | type parameter declaration of generic method or constructor | method_info |
| 0x10 | type in extends clause of class or interface
declaration, or in implements clause of interface
declaration
|
ClassFile |
| 0x11 | type in bound of type parameter declaration of generic class or interface | ClassFile |
| 0x12 | type in bound of type parameter declaration of generic method or constructor | method_info |
| 0x13 | type in field declaration | field_info |
| 0x14 | return type of method or constructor | method_info |
| 0x15 | receiver type of method or constructor | method_info |
| 0x16 | type in formal parameter declaration of method, constructor, or lambda expression | method_info |
| 0x17 | type in throws clause of method or
constructor
|
method_info |
| 0x40-0x4B | types in local variable declarations, resource variable declarations, exception parameter declarations, expressions | Code |
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. A type_parameter_index
value of
0
specifies the first type parameter declaration.
The supertype_target
item indicates that an annotation
appears
on a type in the extends
or implements
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 an extends
clause of a class declaration.
Any other supertype_index
value is an index
into the interfaces
array of the enclosing
ClassFile
structure, and specifies that the annotation
appears
on that superinterface in either the implements
clause of a
class declaration or the extends
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. A type_parameter_index
value of 0
specifies the first type parameter declaration.
The value of the bound_index
item specifies
which bound of the type parameter declaration indicated
by type_parameter_index
is
annotated. A bound_index
value of 0
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 appropriate
Signature
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. A formal_parameter_index
value of
0
specifies the first formal parameter declaration.
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 (§4.3.3) of the method_info
structure enclosing the RuntimeVisibleTypeAnnotations
attribute. A formal_parameter_index
value of
0
indicates the first parameter descriptor in the method
descriptor.
The throws_target
item indicates that an annotation appears
on
the i'th type in the throws
clause of a method or
constructor declaration.
throws_target { u2 throws_type_index; }
The value of the throws_type_index
item is an
index into the exception_index_table
array of
the Exceptions
attribute of the method_info
structure
enclosing the RuntimeVisibleTypeAnnotations
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 a try
-with-resources
statement.
localvar_target { u2 table_length; { u2 start_pc; u2 length; u2 index; } table[table_length]; }
The value of the table_length
item gives the
number of entries in the table
array. Each
entry indicates a range of code
array offsets within which
a
local variable has a value. It also indicates 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:
The given local variable has a value at indices into the
code
array in the interval
[start_pc
, start_pc +
length
), that is,
between start_pc
inclusive
and start_pc + length
exclusive.
The given local variable must be
at index
in the local variable array of
the current frame.
If the local variable at index
is of
type double
or long
, it occupies
both index
and index +
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
,
and index
items in each table entry specify
the same information as a LocalVariableTable
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 appropriate
LocalVariableTable
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
item
is an index into the exception_table
array of
the Code
attribute enclosing the
RuntimeVisibleTypeAnnotations
attribute.
The possibility of more than one type in an
exception parameter declaration arises from the multi-catch
clause of the try
statement, where the type of the
exception
parameter is a union of types (JLS §14.20). A compiler usually
creates one exception_table
entry for each
type in the union, which allows the catch_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
item specifies the
code
array offset of either the instanceof
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
item specifies the
code
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
item specifies which
type in the cast operator is
annotated. A type_argument_index
value of
0
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. A
type_argument_index
value of 0
specifies
the first type argument.
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
top level type or any member type.
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.