Java API Design – Is Implementing an Interface in a Subpackage an Anti-Pattern?

anti-patternsapi-designjavapatterns-and-practices

Let's say I have the following:

package me.my.pkg;
public interface Something {
    /* ... couple of methods go here ... */
}

and:

package me.my;
import me.my.pkg.Something;
public class SomeClass implements Something {
    /* ... implementation of Something goes here ... */
    /* ... some more method implementations go here too ... */
}

That is, the class implementing an interface lives closer to the package hierarchy root than does the interface it implements but they both belong in the same package hierarchy.

The reason for this in the particular case I have in mind is that there is a previously-existing package that groups functionality which the Something interface logically belongs to, and the logical (as in both "the one you'd expect" and "the one where it needs to go given the current architecture") implementation class exists previously and lives one level "up" from the logical placement of the interface. The implementing class does not logically belong anywhere under me.my.pkg.

In my particular case, the class in question implements several interfaces, but that feels like it doesn't make any (or at least no significant) difference here.

I can't decide if this is an acceptable pattern or not. Is it or is it not, and why?

Best Answer

Yes, it's acceptable, as long as the class and the interface are both definitely in the correct packages.

Organising classes into a hierarchical set of packages is a bit like organising classes into an inheritance hierarchy. It works pretty well most of the time, but there are plenty of legitimate cases which just don't fit.

Note that Java doesn't really even have a package hierarchy - the hierarchical nature doesn't extend further than the folder structure. I can't speak for the Java language designers, but I doubt they made this decision by accident!

I sometimes find it helps to think of the 'package hierarchy' as an aide to help programmers find the package they're looking for.

Related Solutions

Java – good reason to use Java’s Collection interface

Abstractions live longer than implementations

In general the more abstract your design the longer it is likely to remain useful. So, since Collection is more abstract that it's sub-interfaces then an API design based on Collection is more likely to remain useful than one based on List.

However, the overarching principle is to use the most appropriate abstraction. So if your collection must support ordered elements then mandate a List, if there are to be no duplicates then mandate a Set, and so on.

A note on generic interface design

Since you're interested in using the Collection interface with generics you may the following helpful. Effective Java by Joshua Bloch recommends the following approach when designing an interface that will rely on generics: Producers Extend, Consumers Super

This is also known as the PECS rule. Essentially, if generic collections that produce data are passed to your class the signature should look like this:

public void pushAll(Collection<? extends E> producerCollection) {}

Thus the input type can be E or any subclass of E (E is defined as both a super- and sub-class of itself in the Java language).

Conversely, a generic collection that is passed in to consume data should have a signature like this:

public void popAll(Collection<? super E> consumerCollection) {}

The method will correctly deal with any superclass of E. Overall, using this approach will make your interface less surprising to your users because you'll be able to pass in Collection<Number> and Collection<Integer> and have them treated correctly.

Java – Explanation of the definition of interface inheritance as described in GoF book

Java classes are similar to C++ as described in the third paragraph. Java interfaces are a different concept.
In Java, a class implicitly specifies both an interface in the GoF sense and the implementation. By contrast a Java interface explicitly specifies an interface in the GoF sense and doesn't specify an implementation. In both cases inheritance implies interface inheritance. Only in the case of class inheritance does it imply implementation inheritance.

For a better example of the distinction, I highly recommend learning just enough Ruby to understand how a class can use method_missing to proxy off of an unrelated object. This provides a very explicit example of interface inheritance without implementation inheritance. (Bonus, Ruby's OO model is the same as Smalltalk's while having a more familiar syntax, which gives you a leg up on the rest of the book.)

Best Answer

Related Solutions

Java – good reason to use Java’s Collection interface

Java – Explanation of the definition of interface inheritance as described in GoF book

Related Topic