Protocols

From APIDesign

Current revision

Protocols are some what special among other APITypes: the amount of freedom when creating a protocol is really large. No restriction to group methods into classes and those in packages. No need to follow any existing grammar. At the end, every stream read or written to disk is an example of a protocol. And content of such streams can be very flexible.

These days the most common (meta) protocol is XML (which enforces a tree structure on the content of the stream), but one can still often find other (one could say legacy) attempts to exchange information without relying on DTD, SOAP or Web Services. One such (and very flexible) form is based on PropertyFiles. But those who are dare enough can even use simple binary streams. 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 letting hundreds of developers type your protocols manually can get you into troubles. Even if you want to talk only to yourself you may face problems with evolution.

For a while there has been an internal server listening on some local port inside every NetBeans application (I talked about it in Chapter 12 too). This server guards access to files under configuration directory by ensuring that only one instance of NetBeans application is using such 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 the mirror.

The Version of Self

One might think there are no protocol related problems in such situation and for a while I shared such false hope too. However there is a way to get into troubles. 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 of yourself on the other side. However that would mean to redesign the (private and proprietary) protocol to contain proper identification as a first sequence of its hand shake. Obviously I did similar mistake like our OSGi comrades, and forget to include the version in the protocol at beginning.

Retrofitting a protocol to include its 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 reconnect to it twice. The first attempt to connect can be refused due to mutual misunderstanding. Then the second attempt is made using the older protocol (which reminds me my babylonian adventure with Europian languages).

Ugly, but since now things shall be well set for a future growth. Both sides of the communication can now 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 or at minimum a version identification. Do it even if you are talking to yourself in the mirror.

<comments/>