Sedna XML Database Client/Server Session Protocol

Legend

The client state is defined by the three variables CX, DX, and TX:

• CX (connection state): one of closed, configure, authenticate, or open
• DX (data exchange state): one of none, query, bulk, or pending
• TX (transaction state): either open or closed

Messages sent by the client are shown in blue.  Messages sent by the server are shown red.  All ErrorResponse messages are shown with a dashed red line.

Start-Up

To begin a session, a client creates a connection to the server and sends the Start-Up message. The server launches a new process that is associated with the session. If launching a new process causes some errors, the server sends the se_ErrorResponse message, if not, it sends the se_SendSessionParameters message to the client. Then client sends the session parameters in the se_SessionParameters message. This message includes the particular protocol version to be used, the name of the user and of the database the user wants to connect to. The server then uses this information to determine whether the connection is acceptable. If not, it sends the error message (se_ErrorResponse). If the connection is acceptable the server then sends an authentication request message, to which the client must reply with an appropriate authentication response message. In principle the authentication request/response cycle could require multiple iterations, but the present authentication method uses exactly one request (se_SendAuthParameters) and response (se_AuthenticationParameters). The authentication cycle ends with the server either rejecting the connection attempt (se_AuthenticationFailed), or sending se_AuthenticationOk.

The possible instructions from the client in this phase are:

• se_Start-Up. Does not contain the body.
• se_SessionParameters. The body contains the protocol version, user name and db name.
• se_AuthenticationParameters. The body contains password.
•  

The possible instructions from the server in this phase are:

• se_SendSessionParameters. Does not contain the body.
• se_SendAuthParameters. Does not contain the body.
• se_AuthenticationOK. Does not contain the body.
• se_AuthenticationFailed. Body contains info.
• se_ErrorResponse. Body contains info.

Transaction

TODO: message flow description

Clarifications

• What happens to the client state when the server sends a BeginTransactionFailed message?
  • TBD.  Given that RollbackTransactionFailed closes the connection, it seems reasonable to expect the same of BeginTransactionFailed.
• What happens to the client state when the server sends an ErrorResponse message after a BeginTransaction message?
• What happens to the client state when the server sends an ErrorResponse message after a RollbackTransaction message?
• What happens to the client state when the server sends an ErrorResponse message after a CommitTransaction message?

---

Session Options

Since version 3.0 of the Sedna Client-Server protocol it is possible to set session options. There are a number of session options. Session options can be set at any moment during the session except the period when session is in a query evaluation phase (executing or passing result data to a client). To set one or more options client must send se_SetSessionOptions message. If options were set successfully server sends se_SetSessionOptionsOk message to the client. Otherwise server sends se_ErrorResponse to the client. To reset options to their default values client must send se_ResetSessionOptions. If options were reset successfully server sends se_ResetSessionOptionsOk message to the client. Otherwise server sends se_ErrorResponse to the client.

The possible instructions from client are:

• se_SetSessionOptions. The body contains any number of pairs: option id followed by option value. Option id is int, option value is string.
• se_ResetSessionOptions. Does not contain a body.

The possible instructions from the server are:

• se_SetSessionOptionsOk. Does not contain a body.
  

Execution

TODO: message flow description

Clarifications

• Can an update operation be executed without starting a transaction first?
  • NO.  Neither can a simple query operation be executed.  The lack of an open transaction causes an ErrorResponse message.
• Is there a response from the server after the client sends the BulkLoadError message?
• What is the expected state of the client after it sends a BulkLoadError message?
• Must the server send the optional DebugInfo messages before the first occurrence of the ItemPart message?
• Can the server send the optional DebugInfo messages event if the only query result is an ResultEnd message?
• Is it possible for the server to send an ItemEnd message without having sent an ItemPart message first?
• What happens if the server sends an ErrorResponse message after some BulkLoadPortion messages have been accepted (i.e. failure during first bulk load)?
• What happens if the server sends an ErrorResponse message after some BulkLoadEnd messages have been accepted? (i.e. failure during subsequent bulk load)?
• What happens if the client sends an Execute/ExecuteLong message when the server is expecting a BulkLoadPortion/BulkLoadEnd message?
• What happens if the client sends an Execute/ExecuteLong message when the server is sending an ItemPart message?
• Are BulkLoad operations transacted?

---

Termination

TODO: message flow description

Clarifications

• What happens if the CloseConnection message is sent when the server is expecting a BulkLoadPortion or BulkLoadEnd message?
• What happens if the CloseConnection message is sent when the server is expecting an ExecuteLong or LongQueryEnd message?

 

Master Diagram

NOTE: work-in-progress

This diagram is the composition of the above diagrams into a single master diagram.  ErrorResponse messages have been omitted in favor of clarity.  Setting/resetting session options is missing from the diagram.