Sealed Types

This document describes changes to the Java Virtual Machine Specification as modified by Class Loading Cleanup to support sealed types, a preview feature of Java SE 15. A sealed class or interface restricts extension and implementation to an enumerated set of authorized subclasses or subinterfaces. See JEP 360 for an overview of the feature.

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

All attributes have the following general format:

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

For all attributes, the attribute_name_index item must be a valid unsigned 16-bit index into the constant pool of the class. The constant_pool entry at attribute_name_index must be a CONSTANT_Utf8_info structure (4.4.7) representing 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 Seven attributes are critical to correct interpretation of the class file by the Java Virtual Machine:

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

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

   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.30 The PermittedSubtypes Attribute

PermittedSubtypes_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 number_of_classes;
    u2 classes[number_of_classes];
}

Chapter 5: Loading, Linking, and Initializing

5.3 Creation and Loading

5.3.5 Deriving a Class from a class File Representation

The following steps are used to derive a nonarray class or interface C denoted by N using loader L from a purported representation in class file format.

1. First, the Java Virtual Machine determines whether the attempt to derive a class or interface named N for class loader L is invalid. If so, derivation throws a LinkageError.

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

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

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

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

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

2. Otherwise, the Java Virtual Machine attempts to parse the purported representation. However, the purported representation may not in fact be a valid representation of C.

   This phase of derivation must detect the following errors:

   • If the purported representation provides a major and minor version number in its 5th through 8th bytes (4.1), but the version number is not supported by this Java Virtual Machine implementation, derivation throws an instance of UnsupportedClassVersionError.

     UnsupportedClassVersionError, a subclass of ClassFormatError, was introduced to enable easy identification of a ClassFormatError caused by an attempt to load a class whose representation uses an unsupported version of the class file format. In JDK 1.1 and earlier, an instance of NoClassDefFoundError or ClassFormatError was thrown in case of an unsupported version, depending on whether the class was being loaded by the system class loader or a user-defined class loader.

   • Otherwise, if the purported representation is not a ClassFile structure (4.1, 4.8), derivation throws an instance of ClassFormatError.

   • Otherwise, if the purported representation does not actually represent a class or interface named N, derivation throws an instance of NoClassDefFoundError or an instance of one of its subclasses.

     This occurs when the purported representation has either a this_class item which specifies a name other than N, or an access_flags item which has the ACC_MODULE flag set.

3. If C has a direct superclass, the symbolic reference from C to its direct superclass is resolved using the algorithm of 5.4.3.1. Note that if C is an interface it must have Object as its direct superclass. Only Object has no direct superclass.

   Any exceptions that can be thrown due to class or interface resolution can be thrown as a result of this phase of derivation. In addition, this phase of derivation must detect the following errors:

   • If the attempt to resolve the direct superclass leads to the current thread attempting to recursively derive a class named N using loader L, derivation throws a ClassCircularityError.

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

   • Otherwise, if the class named as the direct superclass of C has a PermittedSubtypes attribute (4.7.30), at least one entry in the classes table of the superclass's PermittedSubtypes attribute must reference a class or interface with name N. If not, derivation throws an IncompatibleClassChangeError.

     To ensure that the name N appearing in the superclass refers to C, an attempt is made, using the defining class loader of the superclass, to create a class or interface denoted by N. The attempt must lead to the current thread attempting to recursively derive a class or interface named N using loader L; the attempt is then abandoned. If the recursive attempt at derivation does not occur, derivation throws an IncompatibleClassChangeError.

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

4. If C has any direct superinterfaces, the symbolic references from C to its direct superinterfaces are resolved using the algorithm of 5.4.3.1.

   Any exceptions that can be thrown due to class or interface resolution can be thrown as a result of this phase of derivation. In addition, this phase of derivation must detect the following errors:

   • If the attempt to resolve a direct superinterface leads to the current thread attempting to recursively derive a class named N using loader L, derivation throws a ClassCircularityError.

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

   • Otherwise, for each direct superinterface, if the superinterface has a PermittedSubtypes attribute (4.7.30), at least one entry in the classes table of the superinterface's PermittedSubtypes attribute must reference a class or interface with name N. If not, derivation throws an IncompatibleClassChangeError.

     To ensure that the name N appearing in the superinterface refers to C, an attempt is made, using the defining class loader of the superclass, to create a class or interface denoted by N. The attempt must lead to the current thread attempting to recursively derive a class or interface named N using loader L; the attempt is then abandoned. If the recursive attempt at derivation does not occur, derivation throws an IncompatibleClassChangeError.

5. If, since step 1, in another thread, the Java Virtual Machine has marked a class or interface named N as having L as its defining class loader, that class or interface is the result of class derivation, and the class or interface derived in steps 1-4 is discarded.

   Otherwise, the class or interface derived in steps 1-4 is the result of class derivation, and the Java Virtual Machine marks C as having L as its defining class loader and records that L is an initiating loader of C (5.3.4).