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?
public interface DataCompiler<T>
andpublic T mapThisStructure();
etc?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"