MagicalStrings

From APIDesign

Current revision

One dirty trick to provide an API which looks incapable, but which people with in-depth knowledge can use to perform magical powerful things is to use MagicalStrings. Just define:

public void configure(String url);

and tell people that they can pass in a location of configuration file. So far so good. But then also provide additional API which, if the string starts with purge! removes the existing configuration. To make things even more magical, don't mention this in Javadoc of the method. Silly? Maybe, but can you see how capable APIs you can offer member of your secret API society?

Recently I faced this while trying to use OSGi containers effectively. I needed to install a bundle. There is a method installBundle(String url), but it copies the JAR from the url location to internal cache. That is not really effective in my case and I wanted to tell the container to use the original JAR. This problem puzzled me for a while. I thought I will have to use some specific container methods. That did not make me happy as Netigso supports both Felix and Equinox and having containerisms is not really flexible. I did not know what to do - so I started with slightly arrogant blog. Surprisingly that helped!

Tom Watson (a member of OSGi secret society, imho) replied and told me that I can just prefix my URL with reference:. Oh, those MagicalStrings! I was searching for a special method installAsReference(String url), but it did not come to my mind to use special pseudo URL protocol! How could it, Javadoc of the method is silent about such possibility. Maybe I should have read the OSGi spec. But I did. Maybe not that carefully, but it is easy to oversight some MagicalStrings in hundred pages document anyway.

I am going to claim that MagicalStrings are API design anti pattern. But on the other hand, they can be quite useful. They increase the value of consultancy! If you create an API full of MagicalStrings, then you will be payed for helping people to use it properly (under the condition that you convince people to get locked in your API).

Not in the OSGi Spec!

According to an email that I got from Richard Hall recently, I could have read the OSGi specification as many times as I wanted and I would still find nothing. The reference: protocol is a non-spec extension honored both by Felix and Equinox!

This is a nice example of Teleinterface. On one side there is the user of Felix or Equinox, on the other side there is the application using OSGi container via in the middle OSGi APIs. The API itself knows nothing about reference: protocol, yet it allows such information to tunnel through. The String parameter in this case serves as an opaque container. Its content is ignored by the API itself, and interpreted just by the actual implementation.

I still consider this to be an anti-pattern (especially due to problems with proper documentation of all the extensions), but it is useful to keep in mind that strings can be used to implement Teleinterfaces.