BackwardCompatibility

From APIDesign

BackwardCompatibility is the tool that helps us, software engineers, practice the style of DistributedDevelopment. In the situation when we build our applications from hundreds and hundreds of external libraries, when we cannot control their schedule, yet we need new upgrades of such downstream libraries. BackwardCompatibility is the mantra that allows us reach smooth Upgradability of such components in our systems.

Source Compatibility

Two versions of the same library are source compatible if any program written and successfully compiled against the older version can also be successfully compiled against the new version.

Obviously this means that one cannot remove or rename accessible objects in the API of the library. What has once been discovered needs to continue to shine on and follow the rules of proper API Design until eternity.

However this kind of compatibility is not easy to reach in Java, as also almost any addition can cause problems. Especially due to language constructs like wildcard import.

Binary Compatibility

Two versions of the same library are binary compatible if any program written and successfully compiled into appropriate binary form against older version of the library, can link (its binary form) with the newer version.

This kind of compatibility is important for assemblers and users of final systems. They usually operated on compiled bits, download them from whatever site and then they expect these bits will work on their system. Usually two applications are often compiled against different versions of libraries, and only due to binary compatibility (if present) they can all successfully link on the final system.

Keeping binary compatibility in Java needs a little bit of understanding of the Java_virtual_machine's ligua franca - the bytecode. The concepts of the bytecode are very similar to concepts of Java language, yet there are differences. As discussed in Chapter 3 it is quite important for a good API designer to understand them.

Functional Compatibility

Two versions of the same library are functionally compatible if any code written, compiled and linked and executed against the older version can successfully be executed against the new version and produces the same result.

This kind of compatibility is quite tricky, as it covers a lot of Runtime Aspects of APIs, yet in the end it is the most important one. In case of BackwardCompatibility we actually do not care that much whether our application compiles and links, but whether it really works, and only applications written against libraries that are functionally compatible can safely upgrade versions of their libraries without fear of becoming broken.

To get better feel for this kind of compatibility, play or read about the API Fest'08 game.