Evolving an interface that is not supposed to be implemented by the client

Question

I'm about to write a Java library. Basically, this library provides something like this to its user:

interface Foo {
  void doA();
  boolean aWorked();
  void doB(int value);
}

The user is not supposed to implement this interface (obviously). Thus, user code will look something like this:

Foo f = Library::SomeFactory();
if (someDecison()) {
  f.doA();
  if (!f.aWorked()) {
    f.doB(21);
  }
} else {
  f.doB(42);
}

I can make sure that neither preconditions nor postconditions of the methods in the interface change in the future. But there might be a new method, say doC().

Now, various resources including Orcale's Docs suggest that just adding this doC() to above interface is a bad idea. They propose different solutions from extending the interface ...

interface Foo2 : extends Foo {
  void doC();
}

... to blowing the code up with command patterns and what not. But the supporting reason is always that "all implementing classes must be changed". That's not an issue in my case, as all implementing classes are "under my control" and will need to be changed either way (when there's a doC()).

Is simply adding the method to Foo really a bad idea? And if so, why? Is there anything that I'm not taking into account here? My primary goal is to not break any user code written against that interface.

// That's what I'm planning
interface Foo {
  void doA();
  boolean aWorked();
  void doB(int value);
  void doC();
}

---

This source supports my feeling that it can be as simple as that:

[..] If the method is added to a class (interface) which Clients are not allowed to subclass (to implement), then it is not a breaking change. [..]

Answer 1

There is no Java mechanism to prevent clients from implementing an interface that is accessible to them. The text you're quoting says "is not allowed to implement". Sadly, the only way that can be true (enforced) is if the interface is inaccessible to the client.

There are reasons a client may want to implement that interface; for example, if they are trying to bring together several different libraries, and they find your interface to be a good abstraction to reuse.

You can caution your clients against implementing your interface -- that your intention is to extend it, or, you can use Java's new default methods when you do extend the interface (or both).

Answer 2

Best practices are fine and dandy, but it's important to be pragmatic.

In this case, I see nothing wrong with extending your interface in-place in the future. Like you mentioned, the only affected classes are in your control.

Also, why have a aWorked() member if you can simply have doA() return a success/failure result?

Answer 3

Evolving an interface without breaking code

Any new methods should supply default behavior, which is an easier (and cleaner) alternative to defining a new subtype.

Why is adding a new abstract method to an interface bad?

It does exactly what you want avoid: break code. If clients used a newer version of your framework for bug fixes, they'll be forced to declare the new method in whatever types implement the interface.

Preventing clients from implementing your interface

Even if Java supported this, which it doesn't, I would advise against it. You would limiting the usage your framework.

If your framework lacks an implementation the client may require/want, they (or anyone else, maybe a more experienced developer) should be able to extend upon Foo to expose new useful implementations that you may not have had the time to write, or maybe never even thought of.

Answer 4

If the interface is not supposed to be implemented by the client, you should make it package-private so clients will not even know it exists. If it defines a type that is part of your public API, you could make it a superclass of your own implementations. The superclass could be abstract or have a package-private constructor, and the implementations could be closed to extension by declaring them final or restricting access to their constructors.

You can always remove these restrictions later if you discover a compelling reason to do so. But you can't add them later without risking breakage in third-party code. So it's good practice in a public API to limit the visibility and extensibility of everything as much as possible, and open it up later.