Consistent Class and Interface Terminology

This document describes changes to the Java Language Specification to clarify the usage of terms related to classes and interfaces, and more clearly distinguish them from types.

The following terminology is preferred: a class or interface declaration is a syntactic structure that introduces a class or an interface. Various class and interface declarations have different syntactic forms, and can appear in different contexts, per the grammar. A class type or an interface type is variable or expression type, derived from a class or an interface; these terms should be avoided when talking about the declaration. An enum declaration is a kind of class declaration that introduces a special kind of class, an enum class. An annotation declaration is a kind of interface declaration that introduces a special kind of interface, an annotation interface.

Changes are described with respect to existing sections of the Java Language 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 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 enum classes, support the definition of small sets of values and their manipulation in a type safe manner. Unlike enumerations in other languages, enums enum constants are objects and may have their own methods.

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 interfaces 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 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), 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) formal parameter, exception parameter, 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 class or interface, 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) or an enum declaration (8.9)

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

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

    Enum constants are not members—they introduce implicit fields, which are members.

  • A field, one of the following:

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

    • 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 (8.4, 8.9.2)

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

• An enum constant (8.9.1)

• A parameter, one of the following:

  • A formal parameter of a method or constructor of a class type or enum type (8.4.1, 8.8.1, 8.9.2), 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 formal parameter of a method of a class or interface (8.4.1), a constructor of a class (8.8.1), or a lambda expression (15.27.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)

• A local class (14.3)

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.

...

6.3 Scope of a Declaration

The scope of a declaration is the region of the program within which the entity declared by the declaration can be referred to using a simple name, provided it is not shadowed (6.4.1).

A declaration is said to be in scope at a particular point in a program if and only if the declaration's scope includes that point.

The scope of the declaration of an observable top level package (7.4.3) is all observable compilation units associated with modules to which the package is uniquely visible (7.4.3).

The declaration of a package that is not observable is never in scope.

The declaration of a subpackage is never in scope.

The package java is always in scope.

The scope of a type class or interface imported by a single-type-import declaration (7.5.1) or a type-import-on-demand declaration (7.5.2) is the module declaration (7.7) and all the class and interface type declarations (7.6) of the compilation unit in which the import declaration appears, as well as any annotations on the module declaration or package declaration of the compilation unit.

The scope of a member imported by a single-static-import declaration (7.5.3) or a static-import-on-demand declaration (7.5.4) is the module declaration and all the class and interface type declarations of the compilation unit in which the import declaration appears, as well as any annotations on the module declaration or package declaration of the compilation unit.

The scope of a top level type class or interface (7.6) is all type class and interface declarations in the package in which the top level type class or interface is declared.

The scope of a declaration of a member m declared in or inherited by a class type or interface C (8.1.6 8.2, 9.2) is the entire body of C, including any nested type class or interface declarations.

The scope of a declaration of a member m declared in or inherited by an interface type I (9.1.4) is the entire body of I, including any nested type declarations.

The scope of an enum constant C declared in an enum type T is the body of T, and any case label of a switch statement whose expression is of enum type T (14.11).

The scope of a formal parameter of a method (8.4.1), constructor (8.8.1), or lambda expression (15.27) is the entire body of the method, constructor, or lambda expression.

The scope of a class's type parameter (8.1.2) is the type parameter section of the class declaration, the type parameter section of any superclass or superinterface of the class declaration, and the class body.

The scope of an interface's type parameter (9.1.2) is the type parameter section of the interface declaration, the type parameter section of any superinterface of the interface declaration, and the interface body.

The scope of a method's type parameter (8.4.4) is the entire declaration of the method, including the type parameter section, but excluding the method modifiers.

The scope of a constructor's type parameter (8.8.4) is the entire declaration of the constructor, including the type parameter section, but excluding the constructor modifiers.

The scope of a local class declaration immediately enclosed by a block (14.2) is the rest of the immediately enclosing block, including its own class declaration.

The scope of a local class declaration immediately enclosed by a switch block statement group (14.11) is the rest of the immediately enclosing switch block statement group, including its own class declaration.

The scope of a local variable declaration in a block (14.4) is the rest of the block in which the declaration appears, starting with its own initializer and including any further declarators to the right in the local variable declaration statement.

The scope of a local variable declared in the ForInit part of a basic for statement (14.14.1) includes all of the following:

• Its own initializer

• Any further declarators to the right in the ForInit part of the for statement

• The Expression and ForUpdate parts of the for statement

• The contained Statement

The scope of a local variable declared in the FormalParameter part of an enhanced for statement (14.14.2) is the contained Statement.

The scope of a parameter of an exception handler that is declared in a catch clause of a try statement (14.20) is the entire block associated with the catch.

The scope of a variable declared in the ResourceSpecification of a try-with-resources statement (14.20.3) is from the declaration rightward over the remainder of the ResourceSpecification and the entire try block associated with the try-with-resources statement.

The translation of a try-with-resources statement implies the rule above.

package points;
class Point {
    int x, y;
    PointList list;
    Point next;
}

class PointList {
    Point first;
}

class Test1 {
    static int x;
    public static void main(String[] args) {
        int x = x;
    }
}

class Test2 {
    static int x;
    public static void main(String[] args) {
        int x = (x=2)*2;
        System.out.println(x);
    }
}

4

class Test3 {
    public static void main(String[] args) {
        System.out.print("2+1=");
        int two = 2, three = two + 1;
        System.out.println(three);
    }
}

2+1=3

6.5 Determining the Meaning of a Name

6.5.4 Meaning of PackageOrTypeNames

6.5.4.1 Simple PackageOrTypeNames

If the PackageOrTypeName, Q, is a valid TypeIdentifier and occurs in the scope of a type class, interface, or type parameter named Q, then the PackageOrTypeName is reclassified as a TypeName.

Otherwise, the PackageOrTypeName is reclassified as a PackageName. The meaning of the PackageOrTypeName is the meaning of the reclassified name.

6.5.4.2 Qualified PackageOrTypeNames

Given a qualified PackageOrTypeName of the form Q.Id, if Id is a valid TypeIdentifier and the type class, interface, type parameter, or package denoted by Q has a member type class or interface named Id, then the qualified PackageOrTypeName name is reclassified as a TypeName.

Otherwise, it is reclassified as a PackageName. The meaning of the qualified PackageOrTypeName is the meaning of the reclassified name.

6.5.5 Meaning of Type Names

The meaning of a name classified as a TypeName is determined as follows.

6.5.5.1 Simple Type Names

If a type name consists of a single Identifier, then the identifier must occur in the scope of exactly one declaration of a type class, interface, or type parameter with this name (6.3), or a compile-time error occurs.

The meaning of the type name is that type class, interface, or type parameter.

6.5.5.2 Qualified Type Names

If a type name is of the form Q.Id, then Q must be either the name of a type class, interface, or type parameter in a package uniquely visible to the current module, or the name of a package uniquely visible to the current module (7.4.3).

If Id names exactly one accessible type class or interface (6.6) that is a member of the type class, interface, type parameter, or package denoted by Q, then the qualified type name denotes that type class or interface.

If Id does not name a member type class or interface within Q (8.5, 9.5), or the member type class or interface named Id within Q is not accessible (6.6), or Id names more than one member type class or interface within Q, then a compile-time error occurs.

class Test {
    public static void main(String[] args) {
        java.util.Date date =
            new java.util.Date(System.currentTimeMillis());
        System.out.println(date.toLocaleString());
    }
}

Sun Jan 21 22:56:29 1996

Chapter 7: Packages and Modules

7.3 Compilation Units

CompilationUnit is the goal symbol (2.1) for the syntactic grammar (2.3) of Java programs. It is defined by the following production:

CompilationUnit:

OrdinaryCompilationUnit

ModularCompilationUnit

OrdinaryCompilationUnit:

[PackageDeclaration] {ImportDeclaration} {TypeDeclaration TopLevelClassOrInterfaceDeclaration}

ModularCompilationUnit:

{ImportDeclaration} ModuleDeclaration

An ordinary compilation unit consists of three parts, each of which is optional:

• A package declaration (7.4), giving the fully qualified name (6.7) of the package to which the compilation unit belongs.

  A compilation unit that has no package declaration is part of an unnamed package (7.4.2).

• import declarations (7.5) that allow types classes and interfaces from other packages and static members of types classes and interfaces to be referred to using their simple names.

• Top level type declarations (7.6) of class and interface types classes and interfaces (7.6).

A modular compilation unit consists of a module declaration (7.7), optionally preceded by import declarations. The import declarations allow types classes and interfaces from packages in this module and other modules, as well as static members of types classes and interfaces, to be referred to using their simple names within the module declaration.

Every compilation unit implicitly imports every public type class or interface name declared in the predefined package java.lang, as if the declaration import java.lang.*; appeared at the beginning of each compilation unit immediately after any package declaration. As a result, the names of all those types classes and interfaces are available as simple names in every compilation unit.

The host system determines which compilation units are observable, except for the compilation units in the predefined package java and its subpackages lang and io, which are all always observable.

Each observable compilation unit may be associated with a module, as follows:

• The host system may determine that an observable ordinary compilation unit is associated with a module chosen by the host system, except for (i) the ordinary compilation units in the predefined package java and its subpackages lang and io, which are all associated with the java.base module, and (ii) any ordinary compilation unit in an unnamed package, which is associated with a module as specified in 7.4.2.

• The host system must determine that an observable modular compilation unit is associated with the module declared by the modular compilation unit.

The observability of a compilation unit influences the observability of its package (7.4.3), while the association of an observable compilation unit with a module influences the observability of that module (7.7.6).

When compiling the modular and ordinary compilation units associated with a module M, the host system must respect the dependences specified in M's declaration. Specifically, the host system must limit the ordinary compilation units that would otherwise be observable, to only those that are visible to M. The ordinary compilation units that are visible to M are the observable ordinary compilation units associated with the modules that are read by M. The modules read by M are given by the result of resolution, as described in the java.lang.module package specification, with M as the only root module. The host system must perform resolution to determine the modules read by M; it is a compile-time error if resolution fails for any of the reasons described in the java.lang.module package specification.

The readability relation is reflexive, so M reads itself, and thus all of the modular and ordinary compilation units associated with M are visible to M.

The modules read by M drive the packages that are uniquely visible to M (7.4.3), which in turn drives both the top level packages in scope and the meaning of package names for code in the modular and ordinary compilation units associated with M (6.3, 6.5.3, 6.5.5).

The rules above ensure that package/type names used in annotations in a modular compilation unit (in particular, annotations applied to the module declaration) are interpreted as if they appeared in an ordinary compilation unit associated with the module.

Types Classes and interfaces declared in different ordinary compilation units can refer to each other, circularly. A Java compiler must arrange to compile all such types classes and interfaces at the same time.

7.5 Import Declarations

An import declaration allows a named type or a class, interface, or static member to be referred to by a simple name (6.2) that consists of a single identifier.

Without the use of an appropriate import declaration, the only way to refer to a type declared in another package, or a static member of another type, is to use a fully qualified name (6.7) a reference to a class or interface declared in another package, or a static member of another class or interface, would typically need to use a qualified name (6.7).

ImportDeclaration:

SingleTypeImportDeclaration

TypeImportOnDemandDeclaration

SingleStaticImportDeclaration

StaticImportOnDemandDeclaration

• A single-type-import declaration (7.5.1) imports a single named type

• class or interface, by mentioning its canonical name (6.7).

• A type-import-on-demand declaration (7.5.2) imports all the accessible types classes and interfaces of a named type or named package, class, or interface as needed, by mentioning the canonical name of a type or package, class, or interface.

• A single-static-import declaration (7.5.3) imports all accessible static members with a given name from a type class or interface, by giving its canonical name.

• A static-import-on-demand declaration (7.5.4) imports all accessible static members of a named type class or interface as needed, by mentioning the canonical name of a type class or interface.

The scope and shadowing of a type class, interface, or member imported by these declarations is specified in 6.3 and 6.4.

An import declaration makes types classes, interfaces, or members available by their simple names only within the compilation unit that actually contains the import declaration. The scope of the type(s) class(es), interface(s), or member(s) introduced by an import declaration specifically does not include other compilation units in the same package, other import declarations in the current compilation unit, or a package declaration in the current compilation unit (except for the annotations of a package declaration).

7.5.1 Single-Type-Import Declarations

A single-type-import declaration imports a single type class or interface 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, or annotation type or interface (6.7).

The type class or interface must be either a member of a named package, or a member of a type class or interface whose outermost lexically enclosing type class or interface 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 class or interface is not accessible (6.6).

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

If the type class or interface 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 class or interface whose simple name is n, and the compilation unit also declares a top level type class or interface (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 class or interface whose simple name is n, and a single-static-import declaration (7.5.3) that imports a type class or interface whose simple name is n, a compile-time error occurs, unless the two types classes or interfaces 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 classes and interfaces of a named package, class, or interface 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, or an interface type, an enum type, or an annotation type.

If the PackageOrTypeName denotes a type class or interface (6.5.4), then the type class or interface must be either a member of a named package, or a member of a type class or interface whose outermost lexically enclosing type class or interface 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 class or interface 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, class, or interface. 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 class or interface, the effect is as if the static member types classes and interfaces of that type class or interface (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 class or interface. 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, or annotation type or interface.

The type class or interface must be either a member of a named package, or a member of a type class or interface whose outermost lexically enclosing type class or interface 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 class or interface is not accessible (6.6).

The Identifier must name at least one static member of the named type class or interface. 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, classes, or interfaces or types with the same name, or several methods with the same name and signature. This occurs when the named type class or interface inherits multiple fields, member types classes, member interfaces, 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 classes or interfaces with the same simple name, then a compile-time error occurs, unless the two types classes or interfaces are the same type, in which case the duplicate declaration is ignored.

If a single-static-import declaration imports a type class or interface whose simple name is n, and the compilation unit also declares a top level type class or interface (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 class or interface whose simple name is n, and a single-type-import declaration (7.5.1) that imports a type class or interface whose simple name is n, a compile-time error occurs, unless the two types classes or interfaces 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 class or interface 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, or annotation type or interface.

The type class or interface must be either a member of a named package, or a member of a type class or interface whose outermost lexically enclosing type class or interface 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 class or interface is not accessible (6.6).

Two or more static-import-on-demand declarations in the same compilation unit may name the same type class or interface; 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, classes, or interfaces or types with the same name, or several methods with the same name and signature. This occurs when the named type class or interface inherits multiple fields, member types classes, member interfaces, 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 class or interface, the effect is as if the static member types classes and interfaces of that type class or interface (8.5, 9.5) were imported only once.

7.6 Top Level Type Class and Interface Declarations

A top level type class or interface declaration declares a top level class type (8 8.1), which may be an enum class (8.9), or a top level interface type (9 9.1), which may be an annotation interface (9.6).

TypeDeclaration: TopLevelClassOrInterfaceDeclaration:

ClassDeclaration

InterfaceDeclaration

ClassOrInterfaceDeclaration

;

Extra ";" tokens appearing at the level of type class or interface declarations in a compilation unit have no effect on the meaning of the compilation unit. Stray semicolons are permitted in the Java programming language solely as a concession to C++ programmers who are used to placing ";" after a class declaration. They should not be used in new Java code.

In the absence of an access modifier, a top level type class or interface has package access: it is accessible only within ordinary compilation units of the package in which it is declared (6.6.1). A type class or interface may be declared public to grant access to the type class or interface from code in other packages of the same module, and potentially from code in packages of other modules.

It is a compile-time error if a top level type class or interface declaration contains any one of the following access modifiers: protected, private, or static.

It is a compile-time error if the name of a top level type class or interface appears as the name of any other top level class or interface type declared in the same package.

The scope and shadowing of a top level type class or interface is specified in 6.3 and 6.4.

The fully qualified name of a top level type class or interface is specified in 6.7.

package test;
import java.util.Vector;
class Point {
    int x, y;
}
interface Point {  // compile-time error #1
    int getR();
    int getTheta();
}
class Vector { Point[] pts; }  // compile-time error #2

package test;
import java.util.*;
class Vector {}  // not a compile-time error

package points;
class Point {
    int x, y;           // coordinates
    PointColor color;   // color of this point
    Point next;         // next point with this color
    static int nPoints;
}
class PointColor {
    Point first;        // first point with this color
    PointColor(int color) { this.color = color; }
    private int color;  // color components
}

class Point { int x, y; }

package vista;
class Point { int x, y; }

An implementation of the Java SE Platform must keep track of types classes and interfaces within packages by the combination of their enclosing module names and their binary names (13.1). Multiple ways of naming a type class or interface must be expanded to binary names to make sure that such names are understood as referring to the same type class or interface.

For example, if a compilation unit contains the single-type-import declaration (7.5.1):

import java.util.Vector;

then within that compilation unit, the simple name Vector and the fully qualified name java.util.Vector refer to the same type class.

If and only if packages are stored in a file system (7.2), the host system may choose to enforce the restriction that it is a compile-time error if a type class or interface is not found in a file under a name composed of the type class or interface name plus an extension (such as .java or .jav) if either of the following is true:

• The type class or interface is referred to by code in other ordinary compilation units of the package in which the type class or interface is declared.

• The type class or interface is declared public (and therefore is potentially accessible from code in other packages).

This restriction implies that there must be at most one such type class or interface per compilation unit. This restriction makes it easy for a Java compiler to find a named class or interface within a package. In practice, many programmers choose to put each class or interface type in its own compilation unit, whether or not it is public or is referred to by code in other compilation units.

For example, the source code for a public type wet.sprocket.Toad would be found in a file Toad.java in the directory wet/sprocket, and the corresponding object code would be found in the file Toad.class in the same directory.

7.7 Module Declarations

7.7.4 Service Provision

The provides directive specifies a service for which the with clause specifies one or more service providers to java.util.ServiceLoader.

The service must be a class type, an interface type, or an annotation type or an interface, and not an enum class. It is a compile-time error if a provides directive specifies an enum type class (8.9) as the service.

The service may be declared in the current module or in another module. If the service is not declared in the current module, then the service must be accessible to code in the current module (6.6), or a compile-time error occurs.

Every service provider must be a public class type or an interface type, that is public, and that is top level or nested static, or a compile-time error occurs.

Every service provider must be declared in the current module, or a compile-time error occurs.

If a service provider explicitly declares a public constructor with no formal parameters, or implicitly declares a public default constructor (8.8.9), then that constructor is called the provider constructor.

If a service provider explicitly declares a public static method called provider with no formal parameters, then that method is called the provider method.

If a service provider has a provider method, then its return type must (i) either be declared in the current module, or be declared in another module and be accessible to code in the current module; and (ii) be a subtype of the service specified in the provides directive; or a compile-time error occurs.

While a service provider that is specified by a provides directive must be declared in the current module, its provider method may have a return type that is declared in another module. Also, note that when a service provider declares a provider method, the service provider itself need not be a subtype of the service.

If a service provider does not have a provider method, then that service provider must have a provider constructor and must be a subtype of the service specified in the provides directive, or a compile-time error occurs.

It is a compile-time error if more than one provides directive in a module declaration specifies the same service.

It is a compile-time error if the with clause of a given provides directive specifies the same service provider more than once.

Chapter 8: Classes

Class declarations define new reference types and describe how they are implemented (8.1).

A top level class (7.6) is a class that is not a nested class declared at the top level of a compilation unit.

A nested class is any class whose declaration occurs within the body of another class or interface. A nested class may be a member class (8.5, 9.5), a local class (14.3), or an anonymous class (15.9.5).

An inner class (8.1.3) is a nested class that can refer to enclosing class instances, local variables, and type variables.

An enum class (8.9) is a class declared with special syntax that defines a small set of named class instances.

This chapter discusses the common semantics of all classes - top level (7.6) and nested (including member classes (8.5, 9.5), local classes (14.3) and anonymous classes (15.9.5)). Details that are specific to particular kinds of classes are discussed in the sections dedicated to these constructs.

A named class may be declared abstract (8.1.1.1) and must be declared abstract if it is incompletely implemented; such a class cannot be instantiated, but can be extended by subclasses. A class may be declared final (8.1.1.2), in which case it cannot have subclasses. If a class is declared public, then it can be referred to from code in any package of its module and potentially from code in other modules. Each class except Object is an extension of (that is, a subclass of) a single existing class (8.1.4) and may implement interfaces (8.1.5). Classes may be generic (8.1.2), that is, they may declare type variables whose bindings may differ among different instances of the class.

Classes may be decorated with annotations (9.7) just like any other kind of declaration.

The body of a class declares members (fields, and methods, and nested classes, and interfaces), instance and static initializers, and constructors (8.1.6). The scope (6.3) of a member (8.2) is the entire body of the declaration of the class to which the member belongs. Field, method, member class, member interface, and constructor declarations may include the access modifiers (6.6) public, protected, or private. The members of a class include both declared and inherited members (8.2). Newly declared fields can hide fields declared in a superclass or superinterface. Newly declared class members member classes and interface members member interfaces can hide class or interface members member classes and interfaces declared in a superclass or superinterface. Newly declared methods can hide, implement, or override methods declared in a superclass or superinterface.

Field declarations (8.3) describe class variables, which are incarnated once, and instance variables, which are freshly incarnated for each instance of the class. A field may be declared final (8.3.1.2), in which case it can be assigned to only once. Any field declaration may include an initializer.

Member class declarations (8.5) describe nested classes that are members of the surrounding class. Member classes may be static, in which case they have no access to the instance variables of the surrounding class; or they may be inner classes (8.1.3).

Member interface declarations (8.5) describe nested interfaces that are members of the surrounding class.

Method declarations (8.4) describe code that may be invoked by method invocation expressions (15.12). A class method is invoked relative to the class type; an instance method is invoked with respect to some particular object that is an instance of a class type. A method whose declaration does not indicate how it is implemented must be declared abstract. A method may be declared final (8.4.3.3), in which case it cannot be hidden or overridden. A method may be implemented by platform-dependent native code (8.4.3.4). A synchronized method (8.4.3.6) automatically locks an object before executing its body and automatically unlocks the object on return, as if by use of a synchronized statement (14.19), thus allowing its activities to be synchronized with those of other threads (17).

Method names may be overloaded (8.4.9).

Instance initializers (8.6) are blocks of executable code that may be used to help initialize an instance when it is created (15.9).

Static initializers (8.7) are blocks of executable code that may be used to help initialize a class.

Constructors (8.8) are similar to methods, but cannot be invoked directly by a method call; they are used to initialize new class instances. Like methods, they may be overloaded (8.8.8).

8.1 Class Declarations

A class declaration specifies a new named reference type a new class.

NormalClassDeclaration: ClassDeclaration:

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

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.1 Class Modifiers

A class declaration may include class modifiers.

ClassModifier:

(one of)

Annotation public protected private

abstract static final strictfp

The rules for annotation modifiers on a class declaration are specified in 9.7.4 and 9.7.5.

The access modifier public (6.6) pertains only to top level classes (7.6) and member classes (8.5, 9.5), not to local classes (14.3) or anonymous classes (15.9.5).

The access modifiers protected and private pertain only to member classes within a directly enclosing class declaration (8.5).

The modifier static pertains only to member classes (8.5.1), not to top level or local or anonymous classes.

It is a compile-time error if the same keyword appears more than once as a modifier for a class declaration, or if a class declaration has more than one of the access modifiers public, protected, and private (6.6).

If two or more (distinct) class modifiers appear in a class declaration, then it is customary, though not required, that they appear in the order consistent with that shown above in the production for ClassModifier.

8.1.1.3 strictfp Classes

The effect of the strictfp modifier is to make all float or double expressions within the class declaration (including within variable initializers, instance initializers, static initializers, and constructors) be explicitly FP-strict (15.4).

This implies that all methods declared in the class, and all nested types class and interfaces declared in the class, are implicitly strictfp.

8.1.3 Inner Classes and Enclosing Instances

An inner class is a nested class that is not explicitly or implicitly declared static.

An inner class may be a non-static member class (8.5), a local class (14.3), or an anonymous class (15.9.5). A member class of an interface is implicitly static (9.5) so is never considered to be an inner class.

It is a compile-time error if an inner class declares a static initializer (8.7).

It is a compile-time error if an inner class declares a member that is explicitly or implicitly static, unless the member is a constant variable (4.12.4).

An inner class may inherit static members that are not constant variables even though it cannot declare them.

A nested class that is not an inner class may declare static members freely, in accordance with the usual rules of the Java programming language.

class HasStatic {
    static int j = 100;
}
class Outer {
    class Inner extends HasStatic {
        static final int x = 3;  // OK: constant variable
        static int y = 4;  // Compile-time error: an inner class
    }
    static class NestedButNotInner{
        static int z = 5;    // OK: not an inner class
    }
    interface NeverInner {}  // Interfaces are never inner
}

A statement or expression occurs in a static context if and only if the innermost method, constructor, instance initializer, static initializer, field initializer, or explicit constructor invocation statement enclosing the statement or expression is a static method, a static initializer, the variable initializer of a static variable, or an explicit constructor invocation statement (8.8.7.1).

An inner class C is a direct inner class of a class or interface O if O is the immediately enclosing type class or interface declaration of C and the declaration of C does not occur in a static context.

If an inner class is a local class or an anonymous class, it may be declared in a static context, and in that case is not considered an inner class of any enclosing class or interface.

A class C is an inner class of class or interface O if it is either a direct inner class of O or an inner class of an inner class of O.

It is unusual, but possible, for the immediately enclosing type class or interface declaration of an inner class to be an interface. This only occurs if the class is a local or anonymous class declared in a default or static method body (9.4). Specifically, it occurs if an anonymous or local class is declared in a default method body, or a member class is declared in the body of an anonymous class that is declared in a default method body.

A class or interface O is the zeroth lexically enclosing type declaration of itself.

A class O is the n'th lexically enclosing type declaration of a class C if it is the immediately enclosing type declaration of the n-1'th lexically enclosing type declaration of C.

An instance i of a direct inner class C of a class or interface O is associated with an instance of O, known as the immediately enclosing instance of i. The immediately enclosing instance of an object, if any, is determined when the object is created (15.9.2).

An object o is the zeroth lexically enclosing instance of itself.

An object o is the n'th lexically enclosing instance of an instance i if it is the immediately enclosing instance of the n-1'th lexically enclosing instance of i.

An instance of an inner class I a local class or an anonymous class whose declaration occurs in a static context has no lexically enclosing instances. However, if I is immediately declared within a static method or static initializer then I does have an enclosing block, which is the innermost block statement lexically enclosing the declaration of I.

For every superclass S of C which is itself a direct inner class of a class or interface SO, there is an instance of SO associated with i, known as the immediately enclosing instance of i with respect to S. The immediately enclosing instance of an object with respect to its class's direct superclass, if any, is determined when the superclass constructor is invoked via an explicit constructor invocation statement (8.8.7.1).

When an inner class (whose declaration does not occur in a static context) refers to an instance variable that is a member of a lexically enclosing type class or interface declaration, the variable of the corresponding lexically enclosing instance is used.

Any local variable, formal parameter, or exception parameter used but not declared in an inner class must either be declared final or be effectively final (4.12.4), or a compile-time error occurs where the use is attempted.

Any local variable used but not declared in an inner class must be definitely assigned (16) before the body of the inner class, or a compile-time error occurs.

Similar rules on variable use apply in the body of a lambda expression (15.27.2).

A blank final field (4.12.4) of a lexically enclosing type class or interface declaration may not be assigned within an inner class, or a compile-time error occurs.

class Outer {
    int i = 100;
    static void classMethod() {
        final int l = 200;
        class LocalInStaticContext {
            int k = i;  // Compile-time error
            int m = l;  // OK
        }
    }
    void foo() {
        class Local {  // A local class
            int j = i;
        }
    }
}

class WithDeepNesting {
    boolean toBe;
    WithDeepNesting(boolean b) { toBe = b; }

    class Nested {
        boolean theQuestion;
        class DeeplyNested {
            DeeplyNested(){
                theQuestion = toBe || !toBe;
            }
        }
    }
}

8.1.6 Class Body and Member Declarations

A class body may contain declarations of members of the class, that is, fields (8.3), methods (8.4), and classes (8.5), and interfaces (8.5).

A class body may also contain instance initializers (8.6), static initializers (8.7), and declarations of constructors (8.8) for the class.

ClassBody:

{ {ClassBodyDeclaration} }

ClassBodyDeclaration:

ClassMemberDeclaration

InstanceInitializer

StaticInitializer

ConstructorDeclaration

ClassMemberDeclaration:

FieldDeclaration

MethodDeclaration

ClassDeclaration

InterfaceDeclaration

ClassOrInterfaceDeclaration

;

The scope and shadowing of a declaration of a member m declared in or inherited by a class type C is specified in 6.3 and 6.4.

If C itself is a nested class, there may be definitions of the same kind (variable, method, or type) and name as m in enclosing scopes. (The scopes may be blocks, classes, or packages.) In all such cases, the member m declared in or inherited by C shadows (6.4.1) the other definitions of the same kind and name.

8.5 Member Type Class and Interface Declarations

A member class is a class whose declaration is directly enclosed in the body of another class or interface declaration (8.1.6, 9.1.4). A member class may be an enum class (8.9).

A member interface is an interface whose declaration is directly enclosed in the body of another class or interface declaration (8.1.6, 9.1.4). A member interface may be an annotation interface (9.6).

The accessibility of a member type class or interface declaration in a class is specified by its access modifier, or by 6.6 if lacking an access modifier.

It is a compile-time error if the same keyword appears more than once as a modifier for a member type declaration in a class, or if a member type declaration has more than one of the access modifiers public, protected, and private (6.6.)

The scope and shadowing of a member type is specified in 6.3 and 6.4.

If a class declares a member type class or interface with a certain name, then the declaration of that type class or interface is said to hide any and all accessible declarations of member types classes and interfaces with the same name in superclasses and superinterfaces of the class.

In this respect, hiding of member types classes and interfaces is similar to hiding of fields (8.3).

A class inherits from its direct superclass and direct superinterfaces all the non-private member types classes and interfaces of the superclass and superinterfaces that are both accessible to code in the class and not hidden by a declaration in the class.

It is possible for a class to inherit more than one member type class or interface with the same name, either from its superclass and superinterfaces or from its superinterfaces alone. Such a situation does not in itself cause a compile-time error. However, any attempt within the body of the class to refer to any such member type class or interface by its simple name will result in a compile-time error, because the reference is ambiguous.

There might be several paths by which the same member type class or interface declaration is inherited from an interface. In such a situation, the member type class or interface is considered to be inherited only once, and it may be referred to by its simple name without ambiguity.

8.5.1 Static Member Type Class and Interface Declarations

The static keyword may modify the declaration of a member type class C within the body of a non-inner class or interface T. Its effect is to declare that C is not an inner class. Just as a static method of T has no current instance of T in its body, C also has no current instance of T, nor does it have any lexically enclosing instances.

It is a compile-time error if a static class contains a usage of a non-static member of an enclosing class.

A member interface is implicitly static (9.1.1). It is permitted for the declaration of a member interface to redundantly specify the static modifier.

8.8 Constructor Declarations

8.8.7 Constructor Body

8.8.7.1 Explicit Constructor Invocations

ExplicitConstructorInvocation:

[TypeArguments] this ( [ArgumentList] ) ;

[TypeArguments] super ( [ArgumentList] ) ;

ExpressionName . [TypeArguments] super ( [ArgumentList] ) ;

Primary . [TypeArguments] super ( [ArgumentList] ) ;

The following productions from 4.5.1 and 15.12 are shown here for convenience:

TypeArguments:

< TypeArgumentList >

ArgumentList:

Expression {, Expression}

Explicit constructor invocation statements are divided into two kinds:

• Alternate constructor invocations begin with the keyword this (possibly prefaced with explicit type arguments). They are used to invoke an alternate constructor of the same class.

• Superclass constructor invocations begin with either the keyword super (possibly prefaced with explicit type arguments) or a Primary expression or an ExpressionName. They are used to invoke a constructor of the direct superclass. They are further divided:

  • Unqualified superclass constructor invocations begin with the keyword super (possibly prefaced with explicit type arguments).

  • Qualified superclass constructor invocations begin with a Primary expression or an ExpressionName. They allow a subclass constructor to explicitly specify the newly created object's immediately enclosing instance with respect to the direct superclass (8.1.3). This may be necessary when the superclass is an inner class.

An explicit constructor invocation statement in a constructor body may not refer to any instance variables or instance methods or inner classes declared in this class or any superclass, or use this or super in any expression; otherwise, a compile-time error occurs.

This prohibition on using the current instance explains why an explicit constructor invocation statement is deemed to occur in a static context (8.1.3).

If TypeArguments is present to the left of this or super, then it is a compile-time error if any of the type arguments are wildcards (4.5.1).

Let C be the class being instantiated, and let S be the direct superclass of C.

If a superclass constructor invocation statement is unqualified, then:

• If S is an inner member class, but S is not a member of a class enclosing C, then a compile-time error occurs.

If a superclass constructor invocation statement is qualified, then:

• If S is not an inner class, or if the declaration of S occurs in a static context, then a compile-time error occurs.

• Otherwise, let p be the Primary expression or the ExpressionName immediately preceding ".super", and let O be the immediately enclosing class of S. It is a compile-time error if the type of p is not O or a subclass of O, or if the type of p is not accessible (6.6).

The exception types that an explicit constructor invocation statement can throw are specified in 11.2.2.

Evaluation of an alternate constructor invocation statement proceeds by first evaluating the arguments to the constructor, left-to-right, as in an ordinary method invocation; and then invoking the constructor.

Evaluation of a superclass constructor invocation statement proceeds as follows:

1. Let i be the instance being created. The immediately enclosing instance of i with respect to S (if any) must be determined:

   • If S is not an inner class, or if the declaration of S occurs in a static context, then no immediately enclosing instance of i with respect to S exists.

   • If the superclass constructor invocation is unqualified, then S is necessarily a local class or an inner member class.

     If S is a local class, then let O be the immediately enclosing type class or interface declaration of S.

     If S is an inner member class, then let O be the innermost enclosing class of C of which S is a member.

     Let n be an integer (n ≥ 1) such that O is the n'th lexically enclosing type class or interface declaration of C.

     The immediately enclosing instance of i with respect to S is the n'th lexically enclosing instance of this.

     While it may be the case that S is a member of C due to inheritance, the zeroth lexically enclosing instance of this (that is, this itself) is never used as the immediately enclosing instance of i with respect to S.

   • If the superclass constructor invocation is qualified, then the Primary expression or the ExpressionName immediately preceding ".super", p, is evaluated.

     If p evaluates to null, a NullPointerException is raised, and the superclass constructor invocation completes abruptly.

     Otherwise, the result of this evaluation is the immediately enclosing instance of i with respect to S.

2. After determining the immediately enclosing instance of i with respect to S (if any), evaluation of the superclass constructor invocation statement proceeds by evaluating the arguments to the constructor, left-to-right, as in an ordinary method invocation; and then invoking the constructor.

3. Finally, if the superclass constructor invocation statement completes normally, then all instance variable initializers of C and all instance initializers of C are executed. If an instance initializer or instance variable initializer I textually precedes another instance initializer or instance variable initializer J, then I is executed before J.

   Execution of instance variable initializers and instance initializers is performed regardless of whether the superclass constructor invocation actually appears as an explicit constructor invocation statement or is provided implicitly. (An alternate constructor invocation does not perform this additional implicit execution.)

class Point {
    int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
}
class ColoredPoint extends Point {
    static final int WHITE = 0, BLACK = 1;
    int color;
    ColoredPoint(int x, int y) {
        this(x, y, color);  // Changed to color from WHITE
    }
    ColoredPoint(int x, int y, int color) {
        super(x, y);
        this.color = color;
    }
}

class Outer {
    class Inner {}
}
class ChildOfInner extends Outer.Inner {
    ChildOfInner() { (new Outer()).super(); }
}

class Outer {
    int secret = 5;
    class Inner {
        int  getSecret()      { return secret; }
        void setSecret(int s) { secret = s; }
    }
}
class ChildOfInner extends Outer.Inner {
    ChildOfInner(Outer x) { x.super(); }
}

public class Test {
    public static void main(String[] args) {
        Outer x = new Outer();
        ChildOfInner a = new ChildOfInner(x);
        ChildOfInner b = new ChildOfInner(x);
        System.out.println(b.getSecret());
        a.setSecret(6);
        System.out.println(b.getSecret());
    }
}

5
6

8.9 Enum Types Classes

An enum declaration specifies a new enum type class, a special kind of class type that defines a small set of named class instances.

EnumDeclaration:

{ClassModifier} enum TypeIdentifier [Superinterfaces] EnumBody

An enum declaration may specify a top level enum class (7.6) or a member enum class (8.5, 9.5).

It is a compile-time error if an enum declaration has the modifier abstract or final.

An enum declaration is implicitly final unless it contains at least one enum constant that has a class body (8.9.1).

A nested member enum type declaration is implicitly static. It is permitted for the declaration of a nested member enum type class to redundantly specify the static modifier.

This implies that it is impossible to declare an enum type class in the body of as a member of an inner class (8.1.3), because an inner class cannot have static members except for constant variables.

It is a compile-time error if the same keyword appears more than once as a modifier for an enum declaration, or if an enum declaration has more than one of the access modifiers public, protected, and private (6.6).

The direct superclass type of an enum type class E is Enum<E> (8.1.4).

An enum type class has no instances other than those defined by its enum constants. It is a compile-time error to attempt to explicitly instantiate an enum type class (15.9.1).

In addition to the compile-time error, three further mechanisms ensure that no instances of an enum type class exist beyond those defined by its enum constants:

• The final clone method in Enum ensures that enum constants can never be cloned.

• Reflective instantiation of enum types classes is prohibited.

• Special treatment by the serialization mechanism ensures that duplicate instances are never created as a result of deserialization.

8.9.1 Enum Constants

The body of an enum declaration may contain enum constants. An enum constant defines an instance of the enum type class.

EnumBody:

{ [EnumConstantList] [,] [EnumBodyDeclarations] }

EnumConstantList:

EnumConstant {, EnumConstant}

EnumConstant:

{EnumConstantModifier} Identifier [( [ArgumentList] )] [ClassBody]

EnumConstantModifier:

Annotation

The following production from 15.12 is shown here for convenience:

ArgumentList:

Expression {, Expression}

The rules for annotation modifiers on an enum constant declaration are specified in 9.7.4 and 9.7.5.

The Identifier in a EnumConstant may be used in a name to refer to the enum constant.

The scope and shadowing of an enum constant is specified in 6.3 and 6.4.

An enum constant may be followed by arguments, which are passed to the constructor of the enum when the constant is created during class initialization as described later in this section. The constructor to be invoked is chosen using the normal rules of overload resolution (15.12.2). If the arguments are omitted, an empty argument list is assumed.

The optional class body of an enum constant implicitly defines an anonymous class declaration (15.9.5) that extends the immediately enclosing enum type class. The class body is governed by the usual rules of anonymous classes; in particular it cannot contain any constructors. Instance methods declared in these class bodies may be invoked outside the enclosing enum type class only if they override accessible methods in the enclosing enum type class (8.4.8).

It is a compile-time error for the class body of an enum constant to declare an abstract method.

Because there is only one instance of each enum constant, it is permitted to use the == operator in place of the equals method when comparing two object references if it is known that at least one of them refers to an enum constant.

The equals method in Enum is a final method that merely invokes super.equals on its argument and returns the result, thus performing an identity comparison.

8.9.2 Enum Body Declarations

In addition to enum constants, the body of an enum declaration may contain constructor and member declarations as well as instance and static initializers.

EnumBodyDeclarations:

; {ClassBodyDeclaration}

The following productions from 8.1.6 are shown here for convenience:

ClassBodyDeclaration:

ClassMemberDeclaration

InstanceInitializer

StaticInitializer

ConstructorDeclaration

ClassMemberDeclaration:

FieldDeclaration

MethodDeclaration

ClassDeclaration

InterfaceDeclaration

ClassOrInterfaceDeclaration

;

Any constructor or member declarations in the body of an enum declaration apply to the enum type class exactly as if they had been present in the body of a normal class declaration, unless explicitly stated otherwise.

It is a compile-time error if a constructor declaration in an enum declaration is public or protected (6.6).

It is a compile-time error if a constructor declaration in an enum declaration contains a superclass constructor invocation statement (8.8.7.1).

It is a compile-time error to refer to a static field of an enum type class from a constructor, instance initializer, or instance variable initializer of the enum type declaration, unless the field is a constant variable (4.12.4).

In an enum declaration, a constructor declaration with no access modifiers is private.

In an enum declaration with no constructor declarations, a default constructor is implicitly declared. The default constructor is private, has no formal parameters, and has no throws clause.

In practice, a compiler is likely to mirror the Enum type class by declaring String and int parameters in the default constructor of an enum type. However, these parameters are not specified as "implicitly declared" because different compilers do not need to agree on the form of the default constructor. Only the compiler of an enum type declaration knows how to instantiate the enum constants; other compilers can simply rely on the implicitly declared public static fields of the enum type class (8.9.3) without regard for how those fields were initialized.

It is a compile-time error if an enum declaration E has an abstract method m as a member, unless E has at least one enum constant and all of E's enum constants have class bodies that provide concrete implementations of m.

It is a compile-time error for an enum declaration to declare a finalizer (12.6). An instance of an enum type class may never be finalized.

enum Coin {
    PENNY(1), NICKEL(5), DIME(10), QUARTER(25);
    Coin(int value) { this.value = value; }

    private final int value;
    public int value() { return value; }
}

import java.util.Map;
import java.util.HashMap;

enum Color {
    RED, GREEN, BLUE;
    Color() { colorMap.put(toString(), this); }

    static final Map<String,Color> colorMap =
        new HashMap<String,Color>();
}

import java.util.Map;
import java.util.HashMap;

enum Color {
    RED, GREEN, BLUE;

    static final Map<String,Color> colorMap =
        new HashMap<String,Color>();
    static {
        for (Color c : Color.values())
            colorMap.put(c.toString(), c);
    }
}

8.9.3 Enum Members

The members of an enum type class E are all of the following:

• Members declared in the body of the declaration of E.

• Members inherited from Enum<E>.

• For each enum constant c declared in the body of the declaration of E, E has an implicitly declared public static final field of type E that has the same name as c. The field has a variable initializer which instantiates E and passes any arguments of c to the constructor chosen for E. The field has the same annotations as c (if any).

  These fields are implicitly declared in the same order as the corresponding enum constants, before any static fields explicitly declared in the body of the declaration of E.

  An enum constant is said to be created when the corresponding implicitly declared field is initialized.

• An implicitly declared method public static E[] values(), which returns an array containing the enum constants of E, in the same order as they appear in the body of the declaration of E.

• An implicitly declared method public static E valueOf(String name), which returns the enum constant of E with the specified name.

• The following implicitly declared methods:

  /**
  * Returns an array containing the constants of this enum 

  * type, in the order they're declared.  This method may be

  * class, in the order they're declared.  This method may be

  * used to iterate over the constants as follows:
  *
  *    for(E c : E.values())
  *        System.out.println(c);
  *
  * @return an array containing the constants of this enum 

  * type, in the order they're declared

  * class, in the order they're declared

  */
  public static E[] values();
  
  /**

  * Returns the enum constant of this type with the specified

  * Returns the enum constant of this class with the specified

  * name.
  * The string must match exactly an identifier used to declare

  * an enum constant in this type.  (Extraneous whitespace 

  * an enum constant in this class.  (Extraneous whitespace 

  * characters are not permitted.)
  * 
  * @return the enum constant with the specified name

  * @throws IllegalArgumentException if this enum type has no

  * @throws IllegalArgumentException if this enum class has no

  * constant with the specified name
  */
  public static E valueOf(String name);

It follows that the declaration of enum type class E cannot contain fields that conflict with the implicitly declared fields corresponding to E's enum constants, nor contain methods that conflict with implicitly declared methods or override final methods of class Enum<E>.

public class Test {
    enum Season { WINTER, SPRING, SUMMER, FALL }

    public static void main(String[] args) {
        for (Season s : Season.values())
            System.out.println(s);
    }
}

WINTER
SPRING
SUMMER
FALL

class Test {
    enum CoinColor { COPPER, NICKEL, SILVER }

    static CoinColor color(Coin c) {
        switch (c) {
            case PENNY:
                return CoinColor.COPPER;
            case NICKEL:
                return CoinColor.NICKEL;
            case DIME: case QUARTER:
                return CoinColor.SILVER;
            default:
                throw new AssertionError("Unknown coin: " + c);
        }
    }

    public static void main(String[] args) {
        for (Coin c : Coin.values())
            System.out.println(c + "\t\t" +
                               c.value() + "\t" + color(c));
    }
}

PENNY           1       COPPER
NICKEL          5       NICKEL
DIME            10      SILVER
QUARTER         25      SILVER

enum Operation {
    PLUS {
        double eval(double x, double y) { return x + y; }
    },
    MINUS {
        double eval(double x, double y) { return x - y; }
    },
    TIMES {
        double eval(double x, double y) { return x * y; }
    },
    DIVIDED_BY {
        double eval(double x, double y) { return x / y; }
    };

    // Each constant supports an arithmetic operation
    abstract double eval(double x, double y);

    public static void main(String args[]) {
        double x = Double.parseDouble(args[0]);
        double y = Double.parseDouble(args[1]);
        for (Operation op : Operation.values())
            System.out.println(x + " " + op + " " + y +
                               " = " + op.eval(x, y));
    }
}

java Operation 2.0 4.0
2.0 PLUS 4.0 = 6.0
2.0 MINUS 4.0 = -2.0
2.0 TIMES 4.0 = 8.0
2.0 DIVIDED_BY 4.0 = 0.5

import java.util.List;
import java.util.ArrayList;
class Card implements Comparable<Card>,
                      java.io.Serializable {
    public enum Rank { DEUCE, THREE, FOUR, FIVE, SIX, SEVEN,
                       EIGHT, NINE, TEN,JACK, QUEEN, KING, ACE }

    public enum Suit { CLUBS, DIAMONDS, HEARTS, SPADES }

    private final Rank rank;
    private final Suit suit;
    public Rank rank() { return rank; }
    public Suit suit() { return suit; }

    private Card(Rank rank, Suit suit) {
        if (rank == null || suit == null)
            throw new NullPointerException(rank + ", " + suit);
        this.rank = rank;
        this.suit = suit;
    }

    public String toString() { return rank + " of " + suit; }

    // Primary sort on suit, secondary sort on rank
    public int compareTo(Card c) {
        int suitCompare = suit.compareTo(c.suit);
        return (suitCompare != 0 ?
                    suitCompare :
                    rank.compareTo(c.rank));
    }

    private static final List<Card> prototypeDeck =
        new ArrayList<Card>(52);

    static {
        for (Suit suit : Suit.values())
            for (Rank rank : Rank.values())
                prototypeDeck.add(new Card(rank, suit));
    }

    // Returns a new deck
    public static List<Card> newDeck() {
        return new ArrayList<Card>(prototypeDeck);
    }
}

import java.util.List;
import java.util.ArrayList;
import java.util.Collections;
class Deal {
    public static void main(String args[]) {
        int numHands     = Integer.parseInt(args[0]);
        int cardsPerHand = Integer.parseInt(args[1]);
        List<Card> deck  = Card.newDeck();
        Collections.shuffle(deck);
        for (int i=0; i < numHands; i++)
            System.out.println(dealHand(deck, cardsPerHand));
    }

    /**
     * Returns a new ArrayList consisting of the last n
     * elements of deck, which are removed from deck.
     * The returned list is sorted using the elements'
     * natural ordering.
     */
    public static <E extends Comparable<E>>
    ArrayList<E> dealHand(List<E> deck, int n) {
        int deckSize = deck.size();
        List<E> handView = deck.subList(deckSize - n, deckSize);
        ArrayList<E> hand = new ArrayList<E>(handView);
        handView.clear();
        Collections.sort(hand);
        return hand;
    }
}

java Deal 4 3
[DEUCE of CLUBS, SEVEN of CLUBS, QUEEN of DIAMONDS]
[NINE of HEARTS, FIVE of SPADES, ACE of SPADES]
[THREE of HEARTS, SIX of HEARTS, TEN of SPADES]
[TEN of CLUBS, NINE of DIAMONDS, THREE of SPADES]

Chapter 9: Interfaces

An interface declaration introduces a new abstract reference type whose members are classes, interfaces, constants, and methods that can be implemented by one or more classes. Programs can use interfaces to provide a common supertype for otherwise-unrelated classes.

This type has Interfaces have no instance variables, and typically declares declare one or more abstract methods; otherwise unrelated classes can implement the an interface by providing implementations for its abstract methods. Interfaces may not be directly instantiated.

A nested interface is any interface whose declaration occurs within the body of another class or interface.

A top level interface is an interface that is not a nested interface.

A top level interface (7.6) is an interface that is declared at the top level of a compilation unit.

A nested interface is any interface whose declaration occurs as a member interface (8.5, 9.5) of another class or interface.

We distinguish between two kinds of interfaces - normal interfaces and annotation types.

An annotation interface (9.6) is an interface declared with special syntax, intended to be implemented by reflective representations of annotations (9.7).

This chapter discusses the common semantics of all interfaces - normal interfaces, both top level (7.6) and nested (8.5, 9.5), and annotation types (9.6). Details that are specific to particular kinds of interfaces are discussed in the sections dedicated to these constructs.

Programs can use interfaces to make it unnecessary for related classes to share a common abstract superclass or to add methods to Object.

An interface may be declared to be a direct extension of one or more other interfaces, meaning that it inherits all the member types classes and interfaces, instance methods, and constants static fields of the interfaces it extends, except for any members that it may override or hide.

A class may be declared to directly implement one or more interfaces, meaning that any instance of the class implements all the abstract methods specified by the interface or interfaces. A class necessarily implements all the interfaces that its direct superclasses and direct superinterfaces do. This (multiple) interface inheritance allows objects to support (multiple) common behaviors without sharing a superclass.

A variable whose declared type is an interface type may have as its value a reference to any instance of a class which implements the specified interface. It is not sufficient that the class happen to implement all the abstract methods of the interface; the class or one of its superclasses must actually be declared to implement the interface, or else the class is not considered to implement the interface.

9.1 Interface Declarations

An interface declaration specifies a new named reference type. There are two kinds of interface declarations - normal interface declarations and annotation type declarations (9.6).

NormalInterfaceDeclaration: InterfaceDeclaration:

{InterfaceModifier} interface TypeIdentifier [TypeParameters]
[ExtendsInterfaces] InterfaceBody

The TypeIdentifier in an interface declaration specifies the name of the interface.

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

The scope and shadowing of an interface declaration is specified in 6.3 and 6.4.

9.1.4 Interface Body and Member Declarations

The body of an interface may declare members of the interface, that is, fields (9.3), methods (9.4), and classes (9.5), and interfaces (9.5).

InterfaceBody:

{ {InterfaceMemberDeclaration} }

InterfaceMemberDeclaration:

ConstantDeclaration

InterfaceMethodDeclaration

ClassDeclaration

InterfaceDeclaration

ClassOrInterfaceDeclaration

;

The scope of a declaration of a member m declared in or inherited by an interface type I is specified in 6.3.

9.5 Member Type Class and Interface Declarations

Interfaces may contain member type class and interface declarations (8.5).

Every member type class or interface declaration in the body of an interface is implicitly public and static. It is permitted to redundantly specify either or both of these modifiers.

It is a compile-time error if a member type class or interface declaration in an interface has the modifier protected or private.

It is a compile-time error if the same keyword appears more than once as a modifier for a member type declaration in an interface.

If an interface declares a member type class or interface with a certain name, then the declaration of that type class or interface is said to hide any and all accessible declarations of member types classes and interfaces with the same name in superinterfaces of the interface.

An interface inherits from its direct superinterfaces all the non-private member types classes and interfaces of the superinterfaces that are both accessible to code in the interface and not hidden by a declaration in the interface.

It is possible for an interface to inherit more than one member type class or interface with the same name. Such a situation does not in itself cause a compile-time error. However, any attempt within the body of the interface to refer to any such member type class or interface by its simple name will result in a compile-time error, because the reference is ambiguous.

There might be several paths by which the same member type class or interface declaration is inherited from an interface. In such a situation, the member type class or interface is considered to be inherited only once, and it may be referred to by its simple name without ambiguity.

9.6 Annotation Types Interfaces

An annotation type declaration specifies a new annotation type interface, a special kind of interface type. To distinguish an annotation type declaration from a normal interface declaration, the keyword interface is preceded by an at-sign at sign (@).

AnnotationTypeDeclaration: AnnotationDeclaration:

{InterfaceModifier} @ interface TypeIdentifier AnnotationTypeBody AnnotationInterfaceBody

Note that the at-sign at sign (@) and the keyword interface are distinct tokens. It is possible to separate them with whitespace, but this is discouraged as a matter of style.

The rules for annotation modifiers on an annotation type declaration are specified in 9.7.4 and 9.7.5.

The TypeIdentifier in an annotation type declaration specifies the name of the annotation type interface.

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

The direct superinterface of every annotation type interface is java.lang.annotation.Annotation.

By virtue of the AnnotationTypeDeclaration AnnotationInterfaceDeclaration syntax, an annotation type interface declaration cannot be generic, and no extends clause is permitted.

A consequence of the fact that an annotation type interface cannot explicitly declare a superclass or superinterface is that a subclass or subinterface of an annotation type interface is never itself an annotation type interface. Similarly, java.lang.annotation.Annotation is not itself an annotation type interface.

An annotation type interface inherits several members from java.lang.annotation.Annotation, including the implicitly declared methods corresponding to the instance methods of Object, yet these methods do not define elements of the annotation type interface (9.6.1).

Because these methods do not define elements of the annotation type interface, it is illegal to use them in annotations of that type (9.7). Without this rule, we could not ensure that elements were of the types representable in annotations, or that accessor methods for them would be available.

Unless explicitly modified herein, all of the rules that apply to normal interface declarations apply to annotation type declarations.

For example, annotation types interfaces share the same namespace as normal class and interface types classes and interfaces; and annotation type declarations are legal wherever interface declarations are legal, and have the same scope and accessibility as interface declarations.

9.6.1 Annotation Type Elements

The body of an annotation type declaration may contain method declarations, each of which defines an element of the annotation type interface. An annotation type interface has no elements other than those defined by the methods it explicitly declares.

AnnotationTypeBody: AnnotationInterfaceBody:

{ {AnnotationTypeMemberDeclaration AnnotationMemberDeclaration} }

AnnotationTypeMemberDeclaration: AnnotationMemberDeclaration:

AnnotationTypeElementDeclaration AnnotationElementDeclaration

ConstantDeclaration

ClassDeclaration

InterfaceDeclaration

ClassOrInterfaceDeclaration

;

AnnotationTypeElementDeclaration: AnnotationElementDeclaration:

{AnnotationTypeElementModifier AnnotationElementModifier} UnannType Identifier ( ) [Dims]
[DefaultValue] ;

AnnotationTypeElementModifier: AnnotationElementModifier:

(one of)

Annotation public

abstract

By virtue of the AnnotationTypeElementDeclaration AnnotationElementDeclaration production, a method declaration in an annotation type declaration cannot have formal parameters, type parameters, or a throws clause. The following production from 4.3 is shown here for convenience:

Dims:

{Annotation} [ ] {{Annotation} [ ]}

By virtue of the AnnotationTypeElementModifier AnnotationElementModifier production, a method declaration in an annotation type declaration cannot be default or static. Thus, an annotation type interface cannot declare the same variety of methods as a normal interface type. Note that it is still possible for an annotation type interface to inherit a default method from its implicit superinterface, java.lang.annotation.Annotation, though no such default method exists as of Java SE 14.

By convention, the only AnnotationTypeElementModifiers AnnotationElementModifiers that should be present on an annotation type element declaration are annotations.

The return type of a method declared in an annotation type interface must be one of the following, or a compile-time error occurs:

• A primitive type

• String

• Class or an invocation of Class (4.5)

• An enum type

• An annotation type

• An array type whose component type is one of the preceding types (10.1).

This rule precludes elements with nested array types, such as:

@interface Verboten {
    String[][] value();
}

The declaration of a method that returns an array is allowed to place the bracket pair that denotes the array type after the empty formal parameter list. This syntax is supported for compatibility with early versions of the Java programming language. It is very strongly recommended that this syntax is not used in new code.

It is a compile-time error if any method declared in an annotation type interface has a signature that is override-equivalent to that of any public or protected method declared in class Object or in the interface java.lang.annotation.Annotation.

It is a compile-time error if an annotation type declaration a declaration of an annotation interface T contains an element of type T, either directly or indirectly.

For example, this is illegal:

@interface SelfRef { SelfRef value(); }

and so is this:

@interface Ping { Pong value(); }
@interface Pong { Ping value(); }

An annotation type interface with no elements is called a marker annotation type interface.

An annotation type interface with one element is called a single-element annotation type interface.

By convention, the name of the sole element in a single-element annotation type interface is value. Linguistic support for this convention is provided by single-element annotations (9.7.3).

/**
 * Describes the "request-for-enhancement" (RFE)
 * that led to the presence of the annotated API element.
 */
@interface RequestForEnhancement {
    int    id();        // Unique ID number associated with RFE
    String synopsis();  // Synopsis of RFE
    String engineer();  // Name of engineer who implemented RFE
    String date();      // Date RFE was implemented
}

/**
 * An annotation with this type indicates that the 
 * specification of the annotated API element is 
 * preliminary and subject to change.
 */
@interface Preliminary {}

/**
 * Associates a copyright notice with the annotated API element.
 */
@interface Copyright {
    String value();
}

/**
 * Associates a list of endorsers with the annotated class.
 */
@interface Endorsers {
    String[] value();
}

interface Formatter {}

// Designates a formatter to pretty-print the annotated class
@interface PrettyPrinter {
    Class<? extends Formatter> value();
}

/**
 * Indicates the author of the annotated program element.
 */
@interface Author {
    Name value();
}
/**

 * A person's name.  This annotation type is not designed
 * to be used directly to annotate program elements, but to
 * define elements of other annotation types.

 * A person's name.  This annotation interface is not designed
 * to be used directly to annotate program elements, but to
 * define elements of other annotation interfaces.

*/
@interface Name {
   String first();
   String last();
}

@interface Quality {
    enum Level { BAD, INDIFFERENT, GOOD }
    Level value();
}

9.6.2 Defaults for Annotation Type Elements

An annotation type element declaration may have a default value, specified by following the element's (empty) parameter list with the keyword default and an ElementValue (9.7.1).

DefaultValue:

default ElementValue

It is a compile-time error if the type of the element is not commensurate (9.7) with the default value specified.

Default values are not compiled into annotations, but rather applied dynamically at the time annotations are read. Thus, changing a default value affects annotations even in classes that were compiled before the change was made (presuming these annotations lack an explicit value for the defaulted element).

@interface RequestForEnhancementDefault {
    int    id();       // No default - must be specified in 
                       // each annotation
    String synopsis(); // No default - must be specified in 
                       // each annotation
    String engineer()  default "[unassigned]";
    String date()      default "[unimplemented]";
}

9.6.3 Repeatable Annotation Types Interfaces

An annotation type interface T is repeatable if its declaration is (meta-)annotated with an @Repeatable annotation (9.6.4.8) whose value element indicates a containing annotation type interface of T.

An annotation type interface TC is a containing annotation type interface of T if all of the following are true:

1. TC declares a value() method element whose return type is T[].

2. Any methods elements declared by TC other than value() have a default value.

3. TC is retained for at least as long as T, where retention is expressed explicitly or implicitly with the @Retention annotation (9.6.4.2). Specifically:

   • If the retention of TC is java.lang.annotation.RetentionPolicy.SOURCE, then the retention of T is java.lang.annotation.RetentionPolicy.SOURCE.

   • If the retention of TC is java.lang.annotation.RetentionPolicy.CLASS, then the retention of T is either java.lang.annotation.RetentionPolicy.CLASS or java.lang.annotation.RetentionPolicy.SOURCE.

   • If the retention of TC is java.lang.annotation.RetentionPolicy.RUNTIME, then the retention of T is java.lang.annotation.RetentionPolicy.SOURCE, java.lang.annotation.RetentionPolicy.CLASS, or java.lang.annotation.RetentionPolicy.RUNTIME.

4. T is applicable to at least the same kinds of program element as TC (9.6.4.1). Specifically, if the kinds of program element where T is applicable are denoted by the set m₁, and the kinds of program element where TC is applicable are denoted by the set m₂, then each kind in m₂ must occur in m₁, except that:

   • If the kind in m₂ is java.lang.annotation.ElementType.ANNOTATION_TYPE, then at least one of java.lang.annotation.ElementType.ANNOTATION_TYPE or java.lang.annotation.ElementType.TYPE or java.lang.annotation.ElementType.TYPE_USE must occur in m₁.

   • If the kind in m₂ is java.lang.annotation.ElementType.TYPE, then at least one of java.lang.annotation.ElementType.TYPE or java.lang.annotation.ElementType.TYPE_USE must occur in m₁.

   • If the kind in m₂ is java.lang.annotation.ElementType.TYPE_PARAMETER, then at least one of java.lang.annotation.ElementType.TYPE_PARAMETER or java.lang.annotation.ElementType.TYPE_USE must occur in m₁.

   This clause implements the policy that an annotation type interface may be repeatable on only some of the kinds of program element where it is applicable.

5. If the declaration of T has a (meta-)annotation that corresponds to java.lang.annotation.Documented, then the declaration of TC must have a (meta-)annotation that corresponds to java.lang.annotation.Documented.

   Note that it is permissible for TC to be @Documented while T is not @Documented.

6. If the declaration of T has a (meta-)annotation that corresponds to java.lang.annotation.Inherited, then the declaration of TC must have a (meta)-annotation that corresponds to java.lang.annotation.Inherited.

   Note that it is permissible for TC to be @Inherited while T is not @Inherited.

It is a compile-time error if an annotation type interface T is (meta-)annotated with an @Repeatable annotation whose value element indicates a type which is not a containing annotation type interface of T.

import java.lang.annotation.Repeatable;

@Repeatable(FooContainer.class)
@interface Foo {}

@interface FooContainer { Object[] value(); }

The @Repeatable annotation cannot be repeated, so only one containing annotation type interface can be specified by a repeatable annotation type interface.

Allowing more than one containing annotation type interface to be specified would cause an undesirable choice at compile time, when multiple annotations of the repeatable annotation type interface are logically replaced with a container annotation (9.7.5).

An annotation type interface can be the containing annotation type interface of at most one annotation type interface.

This is implied by the requirement that if the declaration of an annotation type interface T specifies a containing annotation type interface of TC, then the value() method of TC has a return type involving T, specifically T[].

An annotation type interface cannot specify itself as its containing annotation type interface.

This is implied by the requirement on the value() method of the containing annotation type interface. Specifically, if an annotation type interface A specified itself (via @Repeatable) as its containing annotation type interface, then the return type of A's value() method would have to be A[]; but this would cause a compile-time error since an annotation type interface cannot refer to itself in its elements (9.6.1). More generally, two annotation types interfaces cannot specify each other to be their containing annotation types interfaces, because cyclic annotation type interface declarations are illegal.

An annotation type interface TC may be the containing annotation type interface of some annotation type interface T while also having its own containing annotation type interface TC '. That is, a containing annotation type interface may itself be a repeatable annotation type interface.

import java.lang.annotation.Target;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;

@Target(ElementType.TYPE)
@Repeatable(FooContainer.class)
@interface Foo {}

@Target(ElementType.ANNOTATION_TYPE)
@interface FooContainer {
    Foo[] value();
}

@Foo @Foo
@interface Anno {}

@Foo @Foo
interface Intf {}

import java.lang.annotation.Repeatable;

// Foo: Repeatable annotation type

// Foo: Repeatable annotation interface

@Repeatable(FooContainer.class)
@interface Foo { int value(); }

// FooContainer: Containing annotation type of Foo
//               Also a repeatable annotation type itself

// FooContainer: Containing annotation interface of Foo
//               Also a repeatable annotation interface itself

@Repeatable(FooContainerContainer.class)
@interface FooContainer { Foo[] value(); }

// FooContainerContainer: Containing annotation type of FooContainer

// FooContainerContainer: Containing annotation interface of FooContainer

@interface FooContainerContainer { FooContainer[] value(); }

@FooContainer({@Foo(1)}) @FooContainer({@Foo(2)})
class Test {}

9.6.4 Predefined Annotation Types Interfaces

Several annotation types interfaces are predefined in the libraries of the Java SE Platform. Some of these predefined annotation types interfaces have special semantics. These semantics are specified in this section. This section does not provide a complete specification for the predefined annotations contained here in; that is the role of the appropriate API specifications. Only those semantics that require special behavior on the part of a Java compiler or Java Virtual Machine implementation are specified here.

9.6.4.1 @Target

An annotation of type java.lang.annotation.Target is used on the declaration of an annotation type interface 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 interfaces 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 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, and annotation type declarations (8.1.1, 9.1.1, 8.5, 9.5, 8.9, 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 interfaces) (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

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 interface T, then T is applicable in all nine declaration contexts and in all 16 type contexts.

9.6.4.2 @Retention

Annotations may be present only in source code, or they may be present in the binary form of a class or interface. An annotation that is present in the binary form may or may not be available at run time via the reflection libraries of the Java SE Platform. The annotation type interface java.lang.annotation.Retention is used to choose among these possibilities.

If an annotation a corresponds to a type an annotation interface T, and T has a (meta-)annotation m that corresponds to java.lang.annotation.Retention, then:

• If m has an element whose value is java.lang.annotation.RetentionPolicy.SOURCE, then a Java compiler must ensure that a is not present in the binary representation of the class or interface in which a appears.

• If m has an element whose value is java.lang.annotation.RetentionPolicy.CLASS or java.lang.annotation.RetentionPolicy.RUNTIME, then a Java compiler must ensure that a is represented in the binary representation of the class or interface in which a appears, unless a annotates a local variable declaration or a annotates a formal parameter declaration of a lambda expression.

  An annotation on the declaration of a local variable, or on the declaration of a formal parameter of a lambda expression, is never retained in the binary representation. In contrast, an annotation on the type of a local variable, or on the type of a formal parameter of a lambda expression, is retained in the binary representation if the annotation type interface specifies a suitable retention policy.

  Note that it is not illegal for an annotation type interface to be meta-annotated with @Target(java.lang.annotation.ElementType.LOCAL_VARIABLE) and @Retention(java.lang.annotation.RetentionPolicy.CLASS) or @Retention(java.lang.annotation.RetentionPolicy.RUNTIME).

  If m has an element whose value is java.lang.annotation.RetentionPolicy.RUNTIME, the reflection libraries of the Java SE Platform must make a available at run time.

If T does not have a (meta-)annotation m that corresponds to java.lang.annotation.Retention, then a Java compiler must treat T as if it does have such a meta-annotation m with an element whose value is java.lang.annotation.RetentionPolicy.CLASS.

9.6.4.3 @Inherited

The annotation type interface java.lang.annotation.Inherited is used to indicate that annotations on a class C corresponding to a given annotation type interface are inherited by subclasses of C.

9.6.4.4 @Override

Programmers occasionally overload a method declaration when they mean to override it, leading to subtle problems. The annotation type interface Override supports early detection of such problems.

The classic example concerns the equals method. Programmers write the following in class Foo:

public boolean equals(Foo that) { ... }

when they mean to write:

public boolean equals(Object that) { ... }

This is perfectly legal, but class Foo inherits the equals implementation from Object, which can cause some subtle bugs.

If a method declaration in type class or interface T is annotated with @Override, but the method does not override from T a method declared in a supertype of T (8.4.8.1, 9.4.1.1), or is not override-equivalent to a public method of Object (4.3.2, 8.4.2), then a compile-time error occurs.

This behavior differs from Java SE 5.0, where @Override only caused a compile-time error if applied to a method that implemented a method from a superinterface that was not also present in a superclass.

The clause about overriding a public method is motivated by use of @Override in an interface. Consider the following type declarations:

class Foo     { @Override public int hashCode() {..} }
interface Bar { @Override int hashCode(); }

The use of @Override in the class declaration is legal by the first clause, because Foo.hashCode overrides from Foo the method Object.hashCode.

For the interface declaration, consider that while an interface does not have Object as a supertype, an interface does have public abstract members that correspond to the public members of Object (9.2). If an interface chooses to declare them explicitly (that is, to declare members that are override-equivalent to public methods of Object), then the interface is deemed to override them, and use of @Override is allowed.

However, consider an interface that attempts to use @Override on a clone method: (finalize could also be used in this example)

interface Quux { @Override Object clone(); }

Because Object.clone is not public, there is no member called clone implicitly declared in Quux. Therefore, the explicit declaration of clone in Quux is not deemed to "implement" any other method, and it is erroneous to use @Override. (The fact that Quux.clone is public is not relevant.)

In contrast, a class declaration that declares clone is simply overriding Object.clone, so is able to use @Override:

class Beep { @Override protected Object clone() {..} }

9.6.4.5 @SuppressWarnings

Java compilers are increasingly capable of issuing helpful "lint-like" warnings. To encourage the use of such warnings, there should be some way to disable a warning in a part of the program when the programmer knows that the warning is inappropriate.

The annotation type interface SuppressWarnings supports programmer control over warnings otherwise issued by a Java compiler. It defines a single element that is an array of String.

If a declaration is annotated with @SuppressWarnings(value = {S1, ..., Sk}), then a Java compiler must suppress (that is, not report) any warning specified by one of S₁ ... S_k if that warning would have been generated as a result of the annotated declaration or any of its parts.

The Java programming language defines four kinds of warnings that can be specified by @SuppressWarnings:

• Unchecked warnings (4.8, 5.1.6, 5.1.9, 8.4.1, 8.4.8.3, 15.12.4.2, 15.13.2, 15.27.3) are specified by the string "unchecked".

• Deprecation warnings (9.6.4.6) are specified by the string "deprecation".

• Removal warnings (9.6.4.6) are specified by the string "removal".

• Preview warnings (1.5) are specified by the string "preview".

Any other string specifies a non-standard warning. A Java compiler must ignore any such string that it does not recognize.

Compiler vendors are encouraged to document the strings they support for @SuppressWarnings, and to cooperate to ensure that the same strings are recognized across multiple compilers.

9.6.4.6 @Deprecated

Programmers are sometimes discouraged from using certain program elements (modules, types classes, interfaces, fields, methods, and constructors) because they are dangerous or because a better alternative exists. The annotation type interface Deprecated allows a compiler to warn about uses of these program elements.

A deprecated program element is a module, type class, interface, field, method, or constructor whose declaration is annotated with @Deprecated. The manner in which a program element is deprecated depends on the value of the forRemoval element of the annotation:

• If forRemoval=false (the default), then the program element is ordinarily deprecated.

  An ordinarily deprecated program element is not intended to be removed in a future release, but programmers should nevertheless migrate away from using it.

• If forRemoval=true, then the program element is terminally deprecated.

  A terminally deprecated program element is intended to be removed in a future release. Programmers should stop using it or risk source and binary incompatibilities (13.2) when upgrading to a newer release.

A Java compiler must produce a deprecation warning when an ordinarily deprecated program element is used (overridden, invoked, or referenced by name) in the declaration of a program element (whether explicitly or implicitly declared), unless:

• The use is within a declaration that is itself deprecated, either ordinarily or terminally; or

• The use is within a declaration that is annotated to suppress deprecation warnings (9.6.4.5); or

• The declaration where the use appears and the declaration of the ordinarily deprecated program element are both within the same outermost class; or

• The use is within an import declaration that imports the ordinarily deprecated type or member; or

• The use is within an exports or opens directive (7.7.2).

A Java compiler must produce a removal warning when a terminally deprecated program element is used (overridden, invoked, or referenced by name) in the declaration of a program element (whether explicitly or implicitly declared), unless:

• The use is within a declaration that is annotated to suppress removal warnings (9.6.4.5); or

• The declaration where the use appears and the declaration of the terminally deprecated program element are both within the same outermost class; or

• The use is within an import declaration that imports the terminally deprecated type class, interface, or member; or

• The use is within an exports or opens directive.

Terminal deprecation is sufficiently urgent that the use of a terminally deprecated element will cause a removal warning even if the using element is itself deprecated, since there is no guarantee that both elements will be removed at the same time. To dismiss the warning but continue using the element, the programmer must manually acknowledge the risk via an @SuppressWarnings annotation.

No deprecation warning or removal warning is produced when:

• a local variable or formal parameter is used (referenced by name), even if the declaration of the local variable or formal parameter is annotated with @Deprecated.

• the name of a package is used (referenced by a qualified type name, or an import declaration, or an exports or opens directive), even if the declaration of the package is annotated with @Deprecated.

• the name of a module is used by a qualified exports or opens directive, even if the declaration of the friend module is annotated with @Deprecated.

A module declaration that exports or opens a package is usually controlled by the same programmer or team that controls the package's declaration. As such, there is little benefit in warning that the package declaration is annotated with @Deprecated when the package is exported or opened by the module declaration. In contrast, a module declaration that exports or opens a package to a friend module is usually not controlled by the same programmer or team that controls the friend module. Simply exporting or opening the package does not make the module declaration rely on the friend module, so there is little value in warning if the friend module is deprecated; the programmer of the module declaration would almost always wish to suppress such a warning.

The only implicit declaration that can cause a deprecation warning or removal warning is a container annotation (9.7.5). Namely, if T is a repeatable annotation type interface and TC is its containing annotation type interface, and TC is deprecated, then repeating the @T annotation will cause a warning. The warning is due to the implicit @TC container annotation. It is strongly discouraged to deprecate a containing annotation type interface without deprecating the corresponding repeatable annotation type interface.

9.6.4.7 @SafeVarargs

A variable arity parameter with a non-reifiable element type (4.7) can cause heap pollution (4.12.2) and give rise to compile-time unchecked warnings (5.1.9). Such warnings are uninformative if the body of the variable arity method is well-behaved with respect to the variable arity parameter.

The annotation type interface SafeVarargs, when used to annotate a method or constructor declaration, makes a programmer assertion that prevents a Java compiler from reporting unchecked warnings for the declaration or invocation of a variable arity method or constructor where the compiler would otherwise do so due to the variable arity parameter having a non-reifiable element type.

The annotation @SafeVarargs has non-local effects because it suppresses unchecked warnings at method invocation expressions, in addition to an unchecked warning pertaining to the declaration of the variable arity method itself (8.4.1). In contrast, the annotation @SuppressWarnings("unchecked") has local effects because it only suppresses unchecked warnings pertaining to the declaration of a method.

The canonical target for @SafeVarargs is a method like java.util.Collections.addAll, whose declaration starts with:

public static <T> boolean
  addAll(Collection<? super T> c, T... elements)

The variable arity parameter has declared type T[], which is non-reifiable. However, the method fundamentally just reads from the input array and adds the elements to a collection, both of which are safe operations with respect to the array. Therefore, any compile-time unchecked warnings at method invocation expressions for java.util.Collections.addAll are arguably spurious and uninformative. Applying @SafeVarargs to the method declaration prevents generation of these unchecked warnings at the method invocation expressions.

It is a compile-time error if a fixed arity method or constructor declaration is annotated with the annotation @SafeVarargs.

It is a compile-time error if a variable arity method declaration that is neither static nor final nor private is annotated with the annotation @SafeVarargs.

Since @SafeVarargs is only applicable to static methods, final and/or private instance methods, and constructors, the annotation is not usable where method overriding occurs. Annotation inheritance only works for annotations on classes (not on methods, interfaces, or constructors), so an @SafeVarargs-style annotation cannot be passed through instance methods in classes or through interfaces.

9.6.4.8 @Repeatable

The annotation type interface java.lang.annotation.Repeatable is used on the declaration of a repeatable annotation type interface to indicate its containing annotation type interface (9.6.3).

Note that an @Repeatable meta-annotation on the declaration of T, indicating TC, is not sufficient to make TC the containing annotation type interface of T. There are numerous well-formedness rules for TC to be considered the containing annotation type interface of T.

9.6.4.9 @FunctionalInterface

The annotation type interface FunctionalInterface is used to indicate that an interface is meant to be a functional interface (9.8). It facilitates early detection of inappropriate method declarations appearing in or inherited by an interface that is meant to be functional.

It is a compile-time error if an interface declaration is annotated with @FunctionalInterface but is not, in fact, a functional interface.

Because some interfaces are functional incidentally, it is not necessary or desirable that all declarations of functional interfaces be annotated with @FunctionalInterface.

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 14 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 class or interface (7.6) is its canonical name (6.7).

   • The binary name of a member type class or interface (8.5, 9.5) consists of the binary name of its immediately enclosing type class or interface, 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 class or interface, 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 class or interface, 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 class or interface, 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 class or interface 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 class 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 class or interface.

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 class or interface 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 class or interface 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 class or interface must contain sufficient information to recover its canonical name (6.7).

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

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

10. Every class or interface must contain symbolic references to all of its member types classes and interfaces (8.5, 9.5), and to all local and anonymous classes that appear in its methods, constructors, static initializers, instance initializers, and field initializers other nested classes and interfaces declared within its body.

    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 an inner class (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 class (8.9.3).

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)

• Anonymous constructors (15.9.5.1)

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

• Certain public fields of enum types classes (8.9.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 class or interface 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 classes and interfaces indicated by the directive's with clause (7.7.4). Also, the specification must give a symbolic reference to the name of the type class or interface 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.26 Evolution of Enums Enum Classes

Adding or reordering constants in an enum declaration will not break compatibility with pre-existing binaries.

If a pre-existing binary attempts to access an enum constant that no longer exists, the client will fail at run time with a NoSuchFieldError. Therefore such a change is not recommended for widely distributed enums.

Removing an enum constant will remove the corresponding implicit field declaration, with consequences described in 13.4.8.

In all other respects, the binary compatibility rules for enums enum classes are identical to those for classes normal classes.

13.5 Evolution of Interfaces

13.5.7 Evolution of Annotation Types Interfaces

Annotation types interfaces behave exactly like any other interface. Adding or removing an element from an annotation type interface is analogous to adding or removing a method. There are important considerations governing other changes to annotation types interfaces, such as making an annotation type interface repeatable (9.6.3), but these have no effect on the linkage of binaries by the Java Virtual Machine. Rather, such changes affect the behavior of reflective APIs that manipulate annotations. The documentation of these APIs specifies their behavior when various changes are made to the underlying annotation types interfaces.

Adding or removing annotations has no effect on the correct linkage of the binary representations of programs in the Java programming language.

Chapter 15: Expressions

15.8 Primary Expressions

15.8.4 Qualified this

Any lexically enclosing instance (8.1.3) can be referred to by explicitly qualifying the keyword this.

Let T be the type denoted by TypeName. Let n be an integer such that T is the n'th lexically enclosing type class or interface declaration of the class or interface in which the qualified this expression appears.

The value of an expression of the form TypeName.this is the n'th lexically enclosing instance of this.

The type of the expression is T.

It is a compile-time error if the expression occurs in a class or interface which is not an inner class of class T or T itself.

15.9 Class Instance Creation Expressions

15.9.2 Determining Enclosing Instances

Let C be the class being instantiated, and let i be the instance being created. If C is an inner class, then i may have an immediately enclosing instance (8.1.3), determined as follows:

• If C is an anonymous class, then:

  • If the class instance creation expression occurs in a static context, then i has no immediately enclosing instance.

  • Otherwise, the immediately enclosing instance of i is this.

• If C is a local class, then:

  • If C occurs in a static context, then i has no immediately enclosing instance.

  • Otherwise, if the class instance creation expression occurs in a static context, then a compile-time error occurs.

  • Otherwise, let O be the immediately enclosing class or interface declaration of C. Let n be an integer such that O is the n'th lexically enclosing type class or interface declaration of the class or interface in which the class instance creation expression appears.

    The immediately enclosing instance of i is the n'th lexically enclosing instance of this.

• If C is an inner member class, then:

  • If the class instance creation expression is unqualified, then:

    • If the class instance creation expression occurs in a static context, then a compile-time error occurs.

    • Otherwise, if C is a member of a class enclosing the class or interface in which the class instance creation expression appears, then let O be the immediately enclosing class of which C is a member. Let n be an integer such that O is the n'th lexically enclosing type class or interface declaration of the class or interface in which the class instance creation expression appears.

      The immediately enclosing instance of i is the n'th lexically enclosing instance of this.

    • Otherwise, a compile-time error occurs.

  • If the class instance creation expression is qualified, then the immediately enclosing instance of i is the object that is the value of the Primary expression or the ExpressionName.

If C is an anonymous class, and its direct superclass S is an inner class, then i may have an immediately enclosing instance with respect to S, determined as follows:

• If S is a local class, then:

  • If S occurs in a static context, then i has no immediately enclosing instance with respect to S.

  • Otherwise, if the class instance creation expression occurs in a static context, then a compile-time error occurs.

  • Otherwise, let O be the immediately enclosing type class or interface declaration of S. Let n be an integer such that O is the n'th lexically enclosing type class or interface declaration of the class or interface in which the class instance creation expression appears.

    The immediately enclosing instance of i with respect to S is the n'th lexically enclosing instance of this.

• If S is an inner member class, then:

  • If the class instance creation expression is unqualified, then:

    • If the class instance creation expression occurs in a static context, then a compile-time error occurs.

    • Otherwise, if S is a member of a class enclosing the class or interface in which the class instance creation expression appears, then let O be the immediately enclosing class of which S is a member. Let n be an integer such that O is the n'th lexically enclosing type class or interface declaration of the class or interface in which the class instance creation expression appears.

      The immediately enclosing instance of i with respect to S is the n'th lexically enclosing instance of this.

    • Otherwise, a compile-time error occurs.

  • If the class instance creation expression is qualified, then the immediately enclosing instance of i with respect to S is the object that is the value of the Primary expression or the ExpressionName.

15.12 Method Invocation Expressions

15.12.1 Compile-Time Step 1: Determine Class or Interface to Search

The first step in processing a method invocation at compile time is to figure out the name of the method to be invoked and which class or interface to search for definitions of methods of that name.

The name of the method is specified by the MethodName or Identifier which immediately precedes the left parenthesis of the MethodInvocation.

For the class or interface to search, there are six cases to consider, depending on the form that precedes the left parenthesis of the MethodInvocation:

• If the form is MethodName, that is, just an Identifier, then:

  If the Identifier appears in the scope of a method declaration with that name (6.3, 6.4.1), then:

  • If there is an enclosing type class or interface declaration of which that method is a member, let T be the innermost such type class or interface declaration. The class or interface to search is T.

    This search policy is called the "comb rule". It effectively looks for methods in a nested class's superclass hierarchy before looking for methods in an enclosing class and its superclass hierarchy. See 6.5.7.1 for an example.

  • Otherwise, the method declaration may be in scope due to one or more single-static-import or static-import-on-demand declarations. There is no class or interface to search, as the method to be invoked is determined later (15.12.2.1).

• If the form is TypeName . [TypeArguments] Identifier, then the type to search is the type denoted by TypeName.

• If the form is ExpressionName . [TypeArguments] Identifier, then the class or interface to search is the declared type T of the variable denoted by ExpressionName if T is a class or interface type, or the upper bound of T if T is a type variable.

• If the form is Primary . [TypeArguments] Identifier, then let T be the type of the Primary expression. The class or interface to search is T if T is a class or interface type, or the upper bound of T if T is a type variable.

  It is a compile-time error if T is not a reference type.

• If the form is super . [TypeArguments] Identifier, then the class to search is the superclass of the class whose declaration contains the method invocation.

  Let T be the type class or interface declaration immediately enclosing the method invocation. It is a compile-time error if T is the class Object or T is an interface.

• If the form is TypeName . super . [TypeArguments] Identifier, then:

  • It is a compile-time error if TypeName denotes neither a class nor an interface.

  • If TypeName denote a class, C, then the class to search is the superclass of C.

    It is a compile-time error if C is not a lexically enclosing type class or interface declaration of the current class or interface, or if C is the class Object.

    Let T be the type class or interface declaration immediately enclosing the method invocation. It is a compile-time error if T is the class Object.

  • Otherwise, TypeName denotes the interface to be searched, I.

    Let T be the type class or interface declaration immediately enclosing the method invocation. It is a compile-time error if I is not a direct superinterface of T, or if there exists some other direct superclass or direct superinterface of T, J, such that J is a subtype of I.

The TypeName . super syntax is overloaded: traditionally, the TypeName refers to a lexically enclosing type class declaration which is a class, and the target is the superclass of this class, as if the invocation were an unqualified super in the lexically enclosing type class declaration.

class Superclass {
    void foo() { System.out.println("Hi"); }
}

class Subclass1 extends Superclass {
    void foo() { throw new UnsupportedOperationException(); }

    Runnable tweak = new Runnable() {
        void run() {
            Subclass1.super.foo();  // Gets the 'println' behavior
        }
    };
}

To support invocation of default methods in superinterfaces, the TypeName may also refer to a direct superinterface of the current class or interface, and the target is that superinterface.

interface Superinterface {
    default void foo() { System.out.println("Hi"); }
}

class Subclass2 implements Superinterface {
    void foo() { throw new UnsupportedOperationException(); }

    void tweak() {
        Superinterface.super.foo();  // Gets the 'println' behavior
    }
}

No syntax supports a combination of these forms, that is, invoking a superinterface method of a lexically enclosing type class declaration which is a class, as if the invocation were of the form InterfaceName . super in the lexically enclosing type class declaration.

class Subclass3 implements Superinterface {
    void foo() { throw new UnsupportedOperationException(); }

    Runnable tweak = new Runnable() {
        void run() {
            Subclass3.Superinterface.super.foo();  // Illegal
        }
    };
}

A workaround is to introduce a private method in the lexically enclosing type class declaration, that performs the interface super call.

15.12.3 Compile-Time Step 3: Is the Chosen Method Appropriate?

If there is a most specific method declaration for a method invocation, it is called the compile-time declaration for the method invocation.

It is a compile-time error if an argument to a method invocation is not compatible with its target type, as derived from the invocation type of the compile-time declaration.

If the compile-time declaration is applicable by variable arity invocation, then where the last formal parameter type of the invocation type of the method is F_n[], it is a compile-time error if the type which is the erasure of F_n is not accessible (6.6) at the point of invocation.

If the compile-time declaration is void, then the method invocation must be a top level expression (that is, the Expression in an expression statement or in the ForInit or ForUpdate part of a for statement), or a compile-time error occurs. Such a method invocation produces no value and so must be used only in a situation where a value is not needed.

In addition, whether the compile-time declaration is appropriate may depend on the form of the method invocation expression before the left parenthesis, as follows:

• If the form is MethodName - that is, just an Identifier - and the compile-time declaration is an instance method, then:

  • It is a compile-time error if the method invocation occurs in a static context (8.1.3).

  • Otherwise, let C be the immediately enclosing class of which the compile-time declaration is a member. If the method invocation is not directly enclosed by C or an inner class of C, then a compile-time error occurs.

• If the form is TypeName . [TypeArguments] Identifier, then the compile-time declaration must be static, or a compile-time error occurs.

• If the form is ExpressionName . [TypeArguments] Identifier or Primary . [TypeArguments] Identifier, then the compile-time declaration must not be a static method declared in an interface, or a compile-time error occurs.

• If the form is super . [TypeArguments] Identifier, then:

  • It is a compile-time error if the compile-time declaration is abstract.

  • It is a compile-time error if the method invocation occurs in a static context.

• If the form is TypeName . super . [TypeArguments] Identifier, then:

  • It is a compile-time error if the compile-time declaration is abstract.

  • It is a compile-time error if the method invocation occurs in a static context.

  • If TypeName denotes a class C, then if the method invocation is not directly enclosed by C or an inner class of C, a compile-time error occurs.

  • If TypeName denotes an interface, let T be the type class or interface declaration immediately enclosing the method invocation. A compile-time error occurs if there exists a method, distinct from the compile-time declaration, that overrides (9.4.1) the compile-time declaration from a direct superclass or direct superinterface of T.

    In the case that a superinterface overrides a method declared in a grandparent interface, this rule prevents the child interface from "skipping" the override by simply adding the grandparent to its list of direct superinterfaces. The appropriate way to access functionality of a grandparent is through the direct superinterface, and only if that interface chooses to expose the desired behavior. (Alternately, the programmer is free to define an additional superinterface that exposes the desired behavior with a super method invocation.)

...