Movatterモバイル変換

CHAPTER 4

The File Format

This chapter describes the Java virtual machineclass file format. Eachclass 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 theclass file format.

Aclass 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 and Java 2 platforms, this format is supported by interfacesjava.io.DataInput andjava.io.DataOutput and classes such asjava.io.DataInputStream andjava.io.DataOutputStream.

This chapter defines its own set of data types representingclass file data: The typesu1,u2, andu4 represent an unsigned one-, two-, or four-byte quantity, respectively. In the Java and Java 2 platforms, these types may be read by methods such asreadUnsignedByte,readUnsignedShort, andreadInt of the interfacejava.io.DataInput.

This chapter presents theclass 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 theclass file format are referred to asitems. Successive items are stored in theclass file sequentially, without padding or alignment.

Tables, consisting of zero or more variable-sized items, are used in severalclass 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.

4.1 TheClassFile 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];    }

magic

Themagic item supplies the magic number identifying theclass file format; it has the value0xCAFEBABE.

minor_version,major_version

The values of theminor_version andmajor_version items are the minor and major version numbers of thisclass file.Together, a major and a minor version number determine the version of theclass file format. If aclass file has major version number M and minor version number m, we denote the version of itsclass file format as M.m. Thus,class file format versions may be ordered lexicographically, for example, 1.5< 2.0< 2.1.

A Java virtual machine implementation can support aclass file format of version v if and only if v lies in some contiguous range Mi.0 v Mj.m. Only Sun can specify what range of versions a Java virtual machine implementation conforming to a certain release level of the Java platform may support.¹

constant_pool_count

The value of theconstant_pool_count item is equal to the number of entries in theconstant_pool table plus one. Aconstant_pool index is considered valid if it is greater than zero and less thanconstant_pool_count, with the exception for constants of typelong anddouble noted in§4.4.5.

constant_pool[]

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

Theconstant_pool table is indexed from1 toconstant_pool_count-1.

access_flags

The value of theaccess_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 as shown inTable 4.1.

An interface is distinguished by itsACC_INTERFACE flag being set. If itsACC_INTERFACE flag is not set, thisclass file defines a class, not an interface.

If theACC_INTERFACE flag of thisclass file is set, itsACC_ABSTRACT flag must also be set(§2.13.1) and itsACC_PUBLIC flag may be set. Such aclass file may not have any of the other flags inTable 4.1 set.

If theACC_INTERFACE flag of thisclass file is not set, it may have any of the other flags inTable 4.1 set. However, such aclass file cannot have both itsACC_FINAL andACC_ABSTRACT flags set(§2.8.2).

The setting of theACC_SUPER flag indicates which of two alternative semantics for itsinvokespecial instruction the Java virtual machine is to express; theACC_SUPER flag exists for backward compatibility for code compiled by Sun's older compilers for the Java programming language. All new implementations of the Java virtual machine should implement the semantics forinvokespecial documented in this specification. All new compilers to the instruction set of the Java virtual machine should set theACC_SUPER flag. Sun's older compilers generatedClassFile flags withACC_SUPER unset. Sun's older Java virtual machine implementations ignore the flag if it is set.

All bits of theaccess_flags item not assigned inTable 4.1 are reserved for future use. They should be set to zero in generatedclass files and should be ignored by Java virtual machine implementations.

this_class

The value of thethis_class item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Class_info(§4.4.1) structure representing the class or interface defined by thisclass file.

super_class

For a class, the value of thesuper_class item either must be zero or must be a valid index into theconstant_pool table. If the value of thesuper_class item is nonzero, theconstant_pool entry at that index must be aCONSTANT_Class_info(§4.4.1) structure representing the direct superclass of the class defined by thisclass file. Neither the direct superclass nor any of its superclasses may be afinal class.

If the value of thesuper_class item is zero, then thisclass file must represent the classObject, the only class or interface without a direct superclass.

For an interface, the value of thesuper_class item must always be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Class_info structure representing the classObject.

interfaces_count

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

interfaces[]

Each value in theinterfaces array must be a valid index into theconstant_pool table. Theconstant_pool entry at each value ofinterfaces[i], where0 i<interfaces_count, must be aCONSTANT_Class_info(§4.4.1) 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.

fields_count

The value of thefields_count item gives the number offield_info structures in thefields table. Thefield_info(§4.5) structures represent all fields, both class variables and instance variables, declared by this class or interface type.

fields[]

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

methods_count

The value of themethods_count item gives the number ofmethod_info structures in themethods table.

methods[]

Each value in themethods table must be amethod_info(§4.6) structure giving a complete description of a method in this class or interface. If the method is notnative orabstract, the Java virtual machine instructions implementing the method are also supplied.

Themethod_info structures represent all methods declared by this class or interface type, including instance methods, class (static) methods, instance initialization methods(§3.9), and any class or interface initialization method(§3.9). Themethods table does not include items representing methods that are inherited from superclasses or superinterfaces.

attributes_count

The value of theattributes_count item gives the number of attributes(§4.7) in theattributes table of this class.

attributes[]

Each value of theattributes table must be an attribute structure(§4.7).

The only attributes defined by this specification as appearing in theattributes table of aClassFile structure are theSourceFile attribute(§4.7.7) and theDeprecated(§4.7.10) attribute.

A Java virtual machine implementation is required to silently ignore any or all attributes in theattributes table of aClassFile structure that it does not recognize. Attributes not defined in this specification are not allowed to affect the semantics of theclass file, but only to provide additional descriptive information(§4.7.1).

4.2 The Internal Form of Fully Qualified Class and Interface Names

For historical reasons the syntax of fully qualified class and interface names that appear inclass file structures differs from the familiar syntax of fully qualified names documented in§2.7.5. In this internal form, the ASCII periods ('.') that normally separate the identifiers that make up the fully qualified name are replaced by ASCII forward slashes ('/'). For example, the normal fully qualified name of classThread isjava.lang.Thread. In the form used in descriptors in theclass file format, a reference to the name of classThread is implemented using aCONSTANT_Utf8_info structure representing the string"java/lang/Thread".

4.3 Descriptors

4.3.1 Grammar Notation

FieldType:
     BaseType
     ObjectType
     ArrayType

states that aFieldType may represent either aBaseType, anObjectType, or anArrayType.

A nonterminal symbol on the right-hand side of a production that is followed by an asterisk (*) represents zero or more possibly different values produced from that nonterminal, appended without any intervening space. The production:

MethodDescriptor:
     (ParameterDescriptor* )ReturnDescriptor

states that aMethodDescriptor represents a left parenthesis, followed by zero or moreParameterDescriptor values, followed by a right parenthesis, followed by aReturnDescriptor.

4.3.2 Field Descriptors

       FieldDescriptor:

FieldType

       ComponentType:

FieldType

       FieldType:

BaseType

ObjectType

ArrayType

       BaseType:

B

C

D

F

I

J

S

Z

L <classname> ;

[ComponentType

The interpretation of the field types is as shown inTable 4.2.

For example, the descriptor of an instance variable of typeint is simply I. The descriptor of an instance variable of typeObject is Ljava/lang/Object;. Note that the internal form of the fully qualified name for classObject is used. The descriptor of an instance variable that is a multidimensionaldouble array,

    double d[][][];

    [[[D

4.3.3 Method Descriptors

MethodDescriptor:
    (ParameterDescriptor* )ReturnDescriptor

ParameterDescriptor:
    FieldType

ReturnDescriptor:
    FieldType
    V

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 forthis 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 typelong ordouble contributes two units to the length and a parameter of any other type contributes one unit.

For example, the method descriptor for the method

    Object mymethod(int i, double d, Thread t)

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

The method descriptor formymethod is the same whethermymethod is a class or an instance method. Although an instance method is passedthis, a reference to the current class instance, in addition to its intended parameters, that fact is not reflected in the method descriptor. (A reference tothis is not passed to a class method.) The reference tothis is passed implicitly by the method invocation instructions of the Java virtual machine used to invoke instance methods.

4.4 The Constant Pool

Allconstant_pool table entries have the following general format:

    cp_info {    u1 tag;    u1 info[];    }

4.4.1 TheCONSTANT_Class_info Structure

    CONSTANT_Class_info {    u1 tag;    u2 name_index;    }

tag

Thetag item has the valueCONSTANT_Class (7).

name_index

The value of thename_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing a valid fully qualified class or interface name(§2.8.1) encoded in internal form (§4.2).

Because arrays are objects, the opcodesanewarray andmultianewarray can reference array "classes" viaCONSTANT_Class_info(§4.4.1) structures in theconstant_pool table. For such array classes, the name of the class is the descriptor of the array type. For example, the class name representing a two-dimensionalint array type

    int[][]

    [[I

    Thread[]

    [Ljava/lang/Thread;

4.4.2 TheCONSTANT_Fieldref_info,CONSTANT_Methodref_info, andCONSTANT_InterfaceMethodref_info 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;    }

tag

Thetag item of aCONSTANT_Fieldref_info structure has the valueCONSTANT_Fieldref (9).

Thetag item of aCONSTANT_Methodref_info structure has the valueCONSTANT_Methodref (10).

Thetag item of aCONSTANT_InterfaceMethodref_info structure has the valueCONSTANT_InterfaceMethodref (11).

class_index

The value of theclass_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Class_info(§4.4.1) structure representing the class or interface type that contains the declaration of the field or method.

Theclass_index item of aCONSTANT_Methodref_info structure must be a class type, not an interface type. Theclass_index item of aCONSTANT_InterfaceMethodref_info structure must be an interface type. Theclass_index item of aCONSTANT_Fieldref_info structure may be either a class type or an interface type.

name_and_type_index

The value of thename_and_type_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_NameAndType_info(§4.4.6) structure. Thisconstant_pool entry indicates the name and descriptor of the field or method. In aCONSTANT_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 aCONSTANT_Methodref_info structure begins with a' <' ('\u003c'), then the name must be the special name<init>, representing an instance initialization method(§3.9). Such a method must return no value.

4.4.3 TheCONSTANT_String_info Structure

    CONSTANT_String_info {    u1 tag;    u2 string_index;    }

tag

Thetag item of theCONSTANT_String_info structure has the valueCONSTANT_String (8).

string_index

The value of thestring_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing the sequence of characters to which theString object is to be initialized.

4.4.4 TheCONSTANT_Integer_info andCONSTANT_Float_info Structures

    CONSTANT_Integer_info {    u1 tag;    u4 bytes;    }

    CONSTANT_Float_info {    u1 tag;    u4 bytes;    }

tag

Thetag item of theCONSTANT_Integer_info structure has the valueCONSTANT_Integer (3).

Thetag item of theCONSTANT_Float_info structure has the valueCONSTANT_Float (4).

bytes

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

Thebytes item of theCONSTANT_Float_info structure represents the value of thefloat constant in IEEE 754 floating-point single format(§3.3.2). The bytes of the single format representation are stored in big-endian (high byte first) order.

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

• If bits is0x7f800000, thefloat value will be positive infinity.
• If bits is0xff800000, thefloat value will be negative infinity.
• If bits is in the range0x7f800001 through0x7fffffff or in the range0xff800001 through0xffffffff, thefloat value will be NaN.
• In all other cases, lets,e, andm be three values that might be computed frombits:

    int s = ((bits >> 31) == 0) ? 1 : -1;    int e = ((bits >> 23) & 0xff);    int m = (e == 0) ?    (bits & 0x7fffff) << 1 :    (bits & 0x7fffff) | 0x800000;Then thefloat value equals the result of the mathematical expressions·m·2e-150.

4.4.5 TheCONSTANT_Long_info andCONSTANT_Double_info Structures

TheCONSTANT_Long_info andCONSTANT_Double_info represent 8-byte numeric (long anddouble) 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 theconstant_pool table of theclass file. If aCONSTANT_Long_info orCONSTANT_Double_info structure is the item in theconstant_pool table at indexn, then the next usable item in the pool is located at indexn+2. Theconstant_pool indexn+1 must be valid but is considered unusable.²

The items of these structures are as follows:

tag

Thetag item of theCONSTANT_Long_info structure has the valueCONSTANT_Long (5).

Thetag item of theCONSTANT_Double_info structure has the valueCONSTANT_Double (6).

high_bytes,low_bytes

The unsignedhigh_bytes andlow_bytes items of theCONSTANT_Long_info structure together represent the value of thelong constant ((long)high_bytes<< 32) +low_bytes, where the bytes of each ofhigh_bytes andlow_bytes are stored in big-endian (high byte first) order.

Thehigh_bytes andlow_bytes items of theCONSTANT_Double_info structure together represent thedouble value in IEEE 754 floating-point double format(§3.3.2). The bytes of each item are stored in big-endian (high byte first) order.

The value represented by theCONSTANT_Double_info structure is determined as follows. Thehigh_bytes andlow_bytes items are first converted into thelong constant bits, which is equal to ((long)high_bytes<< 32) +low_bytes. Then:

• If bits is0x7ff0000000000000L, thedouble value will be positive infinity.
• If bits is0xfff0000000000000L, thedouble value will be negative infinity.
• If bits is in the range0x7ff0000000000001L through0x7fffffffffffffffL or in the range0xfff0000000000001L through0xffffffffffffffffL, thedouble value will be NaN.
• In all other cases, lets,e, andm be three values that might be computed from bits:

    int s = ((bits >> 63) == 0) ? 1 : -1;    int e = (int)((bits >> 52) & 0x7ffL);    long m = (e == 0) ?    (bits & 0xfffffffffffffL) << 1 :    (bits & 0xfffffffffffffL) | 0x10000000000000L;
Then the floating-point value equals thedouble value of the mathematical expressions·m·2e-1075.

4.4.6 TheCONSTANT_NameAndType_info Structure

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

tag

Thetag item of theCONSTANT_NameAndType_info structure has the valueCONSTANT_NameAndType (12).

name_index

The value of thename_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing either a valid field or method name(§2.7) stored as a simple name(§2.7.1), that is, as a Java programming language identifier(§2.2) or as the special method name<init>(§3.9).

descriptor_index

The value of thedescriptor_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing a valid field descriptor(§4.3.2) or method descriptor(§4.3.3).

4.4.7 TheCONSTANT_Utf8_info Structure

UTF-8 strings are encoded so that character sequences that contain only non-null ASCII characters can be represented using only 1 byte per character, but characters of up to 16 bits can be represented. All characters 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 character represented. The null character ('\u0000') and characters in the range'\u0080' to'\u07FF' are representedby a pair of bytes x and y:

The bytes represent the character with the value ((x &0x1f)<<6) + (y &0x3f).

Characters in the range'\u0800' to'\uFFFF' are represented by 3 bytes x, y, and z:

The character with the value ((x &0xf)<<12) + ((y &0x3f)<<6) + (z &0x3f) is represented by the bytes.

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

There are two differences between this format and the "standard" UTF-8 format. First, the null byte(byte)0 is encoded using the 2-byte format rather than the 1-byte format, so that Java virtual machine UTF-8 strings never have embedded nulls. Second, only the 1-byte, 2-byte, and 3-byte formats are used. The Java virtual machine does not recognize the longer UTF-8 formats.

For more information regarding the UTF-8 format, seeFile System Safe UCS Transformation Format (FSS_UTF), X/Open Preliminary Specification (X/Open Company Ltd., Document Number: P316). This information also appears in ISO/IEC 10646, Annex P.

TheCONSTANT_Utf8_info structure is

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

tag

Thetag item of theCONSTANT_Utf8_info structure has the valueCONSTANT_Utf8 (1).

length

The value of thelength item gives the number of bytes in thebytes array (not the length of the resulting string). The strings in theCONSTANT_Utf8_info structure are not null-terminated.

bytes[]

Thebytes array contains the bytes of the string. No byte may have the value(byte)0 or lie in the range(byte)0xf0-(byte)0xff.

4.5 Fields

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

access_flags

The value of theaccess_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 as shown inTable 4.4.

Fields of classes may set any of the flags inTable 4.4. However, a specific field of a class may have at most one of itsACC_PRIVATE,ACC_PROTECTED, andACC_PUBLIC flags set(§2.7.4) and may not have both itsACC_FINAL andACC_VOLATILE flags set(§2.9.1).

Flag Name	Value	Interpretation
ACC_PUBLIC	0x0001	Declaredpublic; may be accessed from outside its package.
ACC_PRIVATE	0x0002	Declaredprivate; usable only within the defining class.
ACC_PROTECTED	0x0004	Declaredprotected; may be accessed within subclasses.
ACC_STATIC	0x0008	Declaredstatic.
ACC_FINAL	0x0010	Declaredfinal; no further assignment after initialization.
ACC_VOLATILE	0x0040	Declaredvolatile; cannot be cached.
ACC_TRANSIENT	0x0080	Declaredtransient; not written or read by a persistent object manager.

Fields of classes may set any of the flags inTable 4.4. However, a specific field of a class may have at most one of itsACC_PRIVATE,ACC_PROTECTED, andACC_PUBLIC flags set(§2.7.4) and may not have both itsACC_FINAL andACC_VOLATILE flags set(§2.9.1).

All fields of interfaces must have theirACC_PUBLIC,ACC_STATIC, andACC_FINAL flags set and may not have any of the other flags inTable 4.4 set(§2.13.3.1).

All bits of theaccess_flags item not assigned inTable 4.4 are reserved for future use. They should be set to zero in generatedclass files and should be ignored by Java virtual machine implementations.

name_index

The value of thename_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure which must represent a valid field name(§2.7) stored as a simple name(§2.7.1), that is, as a Java programming language identifier(§2.2).

descriptor_index

The value of thedescriptor_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure that must represent a valid field descriptor(§4.3.2).

attributes_count

The value of theattributes_count item indicates the number of additional attributes(§4.7) of this field.

attributes[]

Each value of theattributes table must be an attribute structure(§4.7). A field can have any number of attributes associated with it.

The attributes defined by this specification as appearing in theattributes table of afield_info structure are theConstantValue(§4.7.2),Synthetic(§4.7.6), andDeprecated(§4.7.10) attributes.

A Java virtual machine implementation must recognize and correctly readConstantValue(§4.7.2) attributes found in theattributes table of afield_info structure. A Java virtual machine implementation is required to silently ignore any or all other attributes in theattributes table that it does not recognize. Attributes not defined in this specification are not allowed to affect the semantics of theclass file, but only to provide additional descriptive information(§4.7.1).

4.6 Methods

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];    }

access_flags

The value of theaccess_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 as shown inTable 4.5.

Flag Name	Value	Interpretation
ACC_PUBLIC	0x0001	Declaredpublic; may be accessed from outside its package.
ACC_PRIVATE	0x0002	Declaredprivate; accessible only within the defining class.
ACC_PROTECTED	0x0004	Declaredprotected; may be accessed within subclasses.
ACC_STATIC	0x0008	Declaredstatic.
ACC_FINAL	0x0010	Declaredfinal; may not be overridden.
ACC_SYNCHRONIZED	0x0020	Declaredsynchronized; invocation is wrapped in a monitor lock.
ACC_NATIVE	0x0100	Declarednative; implemented in a language other than Java.
ACC_ABSTRACT	0x0400	Declaredabstract; no implementation is provided.
ACC_STRICT	0x0800	Declaredstrictfp; floating-point mode is FP-strict

Methods of classes may set any of the flags inTable 4.5. However, a specific method of a class may have at most one of itsACC_PRIVATE,ACC_PROTECTED, andACC_PUBLICflags set(§2.7.4). If such a method has itsACC_ABSTRACT flag set it may not have any of itsACC_FINAL,ACC_NATIVE,ACC_PRIVATE,ACC_STATIC,ACC_STRICT, orACC_SYNCHRONIZED flags set(§2.13.3.2).

All interface methods must have theirACC_ABSTRACT andACC_PUBLIC flags set and may not have any of the other flags inTable 4.5 set(§2.13.3.2).

A specific instance initialization method(§3.9) may have at most one of itsACC_PRIVATE,ACC_PROTECTED, andACC_PUBLIC flags set and may also have itsACC_STRICT flag set, but may not have any of the other flags inTable 4.5 set.

Class and interface initialization methods(§3.9) are called implicitly by the Java virtual machine; the value of theiraccess_flags item is ignored except for the settings of theACC_STRICTflag.

All bits of theaccess_flags item not assigned inTable 4.5 are reserved for future use. They should be set to zero in generatedclass files and should be ignored by Java virtual machine implementations.

name_index

The value of thename_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing either one of the special method names(§3.9),<init> or<clinit>, or a valid method name in the Java programming language(§2.7), stored as a simple name(§2.7.1).

descriptor_index

The value of thedescriptor_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing a valid method descriptor(§4.3.3).

attributes_count

The value of theattributes_count item indicates the number of additional attributes(§4.7) of this method.

attributes[]

Each value of theattributes table must be an attribute structure(§4.7). A method can have any number of optional attributes associated with it.

The only attributes defined by this specification as appearing in theattributes table of amethod_info structure are theCode(§4.7.3),Exceptions(§4.7.4),Synthetic(§4.7.6), andDeprecated(§4.7.10) attributes.

A Java virtual machine implementation must recognize and correctly readCode(§4.7.3) andExceptions(§4.7.4) attributes found in theattributes table of amethod_info structure. A Java virtual machine implementation is required to silently ignore any or all other attributes in theattributes table of amethod_info structure that it does not recognize. Attributes not defined in this specification are not allowed to affect the semantics of theclass file, but only to provide additional descriptive information(§4.7.1).

4.7 Attributes

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

Certain attributes are predefined as part of theclass file specification. The predefined attributes are theSourceFile(§4.7.7),ConstantValue(§4.7.2),Code(§4.7.3),Exceptions(§4.7.4),InnerClasses(§4.7.5),Synthetic(§4.7.6),LineNumberTable(§4.7.8),LocalVariableTable(§4.7.9), andDeprecated(§4.7.10) attributes. Within the context of their use in this specification, that is, in theattributes tables of theclass file structures in which they appear, the names of these predefined attributes are reserved.

Of the predefined attributes, theCode,ConstantValue, andExceptions attributes must be recognized and correctly read by aclass file reader for correct interpretation of theclass file by a Java virtual machine implementation. TheInnerClasses andSynthetic attributes must be recognized and correctly read by aclass file reader in order to properly implement the Java and Java 2 platform class libraries(§3.12). Use of the remaining predefined attributes is optional; aclass file reader may use the information they contain, or otherwise must silently ignore those attributes.

4.7.1 Defining and Naming New Attributes

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

Java virtual machine implementations are specifically prohibited from throwing an exception or otherwise refusing to useclass files simply because of the presence of some new attribute. Of course, tools operating onclass files may not run correctly if givenclass files that do not contain all the attributes they require.

Two attributes that are intended to be distinct, but that happen to use the same attribute name and are of the same length, will conflict on implementations that recognize either attribute. Attributes defined other than by Sun must have names chosen according to the package naming convention defined byThe Java Language Specification. For instance, a new attribute defined by Netscape might have the name"com.Netscape.new-attribute".³

Sun may define additional attributes in future versions of thisclass file specification.

4.7.2 TheConstantValue Attribute

If afield_info structure representing a non-static field has aConstantValue attribute, then that attribute must silently be ignored. Every Java virtual machine implementation must recognizeConstantValue attributes.

TheConstantValue attribute has the following format:

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

attribute_name_index

The value of theattribute_name_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing the string"ConstantValue".

attribute_length

The value of theattribute_length item of aConstantValue_attribute structure must be2.

constantvalue_index

The value of theconstantvalue_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index gives the constant value represented by this attribute. Theconstant_pool entry must be of a type appropriate to the field, as shown byTable 4.6.

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

4.7.3 TheCode Attribute

TheCode 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];    }

attribute_name_index

The value of theattribute_name_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing the string"Code".

attribute_length

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

max_stack

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

max_locals

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

The greatest local variable index for a value of typelong ordouble ismax_locals-2. The greatest local variable index for a value of any other type ismax_locals-1.

code_length

The value of thecode_length item gives the number of bytes in thecode array for this method. The value ofcode_length must be greater than zero; thecode array must not be empty.

code[]

Thecode array gives the actual bytes of Java virtual machine code that implement the method.

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

The detailed constraints on the contents of thecode array are extensive and are given in a separate section(§4.8).

exception_table_length

The value of theexception_table_length item gives the number of entries in theexception_table table.

exception_table[]

Each entry in theexception_table array describes one exception handler in thecode array. The order of the handlers in theexception_table array is significant. SeeSection 3.10 for more details.

Eachexception_table entry contains the following four items:

start_pc,end_pc

The values of the two itemsstart_pc andend_pc indicate the ranges in thecode array at which the exception handler is active. The value ofstart_pc must be a valid index into thecode array of the opcode of an instruction. The value ofend_pc either must be a valid index into thecode array of the opcode of an instruction or must be equal tocode_length, the length of thecode array. The value ofstart_pc must be less than the value ofend_pc.

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

handler_pc

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

catch_type

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

If the value of thecatch_type item is zero, this exception handler is called for all exceptions. This is used to implementfinally (seeSection 7.13, "Compilingfinally").

4.7.4 TheExceptions Attribute

TheExceptions 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];    }

attribute_name_index

The value of theattribute_name_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must betheCONSTANT_Utf8_info(§4.4.7) structure representing the string"Exceptions".

attribute_length

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

number_of_exceptions

The value of thenumber_of_exceptions item indicates the number of entries in theexception_index_table.

exception_index_table[]

Each value in theexception_index_table array must be a valid index into theconstant_pool table. Theconstant_pool entry referenced by each table item must be aCONSTANT_Class_info(§4.4.1) structure representing a class type that this method is declared to throw.

• The exception is an instance ofRuntimeException or one of its subclasses.

• The exception is an instance ofError or one of its subclasses.

• The exception is an instance of one of the exception classes specified in theexception_index_table just described, or one of their subclasses.

4.7.5 TheInnerClasses Attribute

TheInnerClasses 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];    }

attribute_name_index

The value of theattribute_name_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing the string"InnerClasses".

attribute_length

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

number_of_classes

The value of thenumber_of_classes item indicates the number of entries in theclasses array.

classes[]

EveryCONSTANT_Class_info entry in theconstant_pool table which represents a class or interface C that is not a package member must have exactly one corresponding entry in theclasses array.

If a class has members that are classes or interfaces, itsconstant_pool table (and hence itsInnerClasses attribute) must refer to each such member, even if that member is not otherwise mentioned by the class. These rules imply that a nested class or interface member will haveInnerClasses information for each enclosing class and for each immediate member.

Eachclasses array entry contains the following four items:

inner_class_info_index

The value of theinner_class_info_index item must be zero or a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Class_info(§4.4.1) structure representing C. The remaining items in theclasses array entry give information about C.

outer_class_info_index

If C is not a member, the value of theouter_class_info_index item must be zero. Otherwise, the value of theouter_class_info_index item must be a valid index into theconstant_pool table, and the entry at that index must be aCONSTANT_Class_info(§4.4.1) structure representing the class or interface of which C is a member.

inner_name_index

If C is anonymous, the value of theinner_name_index item must be zero. Otherwise, the value of theinner_name_index item must be a valid index into theconstant_pool table, and the entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure that represents the original simple name of C, as given in the source code from which thisclass file was compiled.

inner_class_access_flags

The value of theinner_class_access_flags item is a mask of flags used to denote access permissions to and properties of class or interface C as declared in the source code from which thisclass file was compiled. It is used by compilers to recover the original information when source code is not available. The flags are shown inTable 4.7.

Flag Name	Value	Meaning
ACC_PUBLIC	0x0001	Marked or implicitlypublic in source.
ACC_PRIVATE	0x0002	Markedprivate in source.
ACC_PROTECTED	0x0004	Markedprotected in source.
ACC_STATIC	0x0008	Marked or implicitlystatic in source.
ACC_FINAL	0x0010	Markedfinal in source.
ACC_INTERFACE	0x0200	Was aninterface in source.
ACC_ABSTRACT	0x0400	Marked or implicitlyabstract in source.

All bits of theinner_class_access_flags item not assigned inTable 4.7 are reserved for future use. They should be set to zero in generatedclass files and should be ignored by Java virtual machine implementations.

4.7.6 TheSynthetic Attribute

TheSynthetic attribute has the following format:

    Synthetic_attribute {    u2 attribute_name_index;    u4 attribute_length;    }

attribute_name_index

The value of theattribute_name_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing the string"Synthetic".

attribute_length

The value of theattribute_length item is zero.

4.7.7 TheSourceFile Attribute

TheSourceFile attribute has the following format:

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

attribute_name_index

The value of theattribute_name_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing the string"SourceFile".

attribute_length

The value of theattribute_length item of aSourceFile_attribute structure must be2.

sourcefile_index

The value of thesourcefile_index item must be a valid index into theconstant_pool table. The constant pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing a string.

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

4.7.8 TheLineNumberTable Attribute

TheLineNumberTable 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];    }

attribute_name_index

The value of theattribute_name_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing the string"LineNumberTable".

attribute_length

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

line_number_table_length

The value of theline_number_table_length item indicates the number of entries in theline_number_table array.

line_number_table[]

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

start_pc

The value of thestart_pc item must indicate the index into thecode array at which the code for a new line in the original source file begins. The value ofstart_pc must be less than the value of thecode_length item of theCode attribute of which thisLineNumberTable is an attribute.

line_number

The value of theline_number item must give the corresponding line number in the original source file.

4.7.9 TheLocalVariableTable Attribute

TheLocalVariableTable 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];    }

attribute_name_index

The value of theattribute_name_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing the string"LocalVariableTable".

attribute_length

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

local_variable_table_length

The value of thelocal_variable_table_length item indicates the number of entries in thelocal_variable_table array.

local_variable_table[]

Each entry in thelocal_variable_table array indicates a range ofcode 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:

start_pc,length

The given local variable must have a value at indices into thecode array in the interval [start_pc,start_pc+length], that is, betweenstart_pc andstart_pc+length inclusive. The value ofstart_pc must be a valid index into thecode array of thisCode attribute and must be the index of the opcode of an instruction. Either the value ofstart_pc+length must be a valid index into thecode array of thisCode attribute and be the index of the opcode of an instruction, or it must be the first index beyond the end of thatcode array.

name_index,descriptor_index

The value of thename_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must contain aCONSTANT_Utf8_info(§4.4.7)structure representing a valid local variable name stored as a simple name(§2.7.1).

The value of thedescriptor_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must contain aCONSTANT_Utf8_info(§4.4.7) structure representing a field descriptor(§4.3.2) encoding the type of a local variable in the source program.

index

The given local variable must be atindex in the local variable array of the current frame. If the local variable atindex is of typedouble orlong, it occupies bothindex andindex+1.

4.7.10 TheDeprecated Attribute

TheDeprecated attribute has the following format:

    Deprecated_attribute {    u2 attribute_name_index;    u4 attribute_length;    }

attribute_name_index

The value of theattribute_name_index item must be a valid index into theconstant_pool table. Theconstant_pool entry at that index must be aCONSTANT_Utf8_info(§4.4.7) structure representing the string"Deprecated".

attribute_length

The value of theattribute_length item is zero.

4.8 Constraints on Java Virtual Machine Code

4.8.1 Static Constraints

The static constraints on the instructions in thecode array are as follows:

• Thecode array must not be empty, so thecode_length item cannot have the value0.

• The value of thecode_length item must be less than65536.

• The opcode of the first instruction in thecode array begins at index0.

• Only instances of the instructions documented inSection 6.4 may appear in thecode array. Instances of instructions using the reserved opcodes(§6.2) or any opcodes not documented in this specification may not appear in thecode array.

• For each instruction in thecode array except the last, the index of the opcode of the next instruction equals the index of the opcode of the current instruction plus the length of that instruction, including all its operands. Thewide instruction is treated like any other instruction for these purposes; the opcode specifying the operation that awide instruction is to modify is treated as one of the operands of thatwide instruction. That opcode must never be directly reachable by the computation.

• The last byte of the last instruction in thecode array must be the byte at indexcode_length-1.

• The target of each jump and branch instruction (jsr,jsr_w,goto,goto_w,ifeq,ifne,ifle,iflt,ifge,ifgt,ifnull,ifnonnull,if_icmpeq,if_icmpne,if_icmple,if_icmplt,if_icmpge,if_icmpgt,if_acmpeq,if_acmpne) must be the opcode of an instruction within this method. The target of a jump or branch instruction must never be the opcode used to specify the operation to be modified by awide instruction; a jump or branch target may be thewide instruction itself.

• Each target, including the default, of eachtableswitch instruction must be the opcode of an instruction within this method. Eachtableswitch instruction must have a number of entries in its jump table that is consistent with the value of itslow andhigh jump table operands, and itslow value must be less than or equal to itshigh value. No target of atableswitch instruction may be the opcode used to specify the operation to be modified by awide instruction; atableswitch target may be awide instruction itself.

• Each target, including the default, of eachlookupswitch instruction must be the opcode of an instruction within this method. Eachlookupswitch instruction must have a number ofmatch-offset pairs that is consistent with the value of itsnpairs operand. Thematch-offset pairs must be sorted in increasing numerical order by signedmatch value. No target of alookupswitch instruction may be the opcode used to specify the operation to be modified by awide instruction; alookupswitch target may be awide instruction itself.

• The operand of eachldc instruction must be a valid index into theconstant_pool table. The operands of eachldc_w instruction must represent a valid index into theconstant_pool table. In both cases the constant pool entry referenced by that index must be of typeCONSTANT_Integer,CONSTANT_Float, orCONSTANT_String.

• The operands of eachldc2_w instruction must represent a valid index into theconstant_pool table. The constant pool entry referenced by that index must be of typeCONSTANT_Long orCONSTANT_Double. In addition, the subsequent constant pool index must also be a valid index into the constant pool, and the constant pool entry at that index must not be used.

• The operands of eachgetfield,putfield,getstatic, andputstatic instruction must represent a valid index into theconstant_pool table. The constant pool entry referenced by that index must be of typeCONSTANT_Fieldref.

• The indexbyte operands of eachinvokevirtual,invokespecial, andinvokestatic instruction must represent a valid index into theconstant_pool table. The constant pool entry referenced by that index must be of typeCONSTANT_Methodref.

• Only theinvokespecial instruction is allowed to invoke an instance initialization method(§3.9). No other method whose name begins with the character'<' ('\u003c') may be called by the method invocation instructions. In particular, the class or interface initialization method specially named<clinit> is never called explicitly from Java virtual machine instructions, but only implicitly by the Java virtual machine itself.

• The indexbyte operands of eachinvokeinterface instruction must represent a valid index into theconstant_pool table. The constant pool entry referenced by that index must be of typeCONSTANT_InterfaceMethodref. The value of thecount operand of eachinvokeinterface instruction must reflect the number of local variables necessary to store the arguments to be passed to the interface method, as implied by the descriptor of theCONSTANT_NameAndType_info structure referenced by theCONSTANT_InterfaceMethodref constant pool entry. The fourth operand byte of eachinvokeinterface instruction must have the value zero.

• The operands of eachinstanceof,checkcast,new, andanewarray instruction and the indexbyte operands of eachmultianewarray instruction must represent a valid index into theconstant_pool table. The constant pool entry referenced by that index must be of typeCONSTANT_Class.

• Noanewarray instruction may be used to create an array of more than 255 dimensions.

• Nonew instruction may reference aCONSTANT_Classconstant_pool table entry representing an array class. Thenew instruction cannot be used to create an array. Thenew instruction also cannot be used to create an instance of an interface or an instance of anabstract class.

• Amultianewarray instruction must be used only to create an array of a type that has at least as many dimensions as the value of itsdimensions operand. That is, while amultianewarray instruction is not required to create all of the dimensions of the array type referenced by its indexbyte operands, it must not attempt to create more dimensions than are in the array type. Thedimensions operand of eachmultianewarray instruction must not be zero.

• Theatype operand of eachnewarray instruction must take one of the valuesT_BOOLEAN (4),T_CHAR (5),T_FLOAT (6),T_DOUBLE (7),T_BYTE (8),T_SHORT (9),T_INT (10), orT_LONG (11).

• The index operand of eachiload,fload,aload,istore,fstore,astore,iinc, andret instruction must be a nonnegative integer no greater thanmax_locals-1.

• The implicit index of eachiload_<n>,fload_<n>,aload_<n>,istore_<n>,fstore_<n>, andastore_<n> instruction must be no greater than the value ofmax_locals-1.

• The index operand of eachlload,dload,lstore, anddstore instruction must be no greater than the value ofmax_locals-2.

• The implicit index of eachlload_<n>,dload_<n>,lstore_<n>, anddstore_<n> instruction must be no greater than the value ofmax_locals-2.

• The indexbyte operands of eachwide instruction modifying aniload,fload,aload,istore,fstore,astore,ret, oriinc instruction must represent a nonnegative integer no greater thanmax_locals-1. The indexbyte operands of eachwide instruction modifying anlload,dload,lstore, ordstore instruction must represent a nonnegative integer no greater thanmax_locals-2.

4.8.2 Structural Constraints

• Each instruction must only be executed with the appropriate type and number of arguments in the operand stack and local variable array, regardless of the execution path that leads to its invocation. An instruction operating on values of typeint is also permitted to operate on values of typeboolean,byte,char, andshort. (As noted in§3.3.4 and§3.11.1, the Java virtual machine internally converts values of typesboolean,byte,char, andshort to typeint.)

• If an instruction can be executed along several different execution paths, the operand stack must have the same depth(§3.6.2) prior to the execution of the instruction, regardless of the path taken.

• At no point during execution can the order of the local variable pair holding a value of typelong ordouble be reversed or the pair split up. At no point can the local variables of such a pair be operated on individually.

• No local variable (or local variable pair, in the case of a value of typelong ordouble) can be accessed before it is assigned a value.

• At no point during execution can the operand stack grow to a depth(§3.6.2) greater than that implied by themax_stack item.

• At no point during execution can more values be popped from the operand stack than it contains.

• Eachinvokespecial instruction must name an instance initialization method(§3.9), a method in the current class, or a method in a superclass of the current class.

• When the instance initialization method(§3.9) is invoked, an uninitialized class instance must be in an appropriate position on the operand stack. An instance initialization method must never be invoked on an initialized class instance.

• When any instance method is invoked or when any instance variable is accessed, the class instance that contains the instance method or instance variable must already be initialized.

• There must never be an uninitialized class instance on the operand stack or in a local variable when any backwards branch is taken. There must never be an uninitialized class instance in a local variable in code protected by an exception handler. However, an uninitialized class instance may be on the operand stack in code protected by an exception handler. When an exception is thrown, the contents of the operand stack are discarded.

• Each instance initialization method(§3.9), except for the instance initialization method derived from the constructor of classObject, must call either another instance initialization method ofthis or an instance initialization method of its direct superclasssuper before its instance members are accessed. However, instance fields ofthis that are declared in the current class may be assigned before calling any instance initialization method.

• The arguments to each method invocation must be method invocation compatible(§2.6.8) with the method descriptor(§4.3.3).

• The type of every class instance that is the target of a method invocation instruction must be assignment compatible(§2.6.7) with the class or interface type specified in the instruction.

• Each return instruction must match its method's return type. If the method returns aboolean,byte,char,short, orint, only theireturn instruction may be used. If the method returns afloat,long, ordouble, only anfreturn,lreturn, or dreturninstruction, respectively, may be used. If the method returns areference type, it must do so using anareturn instruction, and the type of the returned value must be assignment compatible(§2.6.7) with the return descriptor(§4.3.3) of the method. All instance initialization methods, class or interface initialization methods, and methods declared to returnvoid must use only thereturn instruction.

• Ifgetfieldor putfield is used to access aprotected field of a superclass, then the type of the class instance being accessed must be the same as or a subclass of the current class. Ifinvokevirtual orinvokespecialis used to access aprotected method of a superclass, then the type of the class instance being accessed must be the same as or a subclass of the current class.

• The type of every class instance accessed by agetfield instruction or modified by aputfield instruction must be assignment compatible(§2.6.7) with the class type specified in the instruction.

• The type of every value stored by aputfield orputstatic instruction must be compatible with the descriptor of the field(§4.3.2) of the class instance or class being stored into. If the descriptor type isboolean,byte,char,short, orint, then the value must be anint. If the descriptor type isfloat,long, ordouble, then the value must be afloat,long, ordouble, respectively. If the descriptor type is areference type, then the value must be of a type that is assignment compatible(§2.6.7) with the descriptor type.

• The type of every value stored into an array of typereference by anaastore instruction must be assignment compatible(§2.6.7) with the component type of the array.

• Eachathrow instruction must throw only values that are instances of classThrowable or of subclasses ofThrowable.

• Execution never falls off the bottom of thecode array.

• No return address (a value of typereturnAddress) may be loaded from a local variable.

• The instruction following eachjsr orjsr_w instruction may be returned to only by a singleret instruction.

• Nojsr orjsr_w instruction may be used to recursively call a subroutine if that subroutine is already present in the subroutine call chain. (Subroutines can be nested when usingtry-finally constructs from within afinally clause. For more information on Java virtual machine subroutines, see§4.9.6.)

• Each instance of typereturnAddress can be returned to at most once. If aret instruction returns to a point in the subroutine call chain above theret instruction corresponding to a given instance of typereturnAddress, then that instance can never be used as a return address.

4.9 Verification of Files

An additional problem with compile-time checking is version skew. A user may have successfully compiled a class, sayPurchaseStockOptions, to be a subclass ofTradingClass. But the definition ofTradingClass might have changed since the time the class was compiled in a way that is not compatible with preexisting binaries. Methods might have been deleted or had their return types or modifiers changed. Fields might have changed types or changed from instance variables to class variables. The access modifiers of a method or variable may have changed frompublic toprivate. For a discussion of these issues, see Chapter 13, "Binary Compatibility," in the first edition ofTheJava Language Specification or the equivalent chapter in the second edition.

Because of these potential problems, the Java virtual machine needs to verify for itself that the desired constraints are satisfied by theclass files it attempts to incorporate. A Java virtual machine implementation verifies that eachclass file satisfies the necessary constraints at linking time(§2.17.3). Structural constraints on the Java virtual machine code may be checked using a simple theorem prover.

Linking-time verification enhances the performance of the interpreter. Expensive checks that would otherwise have to be performed to verify constraints at run time for each interpreted instruction can be eliminated. The Java virtual machine can assume that these checks have already been performed. For example, the Java virtual machine will already know the following:

• There are no operand stack overflows or underflows.

• All local variable uses and stores are valid.

• The arguments to all the Java virtual machine instructions are of valid types.

Theclass file verifier is also independent of the Java programming language. Programs written in other languages can be compiled into theclass file format, but will pass verification only if all the same constraints are satisfied.

4.9.1 The Verification Process

Pass 1:
When a prospectiveclass file is loaded(§2.17.2) by the Java virtual machine, the Java virtual machine first ensures that the file has the basic format of aclass file. The first four bytes must contain the right magic number. All recognized attributes must be of the proper length. Theclass file must not be truncated or have extra bytes at the end. The constant pool must not contain any superficially unrecognizable information.

Whileclass file verification properly occurs during class linking(§2.17.3), this check for basicclass file integrity is necessary for any interpretation of theclass file contents and can be considered to be logically part of the verification process.

Pass 2:
When theclass file is linked, the verifier performs all additional verification that can be done without looking at thecode array of theCode attribute (§4.7.3). The checks performed by this pass include the following:

• Ensuring thatfinal classes are not subclassed and thatfinal methods are not overridden.

• Checking that every class (exceptObject) has a direct superclass.

• Ensuring that the constant pool satisfies the documented static constraints: for example, that eachCONSTANT_Class_info structure in the constant pool contains in itsname_index item a valid constant pool index for aCONSTANT_Utf8_info structure.

• Checking that all field references and method references in the constant pool have valid names, valid classes, and a valid type descriptor.

Pass 3:
During linking, the verifier checks thecode array of theCode attribute for each method of theclass file by performing data-flow analysis on each method. The verifier ensures that at any given point in the program, no matter what code path is taken to reach that point, the following is true:

• The operand stack is always the same size and contains the same types of values.

• No local variable is accessed unless it is known to contain a value of an appropriate type.

• Methods are invoked with the appropriate arguments.

• Fields are assigned only using values of appropriate types.

• All opcodes have appropriate type arguments on the operand stack and in the local variable array.

Pass 4:
For efficiency reasons, certain tests that could in principle be performed in Pass 3 are delayed until the first time the code for the method is actually invoked. In so doing, Pass 3 of the verifier avoids loadingclass files unless it has to.

For example, if a method invokes another method that returns an instance of classA, and that instance is assigned only to a field of the same type, the verifier does not bother to check if the classA actually exists. However, if it is assigned to a field of the typeB, the definitions of bothA andB must be loaded in to ensure thatA is a subclass ofB.

Pass 4 is a virtual pass whose checking is done by the appropriate Java virtual machine instructions. The first time an instruction that references a type is executed, the executing instruction does the following:

• Loads in the definition of the referenced type if it has not already been loaded.

• Checks that the currently executing type is allowed to reference the type.

• Ensures that the referenced method or field exists in the given class.

• Checks that the referenced method or field has the indicated descriptor.

• Checks that the currently executing method has access to the referenced method or field.

A Java virtual machine implementation is allowed to perform any or all of the Pass 4 steps as part of Pass 3; see2.17.1, "Virtual Machine Start-up" for an example and more discussion.

In one of Sun's Java virtual machine implementations, after the verification has been performed, the instruction in the Java virtual machine code is replaced with an alternative form of the instruction. This alternative instruction indicates that the verification needed by this instruction has taken place and does not need to be performed again. Subsequent invocations of the method will thus be faster. It is illegal for these alternative instruction forms to appear inclass files, and they should never be encountered by the verifier.

4.9.2 The Bytecode Verifier

The code for each method is verified independently. First, the bytes that make up the code are broken up into a sequence of instructions, and the index into thecode array of the start of each instruction is placed in an array. The verifier then goes through the code a second time and parses the instructions. During this pass a data structure is built to hold information about each Java virtual machine instruction in the method. The operands, if any, of each instruction are checked to make sure they are valid. For instance:

• Branches must be within the bounds of thecode array for the method.

• The targets of all control-flow instructions are each the start of an instruction. In the case of awide instruction, thewide opcode is considered the start of the instruction, and the opcode giving the operation modified by thatwide instruction is not considered to start an instruction. Branches into the middle of an instruction are disallowed.

• No instruction can access or modify a local variable at an index greater than or equal to the number of local variables that its method indicates it allocates.

• All references to the constant pool must be to an entry of the appropriate type. For example: the instructionldc can be used only for data of typeint or float or for instances of classString; the instructiongetfield must reference a field.

• The code does not end in the middle of an instruction.

• Execution cannot fall off the end of the code.

• For each exception handler, the starting and ending point of code protected by the handler must be at the beginning of an instruction or, in the case of the ending point, immediately past the end of the code. The starting point must be before the ending point. The exception handler code must start at a valid instruction, and it may not start at an opcode being modified by thewide instruction.

Next, a data-flow analyzer is initialized. For the first instruction of the method, the local variables that represent parameters initially contain values of the types indicated by the method's type descriptor; the operand stack is empty. All other local variables contain an illegal value. For the other instructions, which have not been examined yet, no information is available regarding the operand stack or local variables.

Finally, the data-flow analyzer is run. For each instruction, a "changed" bit indicates whether this instruction needs to be looked at. Initially, the "changed" bit is set only for the first instruction. The data-flow analyzer executes the following loop:

1. Select a virtual machine instruction whose "changed" bit is set. If no instruction remains whose "changed" bit is set, the method has successfully been verified. Otherwise, turn off the "changed" bit of the selected instruction.

2. Model the effect of the instruction on the operand stack and local variable array by doing the following:
   • If the instruction uses values from the operand stack, ensure that there are a sufficient number of values on the stack and that the top values on the stack are of an appropriate type. Otherwise, verification fails.

   • If the instruction uses a local variable, ensure that the specified local variable contains a value of the appropriate type. Otherwise, verification fails.

   • If the instruction pushes values onto the operand stack, ensure that there is sufficient room on the operand stack for the new values. Add the indicated types to the top of the modeled operand stack.

   • If the instruction modifies a local variable, record that the local variable now contains the new type.

3. Determine the instructions that can follow the current instruction. Successor instructions can be one of the following:
   • The next instruction, if the current instruction is not an unconditional control transfer instruction (for instancegoto,return, orathrow). Verification fails if it is possible to "fall off" the last instruction of the method.

   • The target(s) of a conditional or unconditional branch or switch.

   • Any exception handlers for this instruction.

4. Merge the state of the operand stack and local variable array at the end of the execution of the current instruction into each of the successor instructions. In the special case of control transfer to an exception handler, the operand stack is set to contain a single object of the exception type indicated by the exception handler information.
   • If this is the first time the successor instruction has been visited, record that the operand stack and local variable values calculated in steps 2 and 3 are the state of the operand stack and local variable array prior to executing the successor instruction. Set the "changed" bit for the successor instruction.

   • If the successor instruction has been seen before, merge the operand stack and local variable values calculated in steps 2 and 3 into the values already there. Set the "changed" bit if there is any modification to the values.

5. Continue at step 1.

To merge two local variable array states, corresponding pairs of local variables are compared. If the two types are not identical, then unless both containreference values, the verifier records that the local variable contains an unusable value. If both of the pair of local variables containreference values, the merged state contains areference to an instance of the first common superclass of the two types.

If the data-flow analyzer runs on a method without reporting a verification failure, then the method has been successfully verified by Pass 3 of theclass file verifier.

Certain instructions and data types complicate the data-flow analyzer. We now examine each of these in more detail.

4.9.3 Values of Typeslong anddouble

Whenever a value of typelong ordouble is moved into a local variable at indexn, indexn + 1 is specially marked to indicate that it has been reserved by the value at indexn and may not be used as a local variable index. Any value previously at indexn + 1 becomes unusable.

Whenever a value is moved to a local variable at indexn, the indexn - 1 is examined to see if it is the index of a value of typelong ordouble. If so, the local variable at indexn - 1 is changed to indicate that it now contains an unusable value. Since the local variable at indexn has been overwritten, the local variable at indexn - 1 cannot represent a value of typelong ordouble.

Dealing with values of typeslong ordouble on the operand stack is simpler; the verifier treats them as single values on the stack. For example, the verification code for thedadd opcode (add twodouble values) checks that the top two items on the stack are both of typedouble. When calculating operand stack length, values of typelong anddouble have length two.

Untyped instructions that manipulate the operand stack must treat values of typedouble andlong as atomic (indivisible). For example, the verifier reports a failure if the top value on the stack is adouble and it encounters an instruction such aspop ordup. The instructionspop2 ordup2 must be used instead.

4.9.4 Instance Initialization Methods and Newly Created Objects

    ...    new myClass(i, j, k);    ...

    ...    new#1// Allocate uninitialized space formyClass    dup// Duplicate object on the operand stack    iload_1// Push i    iload_2// Push j    iload_3// Push k    invokespecial #5 // InvokemyClass.<init>    ...

The instance initialization method(§3.9) for classmyClass sees the new uninitialized object as itsthis argument in local variable0. Before that method invokes another instance initialization method ofmyClass or its direct superclass onthis, the only operation the method can perform onthis is assigning fields declared withinmyClass.

When doing dataflow analysis on instance methods, the verifier initializes local variable0 to contain an object of the current class, or, for instance initialization methods, local variable0 contains a special type indicating an uninitialized object. After an appropriate instance initialization method is invoked (from the current class or the current superclass) on this object, all occurrences of this special type on the verifier's model of the operand stack and in the local variable array are replaced by the current class type. The verifier rejects code that uses the new object before it has been initialized or that initializes the object more than once. In addition, it ensures that every normal return of the method has invoked an instance initialization method either in the class of this method or in the direct superclass.

Similarly, a special type is created and pushed on the verifier's model of the operand stack as the result of the Java virtual machine instructionnew. The special type indicates the instruction by which the class instance was created and the type of the uninitialized class instance created. When an instance initialization method is invoked on that class instance, all occurrences of the special type are replaced by the intended type of the class instance. This change in type may propagate to subsequent instructions as the dataflow analysis proceeds.

The instruction number needs to be stored as part of the special type, as there may be multiple not-yet-initialized instances of a class in existence on the operand stack at one time. For example, the Java virtual machine instruction sequence that implements

new InputStream(new Foo(), new InputStream("foo"))

may have two uninitialized instances ofInputStream on the operand stack at once. When an instance initialization method is invoked on a class instance, only those occurrences of the special type on the operand stack or in the local variable array that are thesame object as the class instance are replaced.

A valid instruction sequence must not have an uninitialized object on the operand stack or in a local variable during a backwards branch, or in a local variable in code protected by an exception handler or afinally clause. Otherwise, a devious piece of code might fool the verifier into thinking it had initialized a class instance when it had, in fact, initialized a class instance created in a previous pass through a loop.

4.9.5 Exception Handlers

• Either the ranges of instructions protected by two different exception handlers always are completely disjoint, or else one is a subrange of the other. There is never a partial overlap of ranges.

• The handler for an exception will never be inside the code that is being protected.

• The only entry to an exception handler is through an exception. It is impossible to fall through or "goto" the exception handler.

4.9.6 Exceptions andfinally

    ...    try {        startFaucet();        waterLawn();    } finally {        stopFaucet();    }    ...

To implement thetry-finally construct, Sun's compiler for the Java programming language uses the exception-handling facilities together with two special instructions:jsr ("jump to subroutine") andret ("return from subroutine"). Thefinally clause is compiled as a subroutine within the Java virtual machine code for its method, much like the code for an exception handler. When ajsr instruction that invokes the subroutine is executed, it pushes its return address, the address of the instruction after thejsr that is being executed, onto the operand stack as a value of typereturnAddress. The code for the subroutine stores the return address in a local variable. At the end of the subroutine, aret instruction fetches the return address from the local variable and transfers control to the instruction at the return address.

Control can be transferred to thefinally clause (thefinally subroutine can be invoked) in several different ways. If thetry clause completes normally, thefinally subroutine is invoked via ajsr instruction before evaluating the next expression. Abreak orcontinue inside thetry clause that transfers control outside thetry clause executes ajsr to the code for thefinally clause first. If thetry clause executes areturn, the compiled code does the following:

1. Saves the return value (if any) in a local variable.
2. Executes ajsr to the code for thefinally clause.
3. Upon return from thefinally clause, returns the value saved in the local variable.

1. Saves the exception in a local variable.
2. Executes ajsr to thefinally clause.
3. Upon return from thefinally clause, rethrows the exception.

The code for thefinally clause presents a special problem to the verifier. Usually, if a particular instruction can be reached via multiple paths and a particular local variable contains incompatible values through those multiple paths, then the local variable becomes unusable. However, afinally clause might be called from several different places, yielding several different circumstances:

• The invocation from the exception handler may have a certain local variable that contains an exception.

• The invocation to implementreturn may have some local variable that contains the return value.

• The invocation from the bottom of thetry clause may have an indeterminate value in that same local variable.

Verifying code that contains afinally clause is complicated. The basic idea is the following:

• Each instruction keeps track of the list ofjsr targets needed to reach that instruction. For most code, this list is empty. For instructions inside code for thefinally clause, it is of length one. For multiply nestedfinally code (extremely rare!), it may be longer than one.

• For each instruction and eachjsr needed to reach that instruction, a bit vector is maintained of all local variables accessed or modified since the execution of thejsr instruction.

• When executing theret instruction, which implements a return from a subroutine, there must be only one possible subroutine from which the instruction can be returning. Two different subroutines cannot "merge" their execution to a singleret instruction.

• To perform the data-flow analysis on aret instruction, a special procedure is used. Since the verifier knows the subroutine from which the instruction must be returning, it can find all thejsr instructions that call the subroutine and merge the state of the operand stack and local variable array at the time of theret instruction into the operand stack and local variable array of the instructions following thejsr. Merging uses a special set of values for local variables:
  • For any local variable that the bit vector (constructed above) indicates has been accessed or modified by the subroutine, use the type of the local variable at the time of theret.

  • For other local variables, use the type of the local variable before thejsr instruction.

4.10 Limitations of the Java Virtual Machine

• The per-class or per-interface constant pool is limited to 65535 entries by the 16-bitconstant_pool_count field of theClassFile structure(§4.1). This acts as an internal limit on the total complexity of a single class or interface.

• The amount of code per non-native, non-abstract method is limited to 65536 bytes by the sizes of the indices in theexception_table of theCode attribute (§4.7.3), in theLineNumberTable attribute(§4.7.8), and in theLocalVariableTable attribute(§4.7.9).

• The greatest number of local variables in the local variables array of a frame created upon invocation of a method is limited to 65535 by the size of themax_locals item of theCode attribute(§4.7.3) giving the code of the method. Note that values of typelong anddouble are each considered to reserve two local variables and contribute two units toward themax_locals value, so use of local variables of those types further reduces this limit.

• The number of fields that may be declared by a class or interface is limited to 65535 by the size of thefields_count item of theClassFile structure(§4.1). Note that the value of thefields_count item of theClassFile structure does not include fields that are inherited from superclasses or superinterfaces.

• The number of methods that may be declared by a class or interface is limited to 65535 by the size of themethods_count item of theClassFile structure(§4.1). Note that the value of themethods_count item of theClassFile structure does not include methods that are inherited from superclasses or superinterfaces.

• The number of direct superinterfaces of a class or interface is limited to 65535 by the size of theinterfaces_count item of theClassFile structure(§4.1).

• The size of an operand stack in a frame(§3.6) is limited to 65535 values by themax_stack field of theCode_attribute structure(§4.7.3). Note that values of typelong anddouble are each considered to contribute two units toward themax_stack value, so use of values of these types on the operand stack further reduces this limit.

• The number of local variables in a frame(§3.6) is limited to 65535 by themax_locals field of theCode_attribute structure(§4.7.3) and the 16-bit local variable indexing of the Java virtual machine instruction set.

• The number of dimensions in an array is limited to 255 by the size of thedimensions opcode of themultianewarray instruction and by the constraints imposed on themultianewarray,anewarray, andnewarray instructions by§4.8.2.

• The number of method parameters is limited to 255 by the definition of a method descriptor(§4.3.3), where the limit includes one unit forthis in the case of instance or interface method invocations. Note that a method descriptor is defined in terms of a notion of method parameter length in which a parameter of typelong ordouble contributes two units to the length, so parameters of these types further reduce the limit.

• The length of field and method names, field and method descriptors, and other constant string values is limited to 65535 characters by the 16-bit unsignedlength item of theCONSTANT_Utf8_info structure(§4.4.7). Note that the limit is on the number of bytes in the encoding and not on the number of encoded characters. UTF-8 encodes some characters using two or three bytes. Thus, strings incorporating multibyte characters are further constrained.

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

³ The first edition ofThe Java Language Specification required that "com" be in uppercase in this example. The second edition will reverse that convention and use lowercase.

⁴ The fact thatend_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 anycode array) to 65534 bytes.

⁵ TheInnerClasses attribute was introduced in JDK release 1.1 to support nested classes and interfaces.

⁶ TheSynthetic attribute was introduced in JDK release 1.1 to support nested classes and interfaces.

⁷ TheDeprecated attribute was introduced in JDK release 1.1 to support the@deprecated tag in documentation comments.

Contents |Prev |Next |Index