Records (Preview)

This document describes changes to the Java Language Specification to support records. See JEP draft 8222777.

Changes are described with respect to existing sections of the JLS. 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 1: Introduction

1.1 Organization of the Specification

Chapter 2 describes grammars and the notation used to present the lexical and syntactic grammars for the language.

Chapter 3 describes the lexical structure of the Java programming language, which is based on C and C++. The language is written in the Unicode character set. It supports the writing of Unicode characters on systems that support only ASCII.

Chapter 4 describes types, values, and variables. Types are subdivided into primitive types and reference types.

The primitive types are defined to be the same on all machines and in all implementations, and are various sizes of two's-complement integers, single- and double-precision IEEE 754 standard floating-point numbers, a boolean type, and a Unicode character char type. Values of the primitive types do not share state.

Reference types are the class types, the interface types, and the array types. The reference types are implemented by dynamically created objects that are either instances of classes or arrays. Many references to each object can exist. All objects (including arrays) support the methods of the class Object, which is the (single) root of the class hierarchy. A predefined String class supports Unicode character strings. Classes exist for wrapping primitive values inside of objects. In many cases, wrapping and unwrapping is performed automatically by the compiler (in which case, wrapping is called boxing, and unwrapping is called unboxing). Class and interface declarations may be generic, that is, they may be parameterized by other reference types. Such declarations may then be invoked with specific type arguments.

Variables are typed storage locations. A variable of a primitive type holds a value of that exact primitive type. A variable of a class type can hold a null reference or a reference to an object whose type is that class type or any subclass of that class type. A variable of an interface type can hold a null reference or a reference to an instance of any class that implements the interface. A variable of an array type can hold a null reference or a reference to an array. A variable of class type Object can hold a null reference or a reference to any object, whether class instance or array.

Chapter 5 describes conversions and numeric promotions. Conversions change the compile-time type and, sometimes, the value of an expression. These conversions include the boxing and unboxing conversions between primitive types and reference types. Numeric promotions are used to convert the operands of a numeric operator to a common type where an operation can be performed. There are no loopholes in the language; casts on reference types are checked at run time to ensure type safety.

Chapter 6 describes declarations and names, and how to determine what names mean (that is, which declaration a name denotes). The Java programming language does not require classes and interfaces, or their members, to be declared before they are used. Declaration order is significant only for local variables, local classes, and the order of field initializers in a class or interface. Recommended naming conventions that make for more readable programs are described here.

Chapter 7 describes the structure of a program, which is organized into packages. The members of a package are classes, interfaces, and subpackages. Packages, and consequently their members, have names in a hierarchical name space; the Internet domain name system can usually be used to form unique package names. Compilation units contain declarations of the classes and interfaces that are members of a given package, and may import classes and interfaces from other packages to give them short names.

Packages may be grouped into modules that serve as building blocks in the construction of very large programs. The declaration of a module specifies which other modules (and thus packages, and thus classes and interfaces) are required in order to compile and run code in its own packages.

The Java programming language supports limitations on external access to the members of packages, classes, and interfaces. The members of a package may be accessible solely by other members in the same package, or by members in other packages of the same module, or by members of packages in different modules. Similar constraints apply to the members of classes and interfaces.

Chapter 8 describes classes. The members of classes are classes, interfaces, fields (variables) and methods. Class variables exist once per class. Class methods operate without reference to a specific object. Instance variables are dynamically created in objects that are instances of classes. Instance methods are invoked on instances of classes; such instances become the current object this during their execution, supporting the object-oriented programming style.

Classes support single inheritance, in which each class has a single superclass. Each class inherits members from its superclass, and ultimately from the class Object. Variables of a class type can reference an instance of that class or of any subclass of that class, allowing new types to be used with existing methods, polymorphically.

Classes support concurrent programming with synchronized methods. Methods declare the checked exceptions that can arise from their execution, which allows compile-time checking to ensure that exceptional conditions are handled. Objects can declare a finalize method that will be invoked before the objects are discarded by the garbage collector, allowing the objects to clean up their state.

For simplicity, the language has neither declaration "headers" separate from the implementation of a class nor separate type and class hierarchies.

A special form of classes, enums, support the definition of small sets of values and their manipulation in a type safe manner. Unlike enumerations in other languages, enums are objects and may have their own methods.

A second, special form of classes, records, support a compact declaration of simple objects that serve as aggregates of values.

Chapter 9 describes interfaces. The members of interfaces are classes, interfaces, constant fields, and methods. Classes that are otherwise unrelated can implement the same interface. A variable of an interface type can contain a reference to any object that implements the interface.

Classes and interfaces support multiple inheritance from interfaces. A class that implements one or more interfaces may inherit instance methods from both its superclass and its superinterfaces.

Annotation types are specialized interfaces used to annotate declarations. Such annotations are not permitted to affect the semantics of programs in the Java programming language in any way. However, they provide useful input to various tools.

Chapter 10 describes arrays. Array accesses include bounds checking. Arrays are dynamically created objects and may be assigned to variables of type Object. The language supports arrays of arrays, rather than multidimensional arrays.

Chapter 11 describes exceptions, which are nonresuming and fully integrated with the language semantics and concurrency mechanisms. There are three kinds of exceptions: checked exceptions, run-time exceptions, and errors. The compiler ensures that checked exceptions are properly handled by requiring that a method or constructor can result in a checked exception only if the method or constructor declares it. This provides compile-time checking that exception handlers exist, and aids programming in the large. Most user-defined exceptions should be checked exceptions. Invalid operations in the program detected by the Java Virtual Machine result in run-time exceptions, such as NullPointerException. Errors result from failures detected by the Java Virtual Machine, such as OutOfMemoryError. Most simple programs do not try to handle errors.

Chapter 12 describes activities that occur during execution of a program. A program is normally stored as binary files representing compiled classes and interfaces. These binary files can be loaded into a Java Virtual Machine, linked to other classes and interfaces, and initialized.

After initialization, class methods and class variables may be used. Some classes may be instantiated to create new objects of the class type. Objects that are class instances also contain an instance of each superclass of the class, and object creation involves recursive creation of these superclass instances.

When an object is no longer referenced, it may be reclaimed by the garbage collector. If an object declares a finalizer, the finalizer is executed before the object is reclaimed to give the object a last chance to clean up resources that would not otherwise be released. When a class is no longer needed, it may be unloaded.

Chapter 13 describes binary compatibility, specifying the impact of changes to types on other types that use the changed types but have not been recompiled. These considerations are of interest to developers of types that are to be widely distributed, in a continuing series of versions, often through the Internet. Good program development environments automatically recompile dependent code whenever a type is changed, so most programmers need not be concerned about these details.

Chapter 14 describes blocks and statements, which are based on C and C++. The language has no goto statement, but includes labeled break and continue statements. Unlike C, the Java programming language requires boolean (or Boolean) expressions in control-flow statements, and does not convert types to boolean implicitly (except through unboxing), in the hope of catching more errors at compile time. A synchronized statement provides basic object-level monitor locking. A try statement can include catch and finally clauses to protect against non-local control transfers.

Chapter 15 describes expressions. This document fully specifies the (apparent) order of evaluation of expressions, for increased determinism and portability. Overloaded methods and constructors are resolved at compile time by picking the most specific method or constructor from those which are applicable.

Chapter 16 describes the precise way in which the language ensures that local variables are definitely set before use. While all other variables are automatically initialized to a default value, the Java programming language does not automatically initialize local variables in order to avoid masking programming errors.

Chapter 17 describes the semantics of threads and locks, which are based on the monitor-based concurrency originally introduced with the Mesa programming language. The Java programming language specifies a memory model for shared-memory multiprocessors that supports high-performance implementations.

Chapter 18 describes a variety of type inference algorithms used to test applicability of generic methods and to infer types in a generic method invocation.

Chapter 19 presents a syntactic grammar for the language.

Chapter 3: Lexical Structure

3.8 Identifiers

An identifier is an unlimited-length sequence of Java letters and Java digits, the first of which must be a Java letter.

Identifier:

IdentifierChars but not a Keyword or BooleanLiteral or NullLiteral

IdentifierChars:

JavaLetter {JavaLetterOrDigit}

JavaLetter:

any Unicode character that is a "Java letter"

JavaLetterOrDigit:

any Unicode character that is a "Java letter-or-digit"

A "Java letter" is a character for which the method Character.isJavaIdentifierStart(int) returns true.

A "Java letter-or-digit" is a character for which the method Character.isJavaIdentifierPart(int) returns true.

The "Java letters" include uppercase and lowercase ASCII Latin letters A-Z (\u0041-\u005a), and a-z (\u0061-\u007a), and, for historical reasons, the ASCII dollar sign ($, or \u0024) and underscore (_, or \u005f). The dollar sign should be used only in mechanically generated source code or, rarely, to access pre-existing names on legacy systems. The underscore may be used in identifiers formed of two or more characters, but it cannot be used as a one-character identifier due to being a keyword.

The "Java digits" include the ASCII digits 0-9 (\u0030-\u0039).

Letters and digits may be drawn from the entire Unicode character set, which supports most writing scripts in use in the world today, including the large sets for Chinese, Japanese, and Korean. This allows programmers to use identifiers in their programs that are written in their native languages.

An identifier cannot have the same spelling (Unicode character sequence) as a keyword (3.9), boolean literal (3.10.3), or the null literal (3.10.7), or a compile-time error occurs.

Two identifiers are the same only if, after ignoring characters that are ignorable, the identifiers have the same Unicode character for each letter or digit. An ignorable character is a character for which the method Character.isIdentifierIgnorable(int) returns true. Identifiers that have the same external appearance may yet be different.

For example, the identifiers consisting of the single letters LATIN CAPITAL LETTER A (A, \u0041), LATIN SMALL LETTER A (a, \u0061), GREEK CAPITAL LETTER ALPHA (A, \u0391), CYRILLIC SMALL LETTER A (a, \u0430) and MATHEMATICAL BOLD ITALIC SMALL A (a, \ud835\udc82) are all different.

Unicode composite characters are different from their canonical equivalent decomposed characters. For example, a LATIN CAPITAL LETTER A ACUTE (Á, \u00c1) is different from a LATIN CAPITAL LETTER A (A, \u0041) immediately followed by a NON-SPACING ACUTE (´, \u0301) in identifiers. See The Unicode Standard, Section 3.11 "Normalization Forms".

Examples of identifiers are:

• String
• i3
• αρετη
• MAX_VALUE
• isLetterOrDigit

The identifiers var and record are restricted identifiers because they are not allowed in some contexts.

A type identifier is an identifier that is not the character sequence var or the character sequence record.

TypeIdentifier:

Identifier but not var or record

Type identifiers are used in certain contexts involving the declaration or use of types. For example, the name of a class must be a TypeIdentifier, so it is illegal to declare a class named var or record (8.1).

3.9 Keywords

51 character sequences, formed from ASCII letters, are reserved for use as keywords and cannot be used as identifiers (3.8).

Keyword:

(one of)

abstract continue for new switch
assert default if package synchronized
boolean do goto private this
break double implements protected throw
byte else import public throws
case enum instanceof return transient
catch extends int short try
char final interface static void
class finally long strictfp volatile
const float native super while
_ (underscore)

The keywords const and goto are reserved, even though they are not currently used. This may allow a Java compiler to produce better error messages if these C++ keywords incorrectly appear in programs.

A variety of character sequences are sometimes assumed, incorrectly, to be keywords:

• true and false are not keywords, but rather boolean literals (3.10.3).

• null is not a keyword, but rather the null literal (3.10.7).

• var is not a keyword, but rather an identifier with The restricted identifiers var and record are not keywords. var has special meaning as the type of a local variable declaration (14.4, 14.14.1, 14.14.2, 14.20.3) and the type of a lambda formal parameter (15.27.1). record has a special meaning in a record type declaration (8.10).

A further ten character sequences are restricted keywords: open, module, requires, transitive, exports, opens, to, uses, provides, and with. These character sequences are tokenized as keywords solely where they appear as terminals in the ModuleDeclaration, ModuleDirective, and RequiresModifier productions (7.7). They are tokenized as identifiers everywhere else, for compatibility with programs written before the introduction of restricted keywords. There is one exception: immediately to the right of the character sequence requires in the ModuleDirective production, the character sequence transitive is tokenized as a keyword unless it is followed by a separator, in which case it is tokenized as an identifier.

Chapter 6: Names

Names are used to refer to entities declared in a program.

A declared entity (6.1) is a package, class type (normal, or enum, or record), interface type (normal or annotation type), member (class, interface, field, or method) of a reference type, type parameter (of a class, interface, method or constructor), parameter (to a method, constructor, or exception handler), or local variable.

Names in programs are either simple, consisting of a single identifier, or qualified, consisting of a sequence of identifiers separated by "." tokens (6.2).

Every declaration that introduces a name has a scope (6.3), which is the part of the program text within which the declared entity can be referred to by a simple name.

A qualified name N.x may be used to refer to a member of a package or reference type, where N is a simple or qualified name and x is an identifier. If N names a package, then x is a member of that package, which is either a class or interface type or a subpackage. If N names a reference type or a variable of a reference type, then x names a member of that type, which is either a class, an interface, a field, or a method.

In determining the meaning of a name (6.5), the context of the occurrence is used to disambiguate among packages, types, variables, and methods with the same name.

Access control (6.6) can be specified in a class, interface, method, or field declaration to control when access to a member is allowed. Access is a different concept from scope. Access specifies the part of the program text within which the declared entity can be referred to by a qualified name. Access to a declared entity is also relevant in a field access expression (15.11), a method invocation expression in which the method is not specified by a simple name (15.12), a method reference expression (15.13), or a qualified class instance creation expression (15.9). In the absence of an access modifier, most declarations have package access, allowing access anywhere within the package that contains its declaration; other possibilities are public, protected, and private.

Fully qualified and canonical names (6.7) are also discussed in this chapter.

6.1 Declarations

A declaration introduces an entity into a program and includes an identifier (3.8) that can be used in a name to refer to this entity. The identifier is constrained to be a type identifier when the entity being introduced is a class, interface, or type parameter.

A declared entity is one of the following:

• A module, declared in a module declaration (7.7)

• A package, declared in a package declaration (7.4)

• An imported type, declared in a single-type-import declaration or a type-import-on-demand declaration (7.5.1, 7.5.2)

• An imported static member, declared in a single-static-import declaration or a static-import-on-demand declaration (7.5.3, 7.5.4)

• A class, declared in a class type declaration (8.1)

• An interface, declared in an interface type declaration (9.1)

• A type parameter, declared as part of the declaration of a generic class, interface, method, or constructor (8.1.2, 9.1.2, 8.4.4, 8.8.4)

• A member of a reference type (8.2, 9.2, 8.9.3, 9.6, 10.7), one of the following:

  • A member class (8.5, 9.5)

  • A member interface (8.5, 9.5)

  • An enum constant (8.9)

  • A record component (8.10.1)

  • A field, one of the following:

    • A field declared in a class type, or enum type, or record type (8.3, 8.9.2, 8.10.3)

    • A field declared in an interface type or annotation type (9.3, 9.6.1)

    • The field length, which is implicitly a member of every array type (10.7)

  • A method, one of the following:

    • A method (abstract or otherwise) declared in a class type, or enum type, or record type (8.4, 8.9.2, 8.10.3)

    • A method (abstract or otherwise) declared in an interface type or annotation type (9.4, 9.6.1)

• A parameter, one of the following:

  • A formal parameter of a method or constructor of a class type, or enum type, or record type (8.4.1, 8.8.1, 8.9.2, 8.10.3), or of a lambda expression (15.27.1)

  • A formal parameter of an abstract method of an interface type or annotation type (9.4, 9.6.1)

  • An exception parameter of an exception handler declared in a catch clause of a try statement (14.20)

• A local variable, one of the following:

  • A local variable declared in a block (14.4)

  • A local variable declared in a for statement (14.14)

Constructors (8.8) are also introduced by declarations, but use the name of the class in which they are declared rather than introducing a new name.

The declaration of a type which is not generic (class C ...) declares one entity: a non-generic type (C). A non-generic type is not a raw type, despite the syntactic similarity. In contrast, the declaration of a generic type (class C<T> ... or interface C<T> ...) declares two entities: a generic type (C<T>) and a corresponding non-generic type (C). In this case, the meaning of the term C depends on the context where it appears:

• If genericity is unimportant, as in the non-generic contexts identified below, the identifier C denotes the non-generic type C.

• If genericity is important, as in all contexts from 6.5 except the non-generic contexts, the identifier C denotes either:

  • The raw type C which is the erasure (4.6) of the generic type C<T>; or

  • A parameterized type which is a particular parameterization (4.5) of the generic type C<T>.

The 14 non-generic contexts are as follows:

1. In a uses or provides directive in a module declaration (7.7.1)

2. In a single-type-import declaration (7.5.1)

3. To the left of the . in a single-static-import declaration (7.5.3)

4. To the left of the . in a static-import-on-demand declaration (7.5.4)

5. To the left of the ( in a constructor declaration (8.8)

6. After the @ sign in an annotation (9.7)

7. To the left of .class in a class literal (15.8.2)

8. To the left of .this in a qualified this expression (15.8.4)

9. To the left of .super in a qualified superclass field access expression (15.11.2)

10. To the left of .Identifier or .super.Identifier in a qualified method invocation expression (15.12)

11. To the left of .super:: in a method reference expression (15.13)

12. In a qualified expression name in a postfix expression or a try-with-resources statement (15.14.1, 14.20.3)

13. In a throws clause of a method or constructor (8.4.6, 8.8.5, 9.4)

14. In an exception parameter declaration (14.20)

The first eleven non-generic contexts correspond to the first eleven syntactic contexts for a TypeName in 6.5.1. The twelfth non-generic context is where a qualified ExpressionName such as C.x may include a TypeName C to denote static member access. The common use of TypeName in these twelve contexts is significant: it indicates that these contexts involve a less-than-first-class use of a type. In contrast, the thirteenth and fourteenth non-generic contexts employ ClassType, indicating that throws and catch clauses use types in a first-class way, in line with, say, field declarations. The characterization of these two contexts as non-generic is due to the fact that an exception type cannot be parameterized.

Note that the ClassType production allows annotations, so it is possible to annotate the use of a type in a throws or catch clause, whereas the TypeName production disallows annotations, so it is not possible to annotate the name of a type in, say, a single-type-import declaration.

Naming Conventions

The class libraries of the Java SE Platform attempt to use, whenever possible, names chosen according to the conventions presented below. These conventions help to make code more readable and avoid certain kinds of name conflicts.

We recommend these conventions for use in all programs written in the Java programming language. However, these conventions should not be followed slavishly if long-held conventional usage dictates otherwise. So, for example, the sin and cos methods of the class java.lang.Math have mathematically conventional names, even though these method names flout the convention suggested here because they are short and are not verbs.

Package Names and Module Names

Developers should take steps to avoid the possibility of two published packages having the same name by choosing unique package names for packages that are widely distributed. This allows packages to be easily and automatically installed and catalogued. This section specifies a suggested convention for generating such unique package names. Implementations of the Java SE Platform are encouraged to provide automatic support for converting a set of packages from local and casual package names to the unique name format described here.

If unique package names are not used, then package name conflicts may arise far from the point of creation of either of the conflicting packages. This may create a situation that is difficult or impossible for the user or programmer to resolve. The classes ClassLoader and ModuleLayer can be used to isolate packages with the same name from each other in those cases where the packages will have constrained interactions, but not in a way that is transparent to a naïve program.

You form a unique package name by first having (or belonging to an organization that has) an Internet domain name, such as oracle.com. You then reverse this name, component by component, to obtain, in this example, com.oracle, and use this as a prefix for your package names, using a convention developed within your organization to further administer package names. Such a convention might specify that certain package name components be division, department, project, machine, or login names.

com.nighthacks.scrabble.dictionary
org.openjdk.compiler.source.tree
net.jcip.annotations
edu.cmu.cs.bovik.cheese
gov.whitehouse.socks.mousefinder

The first component of a unique package name is always written in all-lowercase ASCII letters and should be one of the top level domain names, such as com, edu, gov, mil, net, or org, or one of the English two-letter codes identifying countries as specified in ISO Standard 3166.

In some cases, the Internet domain name may not be a valid package name. Here are some suggested conventions for dealing with these situations:

• If the domain name contains a hyphen, or any other special character not allowed in an identifier (3.8), convert it into an underscore.

• If any of the resulting package name components are keywords (3.9), append an underscore to them.

• If any of the resulting package name components start with a digit, or any other character that is not allowed as an initial character of an identifier, have an underscore prefixed to the component.

The name of a module should correspond to the name of its principal exported package. If a module does not have such a package, or if for legacy reasons it must have a name that does not correspond to one of its exported packages, then its name should still start with the reversed form of an Internet domain with which its author is associated.

com.nighthacks.scrabble
org.openjdk.compiler
net.jcip.annotations

The first component of a package or module name must not be the identifier java. Package and module names that start with the identifier java are reserved for packages and modules of the Java SE Platform.

The name of a package or module is not meant to imply where the package or module is stored on the Internet. For example, a package named edu.cmu.cs.bovik.cheese is not necessarily obtainable from the host cmu.edu or cs.cmu.edu or bovik.cs.cmu.edu. The suggested convention for generating unique package and module names is merely a way to piggyback a package and module naming convention on top of an existing, widely known unique name registry instead of having to create a separate registry for package and module names.

Class and Interface Type Names

Names of class types should be descriptive nouns or noun phrases, not overly long, in mixed case with the first letter of each word capitalized.

`ClassLoader`
SecurityManager
`Thread`
Dictionary
BufferedInputStream

Likewise, names of interface types should be short and descriptive, not overly long, in mixed case with the first letter of each word capitalized. The name may be a descriptive noun or noun phrase, which is appropriate when an interface is used as if it were an abstract superclass, such as interfaces java.io.DataInput and java.io.DataOutput; or it may be an adjective describing a behavior, as for the interfaces Runnable and Cloneable.

Type Variable Names

Type variable names should be pithy (single character if possible) yet evocative, and should not include lower case letters. This makes it easy to distinguish type parameters from ordinary classes and interfaces.

Container types should use the name E for their element type. Maps should use K for the type of their keys and V for the type of their values. The name X should be used for arbitrary exception types. We use T for type, whenever there is not anything more specific about the type to distinguish it. (This is often the case in generic methods.)

If there are multiple type parameters that denote arbitrary types, one should use letters that neighbor T in the alphabet, such as S. Alternately, it is acceptable to use numeric subscripts (e.g., T1, T2) to distinguish among the different type variables. In such cases, all the variables with the same prefix should be subscripted.

If a generic method appears inside a generic class, it is a good idea to avoid using the same names for the type parameters of the method and class, to avoid confusion. The same applies to nested generic classes.

public class HashSet<E> extends AbstractSet<E> { ... }
public class HashMap<K,V> extends AbstractMap<K,V> { ... }
public class ThreadLocal<T> { ... }
public interface Functor<T, X extends Throwable> {
    T eval() throws X;
}

When type parameters do not fall conveniently into one of the categories mentioned, names should be chosen to be as meaningful as possible within the confines of a single letter. The names mentioned above (E, K, V, X, T) should not be used for type parameters that do not fall into the designated categories.

Method Names

Method names should be verbs or verb phrases, in mixed case, with the first letter lowercase and the first letter of any subsequent words capitalized. Here are some additional specific conventions for method names:

• Methods to get and set an attribute that might be thought of as a variable V should be named get*V* and set*V*. An example is the methods getPriority and setPriority of class Thread.

• A method that returns the length of something should be named length, as in class String.

• A method that tests a boolean condition V about an object should be named is*V*. An example is the method isInterrupted of class Thread.

• A method that converts its object to a particular format F should be named to*F*. Examples are the method toString of class Object and the methods toLocaleString and toGMTString of class java.util.Date.

Whenever possible and appropriate, basing the names of methods in a new class on names in an existing class that is similar, especially a class from the Java SE Platform API, will make it easier to use.

Field Names

Names of fields that are not final should be in mixed case with a lowercase first letter and the first letters of subsequent words capitalized. Note that well-designed classes have very few public or protected fields, except for fields that are constants (static final fields).

Fields should have names that are nouns, noun phrases, or abbreviations for nouns.

Examples of this convention are the fields buf, pos, and count of the class java.io.ByteArrayInputStream and the field bytesTransferred of the class java.io.InterruptedIOException.

Constant Names

The names of constants in interface types should be, and final variables of class types may conventionally be, a sequence of one or more words, acronyms, or abbreviations, all uppercase, with components separated by underscore "_" characters. Constant names should be descriptive and not unnecessarily abbreviated. Conventionally they may be any appropriate part of speech.

Examples of names for constants include MIN_VALUE, MAX_VALUE, MIN_RADIX, and MAX_RADIX of the class Character.

A group of constants that represent alternative values of a set, or, less frequently, masking bits in an integer value, are sometimes usefully specified with a common acronym as a name prefix.

For example:

interface ProcessStates {
    int PS_RUNNING   = 0;
    int PS_SUSPENDED = 1;
}

Local Variable and Parameter Names

Local variable and parameter names should be short, yet meaningful. They are often short sequences of lowercase letters that are not words, such as:

• Acronyms, that is the first letter of a series of words, as in cp for a variable holding a reference to a ColoredPoint

• Abbreviations, as in buf holding a pointer to a buffer of some kind

• Mnemonic terms, organized in some way to aid memory and understanding, typically by using a set of local variables with conventional names patterned after the names of parameters to widely used classes. For example:

  • in and out, whenever some kind of input and output are involved, patterned after the fields of System

  • off and len, whenever an offset and length are involved, patterned after the parameters to the read and write methods of the interfaces DataInput and DataOutput of java.io

One-character local variable or parameter names should be avoided, except for temporary and looping variables, or where a variable holds an undistinguished value of a type. Conventional one-character names are:

• b for a byte
• c for a char
• d for a double
• e for an Exception
• f for a float
• i, j, and k for ints
• l for a long
• o for an Object
• s for a String
• v for an arbitrary value of some type

Local variable or parameter names that consist of only two or three lowercase letters should not conflict with the initial country codes and domain names that are the first component of unique package names.

Chapter 7: Packages and Modules

7.5 Import Declarations

7.5.1 Single-Type-Import Declarations

A single-type-import declaration imports a single type by giving its canonical name, making it available under a simple name in the module, class, and interface declarations of the compilation unit in which the single-type-import declaration appears.

SingleTypeImportDeclaration:

import TypeName ;

The TypeName must be the canonical name of a class type, interface type, enum type, record type, or annotation type (6.7).

The type must be either a member of a named package, or a member of a type whose outermost lexically enclosing type declaration (8.1.3) is a member of a named package, or a compile-time error occurs.

It is a compile-time error if the named type is not accessible (6.6).

If two single-type-import declarations in the same compilation unit attempt to import types with the same simple name, then a compile-time error occurs, unless the two types are the same type, in which case the duplicate declaration is ignored.

If the type imported by the single-type-import declaration is declared in the compilation unit that contains the import declaration, the import declaration is ignored.

If a single-type-import declaration imports a type whose simple name is n, and the compilation unit also declares a top level type (7.6) whose simple name is n, a compile-time error occurs.

If a compilation unit contains both a single-type-import declaration that imports a type whose simple name is n, and a single-static-import declaration (7.5.3) that imports a type whose simple name is n, a compile-time error occurs, unless the two types are the same type, in which case the duplicate declaration is ignored.

import java.util.Vector;

import java.util.Vector;
class Vector { Object[] vec; }

import java.util.Vector;
import myVector.Vector;

package myVector;
public class Vector { Object[] vec; }

import java.util;
class Test { util.Random generator; }
  // incorrect: compile-time error

package Vector;
public class Mosquito { int capacity; }

package strange;
import java.util.Vector;
import Vector.Mosquito;
class Test {
    public static void main(String[] args) {
        System.out.println(new Vector().getClass());
        System.out.println(new Mosquito().getClass());
    }
}

class java.util.Vector
class Vector.Mosquito

7.5.2 Type-Import-on-Demand Declarations

A type-import-on-demand declaration allows all accessible types of a named package or type to be imported as needed.

TypeImportOnDemandDeclaration:

import PackageOrTypeName . * ;

The PackageOrTypeName must be the canonical name (6.7) of a package, a class type, an interface type, an enum type, a record type, or an annotation type.

If the PackageOrTypeName denotes a type (6.5.4), then the type must be either a member of a named package, or a member of a type whose outermost lexically enclosing type declaration (8.1.3) is a member of a named package, or a compile-time error occurs.

It is a compile-time error if the named package is not uniquely visible to the current module (7.4.3), or if the named type is not accessible (6.6).

It is not a compile-time error to name either java.lang or the named package of the current compilation unit in a type-import-on-demand declaration. The type-import-on-demand declaration is ignored in such cases.

Two or more type-import-on-demand declarations in the same compilation unit may name the same type or package. All but one of these declarations are considered redundant; the effect is as if that type was imported only once.

If a compilation unit contains both a type-import-on-demand declaration and a static-import-on-demand declaration (7.5.4) that name the same type, the effect is as if the static member types of that type (8.5, 9.5) were imported only once.

import java.util.*;

7.5.3 Single-Static-Import Declarations

A single-static-import declaration imports all accessible static members with a given simple name from a type. This makes these static members available under their simple name in the module, class, and interface declarations of the compilation unit in which the single-static-import declaration appears.

SingleStaticImportDeclaration:

import static TypeName . Identifier ;

The TypeName must be the canonical name (6.7) of a class type, interface type, enum type, record type, or annotation type.

The type must be either a member of a named package, or a member of a type whose outermost lexically enclosing type declaration (8.1.3) is a member of a named package, or a compile-time error occurs.

It is a compile-time error if the named type is not accessible (6.6).

The Identifier must name at least one static member of the named type. It is a compile-time error if there is no static member of that name, or if all of the named members are not accessible.

It is permissible for one single-static-import declaration to import several fields or types with the same name, or several methods with the same name and signature. This occurs when the named type inherits multiple fields, member types, or methods, all with the same name, from its own supertypes.

If two single-static-import declarations in the same compilation unit attempt to import types with the same simple name, then a compile-time error occurs, unless the two types are the same type, in which case the duplicate declaration is ignored.

If a single-static-import declaration imports a type whose simple name is n, and the compilation unit also declares a top level type (7.6) whose simple name is n, a compile-time error occurs.

If a compilation unit contains both a single-static-import declaration that imports a type whose simple name is n, and a single-type-import declaration (7.5.1) that imports a type whose simple name is n, a compile-time error occurs, unless the two types are the same type, in which case the duplicate declaration is ignored.

7.5.4 Static-Import-on-Demand Declarations

A static-import-on-demand declaration allows all accessible static members of a named type to be imported as needed.

StaticImportOnDemandDeclaration:

import static TypeName . * ;

The TypeName must be the canonical name (6.7) of a class type, interface type, enum type, record type, or annotation type.

The type must be either a member of a named package, or a member of a type whose outermost lexically enclosing type declaration (8.1.3) is a member of a named package, or a compile-time error occurs.

It is a compile-time error if the named type is not accessible (6.6).

Two or more static-import-on-demand declarations in the same compilation unit may name the same type; the effect is as if there was exactly one such declaration.

Two or more static-import-on-demand declarations in the same compilation unit may name the same member; the effect is as if the member was imported exactly once.

It is permissible for one static-import-on-demand declaration to import several fields or types with the same name, or several methods with the same name and signature. This occurs when the named type inherits multiple fields, member types, or methods, all with the same name, from its own supertypes.

If a compilation unit contains both a static-import-on-demand declaration and a type-import-on-demand declaration (7.5.2) that name the same type, the effect is as if the static member types of that type (8.5, 9.5) were imported only once.

Chapter 8: Classes

8.1 Class Declarations

A class declaration specifies a new named reference type.

There are two three kinds of class declarations: normal class declarations, and enum declarations and record declarations.

ClassDeclaration:

NormalClassDeclaration

EnumDeclaration

RecordDeclaration

NormalClassDeclaration:

{ClassModifier} class TypeIdentifier [TypeParameters]
[Superclass] [Superinterfaces] ClassBody

The rules in this section apply to all class declarations, including enum declarations and record declarations. However, special rules apply to enum declarations and record declarations with regard to class modifiers, inner classes, and superclasses; these rules are stated in 8.9 and 8.10.

The TypeIdentifier in a class declaration specifies the name of the class.

It is a compile-time error if a class has the same simple name as any of its enclosing classes or interfaces.

The scope and shadowing of a class declaration is specified in 6.3 and 6.4.

8.1.4 Superclasses and Subclasses

The optional extends clause in a normal class declaration specifies the direct superclass of the current class.

Superclass:

extends ClassType

The extends clause must not appear in the definition of the class Object, or a compile-time error occurs, because it is the primordial class and has no direct superclass.

The ClassType must name an accessible class type (6.6), or a compile-time error occurs.

It is a compile-time error if the ClassType names a class that is final, because final classes are not allowed to have subclasses (8.1.1.2).

It is a compile-time error if the ClassType names the class Enum or any invocation of Enum (8.9).

It is a compile-time error if the ClassType names the class Record (8.10).

If the ClassType has type arguments, it must denote a well-formed parameterized type (4.5), and none of the type arguments may be wildcard type arguments, or a compile-time error occurs.

Given a (possibly generic) class declaration C<F₁,...,F_n> (n ≥ 0, C ≠ Object), the direct superclass of the class type C<F₁,...,F_n> is the type given in the extends clause of the declaration of C if an extends clause is present, or Object otherwise.

Given a generic class declaration C<F₁,...,F_n> (n > 0), the direct superclass of the parameterized class type C<T₁,...,T_n>, where T_i (1 ≤ i ≤ n) is a type, is D<U₁ θ,...,U_k θ>, where D<U₁,...,U_k> is the direct superclass of C<F₁,...,F_n> and θ is the substitution [*F~1~*:=*T~1~*,...,*F~n~*:=*T~n~*].

A class is said to be a direct subclass of its direct superclass. The direct superclass is the class from whose implementation the implementation of the current class is derived.

The subclass relationship is the transitive closure of the direct subclass relationship. A class A is a subclass of class C if either of the following is true:

• A is the direct subclass of C

• There exists a class B such that A is a subclass of B, and B is a subclass of C, applying this definition recursively.

Class C is said to be a superclass of class A whenever A is a subclass of C.

class Point { int x, y; }
final class ColoredPoint extends Point { int color; }
class Colored3DPoint extends ColoredPoint { int z; }  // error

class Point { int x, y; }
class ColoredPoint extends Point { int color; }
final class Colored3dPoint extends ColoredPoint { int z; }

A class C directly depends on a type T if T is mentioned in the extends or implements clause of C either as a superclass or superinterface, or as a qualifier in the fully qualified form of a superclass or superinterface name.

A class C depends on a reference type T if any of the following is true:

• C directly depends on T.

• C directly depends on an interface I that depends (9.1.3) on T.

• C directly depends on a class D that depends on T (using this definition recursively).

It is a compile-time error if a class depends on itself.

If circularly declared classes are detected at run time, as classes are loaded, then a ClassCircularityError is thrown (12.2.1).

class Point extends ColoredPoint { int x, y; }
class ColoredPoint extends Point { int color; }

8.8 Constructor Declarations

A constructor is used in the creation of an object that is an instance of a class (12.5, 15.9).

ConstructorDeclaration:

{ConstructorModifier} ConstructorDeclarator [Throws] ConstructorBody

ConstructorDeclarator:

[TypeParameters] SimpleTypeName
( [ReceiverParameter ,] [FormalParameterList] )

SimpleTypeName:

TypeIdentifier

The rules in this section apply to constructors in all class declarations, including enum declarations and record declarations. However, special rules apply to enum declarations with regard to constructor modifiers, constructor bodies, and default constructors; these rules are stated in 8.9.2. Special rules also apply to record declarations with regard to constructors, including a special compact declaration form; the details are given in 8.10.4.

The SimpleTypeName in the ConstructorDeclarator must be the simple name of the class that contains the constructor declaration, or a compile-time error occurs.

In all other respects, a constructor declaration looks just like a method declaration that has no result (8.4.5).

Constructor declarations are not members. They are never inherited and therefore are not subject to hiding or overriding.

Constructors are invoked by class instance creation expressions (15.9), by the conversions and concatenations caused by the string concatenation operator + (15.18.1), and by explicit constructor invocations from other constructors (8.8.7). Access to constructors is governed by access modifiers (6.6), so it is possible to prevent class instantiation by declaring an inaccessible constructor (8.8.10).

Constructors are never invoked by method invocation expressions (15.12).

class Point {
    int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
}

8.10 Record Types

8.10.1 Record Header

8.10.2 Record Bodies

8.10.3 Record Members

8.10.4 Record Constructor Declarations

record NonNegativePoint(int i, int j) {
  public NonNegativePoint {
    if ( i < 0 )
      i = Math.abs(i);
    if ( j < 0 )
      j = Math.abs(j);
  }
}

record NonNullName(String firstName, String secondName) {
  public NonNullName {
    if ( firstName == null || secondName == null ) 
      throw new IllegalArgumentException();
  }
}

record R(int i, String s) {
    public R {
        this.i = i;
        this.s = s; 
    }
}

record R(int i, String s) {
    public R(int i, String s) { 
        this.i = i;
        this.s = s;
    }
}

record R(int i, String s) {
    public R { 
        if ( i < 0 ) 
            i = Math.abs(i);
    }
}

record R(int i, String s) {
    public R(int i, String s) { 
        if ( i < 0 ) 
            i = Math.abs(i);
        this.i = i;
        this.s = s;
    }
}

record R(int i, int j) {}

record R(int i, int j) {
  public R {}
}

record R(int i, int j) {
  public R(int i, int j) {
    this.i = i;
    this.j = j;
  }
}

Chapter 9: Interfaces

9.6 Annotation Types

9.6.4 Predefined Annotation Types

9.6.4.1 @Target

An annotation of type java.lang.annotation.Target is used on the declaration of an annotation type T to specify the contexts in which T is applicable. java.lang.annotation.Target has a single element, value, of type java.lang.annotation.ElementType[], to specify contexts.

Annotation types may be applicable in declaration contexts, where annotations apply to declarations, or in type contexts, where annotations apply to types used in declarations and expressions.

There are nine ten declaration contexts, each corresponding to an enum constant of java.lang.annotation.ElementType:

1. Module declarations (7.7)

   Corresponds to java.lang.annotation.ElementType.MODULE

2. Package declarations (7.4.1)

   Corresponds to java.lang.annotation.ElementType.PACKAGE

3. Type declarations: class, interface, enum, record, and annotation type declarations (8.1.1, 9.1.1, 8.5, 9.5, 8.9, 8.10, 9.6)

   Corresponds to java.lang.annotation.ElementType.TYPE

   Additionally, annotation type declarations correspond to java.lang.annotation.ElementType.ANNOTATION_TYPE

4. Method declarations (including elements of annotation types) (8.4.3, 9.4, 9.6.1)

   Corresponds to java.lang.annotation.ElementType.METHOD

5. Constructor declarations (8.8.3)

   Corresponds to java.lang.annotation.ElementType.CONSTRUCTOR

6. Type parameter declarations of generic classes, interfaces, methods, and constructors (8.1.2, 9.1.2, 8.4.4, 8.8.4)

   Corresponds to java.lang.annotation.ElementType.TYPE_PARAMETER

7. Field declarations (including enum constants) (8.3.1, 9.3, 8.9.1)

   Corresponds to java.lang.annotation.ElementType.FIELD

8. Formal and exception parameter declarations (8.4.1, 9.4, 14.20)

   Corresponds to java.lang.annotation.ElementType.PARAMETER

9. Local variable declarations (including loop variables of for statements and resource variables of try-with-resources statements) (14.4, 14.14.1, 14.14.2, 14.20.3)

   Corresponds to java.lang.annotation.ElementType.LOCAL_VARIABLE

10. Record component declarations (8.10.1)

    Corresponds to java.lang.annotation.ElementType.RECORD_COMPONENT

There are 16 type contexts (4.11), all represented by the enum constant TYPE_USE of java.lang.annotation.ElementType.

It is a compile-time error if the same enum constant appears more than once in the value element of an annotation of type java.lang.annotation.Target.

If an annotation of type java.lang.annotation.Target is not present on the declaration of an annotation type T, then T is applicable in all declaration contexts except type parameter declarations, and in no type contexts.

These contexts are the syntactic locations where annotations were allowed in Java SE 7.

9.7 Annotations

9.7.4 Where Annotations May Appear

A declaration annotation is an annotation that applies to a declaration, and whose own type is applicable in the declaration context (9.6.4.1) represented by that declaration; or an annotation that applies to a class, interface, enum, record, annotation type, or type parameter declaration, and whose own type is applicable in type contexts (4.11).

A type annotation is an annotation that applies to a type (or any part of a type), and whose own type is applicable in type contexts.

For example, given the field declaration:

@Foo int f;

@Foo is a declaration annotation on f if Foo is meta-annotated by @Target(ElementType.FIELD), and a type annotation on int if Foo is meta-annotated by @Target(ElementType.TYPE_USE). It is possible for @Foo to be both a declaration annotation and a type annotation simultaneously.

Type annotations can apply to an array type or any component type thereof (10.1). For example, assuming that A, B, and C are annotation types meta-annotated with @Target(ElementType.TYPE_USE), then given the field declaration:

@C int @A [] @B [] f;

@A applies to the array type int[][], @B applies to its component type int[], and @C applies to the element type int. For more examples, see 10.2.

An important property of this syntax is that, in two declarations that differ only in the number of array levels, the annotations to the left of the type refer to the same type. For example, @C applies to the type int in all of the following declarations:

@C int f;
@C int[] f;
@C int[][] f;

It is customary, though not required, to write declaration annotations before all other modifiers, and type annotations immediately before the type to which they apply.

It is possible for an annotation to appear at a syntactic location in a program where it could plausibly apply to a declaration, or a type, or both. This can happen in any of the five six declaration contexts where modifiers immediately precede the type of the declared entity:

• Method declarations (including elements of annotation types)

• Constructor declarations

• Field declarations (including enum constants)

• Formal and exception parameter declarations

• Local variable declarations (including loop variables of for statements and resource variables of try-with-resources statements)

• Record component declarations

The grammar of the Java programming language unambiguously treats annotations at these locations as modifiers for a declaration (8.3), but that is purely a syntactic matter. Whether an annotation applies to the declaration or to the type of the declared entity - and thus, whether the annotation is a declaration annotation or a type annotation - depends on the applicability of the annotation's type:

• If the annotation's type is applicable in the declaration context corresponding to the declaration, and not in type contexts, then the annotation is deemed to apply only to the declaration.

• If the annotation's type is applicable in type contexts, and not in the declaration context corresponding to the declaration, then the annotation is deemed to apply only to the type which is closest to the annotation.

• If the annotation's type is applicable in the declaration context corresponding to the declaration and in type contexts, then the annotation is deemed to apply to both the declaration and the type which is closest to the annotation.

In the second and third cases above, the type which is closest to the annotation is determined as follows:

• If the annotation appears before a void method declaration or a local variable declaration that uses var (14.4, 14.14.2, 14.20.3), then there is no closest type. If the annotation's type is deemed to apply only to the type which is closest to the annotation, a compile-time error occurs.

• If the annotation appears before a constructor declaration, then the closest type is the type of the newly constructed object. The type of the newly constructed object is the fully qualified name of the type immediately enclosing the constructor declaration. Within that fully qualified name, the annotation applies to the simple type name indicated by the constructor declaration.

• In all other cases, the closest type is the type written in source code for the declared entity; if that type is an array type, then the element type is deemed to be closest to the annotation.

  For example, in the field declaration @Foo public static String f;, the type which is closest to @Foo is String. (If the type of the field declaration had been written as java.lang.String, then java.lang.String would be the type closest to @Foo, and later rules would prohibit a type annotation from applying to the package name java.) In the generic method declaration @Foo <T> int[] m() {...}, the type written for the declared entity is int[], so @Foo applies to the element type int.

  Local variable declarations which do not use var are similar to formal parameter declarations of lambda expressions, in that both allow declaration annotations and type annotations in source code, but only the type annotations can be stored in the class file.

It is a compile-time error if an annotation of type T is syntactically a modifier for:

• a module declaration, but T is not applicable to module declarations.

• a package declaration, but T is not applicable to package declarations.

• a class, interface, or enum, or record declaration, but T is not applicable to type declarations or type contexts; or an annotation type declaration, but T is not applicable to annotation type declarations or type declarations or type contexts.

• a method declaration (including an element of an annotation type), but T is not applicable to method declarations or type contexts.

• a constructor declaration, but T is not applicable to constructor declarations or type contexts.

• a type parameter declaration of a generic class, interface, method, or constructor, but T is not applicable to type parameter declarations or type contexts.

• a field declaration (including an enum constant), but T is not applicable to field declarations or type contexts.

• a formal or exception parameter declaration, but T is not applicable to either formal and exception parameter declarations or type contexts.

• a receiver parameter, but T is not applicable to type contexts.

• a local variable declaration (including a loop variable of a for statement or a resource variable of a try-with-resources statement), but T is not applicable to local variable declarations or type contexts.

• a record component but T is not applicable to record component declarations, type contexts, type parameter declarations, field declarations, or method declarations.

Five Six of these nine clauses mention "... or type contexts" because they characterize the five six syntactic locations where an annotation could plausibly apply either to a declaration or to the type of a declared entity. Furthermore, two of the nine clauses - for class, interface, enum, record, and annotation type declarations, and for type parameter declarations - mention "... or type contexts" because it may be convenient to apply an annotation whose type is meta-annotated with @Target(ElementType.TYPE_USE) (thus, applicable in type contexts) to a type declaration.

A type annotation is admissible if both of the following are true:

• The simple name to which the annotation is closest is classified as a TypeName, not a PackageName.

• If the simple name to which the annotation is closest is followed by "." and another TypeName - that is, the annotation appears as @Foo T.U - then U denotes an inner class of T.

The intuition behind the second clause is that if Outer.this is legal in a nested class enclosed by Outer, then Outer may be annotated because it represents the type of some object at run time. On the other hand, if Outer.this is not legal - because the class where it appears has no enclosing instance of Outer at run time - then Outer may not be annotated because it is logically just a name, akin to components of a package name in a fully qualified type name.

For example, in the following program, it is not possible to write A.this in the body of B, as B has no lexically enclosing instances (8.5.1). Therefore, it is not possible to apply @Foo to A in the type A.B, because A is logically just a name, not a type.

@Target(ElementType.TYPE_USE)
@interface Foo {}

class Test {
  class A {
    static class B {}
  }

  @Foo A.B x;  // Illegal 
}

On the other hand, in the following program, it is possible to write C.this in the body of D. Therefore, it is possible to apply @Foo to C in the type C.D, because C represents the type of some object at run time.

@Target(ElementType.TYPE_USE)
@interface Foo {}

class Test {
  static class C {
    class D {}
  }

  @Foo C.D x;  // Legal 
}

Finally, note that the second clause looks only one level deeper in a qualified type. This is because a static class may only be nested in a top level class or another static nested class. It is not possible to write a nest like:

@Target(ElementType.TYPE_USE)
@interface Foo {}

class Test {
  class E {
    class F {
      static class G {}
    }
  }

  @Foo E.F.G x;
}

Assume for a moment that the nest was legal. In the type of field x, E and F would logically be names qualifying G, as E.F.this would be illegal in the body of G. Then, @Foo should not be legal next to E. Technically, however, @Foo would be admissible next to E because the next deepest term F denotes an inner class; but this is moot as the class nest is illegal in the first place.

It is a compile-time error if an annotation of type T applies to the outermost level of a type in a type context, and T is not applicable in type contexts or the declaration context (if any) which occupies the same syntactic location.

It is a compile-time error if an annotation of type T applies to a part of a type (that is, not the outermost level) in a type context, and T is not applicable in type contexts.

It is a compile-time error if an annotation of type T applies to a type (or any part of a type) in a type context, and T is applicable in type contexts, and the annotation is not admissible.

For example, assume an annotation type TA which is meta-annotated with just @Target(ElementType.TYPE_USE). The terms @TA java.lang.Object and java.@TA lang.Object are illegal because the simple name to which @TA is closest is classified as a package name. On the other hand, java.lang.@TA Object is legal.

Note that the illegal terms are illegal "everywhere". The ban on annotating package names applies broadly: to locations which are solely type contexts, such as class ... extends @TA java.lang.Object {...}, and to locations which are both declaration and type contexts, such as @TA java.lang.Object f;. (There are no locations which are solely declaration contexts where a package name could be annotated, as class, package, and type parameter declarations use only simple names.)

If TA is additionally meta-annotated with @Target(ElementType.FIELD), then the term @TA java.lang.Object is legal in locations which are both declaration and type contexts, such as a field declaration @TA java.lang.Object f;. Here, @TA is deemed to apply to the declaration of f (and not to the type java.lang.Object) because TA is applicable in the field declaration context.

Chapter 13: Binary Compatibility

13.1 The Form of a Binary

Programs must be compiled either into the class file format specified by The Java Virtual Machine Specification, Java SE 13 Edition, or into a representation that can be mapped into that format by a class loader written in the Java programming language.

A class file corresponding to a class or interface declaration must have certain properties. A number of these properties are specifically chosen to support source code transformations that preserve binary compatibility. The required properties are:

1. The class or interface must be named by its binary name, which must meet the following constraints:

   • The binary name of a top level type (7.6) is its canonical name (6.7).

   • The binary name of a member type (8.5, 9.5) consists of the binary name of its immediately enclosing type, followed by $, followed by the simple name of the member.

   • The binary name of a local class (14.3) consists of the binary name of its immediately enclosing type, followed by $, followed by a non-empty sequence of digits, followed by the simple name of the local class.

   • The binary name of an anonymous class (15.9.5) consists of the binary name of its immediately enclosing type, followed by $, followed by a non-empty sequence of digits.

   • The binary name of a type variable declared by a generic class or interface (8.1.2, 9.1.2) is the binary name of its immediately enclosing type, followed by $, followed by the simple name of the type variable.

   • The binary name of a type variable declared by a generic method (8.4.4) is the binary name of the type declaring the method, followed by $, followed by the descriptor of the method (JVMS §4.3.3), followed by $, followed by the simple name of the type variable.

   • The binary name of a type variable declared by a generic constructor (8.8.4) is the binary name of the type declaring the constructor, followed by $, followed by the descriptor of the constructor (JVMS §4.3.3), followed by $, followed by the simple name of the type variable.

2. A reference to another class or interface type must be symbolic, using the binary name of the type.

3. A reference to a field that is a constant variable (4.12.4) must be resolved at compile time to the value V denoted by the constant variable's initializer.

   If such a field is static, then no reference to the field should be present in the code in a binary file, including the class or interface which declared the field. Such a field must always appear to have been initialized (12.4.2); the default initial value for the field (if different than V) must never be observed.

   If such a field is non-static, then no reference to the field should be present in the code in a binary file, except in the class containing the field. (It will be a class rather than an interface, since an interface has only static fields.) The class should have code to set the field's value to V during instance creation (12.5).

4. Given a legal expression denoting a field access in a class C, referencing a field named f that is not a constant variable and is declared in a (possibly distinct) class or interface D, we define the qualifying type of the field reference as follows:

   • If the expression is referenced by a simple name, then if f is a member of the current class or interface, C, then let T be C. Otherwise, let T be the innermost lexically enclosing type declaration of which f is a member. In either case, T is the qualifying type of the reference.

   • If the reference is of the form TypeName.f, where TypeName denotes a class or interface, then the class or interface denoted by TypeName is the qualifying type of the reference.

   • If the expression is of the form ExpressionName.f or Primary.f, then:

     • If the compile-time type of ExpressionName or Primary is an intersection type V₁ & ... & V_n (4.9), then the qualifying type of the reference is V₁.

     • Otherwise, the compile-time type of ExpressionName or Primary is the qualifying type of the reference.

   • If the expression is of the form super.f, then the superclass of C is the qualifying type of the reference.

   • If the expression is of the form TypeName.super.f, then the superclass of the class denoted by TypeName is the qualifying type of the reference.

   The reference to f must be compiled into a symbolic reference to the erasure (4.6) of the qualifying type of the reference, plus the simple name of the field, f. The reference must also include a symbolic reference to the erasure of the declared type of the field so that the verifier can check that the type is as expected.

5. Given a method invocation expression or a method reference expression in a class or interface C, referencing a method named m declared (or implicitly declared (9.2)) in a (possibly distinct) class or interface D, we define the qualifying type of the method invocation as follows:

   • If D is Object then the qualifying type of the expression is Object.

   • Otherwise:

     • If the method is referenced by a simple name, then if m is a member of the current class or interface C, let T be C; otherwise, let T be the innermost lexically enclosing type declaration of which m is a member. In either case, T is the qualifying type of the method invocation.

     • If the expression is of the form TypeName.m or ReferenceType::m, then the type denoted by TypeName or ReferenceType is the qualifying type of the method invocation.

     • If the expression is of the form ExpressionName.m or Primary.m or ExpressionName::m or Primary::m, then:

       • If the compile-time type of ExpressionName or Primary is an intersection type V₁ & ... & V_n (4.9), then the qualifying type of the method invocation is V₁.

       • Otherwise, the compile-time type of ExpressionName or Primary is the qualifying type of the method invocation.

     • If the expression is of the form super.m or super::m, then the superclass of C is the qualifying type of the method invocation.

     • If the expression is of the form TypeName.super.m or TypeName.super::m, then if TypeName denotes a class X, the superclass of X is the qualifying type of the method invocation; if TypeName denotes an interface X, X is the qualifying type of the method invocation.

   A reference to a method must be resolved at compile time to a symbolic reference to the erasure (4.6) of the qualifying type of the invocation, plus the erasure of the signature (8.4.2) of the method. The signature of a method must include all of the following as determined by 15.12.3:

   • The simple name of the method

   • The number of parameters to the method

   • A symbolic reference to the type of each parameter

   A reference to a method must also include either a symbolic reference to the erasure of the return type of the denoted method or an indication that the denoted method is declared void and does not return a value.

6. Given a class instance creation expression (15.9) or an explicit constructor invocation statement (8.8.7.1) or a method reference expression of the form ClassType :: new (15.13) in a class or interface C referencing a constructor m declared in a (possibly distinct) class or interface D, we define the qualifying type of the constructor invocation as follows:

   • If the expression is of the form new D(...) or ExpressionName.new D(...) or Primary.new D(...) or D :: new, then the qualifying type of the invocation is D.

   • If the expression is of the form new D(...){...} or ExpressionName.new D(...){...} or Primary.new D(...){...}, then the qualifying type of the expression is the compile-time type of the expression.

   • If the expression is of the form super(...) or ExpressionName.super(...) or Primary.super(...), then the qualifying type of the expression is the direct superclass of C.

   • If the expression is of the form this(...), then the qualifying type of the expression is C.

   A reference to a constructor must be resolved at compile time to a symbolic reference to the erasure (4.6) of the qualifying type of the invocation, plus the signature of the constructor (8.8.2). The signature of a constructor must include both:

   • The number of parameters of the constructor

   • A symbolic reference to the type of each formal parameter

A binary representation for a class or interface must also contain all of the following:

1. If it is a class and is not Object, then a symbolic reference to the erasure of the direct superclass of this class.

2. A symbolic reference to the erasure of each direct superinterface, if any.

3. A specification of each field declared in the class or interface, given as the simple name of the field and a symbolic reference to the erasure of the type of the field.

4. If it is a class, then the erased signature of each constructor, as described above.

5. For each method declared in the class or interface (excluding, for an interface, its implicitly declared methods (9.2)), its erased signature and return type, as described above.

6. The code needed to implement the class or interface:

   • For an interface, code for the field initializers and the implementation of each method with a block body (9.4.3).

   • For a class, code for the field initializers, the instance and static initializers, the implementation of each method with a block body (8.4.7), and the implementation of each constructor.

7. Every type must contain sufficient information to recover its canonical name (6.7).

8. Every member type must have sufficient information to recover its source-level access modifier.

9. Every nested class and nested interface must have a symbolic reference to its immediately enclosing type (8.1.3).

10. Every class must contain symbolic references to all of its member types (8.5), and to all local and anonymous classes that appear in its methods, constructors, static initializers, instance initializers, and field initializers.

    Every interface must contain symbolic references to all of its member types (9.5), and to all local and anonymous classes that appear in its default methods and field initializers.

11. A construct emitted by a Java compiler must be marked as synthetic if it does not correspond to a construct declared explicitly or implicitly in source code, unless the emitted construct is a class initialization method (JVMS §2.9).

12. A construct emitted by a Java compiler must be marked as mandated if it corresponds to a formal parameter declared implicitly in source code (8.8.1, 8.8.9, 8.9.3, 15.9.5.1).

The following formal parameters are declared implicitly in source code:

• The first formal parameter of a constructor of a non-private inner member class (8.8.1, 8.8.9).

• The first formal parameter of an anonymous constructor of an anonymous class whose superclass is inner or local (not in a static context) (15.9.5.1).

• The formal parameter name of the valueOf method which is implicitly declared in an enum type (8.9.3).

• The formal parameters of a compact constructor of a record type ( 8.10.4).

For reference, the following constructs are declared implicitly in source code, but are not marked as mandated because only formal parameters can be so marked in a class file (JVMS §4.7.24):

• Default constructors of classes and enum types (8.8.9, 8.9.2)

• Canonical constructors of record types (8.10.4)

• Anonymous constructors (15.9.5.1)

• The values and valueOf methods of enum types (8.9.3)

• Certain public fields of enum types (8.9.3)

• Certain private fields and public methods of record types ( 8.10.3)

• Certain public methods of interfaces (9.2)

• Container annotations (9.7.5)

A class file corresponding to a module declaration must have the properties of a class file for a class whose binary name is module-info and which has no superclass, no superinterfaces, no fields, and no methods. In addition, the binary representation of the module must contain all of the following:

• A specification of the name of the module, given as a symbolic reference to the name indicated after module. Also, the specification must include whether the module is normal or open (7.7).

• A specification of each dependence denoted by a requires directive, given as a symbolic reference to the name of the module indicated by the directive (7.7.1). Also, the specification must include whether the dependence is transitive and whether the dependence is static.

• A specification of each package denoted by an exports or opens directive, given as a symbolic reference to the name of the package indicated by the directive (7.7.2). Also, if the directive was qualified, the specification must give symbolic references to the names of the modules indicated by the directive's to clause.

• A specification of each service denoted by a uses directive, given as a symbolic reference to the name of the type indicated by the directive (7.7.3).

• A specification of the service providers denoted by a provides directive, given as symbolic references to the names of the types indicated by the directive's with clause (7.7.4). Also, the specification must give a symbolic reference to the name of the type indicated as the service by the directive.

The following sections discuss changes that may be made to class and interface type declarations without breaking compatibility with pre-existing binaries. Under the translation requirements given above, the Java Virtual Machine and its class file format support these changes. Any other valid binary format, such as a compressed or encrypted representation that is mapped back into class files by a class loader under the above requirements, will necessarily support these changes as well.

13.4 Evolution of Classes

13.4.27 Evolution of Records