Chapter 8. Classes

Anabstract class is a class that is incomplete, or to be considered incomplete.

It is a compile-time error if an attempt is made to create an instance of anabstract class using a class instance creation expression (§15.9.1).

A subclass of anabstract class that is not itselfabstract may be instantiated, resulting in the execution of a constructor for theabstract class and, therefore, the execution of the field initializers for instance variables of that class.

A normal class may haveabstract methods, that is, methods that are declared but not yet implemented (§8.4.3.1), only if it is anabstract class. It is a compile-time error if a normal class that is notabstract has anabstract method.

A classC hasabstract methods if either of the following is true:

It is a compile-time error to declare anabstract class type such that it is not possible to create a subclass that implements all of itsabstract methods. This situation can occur if the class would have as members twoabstract methods that have the same method signature (§8.4.2) but return types for which no type is return-type-substitutable with both (§8.4.5).

abstract class Point {    int x = 1, y = 1;    void move(int dx, int dy) {        x += dx;        y += dy;        alert();    }    abstract void alert();}abstract class ColoredPoint extends Point {    int color;}class SimplePoint extends Point {    void alert() { }}

Point p = new Point();

Point p = new SimplePoint();

interface Colorable {    void setColor(int color);}abstract class Colored implements Colorable {    public abstract int setColor(int color);}

A class type should be declaredabstract only if the intent is that subclasses can be created to complete the implementation. If the intent is simply to prevent instantiation of a class, the proper way to express this is to declare a constructor (§8.8.10) of no arguments, make itprivate, never invoke it, and declare no other constructors. A class of this form usually contains class methods and variables.

public final class Math {    private Math() { }  // never instantiate this class    . . . declarations of class variables and methods . . .}

A class can be declaredsealed if all its direct subclasses are known when the class is declared (§8.1.6), and no other direct subclasses are desired or required.

Explicit and exhaustive control over a class's direct subclasses is useful when the class hierarchy is used to model the kinds of values in a domain, rather than as a mechanism for code inheritance and reuse. The direct subclasses may themselves be declaredsealed in order to further control the class hierarchy.

A class can be declaredfinal if its definition is complete and no subclasses are desired or required.

It is a compile-time error if a class is declared bothfinal andabstract, because the implementation of such a class could never be completed (§8.1.1.1).

Because afinal class never has any subclasses, the methods of afinal class are never overridden (§8.4.8.1).

A class isfreely extensible if its direct superclass is notsealed (§8.1.4), and none of its direct superinterfaces aresealed (§8.1.5), and it is neithersealed norfinal itself.

A class that has asealed direct superclass or asealed direct superinterface is freely extensible if and only if it is declarednon-sealed.

It is a compile-time error if a class has asealed direct superclass or asealed direct superinterface, and is not declaredfinal,sealed, ornon-sealed either explicitly or implicitly.

Thus, an effect of thesealed keyword is to force all direct subclasses to explicitly declare whether they arefinal,sealed, ornon-sealed. This avoids accidentally exposing a sealed class hierarchy to unwanted subclassing.

An enum class is either implicitlyfinal or implicitlysealed, so it can implement asealed interface. Similarly, a record class is implicitlyfinal, so it can also implement a sealed interface.

It is a compile-time error if a class is declarednon-sealed but has neither asealed direct superclass nor asealed direct superinterface.

Thus, a subclass of anon-sealed class cannot itself be declarednon-sealed.

Thestrictfp modifier on a class declaration is obsolete and should not be used in new code. Its presence or absence has no effect at compile time or run time.

Thestatic modifier specifies that a nested class is not an inner class (§8.1.3). Just as astatic method of a class has no current instance of the class in its body, astatic nested class has no immediately enclosing instance in its body.

References from astatic nested class to type parameters, instance variables, local variables, formal parameters, exception parameters, or instance methods of lexically enclosing class, interface, or method declarations are disallowed (§6.5.5.1,§6.5.6.1, and§15.12.3).

Thestatic modifier does not pertain to all nested classes. It pertains only to member classes, whose declarations may use thestatic modifier, and not to local classes or anonymous classes, whose declarations may not use thestatic modifier (§14.3,§15.9.5). However, some local classes are implicitlystatic, namely local enum classes and local record classes, because all nested enum classes and nested record classes are implicitlystatic (§8.9,§8.10).

For instance, executing the code:

Vector<String>  x = new Vector<String>();Vector<Integer> y = new Vector<Integer>();boolean b = x.getClass() == y.getClass();

will result in the variableb holding the valuetrue.

Example 8.1.2-1. Mutually Recursive Type Variable Bounds

interface ConvertibleTo<T> {    T convert();}class ReprChange<T extends ConvertibleTo<S>,                 S extends ConvertibleTo<T>> {    T t;    void set(S s) { t = s.convert();    }    S get()       { return t.convert(); }}

Example 8.1.2-2. Nested Generic Classes

class Seq<T> {    T      head;    Seq<T> tail;    Seq() { this(null, null); }    Seq(T head, Seq<T> tail) {        this.head = head;        this.tail = tail;    }    boolean isEmpty() { return tail == null; }    class Zipper<S> {        Seq<Pair<T,S>> zip(Seq<S> that) {            if (isEmpty() || that.isEmpty()) {                return new Seq<Pair<T,S>>();            } else {                Seq<T>.Zipper<S> tailZipper =                    tail.new Zipper<S>();                return new Seq<Pair<T,S>>(                    new Pair<T,S>(head, that.head),                    tailZipper.zip(that.tail));            }        }    }}class Pair<T, S> {    T fst; S snd;    Pair(T f, S s) { fst = f; snd = s; }}class Test {    public static void main(String[] args) {        Seq<String> strs =            new Seq<String>(                "a",                new Seq<String>("b",                                new Seq<String>()));        Seq<Number> nums =            new Seq<Number>(                new Integer(1),                new Seq<Number>(new Double(1.5),                                new Seq<Number>()));        Seq<String>.Zipper<Number> zipper =            strs.new Zipper<Number>();        Seq<Pair<String,Number>> combined =            zipper.zip(nums);    }}

• a member class that is not explicitly or implicitlystatic (§8.5)

• a local class that is not implicitlystatic (§14.3)

• an anonymous class (§15.9.5)

• a member enum class (§8.9)

• a local enum class (§14.3)

• a member record class (§8.10)

• a local record class (§14.3)

• a member class of an interface (§9.5)

Example 8.1.3-1. Inner Class Declarations and Static Members

class HasStatic {    static int j = 100;}class Outer {    class Inner extends HasStatic {        static {            System.out.println("Hello from Outer.Inner");        }        static       int x = 3;        static final int y = 4;        static void hello() {            System.out.println("Hello from Outer.Inner.hello");        }        static class VeryNestedButNotInner            extends NestedButNotInner {}    }    static class NestedButNotInner {        int z = Inner.x;    }    interface NeverInner {}  // Implicitly static, so never inner}

• method declaration,

• field declaration,

• constructor declaration,

• instance initializer,

• static initializer, or

• explicit constructor invocation statement

• astatic method declaration (§8.4.3.2,§9.4)

• astatic field declaration (§8.3.1.1,§9.3)

• a static initializer (§8.7)

• an explicit constructor invocation statement (§8.8.7.1)

• this expressions (both unqualified and qualified) are disallowed (§15.8.3,§15.8.4).

• Field accesses, method invocations, and method references may not be qualified bysuper (§15.11.2,§15.12.3,§15.13.1).

• Unqualified references to instance variables of any lexically enclosing class or interface declaration are disallowed (§6.5.6.1).

• Unqualified invocations of instance methods of any lexically enclosing class or interface declaration are disallowed (§15.12.3).

• References to type parameters of any lexically enclosing class or interface declarations are disallowed (§6.5.5.1).

• References to type parameters, local variables, formal parameters, and exception parameters declared by methods or constructors of any lexically enclosing class or interface declarationthat is outside the immediately enclosing class or interface declaration are disallowed (§6.5.5.1,§6.5.6.1).

• Declarations of local normal classes (as opposed to local enum classes) and declarations of anonymous classes both specify classes that are inner, yet when instantiated have no immediately enclosing instances (§15.9.2).

• Class instance creation expressions that instantiate inner member classes must be qualified (§15.9).

Example 8.1.3-2. Inner Class Declarations

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

• The classObject has no direct superclass type.

• For a class other thanObject with a normal class declaration, the direct superclass type isObject.

• For an enum classE, the direct superclass type isEnum<E>.

• For a record classR, the direct superclass type isRecord.

• For an anonymous class, the direct superclass type is defined in§15.9.5.

• A is the direct superclass ofC.

• Where a classB is the direct superclass ofC,A is a superclass ofB, applying this definition recursively.

Example 8.1.4-1. Direct Superclasses and Subclasses

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

Example 8.1.4-2. Superclasses and Subclasses

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

• C directly depends onA.

• C directly depends on an interfaceI that depends (§9.1.3) onA.

• C directly depends on a classB that depends onA, applying this definition recursively.

Example 8.1.4-3. Class Depends on Itself

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

Example 8.1.5-1. Illegal Superinterfaces

class Redundant implements java.lang.Cloneable, Cloneable {    int x;}

• I is a direct superinterface ofC.

• C has some direct superinterfaceJ for whichI is a superinterface, using the definition of "superinterface of an interface" given in§9.1.3.

• I is a superinterface of the direct superclass ofC.

Example 8.1.5-2. Superinterfaces

interface Colorable {    void setColor(int color);    int getColor();}enum Finish { MATTE, GLOSSY }interface Paintable extends Colorable {    void setFinish(Finish finish);    Finish getFinish();}class Point { int x, y; }class ColoredPoint extends Point implements Colorable {    int color;    public void setColor(int color) { this.color = color; }    public int getColor() { return color; }}class PaintedPoint extends ColoredPoint implements Paintable {    Finish finish;    public void setFinish(Finish finish) {        this.finish = finish;    }    public Finish getFinish() { return finish; }}

Example 8.1.5-3. Illegal Multiple Inheritance of an Interface

interface I<T> {}class B implements I<Integer> {}class C extends B implements I<String> {}

Example 8.1.5-4. Implementing Methods of a Superinterface

interface Colorable {    void setColor(int color);    int getColor();}class Point { int x, y; };class ColoredPoint extends Point implements Colorable {    int color;}

interface Fish  { int getNumberOfScales(); }interface Piano { int getNumberOfScales(); }class Tuna implements Fish, Piano {    // You can tune a piano, but can you tuna fish?    public int getNumberOfScales() { return 91; }}

interface Fish       { int    getNumberOfScales(); }interface StringBass { double getNumberOfScales(); }class Bass implements Fish, StringBass {    // This declaration cannot be correct,    // no matter what type is used.    public ?? getNumberOfScales() { return 91; }}

The canonical name of a class does not need to be used in apermits clause, but apermits clause can only specify a class once. For example, the following program fails to compile:

package p;sealed class A     permits B, C, p.B {}  // errornon-sealed class B extends A {}non-sealed class C extends A {}

• IfC is not an enum class, then its permitted direct subclasses are those classes declared in the same compilation unit asC (§7.3) which have a canonical name (§6.7) and whose direct superclass isC.

  That is, the permitted direct subclasses are inferred as the classes in the same compilation unit that specifyC as their direct superclass. The requirement for a canonical name means that no local classes or anonymous classes will be considered.

  It is a compile-time error if the declaration of asealed classC lacks apermits clause andC has no permitted direct subclasses.

• IfC is an enum class, then its permitted direct subclasses, if any, are specified in§8.9.

class Point {    int x, y;    private Point() { reset(); }    Point(int x, int y) { this.x = x; this.y = y; }    private void reset() { this.x = 0; this.y = 0; }}class ColoredPoint extends Point {    int color;    void clear() { reset(); }  // error}class Test {    public static void main(String[] args) {        ColoredPoint c = new ColoredPoint(0, 0);  // error        c.reset();  // error    }}

This program causes four compile-time errors.

One error occurs becauseColoredPoint has no constructor declared with twoint parameters, as requested by the use inmain. This illustrates the fact thatColoredPoint does not inherit the constructors of its superclassPoint.

Another error occurs becauseColoredPoint declares no constructors, and therefore a default constructor for it is implicitly declared (§8.8.9), and this default constructor is equivalent to:

ColoredPoint() { super(); }

which invokes the constructor, with no arguments, for the direct superclass of the classColoredPoint. The error is that the constructor forPoint that takes no arguments isprivate, and therefore is not accessible outside the classPoint, even through a superclass constructor invocation (§8.8.7).

Two more errors occur because the methodreset of classPoint isprivate, and therefore is not inherited by classColoredPoint. The method invocations in methodclear of classColoredPoint and in methodmain of classTest are therefore not correct.

Consider the example where thepoints package declares two compilation units:

package points;public class Point {    int x, y;    public void move(int dx, int dy) { x += dx; y += dy; }}

and:

package points;public class Point3d extends Point {    int z;    public void move(int dx, int dy, int dz) {        x += dx; y += dy; z += dz;    }}

and a third compilation unit, in another package, is:

import points.Point3d;class Point4d extends Point3d {    int w;    public void move(int dx, int dy, int dz, int dw) {        x += dx; y += dy; z += dz; w += dw; // compile-time errors    }}

Here both classes in thepoints package compile. The classPoint3d inherits the fieldsx andy of classPoint, because it is in the same package asPoint. The classPoint4d, which is in a different package, does not inherit the fieldsx andy of classPoint or the fieldz of classPoint3d, and so fails to compile.

A better way to write the third compilation unit would be:

import points.Point3d;class Point4d extends Point3d {    int w;    public void move(int dx, int dy, int dz, int dw) {        super.move(dx, dy, dz); w += dw;    }}

using themove method of the superclassPoint3d to processdx,dy, anddz. IfPoint4d is written in this way, it will compile without errors.

Given the classPoint:

package points;public class Point {    public int x, y;    protected int useCount = 0;    static protected int totalUseCount = 0;    public void move(int dx, int dy) {        x += dx; y += dy; useCount++; totalUseCount++;    }}

thepublic andprotected fieldsx,y,useCount, andtotalUseCount are inherited in all subclasses ofPoint.

Therefore, this test program, in another package, can be compiled successfully:

class Test extends points.Point {    public void moveBack(int dx, int dy) {        x -= dx; y -= dy; useCount++; totalUseCount++;    }}

class Point {    int x, y;    void move(int dx, int dy) {        x += dx; y += dy; totalMoves++;    }    private static int totalMoves;    void printMoves() { System.out.println(totalMoves); }}class Point3d extends Point {    int z;    void move(int dx, int dy, int dz) {        super.move(dx, dy); z += dz; totalMoves++; // error    }}

Here, the class variabletotalMoves can be used only within the classPoint; it is not inherited by the subclassPoint3d. A compile-time error occurs because method move of classPoint3d tries to incrementtotalMoves.

Even though a class might not be declaredpublic, instances of the class might be available at run time to code outside the package in which it is declared by means of apublic superclass or superinterface. An instance of the class can be assigned to a variable of such apublic type. An invocation of apublic method of the object referred to by such a variable may invoke a method of the class if it implements or overrides a method of thepublic superclass or superinterface. (In this situation, the method is necessarily declaredpublic, even though it is declared in a class that is notpublic.)

Consider the compilation unit:

package points;public class Point {    public int x, y;    public void move(int dx, int dy) {        x += dx; y += dy;    }}

and another compilation unit of another package:

package morePoints;class Point3d extends points.Point {    public int z;    public void move(int dx, int dy, int dz) {        super.move(dx, dy); z += dz;    }    public void move(int dx, int dy) {        move(dx, dy, 0);    }}public class OnePoint {    public static points.Point getOne() {        return new Point3d();    }}

An invocationmorePoints.OnePoint.getOne() in yet a third package would return aPoint3d that can be used as aPoint, even though the typePoint3d is not available outside the packagemorePoints. The two-argument version of methodmove could then be invoked for that object, which is permissible because methodmove ofPoint3d ispublic (as it must be, for any method that overrides apublic method must itself bepublic, precisely so that situations such as this will work out correctly). The fieldsx andy of that object could also be accessed from such a third package.

While the fieldz of classPoint3d ispublic, it is not possible to access this field from code outside the packagemorePoints, given only a reference to an instance of classPoint3d in a variablep of typePoint. This is because the expressionp.z is not correct, asp has typePoint and classPoint has no field namedz; also, the expression((Point3d)p).z is not correct, because the class typePoint3d cannot be referred to outside packagemorePoints.

The declaration of the fieldz aspublic is not useless, however. If there were to be, in packagemorePoints, apublic subclassPoint4d of the classPoint3d:

package morePoints;public class Point4d extends Point3d {    public int w;    public void move(int dx, int dy, int dz, int dw) {        super.move(dx, dy, dz); w += dw;    }}

then classPoint4d would inherit the fieldz, which, beingpublic, could then be accessed by code in packages other thanmorePoints, through variables and expressions of thepublic typePoint4d.

A class may inherit two or more fields with the same name, either from its superclass and a superinterface or from two superinterfaces. A compile-time error occurs on any attempt to refer to any ambiguously inherited field by its simple name. A qualified name or a field access expression that contains the keywordsuper (§15.11.2) may be used to access such fields unambiguously. In the program:

interface Frob  { float v = 2.0f; }class SuperTest { int   v = 3; }class Test extends SuperTest implements Frob {    public static void main(String[] args) {        new Test().printV();    }    void printV() { System.out.println(v); }}

the classTest inherits two fields namedv, one from its superclassSuperTest and one from its superinterfaceFrob. This in itself is permitted, but a compile-time error occurs because of the use of the simple namev in methodprintV: it cannot be determined whichv is intended.

The following variation uses the field access expressionsuper.v to refer to the field namedv declared in classSuperTest and uses the qualified nameFrob.v to refer to the field namedv declared in interfaceFrob:

interface Frob  { float v = 2.0f; }class SuperTest { int   v = 3; }class Test extends SuperTest implements Frob {    public static void main(String[] args) {        new Test().printV();    }    void printV() {        System.out.println((super.v + Frob.v)/2);    }}

It compiles and prints:

2.5

Even if two distinct inherited fields have the same type, the same value, and are bothfinal, any reference to either field by simple name is considered ambiguous and results in a compile-time error. In the program:

interface Color        { int RED=0, GREEN=1,  BLUE=2;  }interface TrafficLight { int RED=0, YELLOW=1, GREEN=2; }class Test implements Color, TrafficLight {    public static void main(String[] args) {        System.out.println(GREEN);  // compile-time error        System.out.println(RED);    // compile-time error    }}

it is not astonishing that the reference toGREEN should be considered ambiguous, because classTest inherits two different declarations forGREEN with different values. The point of this example is that the reference toRED is also considered ambiguous, because two distinct declarations are inherited. The fact that the two fields namedRED happen to have the same type and the same unchanging value does not affect this judgment.

If the same field declaration is inherited from an interface by multiple paths, the field is considered to be inherited only once. It may be referred to by its simple name without ambiguity. For example, in the code:

interface Colorable {    int RED = 0xff0000, GREEN = 0x00ff00, BLUE = 0x0000ff;}interface Paintable extends Colorable {    int MATTE = 0, GLOSSY = 1;}class Point { int x, y; }class ColoredPoint extends Point implements Colorable {}class PaintedPoint extends ColoredPoint implements Paintable {    int p = RED;}

the fieldsRED,GREEN, andBLUE are inherited by the classPaintedPoint both through its direct superclassColoredPoint and through its direct superinterfacePaintable. The simple namesRED,GREEN, andBLUE may nevertheless be used without ambiguity within the classPaintedPoint to refer to the fields declared in interfaceColorable.

If a field is declaredstatic, there exists exactly one incarnation of the field, no matter how many instances (possibly zero) of the class may eventually be created. Astatic field, sometimes called aclass variable, is incarnated when the class is initialized (§12.4).

A field that is not declaredstatic is called aninstance variable, and sometimes called a non-static field. Whenever a new instance of a class is created (§12.5), a new variable associated with that instance is created for every instance variable declared in that class or any of its superclasses.

The declaration of a class variable introduces a static context (§8.1.3), which limits the use of constructs that refer to the current object. Notably, the keywordsthis andsuper are prohibited in a static context (§15.8.3,§15.11.2), as are unqualified references to instance variables, instance methods, and type parameters of lexically enclosing declarations (§6.5.5.1,§6.5.6.1,§15.12.3).

References to an instance variable from a static context or a nested class or interface are restricted, as specified in§6.5.6.1.

class Point {    int x, y, useCount;    Point(int x, int y) { this.x = x; this.y = y; }    static final Point origin = new Point(0, 0);}class Test {    public static void main(String[] args) {        Point p = new Point(1,1);        Point q = new Point(2,2);        p.x = 3;        p.y = 3;        p.useCount++;        p.origin.useCount++;        System.out.println("(" + q.x + "," + q.y + ")");        System.out.println(q.useCount);        System.out.println(q.origin == Point.origin);        System.out.println(q.origin.useCount);    }}

(2,2)0true1

q.origin==Point.origin

p.origin.useCount++;

class Point {    static int x = 2;}class Test extends Point {    static double x = 4.7;    public static void main(String[] args) {        new Test().printX();    }    void printX() {        System.out.println(x + " " + super.x);    }}

4.7 2

class Point {    static int x = 2;}class Test extends Point {    public static void main(String[] args) {        new Test().printX();    }    void printX() {        System.out.println(x + " " + super.x);    }}

2 2

class Point {    int x = 2;}class Test extends Point {    double x = 4.7;    void printBoth() {        System.out.println(x + " " + super.x);    }    public static void main(String[] args) {        Test sample = new Test();        sample.printBoth();        System.out.println(sample.x + " " + ((Point)sample).x);    }}

4.7 24.7 2

class Point {    static int x = 2;}class Test extends Point {    void printBoth() {        System.out.println(x + " " + super.x);    }    public static void main(String[] args) {        Test sample = new Test();        sample.printBoth();        System.out.println(sample.x + " " + ((Point)sample).x);    }}

2 22 2

A field can be declaredfinal (§4.12.4). Both class and instance variables (static and non-static fields) may be declaredfinal.

A blankfinal class variable must be definitely assigned by a static initializer of the class in which it is declared, or a compile-time error occurs (§8.7,§16.8).

A blankfinal instance variable must be definitely assigned and moreover not definitely unassigned at the end of every constructor of the class in which it is declared, or a compile-time error occurs (§8.8,§16.9).

Variables may be markedtransient to indicate that they are not part of the persistent state of an object.

class Point {    int x, y;    transient float rho, theta;}

The Java programming language allows threads to access shared variables (§17.1). As a rule, to ensure that shared variables are consistently and reliably updated, a thread should ensure that it has exclusive use of such variables by obtaining a lock that, conventionally, enforces mutual exclusion for those shared variables.

The Java programming language provides a second mechanism,volatile fields, that is more convenient than locking for some purposes.

A field may be declaredvolatile, in which case the Java Memory Model ensures that all threads see a consistent value for the variable (§17.4).

It is a compile-time error if afinal variable is also declaredvolatile.

class Test {    static int i = 0, j = 0;    static void one() { i++; j++; }    static void two() {        System.out.println("i=" + i + " j=" + j);    }}

class Test {    static int i = 0, j = 0;    static synchronized void one() { i++; j++; }    static synchronized void two() {        System.out.println("i=" + i + " j=" + j);    }}

class Test {    static volatile int i = 0, j = 0;    static void one() { i++; j++; }    static void two() {        System.out.println("i=" + i + " j=" + j);    }}

• The initializer may not refer to the current object using the keywordthis or the keywordsuper, as specified in§15.8.3 and§15.11.2, nor refer by simple name to any instance variable or instance method, as specified in§6.5.6.1 and§15.12.3.

• At run time, the initializer is evaluated and the assignment performed exactly once, when the class is initialized (§12.4.2).

  Note thatstatic fields that are constant variables (§4.12.4) are initialized before otherstatic fields (§12.4.2, step 6). This also applies in interfaces (§9.3.1). When such fields are referenced by simple name, they will never be observed to have their default initial values (§4.12.5).

• The initializer may refer to the current object using the keywordthis or the keywordsuper, and may refer by simple name to any class variable declared in or inherited by the class, even one whose declaration occurs to the right of the initializer (§3.5).

• At run time, the initializer is evaluated and the assignment performed each time an instance of the class is created (§12.5).

Example 8.3.2-1. Field Initialization

class Point {    int x = 1, y = 5;}class Test {    public static void main(String[] args) {        Point p = new Point();        System.out.println(p.x + ", " + p.y);    }}

1, 5

Example 8.3.2-2. Forward Reference to a Class Variable

class Test {    float f = j;    static int j = 1;}

• The reference appears either in a class variable initializer ofC or in a static initializer ofC (§8.7); and

• The reference appears either in the initializer off's own declarator or at a point to the left off's declarator; and

• The reference isnot on the left hand side of an assignment expression (§15.26); and

• The innermost class or interface enclosing the reference isC.

• The reference appears either in an instance variable initializer ofC or in an instance initializer ofC (§8.6); and

• The reference appears in the initializer off's own declarator or at a point to the left off's declarator; and

• The reference isnot on the left hand side of an assignment expression (§15.26); and

• The innermost class enclosing the reference isC.

Example 8.3.3-1. Restrictions on Field References

class Test1 {    int i = j;  // compile-time error:                // incorrect forward reference    int j = 1;}

class Test2 {    Test2() { k = 2; }    int j = 1;    int i = j;    int k;}

class Z {    static int i = j + 2;    static int j = 4;}

class Z {    static { i = j + 2; }    static int i, j;    static { j = 4; }}

class Z {    static int peek() { return j; }    static int i = peek();    static int j = 1;}class Test {    public static void main(String[] args) {        System.out.println(Z.i);    }}

0

class UseBeforeDeclaration {    static {        x = 100;          // ok - assignment        int y = x + 1;          // error - read before declaration        int v = x = 3;          // ok - x at left hand side of assignment        int z = UseBeforeDeclaration.x * 2;          // ok - not accessed via simple name        Object o = new Object() {            void foo() { x++; }              // ok - occurs in a different class            { x++; }              // ok - occurs in a different class        };    }    {        j = 200;          // ok - assignment        j = j + 1;          // error - right hand side reads before declaration        int k = j = j + 1;          // error - illegal forward reference to j        int n = j = 300;          // ok - j at left hand side of assignment        int h = j++;          // error - read before declaration        int l = this.j * 3;          // ok - not accessed via simple name        Object o = new Object() {            void foo(){ j++; }              // ok - occurs in a different class            { j = j + 1; }              // ok - occurs in a different class        };    }    int w = x = 3;      // ok - x at left hand side of assignment    int p = x;      // ok - instance initializers may access static fields    static int u =        (new Object() { int bar() { return x; } }).bar();        // ok - occurs in a different class    static int x;    int m = j = 4;      // ok - j at left hand side of assignment    int o =        (new Object() { int bar() { return j; } }).bar();        // ok - occurs in a different class    int j;}

• If the formal parameter is not a variable arity parameter, then the declared type is denoted byUnannType if no bracket pairs appear inUnannType andVariableDeclaratorId, and specified by§10.2 otherwise.

• If the formal parameter is a variable arity parameter, then the declared type is an array type specified by§10.2.

Here are some examples of receiver parameters in instance methods and inner classes' constructors:

class Test {    Test(/* ?? ?? */) {}      // No receiver parameter is permitted in the constructor of      // a top level class, as there is no conceivable type or name.    void m(Test this) {}      // OK: receiver parameter in an instance method    static void n(Test this) {}      // Illegal: receiver parameter in a static method    class A {        A(Test Test.this) {}          // OK: the receiver parameter represents the instance          // of Test which immediately encloses the instance          // of A being constructed.        void m(A this) {}          // OK: the receiver parameter represents the instance          // of A for which A.m() is invoked.        class B {            B(Test.A A.this) {}              // OK: the receiver parameter represents the instance              // of A which immediately encloses the instance of B              // being constructed.            void m(Test.A.B this) {}              // OK: the receiver parameter represents the instance              // of B for which B.m() is invoked.        }    }}

B's constructor and instance method show that the type of the receiver parameter may be denoted with a qualifiedTypeName like any other type; but that the name of the receiver parameter in an inner class's constructor must use the simple name of the enclosing class.

• m2 has the same signature asm1, or

• the signature ofm1 is the same as the erasure (§4.6) of the signature ofm2.

Example 8.4.2-1. Override-Equivalent Signatures

class Point {    int x, y;    abstract void move(int dx, int dy);    void move(int dx, int dy) { x += dx; y += dy; }}

Consider the example:

class CollectionConverter {    List toList(Collection c) {...}}class Overrider extends CollectionConverter {    List toList(Collection c) {...}}

Now, assume this code was written before the introduction of generics, and now the author of classCollectionConverter decides to generify the code, thus:

class CollectionConverter {    <T> List<T> toList(Collection<T> c) {...}}

Without special dispensation,Overrider.toList would no longer overrideCollectionConverter.toList. Instead, the code would be illegal. This would significantly inhibit the use of generics, since library writers would hesitate to migrate existing code.

Anabstract method declaration introduces the method as a member, providing its signature (§8.4.2), result (§8.4.5), andthrows clause if any (§8.4.6), but does not provide an implementation (§8.4.7). A method that is notabstract may be referred to as aconcrete method.

The declaration of anabstract methodm must appear directly within anabstract class (call itA) unless it occurs within an enum declaration (§8.9); otherwise, a compile-time error occurs.

Every subclass ofA that is notabstract (§8.1.1.1) must provide an implementation form, or a compile-time error occurs.

Anabstract class can override anabstract method by providing anotherabstract method declaration.

This can provide a place to put a documentation comment, to refine the return type, or to declare that the set of checked exceptions that can be thrown by that method, when it is implemented by its subclasses, is to be more limited.

An instance method that is notabstract can be overridden by anabstract method.

class BufferEmpty extends Exception {    BufferEmpty() { super(); }    BufferEmpty(String s) { super(s); }}class BufferError extends Exception {    BufferError() { super(); }    BufferError(String s) { super(s); }}interface Buffer {    char get() throws BufferEmpty, BufferError;}abstract class InfiniteBuffer implements Buffer {    public abstract char get() throws BufferError;}

abstract class Point {    int x, y;    public abstract String toString();}

class ColoredPoint extends Point {    int color;    public String toString() {        return super.toString() + ": color " + color;  // error    }}

abstract class Point {    int x, y;    public abstract String toString();    protected String objString() { return super.toString(); }}class ColoredPoint extends Point {    int color;    public String toString() {        return objString() + ": color " + color;  // correct    }}

A method that is declaredstatic is called aclass method.

A class method is always invoked without reference to a particular object. The declaration of a class method introduces a static context (§8.1.3), which limits the use of constructs that refer to the current object. Notably, the keywordsthis andsuper are prohibited in a static context (§15.8.3,§15.11.2), as are unqualified references to instance variables, instance methods, and type parameters of lexically enclosing declarations (§6.5.5.1,§6.5.6.1,§15.12.3).

A method that is not declaredstatic is called aninstance method, and sometimes called a non-static method.

An instance method is always invoked with respect to an object, which becomes the current object to which the keywordsthis andsuper refer during execution of the method body.

References to an instance method from a static context or a nested class or interface are restricted, as specified in§15.12.3.

A method can be declaredfinal to prevent subclasses from overriding or hiding it.

It is a compile-time error to attempt to override or hide afinal method.

Aprivate method and all methods declared immediately within afinal class (§8.1.1.2) behave as if they arefinal, since it is impossible to override them.

At run time, a machine-code generator or optimizer can "inline" the body of afinal method, replacing an invocation of the method with the code in its body. The inlining process must preserve the semantics of the method invocation. In particular, if the target of an instance method invocation isnull, then aNullPointerException must be thrown even if the method is inlined. A Java compiler must ensure that the exception will be thrown at the correct point, so that the actual arguments to the method will be seen to have been evaluated in the correct order prior to the method invocation.

final class Point {    int x, y;    void move(int dx, int dy) { x += dx; y += dy; }}class Test {    public static void main(String[] args) {        Point[] p = new Point[100];        for (int i = 0; i < p.length; i++) {            p[i] = new Point();            p[i].move(i, p.length-1-i);        }    }}

    for (int i = 0; i < p.length; i++) {        p[i] = new Point();        Point pi = p[i];        int j = p.length-1-i;        pi.x += i;        pi.y += j;    }

A method that isnative is implemented in platform-dependent code, typically written in another programming language such as C. The body of anative method is given as a semicolon only, indicating that the implementation is omitted, instead of a block (§8.4.7).

package java.io;public class RandomAccessFile    implements DataOutput, DataInput {    . . .    public native void open(String name, boolean writeable)        throws IOException;    public native int readBytes(byte[] b, int off, int len)        throws IOException;    public native void writeBytes(byte[] b, int off, int len)        throws IOException;    public native long getFilePointer() throws IOException;    public native void seek(long pos) throws IOException;    public native long length() throws IOException;    public native void close() throws IOException;}

Thestrictfp modifier on a method declaration is obsolete and should not be used in new code. Its presence or absence has has no effect at run time.

Asynchronized method acquires a monitor (§17.1) before it executes.

For a class (static) method, the monitor associated with theClass object for the method's class is used.

For an instance method, the monitor associated withthis (the object for which the method was invoked) is used.

class Test {    int count;    synchronized void bump() {        count++;    }    static int classCount;    static synchronized void classBump() {        classCount++;    }}

class BumpTest {    int count;    void bump() {        synchronized (this) { count++; }    }    static int classCount;    static void classBump() {        try {            synchronized (Class.forName("BumpTest")) {                classCount++;            }        } catch (ClassNotFoundException e) {}    }}

public class Box {    private Object boxContents;    public synchronized Object get() {        Object contents = boxContents;        boxContents = null;        return contents;    }    public synchronized boolean put(Object contents) {        if (boxContents != null) return false;        boxContents = contents;        return true;    }}

• M andN have same number of type parameters (possibly zero).

• WhereA₁, ...,A_n are the type parameters ofM andB₁, ...,B_n are the type parameters ofN, letθ=[B₁:=A₁, ...,B_n:=A_n]. Then, for alli (1≤i≤n), the bound ofA_i is the same type asθ applied to the bound ofB_i.

• IfR₁ isvoid thenR₂ isvoid.

• IfR₁ is a primitive type thenR₂ is identical toR₁.

• IfR₁ is a reference type then one of the following is true:

  • R₁, adapted to the type parameters ofd2 (§8.4.4), is a subtype ofR₂.

  • R₁ can be converted to a subtype ofR₂ by unchecked conversion (§5.1.9).

  • d1 does not have the same signature asd2 (§8.4.2), andR₁ = |R₂|.

Example 8.4.6-1. Type Variables as Thrown Exception Types

import java.io.FileNotFoundException;interface PrivilegedExceptionAction<E extends Exception> {    void run() throws E;}class AccessController {    public static <E extends Exception>    Object doPrivileged(PrivilegedExceptionAction<E> action) throws E {        action.run();        return "success";    }}class Test {    public static void main(String[] args) {        try {            AccessController.doPrivileged(              new PrivilegedExceptionAction<FileNotFoundException>() {                  public void run() throws FileNotFoundException {                      // ... delete a file ...                  }              });        } catch (FileNotFoundException f) { /* Do something */ }    }}

• It is a compile-time error if a method declaration is eitherabstract ornative and has a block for its body.

• It is a compile-time error if a method declaration is neitherabstract nornative and has a semicolon for its body.

It is possible for a method to have a return type and yet contain noreturn statements. Here is one example:

class DizzyDean {    int pitch() { throw new RuntimeException("90 mph?!"); }}

• m is a member ofD.

• m ispublic,protected, or declared with package access in the same package asC.

• No method declared inC has a signature that is a subsignature (§8.4.2) of the signature ofm as a member ofD.

• m is a member of the direct superclass type or a direct superinterface type ofC, known in either case asD.

• m ispublic,protected, or declared with package access in the same package asC.

• No method declared inC has a signature that is a subsignature (§8.4.2) of the signature ofm as a member ofD.

• No concrete method inherited byC from its direct superclass type has a signature that is a subsignature of the signature ofm as a member ofD.

• There exists no methodm' that is a member of the direct superclass type or a direct superinterface type ofC,D' (m distinct fromm',D distinct fromD'), such thatm' overrides from the class or interface ofD' the declaration of the methodm (§8.4.8.1,§9.4.1.1).

Example 8.4.8-1. Inheritance

interface I1 {    int foo();}interface I2 {    int foo();}abstract class Test implements I1, I2 {}

An instance methodmC declared in or inherited by classC,overrides fromC another methodmA declared in classA, iff all of the following are true:

IfmC is non-abstract and overrides fromC anabstract methodmA, thenmC is said toimplementmAfromC.

It is a compile-time error if the overridden method,mA, is astatic method.

In this respect, overriding of methods differs from hiding of fields (§8.3), for it is permissible for an instance variable to hide astatic variable.

An instance methodmC declared in or inherited by classC,overrides fromC another methodmI declared in interfaceI, iff all of the following are true:

The signature of an overriding method may differ from the overridden one if a formal parameter in one of the methods has a raw type, while the corresponding parameter in the other has a parameterized type. This accommodates migration of pre-existing code to take advantage of generics.

The notion of overriding includes methods that override another from some subclass of their declaring class. This can happen in two ways:

An overridden method can be accessed by using a method invocation expression (§15.12) that contains the keywordsuper. A qualified name or a cast to a superclass type is not effective in attempting to access an overridden method.

In this respect, overriding of methods differs from hiding of fields.

The presence or absence of thestrictfp modifier has absolutely no effect on the rules for overriding methods and implementingabstract methods. For example, it is permitted for a method that is notstrictfp to override astrictfp method, and it is permitted for astrictfp method to override a method that is notstrictfp.

class Point {    int x = 0, y = 0;    void move(int dx, int dy) { x += dx; y += dy; }}class SlowPoint extends Point {    int xLimit, yLimit;    void move(int dx, int dy) {        super.move(limit(dx, xLimit), limit(dy, yLimit));    }    static int limit(int d, int limit) {        return d > limit ? limit : d < -limit ? -limit : d;    }}

import java.io.IOException;import java.io.OutputStream;class BufferOutput {    private OutputStream o;    BufferOutput(OutputStream o) { this.o = o; }    protected byte[] buf = new byte[512];    protected int pos = 0;    public void putchar(char c) throws IOException {        if (pos == buf.length) flush();        buf[pos++] = (byte)c;    }    public void putstr(String s) throws IOException {        for (int i = 0; i < s.length(); i++)            putchar(s.charAt(i));    }    public void flush() throws IOException {        o.write(buf, 0, pos);        pos = 0;    }}class LineBufferOutput extends BufferOutput {    LineBufferOutput(OutputStream o) { super(o); }    public void putchar(char c) throws IOException {        super.putchar(c);        if (c == '\n') flush();    }}class Test {    public static void main(String[] args) throws IOException {        LineBufferOutput lbo = new LineBufferOutput(System.out);        lbo.putstr("lbo\nlbo");        System.out.print("print\n");        lbo.putstr("\n");    }}

lboprintlbo

If a classC declares or inherits astatic methodm, thenm is said tohide any methodm' declared in a class or interfaceA for which all of the following are true:

It is a compile-time error if astatic method hides an instance method.

In this respect, hiding of methods differs from hiding of fields (§8.3), for it is permissible for astatic variable to hide an instance variable. Hiding is also distinct from shadowing (§6.4.1) and obscuring (§6.4.2).

A hidden method can be accessed by using a qualified name or by using a method invocation expression (§15.12) that contains the keywordsuper or a cast to a superclass type.

In this respect, hiding of methods is similar to hiding of fields.

class Super {    static String greeting() { return "Goodnight"; }    String name() { return "Richard"; }}class Sub extends Super {    static String greeting() { return "Hello"; }    String name() { return "Dick"; }}class Test {    public static void main(String[] args) {        Super s = new Sub();        System.out.println(s.greeting() + ", " + s.name());    }}

Goodnight, Dick

If a method declarationd1 with return typeR₁ overrides or hides the declaration of another methodd2 with return typeR₂, thend1 must be return-type-substitutable (§8.4.5) ford2, or a compile-time error occurs.

This rule allows for covariant return types - refining the return type of a method when overriding it.

IfR₁ is not a subtype ofR₂, then a compile-time unchecked warning occurs, unless suppressed by@SuppressWarnings (§9.6.4.5).

A method that overrides or hides another method, including methods that implementabstract methods defined in interfaces, may not be declared to throw more checked exceptions than the overridden or hidden method.

In this respect, overriding of methods differs from hiding of fields (§8.3), for it is permissible for a field to hide a field of another type.

More precisely, suppose thatB is a class or interface, andA is a superclass or superinterface ofB, and a method declarationm2 inB overrides or hides a method declarationm1 inA. Then:

It is a compile-time error if a class or interfaceC has a member methodm1 and there exists a methodm2 declared inC or a superclass or superinterface ofC,A, such that all of the following are true:

These restrictions are necessary because generics are implemented via erasure. The rule above implies that methods declared in the same class with the same name must have different erasures. It also implies that a class or interface cannot implement or extend two distinct parameterizations of the same generic interface.

The access modifier of an overriding or hiding method must provide at least as much access as the overridden or hidden method, as follows:

Note that aprivate method cannot be overridden or hidden in the technical sense of those terms. This means that a subclass can declare a method with the same signature as aprivate method in one of its superclasses, and there is no requirement that the return type orthrows clause of such a method bear any relationship to those of theprivate method in the superclass.

class C implements Cloneable {    C copy() throws CloneNotSupportedException {        return (C)clone();    }}class D extends C implements Cloneable {    D copy() throws CloneNotSupportedException {        return (D)clone();    }}

class StringSorter {    // turns a collection of strings into a sorted list    List toList(Collection c) {...}}

class Overrider extends StringSorter {    List toList(Collection c) {...}}

class StringSorter {    // turns a collection of strings into a sorted list    List<String> toList(Collection<String> c) {...}}

class BadPointException extends Exception {    BadPointException() { super(); }    BadPointException(String s) { super(s); }}class Point {    int x, y;    void move(int dx, int dy) { x += dx; y += dy; }}class CheckedPoint extends Point {    void move(int dx, int dy) throws BadPointException {        if ((x + dx) < 0 || (y + dy) < 0)            throw new BadPointException();        x += dx; y += dy;    }}

class CheckedPoint extends Point {    void move(int dx, int dy) {        if ((x + dx) < 0 || (y + dy) < 0)            throw new BadPointException();        x += dx; y += dy;    }}

class C<T> {    T id (T x) {...}}class D extends C<String> {    Object id(Object x) {...}}

class C<T> {    T id(T x) {...}}interface I<T> {    T id(T x);}class D extends C<String> implements I<Integer> {   public String  id(String x)  {...}   public Integer id(Integer x) {...}}

It is possible for a class to inherit multiple methods with override-equivalent signatures (§8.4.2).

It is a compile-time error if a classC inherits a concrete method whose signature is override-equivalent with another method inherited byC.

It is a compile-time error if a classC inherits a default method whose signature is override-equivalent with another method inherited byC, unless there exists anabstract method declared in a superclass ofC and inherited byC that is override-equivalent with the two methods.

This exception to the strict default-abstract and default-default conflict rules is made when anabstract method is declared in a superclass: the assertion of abstract-ness coming from the superclass hierarchy essentially trumps the default method, making the default method act as if it wereabstract. However, theabstract method from a class does not override the default method(s), because interfaces are still allowed to refine thesignature of theabstract method coming from the class hierarchy.

Note that the exception does not apply if all override-equivalentabstract methods inherited byC were declared in interfaces.

Otherwise, the set of override-equivalent methods consists of at least oneabstract method and zero or more default methods; then the class is necessarily anabstract class and is considered to inherit all the methods.

One of the inherited methods must be return-type-substitutable for every other inherited method; otherwise, a compile-time error occurs. (Thethrows clauses do not cause errors in this case.)

There might be several paths by which the same method declaration is inherited from an interface. This fact causes no difficulty and never, of itself, results in a compile-time error.

class A<T> {    void m(String s) {} // 1    void m(T t) {} // 2}class C extends A<String> {}

Example 8.4.9-1. Overloading

class Point {    float x, y;    void move(int dx, int dy) { x += dx; y += dy; }    void move(float dx, float dy) { x += dx; y += dy; }    public String toString() { return "("+x+","+y+")"; }}

Example 8.4.9-2. Overloading, Overriding, and Hiding

class Point {    int x = 0, y = 0;    void move(int dx, int dy) { x += dx; y += dy; }    int color;}class RealPoint extends Point {    float x = 0.0f, y = 0.0f;    void move(int dx, int dy) { move((float)dx, (float)dy); }    void move(float dx, float dy) { x += dx; y += dy; }}

class Point {    int x = 0, y = 0, color;    void move(int dx, int dy) { x += dx; y += dy; }    int getX() { return x; }    int getY() { return y; }}class RealPoint extends Point {    float x = 0.0f, y = 0.0f;    void move(int dx, int dy) { move((float)dx, (float)dy); }    void move(float dx, float dy) { x += dx; y += dy; }    float getX() { return x; }    float getY() { return y; }}

class Point {    int x = 0, y = 0;    void move(int dx, int dy) { x += dx; y += dy; }    int getX() { return x; }    int getY() { return y; }    int color;}class RealPoint extends Point {    float x = 0.0f, y = 0.0f;    void move(int dx, int dy) { move((float)dx, (float)dy); }    void move(float dx, float dy) { x += dx; y += dy; }    int getX() { return (int)Math.floor(x); }    int getY() { return (int)Math.floor(y); }}

class Test {    public static void main(String[] args) {        RealPoint rp = new RealPoint();        Point p = rp;        rp.move(1.71828f, 4.14159f);        p.move(1, -1);        show(p.x, p.y);        show(rp.x, rp.y);        show(p.getX(), p.getY());        show(rp.getX(), rp.getY());    }    static void show(int x, int y) {        System.out.println("(" + x + ", " + y + ")");    }    static void show(float x, float y) {        System.out.println("(" + x + ", " + y + ")");    }}

(0, 0)(2.7182798, 3.14159)(2, 3)(2, 3)

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

1. In a class instance creation expression for a non-private inner member class,§15.9.2 specifies the immediately enclosing instance of the member class. The member class may have been emitted by a compiler which is different than the compiler of the class instance creation expression. Therefore, there must be a standard way for the compiler of the creation expression to pass a reference (representing the immediately enclosing instance) to the member class's constructor. Consequently, the Java programming language deems in this section that a non-private inner member class's constructor implicitly declares an initial parameter for the immediately enclosing instance.§15.9.3 specifies that the instance is passed to the constructor.

2. In a class instance creation expression for an inner local class or an anonymous class (not in a static context),§15.9.2 specifies the immediately enclosing instance of the local/anonymous class. The local/anonymous class is necessarily emitted by the same compiler as the class instance creation expression. That compiler can represent the immediately enclosing instance how ever it wishes. There is no need for the Java programming language to implicitly declare a parameter in the local/anonymous class's constructor.

3. In a class instance creation expression for an anonymous class, and where the anonymous class's superclass is an inner class (not in a static context),§15.9.2 specifies the anonymous class's immediately enclosing instance with respect to the superclass. This instance must be transmitted from the anonymous class to its superclass, where it will serve as the immediately enclosing instance. Since the superclass may have been emitted by a compiler which is different than the compiler of the class instance creation expression, it is necessary to transmit the instance in a standard way, by passing it as the first argument to the superclass's constructor. Note that the anonymous class itself is necessarily emitted by the same compiler as the class instance creation expression, so it would be possible for the compiler to transmit the immediately enclosing instance with respect to the superclass to the anonymous class how ever it wishes, before the anonymous class passes the instance to the superclass's constructor. However, for consistency, the Java programming language deems in§15.9.5.1 that, in some circumstances, an anonymous class's constructor implicitly declares an initial parameter for the immediately enclosing instance with respect to the superclass.

• A constructor is not inherited, so there is no need to declare itfinal.

• Anabstract constructor could never be implemented.

• A constructor is always invoked with respect to an object, so it makes no sense for a constructor to bestatic.

• There is no practical need for a constructor to besynchronized, because it would lock the object under construction, which is normally not made available to other threads until all constructors for the object have completed their work.

• The lack ofnative constructors is an arbitrary language design choice that makes it easy for an implementation of the Java Virtual Machine to verify that superclass constructors are always properly invoked during object creation.

• The inability to declare a constructor asstrictfp (in contrast to a method (§8.4.3)) is an intentional language design choice that stemmed from the (now obsolete) ability to declare a class asstrictfp.

Example 8.8.7-1. Constructor Bodies

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, WHITE);    }    ColoredPoint(int x, int y, int color) {        super(x, y);        this.color = color;    }}

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

Explicit constructor invocation statements are divided into two kinds:

An explicit constructor invocation statement introduces a static context (§8.1.3), which limits the use of constructs that refer to the current object. Notably, the keywordsthis andsuper are prohibited in a static context (§15.8.3,§15.11.2), as are unqualified references to instance variables, instance methods, and type parameters of lexically enclosing declarations (§6.5.5.1,§6.5.6.1,§15.12.3).

IfTypeArguments is present to the left ofthis orsuper, then it is a compile-time error if any of the type arguments are wildcards (§4.5.1).

LetC be the class being instantiated, and letS be the direct superclass ofC.

If a superclass constructor invocation statement is unqualified, then:

If a superclass constructor invocation statement is qualified, then:

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:

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());    }}

56

• The default constructor has the same access modifier as the class, unless the class lacks an access modifier, in which case the default constructor has package access (§6.6).

• The default constructor has no formal parameters, except in a non-private inner member class, where the default constructor implicitly declares one formal parameter representing the immediately enclosing instance of the class (§8.8.1,§15.9.2,§15.9.3).

• The default constructor has nothrows clause.

• If the class being declared is the primordial classObject, then the default constructor has an empty body. Otherwise, the default constructor simply invokes the superclass constructor with no arguments.

Example 8.8.9-1. Default Constructors

public class Point {    int x, y;}

public class Point {    int x, y;    public Point() { super(); }}

Example 8.8.9-2. Accessibility of Constructors v. Classes

package p1;public class Outer {    protected class Inner {}}package p2;class SonOfOuter extends p1.Outer {    void foo() {        new Inner();  // compile-time access error    }}

Example 8.8.10-1. Preventing Instantiation via Constructor Accessibility

class ClassOnly {    private ClassOnly() { }    static String just = "only the lonely";}

package just;public class PackageOnly {    PackageOnly() { }    String[] justDesserts = { "cheesecake", "ice cream" };}

Example 8.9.2-1. Enum Body Declarations

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

Example 8.9.2-2. Restriction On Enum Constant Self-Reference

import java.util.HashMap;import java.util.Map;enum Color {    RED, GREEN, BLUE;    Color() { colorMap.put(toString(), this); }    static final Map<String,Color> colorMap =        new HashMap<String,Color>();}

import java.util.HashMap;import java.util.Map;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);    }}

• Members declared in the body of the declaration ofE.

• Members inherited fromEnum<E>.

• For each enum constantc declared in the body of the declaration ofE,E has an implicitly declaredpublicstaticfinal field of typeE that has the same name asc. The field has a variable initializer which instantiatesE and passes any arguments ofc to the constructor chosen forE. The field has the same annotations asc (if any).

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

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

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

• An implicitly declared methodpublicstaticEvalueOf(String name), which returns the enum constant ofE with the specified name.

Example 8.9.3-1. Iterating Over Enum Constants With An Enhancedfor Loop

public class Test {    enum Season { WINTER, SPRING, SUMMER, FALL }    public static void main(String[] args) {        for (Season s : Season.values())            System.out.println(s);    }}

WINTERSPRINGSUMMERFALL

Example 8.9.3-2. Switching Over Enum Constants

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       COPPERNICKEL          5       NICKELDIME            10      SILVERQUARTER         25      SILVER

Example 8.9.3-3. Enum Constants with Class Bodies

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.02.0 PLUS 4.0 = 6.02.0 MINUS 4.0 = -2.02.0 TIMES 4.0 = 8.02.0 DIVIDED_BY 4.0 = 0.5

Example 8.9.3-4. Multiple Enum Classes

import java.util.ArrayList;import java.util.List;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.ArrayList;import java.util.Collections;import java.util.List;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]

• If the record component is not a variable arity record component, then the declared type is denoted byUnannType.

• If the record component is a variable arity record component, then the declared type is an array type specified by§10.2.

• The return type of the accessor method (§8.4.5) must be the same as the declared type of the record component.

• The accessor method must not be generic (§8.4.4).

• The accessor method must be apublic instance method with no formal parameters and nothrows clause.

• Its name is the same as the name of the record component.

• Its return type is the same as the declared type of the record component.

• It is not generic.

• It is apublic instance method with no formal parameters and nothrows clause.

• It is annotated with the annotations, if any, that appear on the corresponding record component and whose annotation interfaces are applicable in the method declaration context, or in type contexts, or both (§9.7.4).

• Its body returns the value of the corresponding component field.

• A methodpublic final boolean equals(Object) that returnstrue if and only if the argument is an instance ofR, and the current instance is equal to the argument instance at every record component ofR; otherwisefalse is returned.

  Equality of an instancea of a record classR with another instanceb of the same record class at a record componentc is determined as follows:

  • If the type of the record componentc is a reference type, equality is determined as follows: if the value of the component fieldc of botha andb is the null reference thentrue is returned; if the value of the component fieldc of eithera orb, but not both, is the null reference thenfalse is returned; otherwise equality is determined by invoking theequals method on the value of the component fieldc ofa, with an argument that is the value of the component fieldc ofb.

  • If the type of the record componentc is a primitive typeT, equality is determined as if by invoking thestatic methodcompare of the wrapper class corresponding toT (§5.1.7), with the first argument given by the value of the component fieldc ofa, and the second argument given by the value of the component fieldc ofb; if the method would return0 thentrue is returned, otherwisefalse is returned.

  The use ofcompare in wrapper classes ensures that the implicitly declaredequals method is reflexive and behaves consistently with the implicitly declaredhashCode method for record classes that have floating-point components.

• A methodpublic final int hashCode() that returns a hash code value derived from the hash code values at every record component ofR.

  The hash code value of an instancea of a record class at a record componentc is as follows:

  • If the type of the record componentc is a reference type, then the hash code value is determined as if by invoking thehashCode method on the value of the component fieldc ofa.

  • If the type of the record componentc is a primitive typeT, then the hash code value is determined as if by subjecting the value of the component fieldc ofa to boxing conversion (§5.1.7) and then invoking the methodhashCode of the wrapper class corresponding toT on the resulting object.

• A methodpublic final String toString() that returns a string derived from the name of the record class and the names and string representations of every record component ofR.

  The string representation of a record componentc of an instancea of a record class is as follows:

  • If the type of the record componentc is a reference type, then the string representation is determined as if by invoking thetoString method on the value of the component fieldc ofa.

  • If the type of the record componentc is a primitive typeT, then the string representation is determined as if by subjecting the value of the component fieldc ofa to boxing conversion (§5.1.7) and then invoking the methodtoString method of the wrapper class corresponding toT on the resulting object.

• If the record class ispublic, then the canonical constructor must bepublic; otherwise, a compile-time error occurs.

• If the record class isprotected, then the canonical constructor must beprotected orpublic; otherwise, a compile-time error occurs.

• If the record class has package access, then the canonical constructor mustnot beprivate; otherwise, a compile-time error occurs.

• If the record class isprivate, then the canonical constructor may be declared with any accessibility.

• The signature ofr has no type parameters, and has formal parameters given by the derived formal parameter list ofR, defined below.

• r has the same access modifier asR, unlessR lacks an access modifier, in which caser has package access.

• r has nothrows clause.

• The body ofr initializes each component field of the record class with the corresponding formal parameter ofr, in the order that record components (corresponding to the component fields) appear in the record header.

• If the record component is not a variable arity record component, then the derived formal parameter has the same name and declared type as the record component.

  If the record component is a variable arity record component, then the derived formal parameter is a variable arity parameter (§8.4.1) with the same name and declared type as the record component.

• The derived formal parameter is annotated with the annotations, if any, that appear on the record component and whose annotation interfaces are applicable in the formal parameter context, or in type contexts, or both (§9.7.4).

A (non-compact) constructor in the declaration of record classR is thecanonical constructor ofR if its signature is override-equivalent (§8.4.2) to the derived constructor signature ofR.

Thederived constructor signature of a record classR is a signature that consists of the nameR, no type parameters, and the formal parameter types derived from the record header ofR by taking the declared type of each record component in order.

As a canonical constructor has a signature that is override-equivalent to the derived constructor signature of the record class, there can be only one canonical constructor declared explicitly in the record class.

The declaration of a (non-compact) canonical constructor must satisfy all of the following conditions, or a compile-time error occurs:

A consequence of these rules is that the annotations on a record component can differ from the annotations on the corresponding formal parameter of an explicitly declared canonical constructor. For example, the following record declaration is valid:

import java.lang.annotation.Target;import java.lang.annotation.ElementType;@interface Foo {}@interface Bar {}record Person(@Foo String name) {    Person(@Bar String name) {        this.name = name;    }}

Acompact constructor declaration is a succinct form of constructor declaration, only available in a record declaration. It declares the canonical constructor of a record class without requiring the record components of the class to be manually repeated as formal parameters of the constructor.

The following productions from§8.8,§8.8.3, and§8.8.7 are shown here for convenience:

It is a compile-time error for a record declaration to have more than one compact constructor declaration.

The formal parameters of a compact constructor of a record class are implicitly declared. They are given by the derived formal parameter list of the record class (§8.10.4).

The compact constructor of a record class is a variable arity constructor (§8.8.1) if the record class has a variable arity record component.

The signature of a compact constructor declaration is equal to the derived constructor signature of the record class (§8.10.4.1).

The body of a compact constructor declaration must satisfy all of the following conditions, or a compile-time error occurs:

If a record declaration has a record component namedc, then the simple namec in the body of a compact constructor denotes the implicit formal parameter namedc, and not the component field namedc.

After the last statement, if any, in the body of the compact constructor has completed normally (§14.1), all component fields of the record class are implicitly initialized to the values of the corresponding formal parameters. The component fields are initialized in the order that the corresponding record components are declared in the record header.

The intent of a compact constructor declaration is that only code to validate or normalize parameters needs to be given in the constructor body; the remaining initialization code is supplied by the compiler. For example, the following record class has a compact constructor that simplifies a rational number:

record Rational(int num, int denom) {    private static int gcd(int a, int b) {        if (b == 0) return Math.abs(a);        else return gcd(b, a % b);    }    Rational {        int gcd = gcd(num, denom);        num    /= gcd;        denom  /= gcd;    }}

The compact constructorRational {...} behaves the same as this normal constructor:

Rational(int num, int denom) {    int gcd = gcd(num, denom);    num    /= gcd;    denom  /= gcd;    this.num   = num;    this.denom = denom;}