'. '

Protocols

From APIDesign

(Difference between revisions)
Jump to: navigation, search
(Hand Shake First)
(Hand Shake First)
Line 11: Line 11:
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.
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 [[API]]s), you may find yourself trying to talk to really different version of ''self''.
+
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 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 [[API]]s), 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 [[PropertyFiles|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 [[BackwardCompatibility|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: [http://hg.netbeans.org/main-silver/rev/a44286c8cc96 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 [http://hg.netbeans.org/main-silver/rev/0a75cd5c132e an example]).
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 [[PropertyFiles|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 [[BackwardCompatibility|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: [http://hg.netbeans.org/main-silver/rev/a44286c8cc96 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 [http://hg.netbeans.org/main-silver/rev/0a75cd5c132e an example]).

Revision as of 03:23, 25 March 2010

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 protocol. And content of such streams can be very flexible.

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 (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 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 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 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/>

Personal tools
buy