CHAPTER 13

Binary Compatibility

Development tools for the Java programming language should support automatic recompilation as necessary whenever source code is available. Particular implementations may also store the source and binary of types in a versioning database and implement a ClassLoader that uses integrity mechanisms of the database to prevent linkage errors by providing binary-compatible versions of types to clients.

Developers of packages and classes that are to be widely distributed face a different set of problems. In the Internet, which is our favorite example of a widely distributed system, it is often impractical or impossible to automatically recompile the pre-existing binaries that directly or indirectly depend on a type that is to be changed. Instead, this specification defines a set of changes that developers are permitted to make to a package or to a class or interface type while preserving (not breaking) compatibility with existing binaries.

The paper quoted above appears in Proceedings of OOPSLA '95, published as ACM SIGPLAN Notices, Volume 30, Number 10, October 1995, pages 426-438. Within the framework of that paper, Java programming language binaries are binary compatible under all relevant transformations that the authors identify (with some caveats with respect to the addition of instance variables). Using their scheme, here is a list of some important binary compatible changes that the Java programming language supports:

• Reimplementing existing methods, constructors, and initializers to improve performance.
• Changing methods or constructors to return values on inputs for which they previously either threw exceptions that normally should not occur or failed by going into an infinite loop or causing a deadlock.
• Adding new fields, methods, or constructors to an existing class or interface.
• Deleting private fields, methods, or constructors of a class.
• When an entire package is updated, deleting default (package-only) access fields, methods, or constructors of classes and interfaces in the package.
• Reordering the fields, methods, or constructors in an existing type declaration.
• Moving a method upward in the class hierarchy.
• Reordering the list of direct superinterfaces of a class or interface.
• Inserting new class or interface types in the type hierarchy.

We encourage development systems to provide facilities that alert developers to the impact of changes on pre-existing binaries that cannot be recompiled.

This chapter first specifies some properties that any binary format for the Java programming language must have (§13.1). It next defines binary compatibility, explaining what it is and what it is not (§13.2). It finally enumerates a large set of possible changes to packages (§13.3), classes (§13.4) and interfaces (§13.5), specifying which of these changes are guaranteed to preserve binary compatibility and which are not.

13.1 The Form of a Binary

The required properties are:

• The class or interface must be named by its binary name, which must meet the following constraints:
  • The binary name of a top-level type is its canonical name (§6.7).
  • The binary name of a member type consists of the binary name of its immediately enclosing type, followed by $ followed by the simple name of the member.
  • The binary name of any nested type must have, as a prefix, the binary name of its enclosing top-level class.
• A reference to another class or interface type must be symbolic, using the binary name of the type.
• Given a legal expression denoting a field access in a class C, referencing a field named f declared in a (possibly distinct) class or interface D, we define the qualifying type of the field reference as follows:
  • If the expression is of the form Primary.f then the compile-time type of Primary is the qualifying type of the reference.
  • If the expression is of the form super.f then the superclass of C is the qualifying type of the reference.
  • If the expression is of the form X.super.f then the superclass of X is the qualifying type of the reference.
  • If the reference is of the form X.f, where X denotes a class or interface, then the class or interface denoted by X is the qualifying type of the reference
  • If the expression is referenced by a simple name, then if f is a member of the current class or interface, C, then let T be C. Otherwise, let T be the innermost lexically enclosing class of which f is a member. T is the qualifying type of the reference.

The reference to f must be compiled into a symbolic reference to the qualifying type of the reference, plus the simple name of the field, f. The reference must also include a symbolic reference to the declared type of the field so that the verifier can check that the type is as expected. References to fields that are final and initialized with compile-time constant expressions are resolved at compile time to the constant value that is denoted. No reference to such a constant field should be present in the code in a binary file (except in the class or interface containing the constant field, which will have code to initialize it), and such constant fields must always appear to have been initialized; the default initial value for the type of such a field must never be observed. See §13.4.8 for a discussion.

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

If D is Object then the qualifying type of the expression is Object. Otherwise:
• If the expression is of the form Primary.m then the compile-time type of Primary is the qualifying type of the method invocation.
• If the expression is of the form super.m then the superclass of C is the qualifying type of the method invocation.
• If the expression is of the form X.super.m then the superclass of X is the qualifying type of the method invocation.
• If the reference is of the form X.m, where X denotes a class or interface, then the class or interface denoted by X is the qualifying type of the method invocation
• If the method is referenced by a simple name, then if m is a member of the current class or interface, C, let T be C. Otherwise, let T be the innermost lexically enclosing class of which m is a member. T is the qualifying type of the method invocation.
A reference to a method must be resolved at compile time to a symbolic reference to the qualifying type of the invocation, plus the signature of the method (§8.4.2). A reference to a method must also include either a symbolic reference to the return type of the denoted method or an indication that the denoted method is declared void and does not return a value. The signature of a method must include all of the following:
• The simple name of the method
• The number of parameters to the method
• A symbolic reference to the type of each parameter

• Given a class instance creation expression (§15.9) or a constructor invocation statement (§8.8.5.1) in a class or interface C referencing a constructor m declared in a (possibly distinct) class or interface D, we define the qualifying type of the constructor invocation as follows:
  • If the expression is of the form new D(...) or X.new D(...), then the qualifying type of the invocation is D.
  • If the expression is of the form new D(..){...} or X.new D(...){...}, then the qualifying type of the expression is the compile-time type of the expression.
  • If the expression is of the form super(...) or Primary.super(...) then the qualifying type of the expression is the direct superclass of C.
  • If the expression is of the form this(...), then the qualifying type of the expression is C.

A reference to a constructor must be resolved at compile time to a symbolic reference to the qualifying type of the invocation, plus the signature of the constructor (§8.8.2). The signature of a constructor must include both:
• The number of parameters to the constructor
• A symbolic reference to the type of each parameter
In addition the constructor of a non-private inner member class must be compiled such that it has as its first parameter, an additional implicit parameter representing the immediately enclosing instance (§8.1.2).

• Any constructs introduced by the compiler that do not have a corresponding construct in the a source code must be marked as synthetic, except for default constructors and the class initialization method.

• If it is a class and is not class Object, then a symbolic reference to the direct superclass of this class
• A symbolic reference to each direct superinterface, if any
• A specification of each field declared in the class or interface, given as the simple name of the field and a symbolic reference to the type of the field
• If it is a class, then the signature of each constructor, as described above
• For each method declared in the class or interface, its signature and return type, as described above
• The code needed to implement the class or interface:
  • For an interface, code for the field initializers
  • For a class, code for the field initializers, the instance and static initializers, and the implementation of each method or constructor
• Every type must contain sufficient information to recover its canonical name (§6.7).
• Every member type must have sufficient information to recover its source level access modifier.
• Every nested class must have a symbolic reference to its immediately enclosing class.
• Every class that contains a nested class must contain symbolic references to all of its member classes, and to all local and anonymous classes that appear in its methods, constructors and static or instance initializers.

13.2 What Binary Compatibility Is and Is Not

Binaries are compiled to rely on the accessible members and constructors of other classes and interfaces. To preserve binary compatibility, a class or interface should treat its accessible members and constructors, their existence and behavior, as a contract with its users.

The Java programming language is designed to prevent additions to contracts and accidental name collisions from breaking binary compatibility; specifically:

• Addition of more methods overloading a particular method name does not break compatibility with preexisting binaries. The method signature that the preexisting binary will use for method lookup is chosen by the method overload resolution algorithm at compile time (§15.12.2). (If the language had been designed so that the particular method to be executed was chosen at run time, then such an ambiguity might be detected at run time. Such a rule would imply that adding an additional overloaded method so as to make ambiguity possible at a call site could break compatibility with an unknown number of preexisting binaries. See §13.4.21 for more discussion.)

13.3 Evolution of Packages

Changes in top-level class and interface types that are not public and that are not a superclass or superinterface, respectively, of a public type, affect only types within the package in which they are declared. Such types may be deleted or otherwise changed, even if incompatibilities are otherwise described here, provided that the affected binaries of that package are updated together.

13.4 Evolution of Classes

13.4.1 abstract Classes

Changing a class that was declared abstract to no longer be declared abstract does not break compatibility with pre-existing binaries.

13.4.2 final Classes

Changing a class that was declared final to no longer be declared final does not break compatibility with pre-existing binaries.

13.4.3 public Classes

If a class that was declared public is changed to not be declared public, then an IllegalAccessError is thrown if a pre-existing binary is linked that needs but no longer has access to the class type; such a change is not recommended for widely distributed classes.

13.4.4 Superclasses and Superinterfaces

Changing the direct superclass or the set of direct superinterfaces of a class type will not break compatibility with pre-existing binaries, provided that the total set of superclasses or superinterfaces, respectively, of the class type loses no members.

If a change to the direct superclass or the set of direct superinterfaces results in any class or interface no longer being a superclass or superinterface, respectively, then link-time errors may result if pre-existing binaries are loaded with the binary of the modified class. Such changes are not recommended for widely distributed classes.

For example, suppose that the following test program:

class Hyper { char h = 'h'; } 
class Super extends Hyper { char s = 's'; }
class Test extends Super {
    public static void main(String[] args) {
        Hyper h = new Super();
        System.out.println(h.h);
    }
}

h

class Super { char s = 's'; }

It is instructive to consider what might happen without the verification step: the program might run and print:

s

The lesson is that an implementation that lacks a verifier or fails to use it will not maintain type safety and is, therefore, not a valid implementation.

13.4.5 Class Body and Member Declarations

Deleting a class member or constructor that is not declared private may cause a linkage error if the member or constructor is used by a pre-existing binary.

If the program:

class Hyper {
	void hello() { System.out.println("hello from Hyper"); }
}
class Super extends Hyper {
	void hello() { System.out.println("hello from Super"); }
}
class Test {
	public static void main(String[] args) {
		new Super().hello();
	}
}

hello from Super

class Super extends Hyper { }

hello from Hyper

The super keyword can be used to access a method declared in a superclass, bypassing any methods declared in the current class. The expression:

super.Identifier

class Hyper {
	void hello() { System.out.println("hello from Hyper"); }
}
class Super extends Hyper { }
class Test extends Super {
	public static void main(String[] args) {
		new Test().hello();
	}
	void hello() {
		super.hello();
	}
}

hello from Hyper

class Super extends Hyper {
	void hello() { System.out.println("hello from Super"); }
}

hello from Super

hello from Hyper

13.4.6 Access to Members and Constructors

Perhaps surprisingly, the binary format is defined so that changing a member or constructor to be more accessible does not cause a linkage error when a subclass (already) defines a method to have less access.

So, for example, if the package points defines the class Point:

package points;
public class Point {
	public int x, y;
	protected void print() {
		System.out.println("(" + x + "," + y + ")");
	}
}

class Test extends points.Point {
	protected void print() { System.out.println("Test"); }
	public static void main(String[] args) {
		Test t = new Test();
		t.print();
	}
}

Test

Allowing superclasses to change protected methods to be public without breaking binaries of preexisting subclasses helps make binaries less fragile. The alternative, where such a change would cause a linkage error, would create additional binary incompatibilities.

13.4.7 Field Declarations

Assume a reference to a field f with qualifying type T. Assume further that f is in fact an instance (respectively static) field declared in a superclass of T, S, and that the type of f is X. If a new field of type X with the same name as f is added to a subclass of S that is a superclass of T or T itself, then a linkage error may occur. Such a linkage error will occur only if, in addition to the above, either one of the following conditions hold:

• The new field is less accessible than the old one.
• The new field is a static (respectively instance) field.

Thus compiling and executing the code:

class Hyper { String h = "hyper"; }
class Super extends Hyper { String s = "super"; }
class Test {
	public static void main(String[] args) {
		System.out.println(new Super().h);
	}
}

hyper

class Super extends Hyper {
	String s = "super";
	int h = 0;
}

hyper

As an example, if the program:

class Hyper { String h = "Hyper"; }
class Super extends Hyper { }
class Test extends Super {
	public static void main(String[] args) {
		String s = new Test().h;
		System.out.println(s);
	}
}

Hyper

class Super extends Hyper { char h = 'h'; }

Hyper

class Hyper { String h = "Hyper"; }
class Super extends Hyper { char h = 'h'; }
class Test extends Super {
	public static void main(String[] args) {
		String s = new Test().h;
		System.out.println(s);
	}
}

Deleting a field from a class will break compatibility with any pre-existing binaries that reference this field, and a NoSuchFieldError will be thrown when such a reference from a pre-existing binary is linked. Only private fields may be safely deleted from a widely distributed class.

13.4.8 final Fields and Constants

For example, if the program:

class Super { static char s; }
class Test extends Super {
	public static void main(String[] args) {
		s = 'a';
		System.out.println(s);
	}
}

a

class Super { final static char s = 'b'; }

Deleting the keyword final or changing the value to which a field is initialized does not break compatibility with existing binaries.

If a field is a compile-time constant, then deleting the keyword final or changing its value will not break compatibility with pre-existing binaries by causing them not to run, but they will not see any new value for the constant unless they are recompiled.

If the example:

class Flags { final static boolean debug = true; }
class Test {
	public static void main(String[] args) {
		if (Flags.debug)
			System.out.println("debug is true");
	}
}

debug is true

class Flags { final static boolean debug = false; }

debug is true

This result is a side-effect of the decision to support conditional compilation, as discussed at the end of §14.20.

This behavior would not change if Flags were changed to be an interface, as in the modified example:

interface Flags { boolean debug = true; }
class Test {
	public static void main(String[] args) {
		if (Flags.debug)
			System.out.println("debug is true");
	}
}

The best way to avoid problems with "inconstant constants" in widely-distributed code is to declare as compile time constants only values which truly are unlikely ever to change. Many compile time constants in interfaces are small integer values replacing enumerated types, which the language does not support; these small values can be chosen arbitrarily, and should not need to be changed. Other than for true mathematical constants, we recommend that source code make very sparing use of class variables that are declared static and final. If the read-only nature of final is required, a better choice is to declare a private static variable and a suitable accessor method to get its value. Thus we recommend:

private static int N;
public static int getN() { return N; }

public static final int N = ...;

public static int N = ...;

interface Flags {
	boolean debug = new Boolean(true).booleanValue();
}

One other thing to note is that static final fields that have constant values (whether of primitive or String type) must never appear to have the default initial value for their type (§4.5.5). This means that all such fields appear to be initialized first during class initialization (§8.3.2.1, §9.3.1, §12.4.2).

13.4.9 static Fields

13.4.10 transient Fields

13.4.11 Method and Constructor Declarations

Assume a reference to a method m with qualifying type T. Assume further that m is in fact an instance (respectively static) method declared in a superclass of T, S. If a new method of type X with the same signature and return type as m is added to a subclass of S that is a superclass of T or T itself, then a linkage error may occur. Such a linkage error will occur only if, in addition to the above, either one of the following conditions hold:

• The new method is less accessible than the old one.
• The new method is a static (respectively instance) method.

If the source code for a class contains no declared constructors, the Java compiler automatically supplies a constructor with no parameters. Adding one or more constructor declarations to the source code of such a class will prevent this default constructor from being supplied automatically, effectively deleting a constructor, unless one of the new constructors also has no parameters, thus replacing the default constructor. The automatically supplied constructor with no parameters is given the same access modifier as the class of its declaration, so any replacement should have as much or more access if compatibility with pre-existing binaries is to be preserved.

13.4.12 Method and Constructor Parameters

13.4.13 Method Result Type

13.4.14 abstract Methods

Changing a method that is not declared abstract to be declared abstract will break compatibility with pre-existing binaries that previously invoked the method, causing an AbstractMethodError.

If the example program:

class Super { void out() { System.out.println("Out"); } }
class Test extends Super {
	public static void main(String[] args) {
		Test t = new Test();
		System.out.println("Way ");
		t.out();
	}
}

Way
Out

abstract class Super {
	abstract void out();
}

13.4.15 final Methods

If the test program:

class Super { void out() { System.out.println("out"); } }
class Test extends Super {
	public static void main(String[] args) {
		Test t = new Test();
		t.out();
	}
	void out() { super.out(); }
}

out

class Super { final void out() { System.out.println("!"); } }

Changing a class (static) method that is not final to be final does not break compatibility with existing binaries, because the method could not have been overridden.

Removing the final modifier from a method does not break compatibility with pre-existing binaries.

13.4.16 native Methods

The impact of changes to types on preexisting native methods that are not recompiled is beyond the scope of this specification and should be provided with the description of an implementation. Implementations are encouraged, but not required, to implement native methods in a way that limits such impact.

13.4.17 static Methods

13.4.18 synchronized Methods

13.4.19 Method and Constructor Throws

13.4.20 Method and Constructor Body

We note that a compiler cannot expand a method inline at compile time.

The keyword final on a method does not mean that the method can be safely inlined; it means only that the method cannot be overridden. It is still possible that a new version of that method will be provided at link time. Furthermore, the structure of the original program must be preserved for purposes of reflection.

In general we suggest that implementations use late-bound (run-time) code generation and optimization.

13.4.21 Method and Constructor Overloading

While adding a new overloaded method or constructor may cause a compile-time error the next time a class or interface is compiled because there is no method or constructor that is most specific (§15.12.2.2), no such error occurs when a program is executed, because no overload resolution is done at execution time.

If the example program:

class Super {
	static void out(float f) { System.out.println("float"); }
}
class Test {
	public static void main(String[] args) {
		Super.out(2);
	}
}

float

class Super {
	static void out(float f) { System.out.println("float"); }
	static void out(int i) { System.out.println("int"); }
}

float

int

13.4.22 Method Overriding

13.4.23 Static Initializers

13.5 Evolution of Interfaces

13.5.1 public Interfaces

If an interface that is declared public is changed to not be declared public, then an IllegalAccessError is thrown if a pre-existing binary is linked that needs but no longer has access to the interface type, so such a change is not recommended for widely distributed interfaces.

13.5.2 Superinterfaces

13.5.3 The Interface Members

Deleting a member from an interface may cause linkage errors in pre-existing binaries.

If the example program:

interface I { void hello(); }
class Test implements I {
	public static void main(String[] args) {
		I anI = new Test();
		anI.hello();
	}
	public void hello() { System.out.println("hello"); }
}

hello

interface I { }

13.5.4 Field Declarations

13.5.5 Abstract Method Declarations