MagicalStrings
From APIDesign
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).