3

I'm programming against a API Library which provides classes like Document, Folder, ContentElement, Action...

These classes are basically just their respective representation from the database.

I'd like to extend (doesn't necessarily mean subclass here, could also be composition) these classes for easier handling in my application, f.e. override toString() and provide dedicated manipulation methods for my use cases.

Naming these 'wrapper' classes poses a problem:

  • going for MyDocument, MyFolder ... is just ugly (even with a better prefix)
  • same goes for postfix notation DocumentWrapper, FolderWrapper ...
  • Using the exact same name leads to ambiguity and naming conflicts
  • Inventing new words (f.e. File instead of Document and Binder instead of Folder) hides which API Class is wrapped and misleads the user of my classes because he can't use his usual terminology

In an ideal world, I would just update the API classes to my needs which I unfortunately can't as the library is closed source.

Is there another way for 'extending without renaming' I missed or do I have to go with one of the solutions above?

  • Are you ever going to refer to the "unwrapped" API outside of your wrapper code? – Caleth Sep 18 '18 at 13:35
  • Personally, I see nothing wrong with suffixes. We use them in our application for this very reason with no issues. As long as the usage is consistent then developers know what to expect. – Dan Wilson Sep 18 '18 at 13:36
  • @Caleth yes, this is very likely @ DanWilson it is the best solution at the moment, I'm just hoping for something even more elegant – tannerli Sep 18 '18 at 13:40
  • In, C#, one can use extension methods for exactly this purpose - extending classes of a library which cannot be changed. No idea if there is something similar in Java, or if it may be added in one of the next Java versions. – Doc Brown Sep 18 '18 at 15:07
  • You can write your own facade library with your choice of entities, in fact, just expose what you need and keep un-necessary parts of original library encapsulated. – S.D. Sep 19 '18 at 5:36
8

The principle of least astonishment would tend to encourage you to avoid renaming as much as possible. The extended version of Folder wouldn't therefore become "ManillaEnvelope", as that would add needless confusion to whomever will read your code.

I believe the crucial point to ask yourself is whether or not you'll ever be referring to the API beyond these wrapped classes, because if not, you could name it the same way, and simply place them in their own package with some meaningful name (root.package.libraryname.api.Folder ?). This is the ideal situation anyway, as if you're wrapping functionality of a library, you should do so completely, as to have only a single place where your program directly interacts with the library itself.

Otherwise, I think you would necessarily have to add a prefix to differentiate, otherwise using the base class and extended class of Folder would get rather messy. And in this case the least of all evils would suggest adding a suffix indicative of the name of the library (abbreviated if library name is too long otherwise).

  • 3
    +1, absolutely. Even if you must occasionally refer to both versions of the classes, it is much better to bite the bullet and occasionally write out com.acme.api.Document to distinguish it from your own Document than to change the term used for a well-established entity in your system. – Kilian Foth Sep 18 '18 at 13:51
  • 2
    Bears emphasising if you name them the same, you would never import com.acme.api.Document, so that Document is unambiguously your wrapper class – Caleth Sep 18 '18 at 13:55

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

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