CHAPTER 8

Classes

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

The name of a class has as its scope all type declarations in the package in which the class is declared (§8.1.1). A class may be declared abstract (§8.1.2.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.2.2), in which case it cannot have subclasses. If a class is declared public, then it can be referred to from other packages.

Each class except Object is an extension of (that is, a subclass of) a single existing class (§8.1.3) and may implement interfaces (§8.1.4).

The body of a class declares members (fields and methods), static initializers, and constructors (§8.1.5). The scope of the name of a member is the entire declaration of the class to which the member belongs. Field, method, 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 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 cannot be assigned to except as part of its declaration. Any field declaration may include an initializer; the declaration of a final field must include an initializer.

Method declarations (§8.4) describe code that may be invoked by method invocation expressions (§15.11). 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 the 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.5) automatically locks an object before executing its body and automatically unlocks the object on return, as if by use of a synchronized statement (§14.17), thus allowing its activities to be synchronized with those of other threads (§17).

Method names may be overloaded (§8.4.7).

Static initializers (§8.5) are blocks of executable code that may be used to help initialize a class when it is first loaded (§12.4).

Constructors (§8.6) 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.6.6).

8.1 Class Declaration

ClassDeclaration:

	ClassModifiersopt class Identifier Superopt Interfacesopt ClassBody

class Point { int x, y; }

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

A compile-time error occurs if the Identifier naming a class appears as the name of any other class type or interface type declared in the same package (§7.6).

A compile-time error occurs if the Identifier naming a class is also declared as a type by a single-type-import declaration (§7.5.1) in the compilation unit (§7.3) containing the class declaration.

In the example:

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

Note, however, that it is not an error for the Identifier that names a class also to name a type that otherwise might be imported by a type-import-on-demand declaration (§7.5.2) in the compilation unit (§7.3) containing the class declaration. In the example:

package test;

import java.util.*;

class Vector { Point[] pts; }											// not a compile-time error

8.1.1 Scope of a Class Type Name

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
}

8.1.2 Class Modifiers

ClassModifiers:

	ClassModifier

	ClassModifiers ClassModifier

ClassModifier: one of

	public abstract final

8.1.2.1 abstract Classes

• It explicitly contains a declaration of an abstract method (§8.4.3).
• It inherits an abstract method from its direct superclass (§8.1.3).
• A direct superinterface (§8.1.4) of the class declares or inherits a method (which is therefore necessarily abstract) and the class neither declares nor inherits a method that implements it.

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

A compile-time error occurs if an attempt is made to create an instance of an abstract class using a class instance creation expression (§15.8). An attempt to instantiate an abstract class using the newInstance method of class Class (§20.3.6) will cause an InstantiationException (§11.5.1) to be thrown. Thus, continuing the example just shown, the statement:

	Point p = new Point();

	Point p = new SimplePoint();

A subclass of an abstract class that is not itself abstract may be instantiated, resulting in the execution of a constructor for the abstract class and, therefore, the execution of the field initializers for instance variables of that class. Thus, in the example just given, instantiation of a SimplePoint causes the default constructor and field initializers for x and y of Point to be executed.

It is a compile-time error to declare an abstract class type such that it is not possible to create a subclass that implements all of its abstract methods. This situation can occur if the class would have as members two abstract methods that have the same method signature (§8.4.2) but different return types. As an example, the declarations:

interface Colorable { void setColor(int color); }

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

A class type should be declared abstract 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.6.8) of no arguments, make it private, never invoke it, and declare no other constructors. A class of this form usually contains class methods and variables. The class java.lang.Math is an example of a class that cannot be instantiated; its declaration looks like this:

public final class Math {

	private Math() { }							// never instantiate this class


	. . . declarations of class variables and methods . . .

}

8.1.2.2 final Classes

Because a final class never has any subclasses, the methods of a final class are never overridden (§8.4.6.1).

8.1.3 Superclasses and Subclasses

Super:

	extends ClassType

ClassType:

	TypeName

In the example:

class Point { int x, y; }


final class ColoredPoint extends Point { int color; }

class Colored3DPoint extends ColoredPoint { int z; } // error

• The class Point is a direct subclass of java.lang.Object.
• The class java.lang.Object is the direct superclass of the class Point.
• The class ColoredPoint is a direct subclass of class Point.
• The class Point is the direct superclass of class ColoredPoint.

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

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

In the example:

class Point { int x, y; }


class ColoredPoint extends Point { int color; }

final class Colored3dPoint extends ColoredPoint { int z; }

• The class Point is a superclass of class ColoredPoint.
• The class Point is a superclass of class Colored3dPoint.
• The class ColoredPoint is a subclass of class Point.
• The class ColoredPoint is a superclass of class Colored3dPoint.
• The class Colored3dPoint is a subclass of class ColoredPoint.
• The class Colored3dPoint is a subclass of class Point.

class Point extends ColoredPoint { int x, y; }

class ColoredPoint extends Point { int color; }

8.1.4 Superinterfaces

Interfaces:

	implements InterfaceTypeList

InterfaceTypeList:

	InterfaceType

	InterfaceTypeList , InterfaceType

InterfaceType:

	TypeName

A compile-time error occurs if the same interface is mentioned two or more times in a single implements clause, even if the interface is named in different ways; for example, the code:

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

An interface type I is a superinterface of class type C if any of the following is true:

• I is a direct superinterface of C.
• C has some direct superinterface J for which I is a superinterface, using the definition of "superinterface of an interface" given in §9.1.3.
• I is a superinterface of the direct superclass of C, using this definition recursively.

In the example:

public interface Colorable {
	void setColor(int color);
	int getColor();
}


public interface Paintable extends Colorable {
	int MATTE = 0, GLOSSY = 1;
	void setFinish(int finish);
	int 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 

{
	int finish;
	public void setFinish(int finish) {
		this.finish = finish;
	}
	public int getFinish() { return finish; }
}

• The interface Paintable is a superinterface of class PaintedPoint.
• The interface Colorable is a superinterface of class ColoredPoint and of class PaintedPoint.
• The interface Paintable is a subinterface of the interface Colorable, and Colorable is a superinterface of Paintable, as defined in §9.1.3.

Unless the class being declared is abstract, the declarations of the methods defined in each direct superinterface must be implemented either by a declaration in this class or by an existing method declaration inherited from the direct superclass, because a class that is not abstract is not permitted to have abstract methods (§8.1.2.1).

Thus, the example:

interface Colorable {
	void setColor(int color);
	int getColor();
}


class Point { int x, y; };


class ColoredPoint extends Point implements Colorable {
	int color;
}

It is permitted for a single method declaration in a class to implement methods of more than one superinterface. For example, in the code:

interface Fish { int getNumberOfScales(); }


interface Piano { int getNumberOfScales(); }

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

On the other hand, in a situation such as this:

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

8.1.5 Class Body and Member Declarations

ClassBody:

	{ ClassBodyDeclarationsopt }

ClassBodyDeclarations:

	ClassBodyDeclaration

	ClassBodyDeclarations ClassBodyDeclaration

ClassBodyDeclaration:

	ClassMemberDeclaration

	StaticInitializer

	ConstructorDeclaration

ClassMemberDeclaration:

	FieldDeclaration

	MethodDeclaration

8.2 Class Members

• Members inherited from its direct superclass (§8.1.3), except in class Object, which has no direct superclass
• Members inherited from any direct superinterfaces (§8.1.4)
• Members declared in the body of the class (§8.1.5)

Constructors and static initializers are not members and therefore are not inherited.

The example:

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

• An error occurs because ColoredPoint has no constructor declared with two integer parameters, as requested by the use in main. This illustrates the fact that ColoredPoint does not inherit the constructors of its superclass Point.
• Another error occurs because ColoredPoint declares no constructors, and therefore a default constructor for it is automatically created (§8.6.7), and this default constructor is equivalent to: ColoredPoint() { super(); }

which invokes the constructor, with no arguments, for the direct superclass of the class ColoredPoint. The error is that the constructor for Point that takes no arguments is private, and therefore is not accessible outside the class Point, even through a superclass constructor invocation (§8.6.5).

• Two more errors occur because the method reset of class Point is private, and therefore is not inherited by class ColoredPoint. The method invocations in method clear of class ColoredPoint and in method main of class Test are therefore not correct.

8.2.1 Examples of Inheritance

8.2.1.1 Example: Inheritance with Default Access

package points;

public class Point {
	int x, y;

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

package points;

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

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

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

8.2.1.2 Inheritance with public and protected

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

}

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

8.2.1.3 Inheritance with private

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

}

8.2.1.4 Accessing Members of Inaccessible Classes

Consider the compilation unit:

package points;

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

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 class OnePoint {
	static points.Point getOne() { return new Point3d(); }
}

While the field z of class Point3d is public, it is not possible to access this field from code outside the package morePoints, given only a reference to an instance of class Point3d in a variable p of type Point. This is because the expression p.z is not correct, as p has type Point and class Point has no field named z; also, the expression ((Point3d)p).z is not correct, because the class type Point3d cannot be referred to outside package morePoints. The declaration of the field z as public is not useless, however. If there were to be, in package morePoints, a public subclass Point4d of the class Point3d:

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

8.3 Field Declarations

FieldDeclaration:

	FieldModifiersopt Type VariableDeclarators ;

VariableDeclarators:

	VariableDeclarator

	VariableDeclarators , VariableDeclarator

VariableDeclarator:

	VariableDeclaratorId

	VariableDeclaratorId = VariableInitializer

VariableDeclaratorId:

	Identifier

	VariableDeclaratorId [ ]

VariableInitializer:

	Expression

	ArrayInitializer

It is a compile-time error for the body of a class declaration to contain declarations of two fields with the same name. Methods and fields may have the same name, since they are used in different contexts and are disambiguated by the different lookup procedures (§6.5).

If the class declares a field with a certain name, then the declaration of that field is said to hide (§6.3.1) any and all accessible declarations of fields with the same name in the superclasses and superinterfaces of the class.

If a field declaration hides the declaration of another field, the two fields need not have the same type.

A class inherits from its direct superclass and direct superinterfaces all the fields 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 field with the same name (§8.3.3.3). 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 field by its simple name will result in a compile-time error, because such a reference is ambiguous.

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

A hidden field can be accessed by using a qualified name (if it is static) or by using a field access expression (§15.10) that contains the keyword super or a cast to a superclass type. See §15.10.2 for discussion and an example.

8.3.1 Field Modifiers

FieldModifiers:

	FieldModifier

	FieldModifiers FieldModifier

FieldModifier: one of

	public protected private

	final static transient volatile

8.3.1.1 static Fields

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

The example program:

class Point {
	int x, y, useCount;
	Point(int x, int y) { this.x = x; this.y = y; }
	final static 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)
0
true
1

q.origin==Point.origin

p.origin.useCount++;

8.3.1.2 final Fields

Any attempt to assign to a final field results in a compile-time error. Therefore, once a final field has been initialized, it always contains the same value. If a final field holds a reference to an object, then the state of the object may be changed by operations on the object, but the field will always refer to the same object. This applies also to arrays, because arrays are objects; if a final field holds a reference to an array, then the components of the array may be changed by operations on the array, but the field will always refer to the same array.

Declaring a field final can serve as useful documentation that its value will not change, can help to avoid programming errors, and can make it easier for a compiler to generate efficient code.

In the example:

class Point {
	int x, y;
	int useCount;
	Point(int x, int y) { this.x = x; this.y = y; }
	final static Point origin = new Point(0, 0);
}

8.3.1.3 transient Fields

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

8.3.1.4 volatile Fields

Java provides a second mechanism that is more convenient for some purposes: a field may be declared volatile, in which case a thread must reconcile its working copy of the field with the master copy every time it accesses the variable. Moreover, operations on the master copies of one or more volatile variables on behalf of a thread are performed by the main memory in exactly the order that the thread requested.

If, in the following example, one thread repeatedly calls the method one (but no more than Integer.MAX_VALUE (§20.7.2) times in all), and another thread repeatedly calls the method two:

class Test {

	static int i = 0, j = 0;


	static void one() { i++; j++; }

	static void two() {
		System.out.println("i=" + i + " j=" + j);
	}

}

One way to prevent this out-or-order behavior would be to declare methods one and two to be synchronized (§8.4.3.5):

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

}

Another approach would be to declare i and j to be volatile:

class Test {

	static volatile int i = 0, j = 0;


	static void one() { i++; j++; }

	static void two() {
		System.out.println("i=" + i + " j=" + j);
	}

}

See §17 for more discussion and examples.

A compile-time error occurs if a final variable is also declared volatile.

8.3.2 Initialization of Fields

• If the declarator is for a class variable (that is, a static field), then the variable initializer is evaluated and the assignment performed exactly once, when the class is initialized (§12.4).
• If the declarator is for an instance variable (that is, a field that is not static), then the variable initializer is evaluated and the assignment performed each time an instance of the class is created (§12.5).

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

Variable initializers are also used in local variable declaration statements (§14.3), where the initializer is evaluated and the assignment performed each time the local variable declaration statement is executed.

It is a compile-time error if the evaluation of a variable initializer for a field of a class (or interface) can complete abruptly with a checked exception (§11.2).

8.3.2.1 Initializers for Class Variables

class Test {
	static float f = j;							// compile-time error: forward reference
	static int j = 1;
	static int k = k+1;							// compile-time error: forward reference
}

If a reference by simple name to any instance variable occurs in an initialization expression for a class variable, then a compile-time error occurs.

If the keyword this (§15.7.2) or the keyword super (§15.10.2, §15.11) occurs in an initialization expression for a class variable, then a compile-time error occurs.

(One subtlety here is that, at run time, static variables that are final and that are initialized with compile-time constant values are initialized first. This also applies to such fields in interfaces (§9.3.1). These variables are "constants" that will never be observed to have their default initial values (§4.5.4), even by devious programs. See §12.4.2 and §13.4.8 for more discussion.)

8.3.2.2 Initializers for Instance Variables

class Test {
	float f = j;
	int j = 1;
	int k = k+1;
}

Initialization expressions for instance variables may use the simple name of any static variable declared in or inherited by the class, even one whose declaration occurs textually later. Thus the example:

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

Initialization expressions for instance variables are permitted to refer to the current object this (§15.7.2) and to use the keyword super (§15.10.2, §15.11).

8.3.3 Examples of Field Declarations

8.3.3.1 Example: Hiding of Class Variables

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

8.3.3.2 Example: Hiding of Instance Variables

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

Code that uses a field access expression to access field x will access the field named x in the class indicated by the type of reference expression. Thus, the expression sample.x accesses a float value, the instance variable declared in class Test, because the type of the variable sample is Test, but the expression ((Point)sample).x accesses an int value, the instance variable declared in class Point, because of the cast to type Point.

If the declaration of x is deleted from class Test, as in the program:

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

8.3.3.3 Example: Multiply Inherited Fields

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 following variation uses the field access expression super.v to refer to the field named v declared in class SuperTest and uses the qualified name Frob.v to refer to the field named v declared in interface Frob:

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

2.5

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

8.3.3.4 Example: Re-inheritance of Fields

public interface Colorable {
	int RED = 0xff0000, GREEN = 0x00ff00, BLUE = 0x0000ff;
}


public 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 
{
	. . .       RED       . . .
}

8.4 Method Declarations

MethodDeclaration:

	MethodHeader MethodBody

MethodHeader:

	MethodModifiersopt ResultType MethodDeclarator Throwsopt

ResultType:

	Type

	void

MethodDeclarator:

	Identifer ( FormalParameterListopt )

The Identifier in a MethodDeclarator may be used in a name to refer to the method. A class can declare a method with the same name as the class or a field of the class.

For compatibility with older versions of Java, a declaration form for a method that returns an array is allowed to place (some or all of) the empty bracket pairs that form the declaration of the array type after the parameter list. This is supported by the obsolescent production:

MethodDeclarator:

	MethodDeclarator [ ]

It is a compile-time error for the body of a class to have as members two methods with the same signature (§8.4.2) (name, number of parameters, and types of any parameters). Methods and fields may have the same name, since they are used in different contexts and are disambiguated by the different lookup procedures (§6.5).

8.4.1 Formal Parameters

FormalParameterList:

	FormalParameter

	FormalParameterList , FormalParameter

FormalParameter:

	Type VariableDeclaratorId

VariableDeclaratorId:

	Identifier

	VariableDeclaratorId [ ]

If two formal parameters are declared to have the same name (that is, their declarations mention the same Identifier), then a compile-time error occurs.

When the method is invoked (§15.11), the values of the actual argument expressions initialize newly created parameter variables, each of the declared Type, before execution of the body of the method. The Identifier that appears in the DeclaratorId may be used as a simple name in the body of the method to refer to the formal parameter.

The scope of formal parameter names is the entire body of the method. These parameter names may not be redeclared as local variables or exception parameters within the method; that is, hiding the name of a parameter is not permitted.

Formal parameters are referred to only using simple names, never by using qualified names (§6.6).

8.4.2 Method Signature

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

8.4.3 Method Modifiers

MethodModifiers:

	MethodModifier

	MethodModifiers MethodModifier

MethodModifier: one of

	public protected private

	abstract static final synchronized native

If two or more method modifiers appear in a method declaration, it is customary, though not required, that they appear in the order consistent with that shown above in the production for MethodModifier.

8.4.3.1 abstract Methods

• B is a superclass of C or is C itself.
• B is a subclass of A.
• B provides a declaration of the method m that is not abstract, and this declaration is inherited by C, thereby providing an implementation of method m that is visible to C.

It is a compile-time error for a private method to be declared abstract. It would be impossible for a subclass to implement a private abstract method, because private methods are not visible to subclasses; therefore such a method could never be used.

It is a compile-time error for a static method to be declared abstract.

It is a compile-time error for a final method to be declared abstract.

An abstract class can override an abstract method by providing another abstract method declaration. This can provide a place to put a documentation comment (§18), or to declare that the set of checked exceptions (§11.2) that can be thrown by that method, when it is implemented by its subclasses, is to be more limited. For example, consider this code:

class BufferEmpty extends Exception {
	BufferEmpty() { super(); }
	BufferEmpty(String s) { super(s); }
}


class BufferError extends Exception {
	BufferError() { super(); }
	BufferError(String s) { super(s); }
}


public interface Buffer {
	char get() throws BufferEmpty, BufferError;
}


public abstract class InfiniteBuffer implements Buffer {
	abstract char get() throws BufferError;
}

An instance method that is not abstract can be overridden by an abstract method. For example, we can declare an abstract class Point that requires its subclasses to implement toString if they are to be complete, instantiable classes:

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

8.4.3.2 static Methods

A method that is not declared static is called an instance 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 keywords this and super refer during execution of the method body.

8.4.3.3 final Methods

A private method and all methods declared in a final class (§8.1.2.2) are implicitly final, because it is impossible to override them. It is permitted but not required for the declarations of such methods to redundantly include the final keyword.

It is a compile-time error for a final method to be declared abstract.

At run-time, a machine-code generator or optimizer can easily and safely "inline" the body of a final method, replacing an invocation of the method with the code in its body, as in the example:

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];
			pi.x += i;
			pi.y += p.length-1-i;
		}

Such inlining cannot be done at compile time unless it can be guaranteed that Test and Point will always be recompiled together, so that whenever Point-and specifically its move method-changes, the code for Test.main will also be updated.

8.4.3.4 native Methods

A compile-time error occurs if a native method is declared abstract.

For example, the class RandomAccessFile of the standard package java.io might declare the following native methods:

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

8.4.3.5 synchronized Methods

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

}

If put and get were not synchronized, and two threads were executing methods for the same instance of Box at the same time, then the code could misbehave. It might, for example, lose track of an object because two invocations to put occurred at the same time.

See §17 for more discussion of threads and locks.

8.4.4 Method Throws

Throws:

	throws ClassTypeList

ClassTypeList:

	ClassType

	ClassTypeList , ClassType

For each checked exception that can result from execution of the body of a method or constructor, a compile-time error occurs unless that exception type or a superclass of that exception type is mentioned in a throws clause in the declaration of the method or constructor.

The requirement to declare checked exceptions allows the compiler to ensure that code for handling such error conditions has been included. Methods or constructors that fail to handle exceptional conditions thrown as checked exceptions will normally result in a compile-time error because of the lack of a proper exception type in a throws clause. Java thus encourages a programming style where rare and otherwise truly exceptional conditions are documented in this way.

The predefined exceptions that are not checked in this way are those for which declaring every possible occurrence would be unimaginably inconvenient:

• Exceptions that are represented by the subclasses of class Error, for example OutOfMemoryError, are thrown due to a failure in or of the virtual machine. Many of these are the result of linkage failures and can occur at unpredictable points in the execution of a Java program. Sophisticated programs may yet wish to catch and attempt to recover from some of these conditions.
• The exceptions that are represented by the subclasses of the class RuntimeException, for example NullPointerException, result from runtime integrity checks and are thrown either directly from the Java program or in library routines. It is beyond the scope of the Java language, and perhaps beyond the state of the art, to include sufficient information in the program to reduce to a manageable number the places where these can be proven not to occur.

More precisely, suppose that B is a class or interface, and A is a superclass or superinterface of B, and a method declaration n in B overrides or hides a method declaration m in A. If n has a throws clause that mentions any checked exception types, then m must have a throws clause, and for every checked exception type listed in the throws clause of n, that same exception class or one of its superclasses must occur in the throws clause of m; otherwise, a compile-time error occurs.

See §11 for more information about exceptions and a large example.

8.4.5 Method Body

MethodBody:

	Block 

	;

If an implementation is to be provided for a method but the implementation requires no executable code, the method body should be written as a block that contains no statements: "{ }".

If a method is declared void, then its body must not contain any return statement (§14.15) that has an Expression.

If a method is declared to have a return type, then every return statement (§14.15) in its body must have an Expression. A compile-time error occurs if the body of the method can complete normally (§14.1). In other words, a method with a return type must return only by using a return statement that provides a value return; it is not allowed to "drop off the end of its body."

Note that it is possible for a method to have a declared return type and yet contain no return statements. Here is one example:

class DizzyDean {

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

}

8.4.6 Inheritance, Overriding, and Hiding

8.4.6.1 Overriding (By Instance Methods)

A compile-time error occurs if an instance method overrides a static method. In this respect, overriding of methods differs from hiding of fields (§8.3), for it is permissible for an instance variable to hide a static variable.

An overridden method can be accessed by using a method invocation expression (§15.11) that contains the keyword super. Note that 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. See §15.11.4.10 for discussion and examples of this point.

8.4.6.2 Hiding (By Class Methods)

A hidden method can be accessed by using a qualified name or by using a method invocation expression (§15.11) that contains the keyword super or a cast to a superclass type. In this respect, hiding of methods is similar to hiding of fields.

8.4.6.3 Requirements in Overriding and Hiding

The access modifier (§6.6) of an overriding or hiding method must provide at least as much access as the overridden or hidden method, or a compile-time error occurs. In more detail:

• If the overridden or hidden method is public, then the overriding or hiding method must be public; otherwise, a compile-time error occurs.
• If the overridden or hidden method is protected, then the overriding or hiding method must be protected or public; otherwise, a compile-time error occurs.
• If the overridden or hidden method has default (package) access, then the overriding or hiding method must not be private; otherwise, a compile-time error occurs.

8.4.6.4 Inheriting Methods with the Same Signature

• If one of the inherited methods is not abstract, then there are two subcases:
  • If the method that is not abstract is static, a compile-time error occurs.
  • Otherwise, the method that is not abstract is considered to override, and therefore to implement, all the other methods on behalf of the class that inherits it. A compile-time error occurs if, comparing the method that is not abstract with each of the other of the inherited methods, for any such pair, either they have different return types or one has a return type and the other is void. Moreover, a compile-time error occurs if the inherited method that is not abstract has a throws clause that conflicts (§8.4.4) with that of any other of the inherited methods.
• If none of the inherited methods is not abstract, then the class is necessarily an abstract class and is considered to inherit all the abstract methods. A compile-time error occurs if, for any two such inherited methods, either they have different return types or one has a return type and the other is void. (The throws clauses do not cause errors in this case.)

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

8.4.7 Overloading

Methods are overridden on a signature-by-signature basis. If, for example, a class declares two public methods with the same name, and a subclass overrides one of them, the subclass still inherits the other method. In this respect, Java differs from C++.

When a method is invoked (§15.11), the number of actual arguments and the compile-time types of the arguments are used, at compile time, to determine the signature of the method that will be invoked (§15.11.2). If the method that is to be invoked is an instance method, the actual method to be invoked will be determined at run time, using dynamic method lookup (§15.11.4).

8.4.8 Examples of Method Declarations

8.4.8.1 Example: Overriding

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

}

8.4.8.2 Example: 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; }

}

In this example, the members of the class RealPoint include the instance variable color inherited from the class Point, the float instance variables x and y declared in RealPoint, and the two move methods declared in RealPoint.

Which of these overloaded move methods of class RealPoint will be chosen for any particular method invocation will be determined at compile time by the overloading resolution procedure described in §15.11.

8.4.8.3 Example: Incorrect Overriding

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

}

8.4.8.4 Example: Overriding versus Hiding

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

}

Consider, then, this test program:

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)

The second line of output shows that the field access rp.x refers to the field x declared in class RealPoint. This field is of type float, and this second line of output accordingly displays floating-point values. Incidentally, this also illustrates the fact that the method name show is overloaded; the types of the arguments in the method invocation dictate which of the two definitions will be invoked.

The last two lines of output show that the method invocations p.getX() and rp.getX() each invoke the getX method declared in class RealPoint. Indeed, there is no way to invoke the getX method of class Point for an instance of class RealPoint from outside the body of RealPoint, no matter what the type of the variable we may use to hold the reference to the object. Thus, we see that fields and methods behave differently: hiding is different from overriding.

8.4.8.5 Example: Invocation of Hidden Class Methods

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

8.4.8.6 Large Example of Overriding

import java.io.OutputStream;


import java.io.IOException;

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

lbo
print
lbo

In the putchar method of a LineBufferOutput object, if the character argument is a newline, then it invokes the flush method. The critical point about overriding in this example is that the method putstr, which is declared in class BufferOutput, invokes the putchar method defined by the current object this, which is not necessarily the putchar method declared in class BufferOutput.

Thus, when putstr is invoked in main using the LineBufferOutput object lbo, the invocation of putchar in the body of the putstr method is an invocation of the putchar of the object lbo, the overriding declaration of putchar that checks for a newline. This allows a subclass of BufferOutput to change the behavior of the putstr method without redefining it.

Documentation for a class such as BufferOutput, which is designed to be extended, should clearly indicate what is the contract between the class and its subclasses, and should clearly indicate that subclasses may override the putchar method in this way. The implementor of the BufferOutput class would not, therefore, want to change the implementation of putstr in a future implementation of BufferOutput not to use the method putchar, because this would break the preexisting contract with subclasses. See the further discussion of binary compatibility in §13, especially §13.2.

8.4.8.7 Example: Incorrect Overriding because of Throws

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

Removing the throws clause does not help:

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

8.5 Static Initializers

StaticInitializer:

	static Block

The static initializers and class variable initializers are executed in textual order and may not refer to class variables declared in the class whose declarations appear textually after the use, even though these class variables are in scope. This restriction is designed to catch, at compile time, circular or otherwise malformed initializations. Thus, both:

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

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

Accesses to class variables by methods are not checked in this way, so:

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

If a return statement (§14.15) appears anywhere within a static initializer, then a compile-time error occurs.

If the keyword this (§15.7.2) or the keyword super (§15.10, §15.11) appears anywhere within a static initializer, then a compile-time error occurs.

8.6 Constructor Declarations

ConstructorDeclaration:

	ConstructorModifiersopt ConstructorDeclarator

		Throwsopt ConstructorBody

ConstructorDeclarator:

	SimpleTypeName ( FormalParameterListopt )

Here is a simple example:

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

Access to constructors is governed by access modifiers (§6.6). This is useful, for example, in preventing instantiation by declaring an inaccessible constructor (§8.6.8).

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

8.6.1 Formal Parameters

8.6.2 Constructor Signature

8.6.3 Constructor Modifiers

ConstructorModifiers:

	ConstructorModifier

	ConstructorModifiers ConstructorModifier

ConstructorModifier: one of

	public protected private

Unlike methods, a constructor cannot be abstract, static, final, native, or synchronized. A constructor is not inherited, so there is no need to declare it final and an abstract constructor could never be implemented. A constructor is always invoked with respect to an object, so it makes no sense for a constructor to be static. There is no practical need for a constructor to be synchronized, 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 of native 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.

8.6.4 Constructor Throws

8.6.5 Constructor Body

ConstructorBody:

	{ ExplicitConstructorInvocationopt BlockStatementsopt }

ExplicitConstructorInvocation:

	this ( ArgumentListopt ) ;

	super ( ArgumentListopt ) ;

If a constructor body does not begin with an explicit constructor invocation and the constructor being declared is not part of the primordial class Object, then the constructor body is implicitly assumed by the compiler to begin with a superclass constructor invocation "super();", an invocation of the constructor of its direct superclass that takes no arguments.

Except for the possibility of explicit constructor invocations, the body of a constructor is like the body of a method (§8.4.5). A return statement (§14.15) may be used in the body of a constructor if it does not include an expression.

In the example:

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;

	}

}

An explicit constructor invocation statement may not refer to any instance variables or instance methods declared in this class or any superclass, or use this or super in any expression; otherwise, a compile-time error occurs. For example, if the first constructor of ColoredPoint in the example above were changed to:

	ColoredPoint(int x, int y) {
		this(x, y, color);
	}

An invocation of the constructor of the direct superclass, whether it actually appears as an explicit constructor invocation statement or is provided automatically (§8.6.7), performs an additional implicit action after a normal return of control from the constructor: all instance variables that have initializers are initialized at that time, in the textual order in which they appear in the class declaration. An invocation of another constructor in the same class using the keyword this does not perform this additional implicit action.

§12.5 describes the creation and initialization of new class instances.

8.6.6 Constructor Overloading

8.6.7 Default Constructor

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

If the class is declared public, then the default constructor is implicitly given the access modifier public (§6.6); otherwise, the default constructor has the default access implied by no access modifier. Thus, the example:

public class Point {
	int x, y;
}

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

8.6.8 Preventing Instantiation of a Class

Thus, in the example:

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

package just;

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

Contents | Prev | Next | Index

Java Language Specification (HTML generated by Suzette Pelouch on February 24, 1998)
Copyright © 1996 Sun Microsystems, Inc. All rights reserved
Please send any comments or corrections to doug.kramer@sun.com