DB Handler Communication Protocols

Date: 22/06/2005

1. Overview

There are two components: the command language (the messages that are being sent/received) and the communication protocol (the wrapping). Section 2 treats the former and section 3 the latter.

2. Command language

ClientAPI.py (CVS version 1.9) defines a set of commands which map onto numbers which are passed to the handler. The following mappings are in place:

 
        0: OpenDB host username password dbname
        1: NewProject projectname
        2: NewJob projectid jobname
        3: SetData jobid name value
        4: GetData jobid name
        5: ListProject
        6: ListJob projectid
        7: ListItem jobid
        8: ImportDingbat jobid name description type value
        9: ExportDingbat jobid name
        10: DeleteDingbat jobid name
        11: DescribeDingbat
        12: GetProject
        13: Version

I would suggest that the most immediate thing to do would be to substitute the numbers (i.e. 0, 1, 2 ...) with the names of the equivalent commands in the client API (i.e. OpenDB, NewProject, NewJob ...). This would need only minor changes to ClientAPI.py and server.py.

3. Protocol

We previously identified three types of messages being passed between the client and the server:

1. requests (from the client to the server, to perform some action)
2. responses (from the server to the client, to report the result of a request)
3. broadcasts (from the server to the client, to report some change in status of the database and not solicited by the client)

Only requests and responses are implemented in the current prototype. Requests need to specify a command and a set of arguments. Responses need to return a value and a status.

The current implement passes raw strings through sockets.As a starting point, previously we had discussed using some kind of (pseudo) XML. One possibility is to wrap the command and the arguments with specific tags that identify the individual parts, for example:

<db_request command="OpenDB">
   <argument name="host">hostname</argument>
   <argument name="user">username</argument>
   ...
</db_request>

<db_response status="OK">value</dbresponse>

An alternative approach is not to use attributes but tags only, e.g.:

<db_request>
    <request_name>OpenDB
       <host>hostname</host>
       <user>username</user>
       ...
    </request_name>
</open_db_request>

<db_response>
   <status>OK</status>
   <result>value</value>
</db_response>

Question: what is the advantage of one over the other?

A further suggestion is to use HTTP to pass the messages between the client and the handler.

Question: would this wrapping be in addition to or instead of the XML-style markup?

3. Implementing the protocol

This will probably require two new functions, one to encode (= wrap a "plain" command or response in XML) and one to decode (= recover it from the XML). ClientAPI functions would encode the arguments from the user and send the encoded string to the server, the server would decode the string and execute the command. It would then encode the response and send that back to the server, which would then decode it and give the result back to the client application.

The client application wouldn't see any difference, provided that it used ClientAPI.py to talk to the database. How this is done in practice probably depends to some extent on how we choose to wrap the commands in the first place.