Specifying a wire protocol
The reason that I was writing the specification is because there are members of the Darkstar community that want clients in languages other than those that we (the core team) are able or willing to support. The most common of these are C#, which is close enough to Java that we tend not to distinguish it, and Action Script, which is the scripting language for Flash. Action Script is one of the most common languages for building the clients for causal games. The problem for the core team is that we are a bunch of old-line system programmers, and none of us know Flash. Thank goodness the community contains people that are ready, willing, and able to write in these languages.
Supporting multiple languages for the client means that we need to have a wire protocol that defines the way that the client and the server communicate. This is where the irony comes in, as a number of years ago (during my time doing the Jini Networking project) I argued that the time for defining wire protocols had passed. The argument was that, if Java was everywhere, then there was no need for wire protocols, since the server could just supply the client with the code needed to call the server, and the wire protocol could be embedded in that code. It was a nice idea, which I still think is the future (in a future in which the virtual machine that abstracts the computer is somewhere above the network, rather than where it is currently, which is below the network and just above the chip). But the Darkstar world is one in which Java (or, more precisely, the Java Virtual Machine) cannot be assume to be everywhere. So it is back to wire protocols.
Those wanting to implement their own clients (in their own languages) wanted to really know what the wire protocol meant. Which is the job for a specification. While the engineer who had come up with the protocol had done a reasonable job of commenting the code that encapsulated the protocol, it wasn't a specification. There were some real holes in what the messages did, who could send them, who could receive them, and what to do when something unexpected happened. So I decided to fill in the existing comments with something that was more complete.
I generally like to write the specification before I write the code, but in this case the code had already been written. This made the job easier in one way-- when I wondered what the behavior of the server was on receipt of a particular message, I could look at the code and see what the current server does. But this was not definitive-- once I knew what the behavior of the current server is, I had to decide if that was the behavior that all servers using this protocol would have to implement, or if it was just the way this particular implementation chose to implement it's response. There were some cases where it was clear that the current behavior was the only one that made sense. There were others where it was clear that the current behavior could be altered without harm to the overall design of the system. But there were others where it wasn't so clear, and so a conversation would ensue between me and some of the other members of the team on what was specification and what was implementation.
The other factor that I find somewhat constraining is that, since we do most all of our documentation using the JavaDoc tool, the specification needed to be written in the JavaDoc. This is nice in that it means that the specification is close to the code that implements that specification. But it also means that it is hard to distinguish between the specification and the implementation, and the proper place to discuss the implementation details of the current server (which dictate a lot about how you would have to write a client that talks to that server) is different from the place you want to write out the specification. Once again, the tools can dictate the way you do things.
Anyway, the first pass at the specification is done, and has been incorporated into the code in the current trunk. Those who are interested can take a look; the wire protocol is specified in the JavaDoc for the class com.sun.sgs.protocol.simple.SimpleSgsProtocol in the shared repository, while the specification of the behavior of the current server implementation is in the overview document for the server. If you see holes, or there are things that you don't understand, or (even more important) if you don't feel you could implement a client with the information that is in these documents, definitely drop me a line or say something on the forums.
