[This needs updating to cover the behavior of japicompat in the presence of 1.5 language features, and the linked text file should be included in the page directly. Summary of the status of 1.5: all 1.5 language features are understood except for annotations applied to classes and members]

japicompat tests for binary compatibility as defined by Sun in the JLS. A full summary of what does and does not break binary compatibility according to Sun is here.

However, japicompat also performs some checks that are not specified by the JLS, for the simple reason that I believe the JLS is wrong to omit them. You can omit these four extra checks by passing the "-s" flag to japicompat, although I'm not sure why you would want to...

The specific checks that I believe the JLS should include are:

• Adding an exception to the throws clause of a method or constructor violates binary compatibility, because a class calling that method may not catch or specify the newly thrown exception. The JLS claims that the VM does not perform any checks on thrown exceptions; I hope this has changed because it makes it trivially easy to write a method that throws any exception you like without specifying it.
• Removing an exception from the throws clause of a method or constructor violates binary compatibility, because a subclass may be overriding the method and throwing the exception. This only applies to non-final methods, but it is worth enforcing this rule for all methods and constructors because otherwise it is possible to break source code compatibility by rendering code in a catch block unreachable.
• Adding a method to an interface violates binary compatibility, because a class that implemented the original version of the interface may not implement the newly added method.
• Adding an abstract method to an abstract class violates binary compatibility, because a concrete class derived from the original version may not provide a concrete implementation of the new method.