This document outlines the general principles for the communications between the handler and the client applications.
The communications between the handler and the clients are via sockets and are marked up in a form of pseudo-XML.
Communications from the client to the handler are requests; communications from the handler to the client are either responses to specific requests, or unsolicited broadcasts which do not correspond to any specific request.
The following sections describe the markup for each type of communication.
Each communication is wrapped in a tag that expresses the overall type of communication (request, response or broadcast). The following implementation details are generally applicable to all types of communication:
Requests are wrapped in the following markup:
<db_request> <command>DbRequest</command> <argument>arg1</argument> <argument>arg2</argument> ... <request_id>id</request_id> </db_request>
Requests fall into one of two broad categories: either a request for data or a request for action. An example of a request for data is asking for the value of a particular database item; an example of a request for action is asking to modify the value of a database item.
Responses to requests are wrapped in the following general markup:
<db_response> <status>Status</status> <result>result</result> <response_id></response_id> </db_response>
The content of the result depends on the type of request and on the status returned by the handler:
Request type | Example request | Response status | Result content |
---|---|---|---|
Action | DbOpen | OK | Message describing the outcome |
ERROR | Message describing the error, with a suggestion for how to recover if appropriate | ||
Data | DbGetData | OK | The requested data |
ERROR | Message describing the error, with a suggestion for how to recover if appropriate |
Within the arg and result tags, the structure of the content may be enforced by additional markup. The following structures are available:
Single value is appropriate when one item is being sent or returned, for example:
<db_request> <command>DbRequest</command> <argument>arg1</argument> <request_id>id</request_id> </db_request> |
or |
<db_response> <status>Status</status> <result>result string</result> <response_id></response_id> </db_response> |
Lists of values are appropriate when a single argument of a request consists of several discrete items, or when multiple items are returned from a single request. Lists are used to provide a programming language-independent description of the data being passed:
<db_request> <command>DbRequest</command> <argument> <list> <item>item1</item> <item>item2</item> ... </list> </argument> <request_id>id</request_id> </db_request> |
or |
<db_response> <status>Status</status> <result> <list> <item>item1</item> <item>item2</item> ... </list> </result> <response_id></response_id> </db_response> |
For responses, lists can also be nested within other lists:
<list> <item> <list><item>item1</item><item>item2</item> ...</list> </item> ... </list>
There is no limit on the level of nesting within responses, so it is possible to have lists inside lists inside lists and so on.
Note however that no nesting is currently permitted in the arguments of requests.
Unsolicited broadcast messages from the handler to the client are wrapped in the following general markup:
<db_broadcast> <message>Message text</message> <project>projectname</project> <jobid>jobid</jobid> <operation>operation</operation> <agent>agent</agent> </db_broadcast>
The message text is not formally defined.
Example requests and matching responses:
Request for status of the handler:
<db_request><command>DbRequestStatus</command><request_id>0</request_id></db_request>
Response:
<db_response><status>OK</status><result>Active</result><response_id>0</response_id></db_response>
Request for user to register with the handler:
<db_request><command>DbRegister</command><argument>wy45</argument><argument>15376</argument><argument>False</argument><request_id>request#1</request_id></db_request>
Response:
<db_response><status>OK</status><result>True</result><response_id>request#1</response_id></db_response>
Example of a broadcast message:
<db_broadcast><message>Update TEST 40</message><project>TEST</project><jobid>40</jobid><operation>data changed</operation><agent>MrBump</agent></db_broadcast>
The following comments suggest future possibilities that are not currently implemented:
Peter Briggs and Wanjuan Yang
Last commit: $Date: 2007/06/18 12:33:51 $