Records (Preview)

This document describes changes to the Java Virtual Machine Specification to support the Java language records feature. See JEP 359.

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

Chapter 4: The class File Format

4.7 Attributes

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

All attributes have the following general format:

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

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

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

• Table 4.7-A is ordered by the attributes' section numbers in this chapter. Each attribute is shown with the first version of the class file format in which it was defined. Also shown is the version of the Java SE Platform which introduced that version of the class file format (4.1).

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

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

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

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

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

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

   • ConstantValue
   • Code
   • StackMapTable
   • BootstrapMethods
   • NestHost
   • NestMembers

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

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

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

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

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

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

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

4.7.8 The Synthetic Attribute

The Synthetic attribute is a fixed-length attribute in the attributes table of a ClassFile, field_info, or method_info structure (4.1, 4.5, 4.6). A class member that does not appear in the source code must 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 members which are not considered implementation artifacts, namely the instance initialization method representing a default constructor of the Java programming language (2.9.1), the class or interface initialization method (2.9.2), and the Enum.values() and Enum.valueOf() methods the implicitly-declared members of enums and records (JLS 8.9.3, 8.10.3).

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

It is a limitation of the class file that, while a method parameter or a module may be marked ACC_MANDATED (4.7.24, 4.7.25), there is no equivalent way to flag compiler-generated methods and fields which are not considered implementation artifacts (JLS 13.1). This limitation means that reflective APIs may not accurately indicate the mandated status of such members.

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:

attribute_name_index

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

attribute_length

The value of the attribute_length item must be zero.

4.7.9 The Signature Attribute

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

There may be at most one Signature attribute in the attributes table of a ClassFile, field_info, or method_info, or record_component_info structure.

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:

attribute_name_index

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

attribute_length

The value of the attribute_length item must be two.

signature_index

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

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

4.7.9.1 Signatures

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

A Java compiler must emit a signature for any class, interface, constructor, method, or field, or record component 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, or record component 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.

  JavaTypeSignature:

  ReferenceTypeSignature

  BaseType

  The following production from 4.3.2 is repeated here for convenience:

  BaseType:

  (one of)

  B C D F I J S Z

• A reference type signature represents a reference type of the Java programming language, that is, a class or interface type, a type variable, or an array type.

  A class type signature represents a (possibly parameterized) class or interface type. A class type signature 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.

  ReferenceTypeSignature:

  ClassTypeSignature

  TypeVariableSignature

  ArrayTypeSignature

  ClassTypeSignature:

  L [PackageSpecifier]
  SimpleClassTypeSignature {ClassTypeSignatureSuffix} ;

  PackageSpecifier:

  Identifier / {PackageSpecifier}

  SimpleClassTypeSignature:

  Identifier [TypeArguments]

  TypeArguments:

  < TypeArgument {TypeArgument} >

  TypeArgument:

  [WildcardIndicator] ReferenceTypeSignature

  *

  WildcardIndicator:

  +

  -

  ClassTypeSignatureSuffix:

  . SimpleClassTypeSignature

  TypeVariableSignature:

  T Identifier ;

  ArrayTypeSignature:

  [ JavaTypeSignature

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

ClassSignature:

[TypeParameters] SuperclassSignature {SuperinterfaceSignature}

TypeParameters:

< TypeParameter {TypeParameter} >

TypeParameter:

Identifier ClassBound {InterfaceBound}

ClassBound:

: [ReferenceTypeSignature]

InterfaceBound:

: ReferenceTypeSignature

SuperclassSignature:

ClassTypeSignature

SuperinterfaceSignature:

ClassTypeSignature

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

MethodSignature:

[TypeParameters] ( {JavaTypeSignature} ) Result {ThrowsSignature}

Result:

JavaTypeSignature

VoidDescriptor

ThrowsSignature:

^ ClassTypeSignature

^ TypeVariableSignature

The following production from 4.3.3 is repeated here for convenience:

VoidDescriptor:

V

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

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

FieldSignature:

ReferenceTypeSignature

4.7.16 The RuntimeVisibleAnnotations Attribute

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

There may be at most one RuntimeVisibleAnnotations attribute in the attributes table of a ClassFile, field_info, or method_info, or record_component_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:

attribute_name_index

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

attribute_length

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

num_annotations

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

annotations[]

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:

type_index

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.

num_element_value_pairs

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

element_value_pairs[]

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

element_name_index

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.

value

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

4.7.17 The RuntimeInvisibleAnnotations Attribute

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

There may be at most one RuntimeInvisibleAnnotations attribute in the attributes table of a ClassFile, field_info, or method_info, or record_component_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:

attribute_name_index

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

attribute_length

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

num_annotations

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

annotations[]

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.

4.7.20 The RuntimeVisibleTypeAnnotations Attribute

The RuntimeVisibleTypeAnnotations attribute is an variable-length attribute in the attributes table of a ClassFile, field_info, or method_info, or record_component_info structure, or Code attribute (4.1, 4.5, 4.6, 4.7.30, 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 record component, or in an expression in the corresponding method body. The RuntimeVisibleTypeAnnotations attribute also records run-time visible annotations on type parameter declarations of generic classes, interfaces, methods, and constructors.

There may be at most one RuntimeVisibleTypeAnnotations attribute in the attributes table of a ClassFile, field_info, or method_info, or record_component_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:

attribute_name_index

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

attribute_length

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

num_annotations

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

annotations[]

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

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

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

The items of the type_annotation structure are as follows:

target_type

The value of the target_type item denotes 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.

target_info

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

target_path

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

type_index, num_element_value_pairs, element_value_pairs[]

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

4.7.20.1 The target_info union

...

• The empty_target item indicates that an annotation appears on either the type in a field declaration, the type in a record component 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.

...

4.7.21 The RuntimeInvisibleTypeAnnotations Attribute

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

There may be at most one RuntimeInvisibleTypeAnnotations attribute in the attributes table of a ClassFile, field_info, or method_info, or record_component_info structure, or Code attribute.

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

The RuntimeInvisibleTypeAnnotations attribute has the following format:

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

The items of the RuntimeInvisibleTypeAnnotations_attribute structure are as follows:

attribute_name_index

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

attribute_length

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

num_annotations

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

annotations[]

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

4.7.30 The Record Attribute

Record_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 components_count;
    record_component_info components[components_count];
}