C API Migration Compatibility Rules (Signature Test)

C.1.1 General Rules

The rules from this group are triggered if the more specific rules from the other groups below are not triggered. For example, adding an interface method defined in rule 2.1, adding constructor in the rule 5.5. In such cases more general rule 1.1 is ignored.

C.1.2 Interfaces and Annotation Types

The rules in this group apply to interfaces and annotation types.

C.1.3 Interfaces and Class Methods

The rules in this group apply to interfaces and class methods.

C.1.4 Interfaces and Class Fields

The rules in this group apply to interfaces and class methods.

C.1.5 Classes

The rules in this group apply to classes.

C.2.1 Rule 1.1

Adding a class can theoretically break source code compatibility because new classes can be incorrectly resolved in an existing client's code with type-import-on-demand declarations (also know as wildcard imports). This can happen if the code uses another type with the same simple name. For example:

//client's code

import com.acme.*;
import com.client.*;

   .....

   Policy p = new Policy();   // this is com.client.Policy

   .....

In this case, after adding class com.acme.Policy, the compiler raises the error

reference to Policy is ambiguous, both class com.acme.Policy in com.acme and class com.client.Policy in com.client match.

This rule is considered a warning because it will probably not affect binary compatibility and adhering to this rule makes API evolution very difficult.

C.2.2 Rule 1.4

Generics are a facility of generic programming that was added to the Java programming language as part of Java SE version 5.0. Generics allow a type or method to operate on objects of various types while providing compile-time type safety. Generification upgrades types using support to-be-specified-later types that are instantiated as needed for specific types that are provided as type parameters.

The Java programming language implements generics using erasure, which ensures that legacy and generic versions usually generate identical class files, except for some auxiliary information about types. Binary compatibility is not broken because it is possible to replace a legacy class file with a generic class file without changing or recompiling any client code.

To facilitate interfacing with non-generic legacy code, it is also possible to use the erasure of a parameterized type as a type. Such a type is called a raw type (Java Language Specification 3/4.8). Allowing the raw type also ensures backward compatibility for source code.

According to this, the following versions of the java.util.Iterator class are both binary and source code backward compatible:

• Class java.util.Iterator as it is defined in Java SE version 1.4:

  public interface Iterator {
      boolean hasNext();
      Object next();
      void remove();
  }
  

• Class java.util.Iterator as it is defined in Java SE version 5.0:

  public interface Iterator<E> {
      boolean hasNext();
      E next();
      void remove();
  }
  

C.2.3 Rule 2.3

Adding a superinterface with a constant field can shadow another entity with the same simple name. Consider the following code:

public interface Poet{
    boolean LITERATE = true;
}

public interface Playwright{
    boolean LITERATE = true;
}

public interface Shakespeare extends Poet {

}

Suppose that a new version of the Shakespeare interface implements interface Playwright as well as Poet as shown here:

public interface Shakespeare extends Poet, Playwright {

}

The following client code will not compile because the reference to LITERATE is ambiguous.

// client code 
public class ShakespeareImpl implements Shakespeare {
    void introduce() {
        System.out.println("Hi, my name is Shakespeare and I'm " + LITERATE ?
                "quite literate" : "rather illiterate" );}
}

C.2.4 Rules 2.5, 2.6

The example below shows how adding a member without a default value to an annotation type breaks source code compatibility.

// annotation type v1
@interface Agent{
   String name();
}

// client's code which uses this annotation type v1
@Agent(name="James Bond")  


// annotation type v2.1
@interface Agent{
   String name();
   String id(); // added member
}

// legacy code is not compilable due to 
// error - annotation Agent is missing id
@Agent(name="James Bond")


// annotation type v2.2
@interface Agent{
   String name();
   String id() default "007";  // added member with default value
}

// legacy code is compilable
@Agent(name="James Bond") 

C.2.5 Rule 3.6

Changing a method from protected to public can break source code compatibility if this method was overridden as protected. In this case the legacy code can not be recompiled because ”access narrowing” is prohibited in the Java programming language. This rule is only a warning because it does not affect binary compatibility, and the probability of its affecting source code compatibility is very low.

C.2.6 Rule 4.2

Changing or removing constant values can break source code compatibility. For example, consider the following client code example. An integer constant named NOTHING with a value of 0 is used:

switch (i) {
    case NOTHING:
        // some actions
    case -1:
        // some other actions
}

Assume that the value of the constant NOTHING is changed from 0 to -1. The client code will not compile because of the duplicate case label. This rule is only a warning because it does not affect binary compatibility, and the probability of its affecting source code compatibility is very low.

C.2.7 Rule 5.1

Adding a regular method to a subclassable class can break source code and binary compatibility because a subclass can have a method with the same signature but with weaker access privileges. For example consider the following code example:

class ClientClass extends APIClass {
    private void foo() {}
}

Assume that the class APIClass is changed, and the method

protected void foo() {}

is added. The code cannot be recompiled due of an error that generates the following error message:

foo() in ClientClass cannot override foo() in APIClass; attempting to assign weaker access privileges; was protected

Binary compatibility is broken as defined in JLS 3/3.14.12

C.2.8 Rule 5.3

Adding a static method to a subclassable class can break source code and binary compatibility, because a subclass can have a method with the same signature. For example consider the following code example:

class ClientClass extends APIClass {
    protected void foo() {}
}

Suppose that the class APIClass is changed and the method

  protected static void foo() {}

is added. The code can not be recompiled due to an error that generates the following error message:

foo() in ClientClass cannot override foo() in APIClass; overridden method is static

Binary compatibility is be broken as defined in JLS 3/3.14.12

C.2.9 Rule 5.7.2

As in the case of rule 2.3, adding a superinterface with a constant field can shadow another entity with the same simple name.