Protocols

From APIDesign

Protocols are some what special among other APITypes: the amount of freedom when creating a protocol is really large. At the end, every stream read or written to disk is an example of protocol.

These days the most common protocol is XML (which enforces a tree structure on the content of the stream), but one can still often find other protocols. Either based on some form of PropertyFiles or even simple binary stream. Regardless the actual form, one principle shall always be followed: good protocols require the involved participants to introduce themselves first!

Hand Shake First

What can happen when one forgets to require a version identification is well demonstrated on the hassle with OSGi Manifests. However not only when you let hundreds of developers user your protocols you can get into trouble. Even if you want to talk only to yourself you may face problems with evolution.

For a while there is an internal server listening on some localport inside every NetBeans application. This server guards access to files under configuration directory by ensuring that only one instance of NetBeans application is using this directory at a given time.

In case another instance is started, it locates the proper port, contacts it and talks to it. So basically this is one instance of NetBeans talking to another instance of NetBeans, both using the same bits. It is just like looking in a mirror.

One may think there are no protocol related problems and for a while I believed in the same false hope too. However there is a potential problem. In spite this protocol being proprietary, used only by the NetBeans code, it may happen that different versions of NetBeans may share the same configuration directory and start to talk to each other. Now it is not just looking in a mirror. Now you can see the man in the mirror with few years latency. And as protocols need to evolve from time to time (just like code and APIs), you may find yourself trying to talk to really different version of self.

This would be much more simplified, if you knew the proper version you on the other side. But that requires, that the (private and proprietary) protocol contains proper identification as a first sequence hand shake. Obviously I did similar mistake like our OSGi comrades, and forget to include the version in the protocol at beginning. Retrofitting the protocol to include the version later (and doing it backward compatibly) is indeed not easy. That is why I delayed changes to my protocol as much as I could. But yesterday I could not wait any longer and had to do it: see the patch. All the beauty is gone, when new protocol tries to talk to old server, it may even require to connect to it twice, but since now things shall be OK. Both sides of the communication can adjust their capabilities to their mutual skills and select a vocabulary they both understand (see an example).

Conclusion

When designing a protocol, always make sure it contains a kind of hand shake. Do it even if you are talking to yourself in a mirror.

<comments/>