Code Against Interfaces, Not Implementations

From APIDesign

Current revision

Have You Ever Wondered...?

Have you ever participated in a flamewar between people who believe API should be full of interfaces and those who believe it is better to use classes? Was the dispute resolved somehow or people just kept their original views? Yes, I've participated in such discussions few times and yes, they never lead to any conclusions. However then I've managed to look at the old code against interfaces advice in new light and things started to make sense. Since then I have eliminated flamewars of this kind almost completely. Probably because the revelation is not only surprising, but also backed by rational reasoning. You can find this all in the chapter 6, plus see application of this rule for Request/Response API Design Pattern.

Errata

Page 89

The chapter 6 discusses protected abstract methods and says that removing such method is source compatible. In fact that was true until Java 5 appeared. However the newly introduced @Override annotation changed everything.

Code from Anagrams.java:

public abstract class Anagrams extends javax.swing.JFrame implements UI {
 
    protected abstract WordLibrary getWordLibrary();
    protected abstract Scrambler getScrambler();
 
    public void display() {
        initWord();
        setVisible(true);
    }
}
 

If you create a new version of public abstract class Anagrams dropping either getWordLibrary or getScrambler (or both), the @Override annotation in AnagramsWithConstructor will cause the compiler to complain:

Code from AnagramsWithConstructor.java:

public class AnagramsWithConstructor extends Anagrams {
 
    private final WordLibrary library;
    private final Scrambler scrambler;
 
    public AnagramsWithConstructor(
        WordLibrary library, Scrambler scrambler
    ) {
        this.library = library;
        this.scrambler = scrambler;
    }
 
    @Override
    protected WordLibrary getWordLibrary() {
        return library;
    }
 
    @Override
    protected Scrambler getScrambler() {
        return scrambler;
    }
}
 

Source compatibility is gone. As an API designer of public class Anagrams you don't know whether your users (writing class AnagramsWithConstructor) will use @Override. As a result don't even try to remove protected abstract methods from an API. It was never good idea anyway and since Java 5 it is not backward compatible.

-- Rijk van Haaften, Oct 8, 2010

Page 90

In the example of defining inserting new super class into existing class hierarchy, the whole source code should have been shown. The newly created SimpleHelloClass should define no argument method. The original HelloClass shall extend it and keep definition of the more complicated sayHelloTo method with one string argument:

Code from SimpleHelloClass.java:

public abstract class SimpleHelloClass {
    public abstract String sayHello();
}
 

Code from HelloClass.java:

public abstract class HelloClass extends SimpleHelloClass {
    public abstract String sayHelloTo(String who);
}
 

Cordeo 21:47, 7 October 2010 (UTC)