'. '

MagicalStrings

From APIDesign

(Difference between revisions)
Jump to: navigation, search
(New page: One dirty trick to provide an API which looks incapable, but which people with in-depth knowledge can use to do magical things is to use MagicalStrings. Just define: <source lang=...)
Current revision (16:46, 17 February 2015) (edit) (undo)
(Not in the OSGi Spec!)
 
(6 intermediate revisions not shown.)
Line 1: Line 1:
-
One dirty trick to provide an [[API]] which looks incapable, but which people with in-depth knowledge can use to do magical things is to use [[MagicalStrings]]. Just define:
+
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:
<source lang="java">
<source lang="java">
Line 5: Line 5:
</source>
</source>
-
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. Can you see how capable [[API]]s you can offer member of your secret [[API]] society?
+
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 [[API]]s 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 [[Netigso|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 [[NetbinoxPerformance|slightly arrogant blog]]. Surprisingly that helped!
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 [[Netigso|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 [[NetbinoxPerformance|slightly arrogant blog]]. Surprisingly that helped!
-
Tom Watson (a member of [[OSGi]] secret society, imho) [[Talk:NetbinoxPerformance|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 page document anyway.
+
Tom Watson (a member of [[OSGi]] secret society, imho) [[Talk:NetbinoxPerformance|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 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 (if they get locked in your [[API]]).
+
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]] [[API]]s. 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 [[Teleinterface]]s.
[[Category:APIDesignPatterns:Anti]]
[[Category:APIDesignPatterns:Anti]]

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.

Personal tools
buy