[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.