I am in the process of writing my first true API. In the process, I am defining an interface for mapping complex data structures onto other complex data structures.

At the moment, the interface contains a set method for the input data structure, a run method to kick off the mapping process, and several methods which basically have the same signature, but of course different names and different documentation. The latter all return java.lang.Object. Something as follows.

public interface DataCompiler {

  public void setInputDataStructure(IDS ids);

  public void run();

   * Maps a "this" structure to a target "this" structure and
   * returns the resulting target "this" structure.
  public Object mapThisStructure();

   * Maps a "that" structure to a target "that" structure and
   * returns the resulting target "that" structure.
  public Object mapThatStructure();

   * Maps an "other" structure to a target "other" structure and
   * returns the resulting target "other" structure.
  public Object mapOtherStructure();


So, an interface is meant to define a contract that must be fulfilled by implementations of the interface.

However, with my interface there is no safety catch in the method signatures themselves to prevent a misuse of any of the last three methods. E.g., mapThisStructure could actually be implemented in the exact way that mapThatStructure is meant to be implemented. Or, someone could put all mapping work into either one of the three mappings (which would of course breach the principle of one method doing one and only one thing), and simply let the other two return null.

Thus actual contract is defined in the JavaDoc. So, does the set up of such an interface make sense?

  • 2
    Is there a reason why you can't define public interface DataCompiler<T> and public T mapThisStructure(); etc?
    – David Arno
    Jan 27 '16 at 13:42
  • What do you want to do with the result of mapThisStructure() if it has no methods of it-s own? Just as a parameter for some other "this"-consumer-method? I think we need a more concrete example or you risk that this question might be closed as "too broad"
    – k3b
    Jan 27 '16 at 13:53

The type system can do many things for you, but even the best type system cannot do everything. There is no problem with having several methods with the same type signature but different contracts. Look at it this way: if everything could be expressed machine-verifiable via the signature, we wouldn't need programmers - just spec writers and compilers. The leeway afforded by this incompleteness is what keeps us all employed.

However, I'm certain returning Object is not the best solution, no matter whether once or thrice. Surely your structures obey some common rules and expected access patterns? That's what you should express via the type system.

  • Thanks. The reason why I used Object as return values is that the interface should be implementable with different data models which declare their own types for each structure; It should be usable with different libraries, so that, e.g., mapThatStructure could return objects of type com.company.ThatStructure as well as org.project.ThatStructure.
    – s.d
    Jan 27 '16 at 13:21
  • 2
    @s.d: With your current interface, the only operations that can safely be assumed to be present are the ones that java.lang.Object defines. For anything more, the client needs to have knowledge beyond what the interface specifies. Are you sure there is no common interface between com.company.ThatStructure and org.project.ThatStructure? Jan 27 '16 at 13:27

Whether or not you use generic parameters as @DavidArno suggests, your interface should probably be written in terms of other interaces, not in terms of classes. It is perfectly reasonable for an abstraction of concepts to require several interfaces. But an interface that consumes and returns classes is probably not fully abstracted. So, keep going until you reach that set of abstract concepts, that set of coordinated interfaces that accomplish a good abstraction.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.