SIRA_PRISE and non-java programs

  1. Preliminary remarks

    This page discusses the order and circumstances in which messages are exchanged between a SIRA_PRISE client and server, and the physical format of those messages. This documentation is provided to allow non-java programs to interact with a SIRA_PRISE server.

    1. Versioning of the message types

      With the exception of the very first message types exchanged between a client and a server (notably the "Session Protocol Negotiation" and "Session Protocol Response" message types), all SIRA_PRISE message types are versioned.  This means that any changes (from one SIRA_PRISE release to another) that impact the actual physical layout of the messages exchanged, will result in a new version for the message type to be defined and documented.  Older versions of the message type shall continue to be supported by any new SIRA_PRISE release.  This will allow easier upgrading of SIRA_PRISE servers to new releases, without immediately requiring all the clients to be upgraded at the same time. It even allows upgrading installations of clients to new releases prior to upgrading the servers those clients are using to the same new release.

      Message version numbers won't coincide with SIRA_PRISE versions. Published message layouts for a particular version of the message type will never be modified. If a new layout is required for some message type due to some newly introduced feature, then this will be done through the definition of a new, additional, version of the message layout. Backward compatibility will be maintained by publishing the default value (that the server will assume in case it is sent an older version of the message type), for all additionally defined fields in the message type.

    2. General message layout

      Apart from the individual fields that are specific to each message type, all messages exchanged between SIRA_PRISE clients and servers follow a common message layout, which is as follows :

      Zone Format Length Description
      MSGLEN INTEGER 4 The total length in bytes of the remaining part of the message.
      MESSAGETYPE INTEGER 4 The unique identification of the message type of this message. These identifications are defined in the discussion of the individual message types.
      MAJORVERSION INTEGER 2 The major version number of the message layout used in this message.
      MINORVERSION INTEGER 2 The minor version number of the message layout used in this message.
      DETAIL BYTES   The actual content of the message.

      The definition of the byte layouts corresponding to the format names used to denote the physical format of the fields of a message type are given in the following sections.

      1. BYTES

        BYTES abstractly defines an arbitrary sequence of bytes. It is used where some layout definition (that will determine the actual layout to be used) can be determined from context. E.g. in the general SIRA_PRISE message layout, the actual layout to be used can be derived from the values of the MESSAGETYPE, MAJORVERSION, and MINORVERSION fields.

      2. INTEGER

        INTEGER stores the high-order bytes first. That is, 0x0100 denotes the value 256, not the value 1.

      3. STRING

        STRING type values are recorded in messages using the following layout :

        Zone Format Length Description
        TLENGTH INTEGER 2 Length in tokens of STRING.
        BLENGTH INTEGER 2 Length in bytes of the UTF-8 encoding of the string value.
        STRING BYTES   The string value, encoded in UTF-8.

      4. LSTRING

        LSTRING type values are recorded in messages using the following layout :

        Zone Format Length Description
        TLENGTH INTEGER 4 Length in tokens of STRING.
        BLENGTH INTEGER 4 Length in bytes of the UTF-8 encoding of the string value.
        STRING BYTES   The string value, encoded in UTF-8.

    3. Organisation of this documentation

      The links on this page will bring you to the JavaDoc that comes with the 'messages' package, which defines all the message types. In particular, they will link to the documentation of an abstract java class, which encompasses all versions of the concerned message type. The value to be used for the MESSAGETYPE field of the general message layout, is found right there in the JavaDoc of that abstract class. An individual version of a message type is implemented as a subclass of such an abstract MessageType class. The particular byte layout of the DETAIL field of the general message layout, is documented in the corresponding subclass implementing that particular message type version. That documentation will also state the SIRA_PRISE release that first introduced this message type version.

  2. The SIRA_PRISE DML communication scenario

    1. Obtaining a "regular connection"

      The SIRA_PRISE server waits for incoming connections using the standard TCP accept() call. Obtaining a connection to SIRA_PRISE is thus done by opening a client socket connected to a server socket on the host & port where SIRA_PRISE is running. Two distinct types of connection can be made, each having its own communication scenario (and set of message types used) : a "regular" connection on which the DML commands can be executed, or a monitorconnection on which the Monitor commands can be executed. These two types of connection differ by the TCP port number. The port number for DML connections is 50000, the port number for monitor connections is 50002.

      After the TCP connection has been obtained successfully, the SIRA_PRISE message exchange scenarios can start. Before discussing the details of these communication scenarios, a general remark on error handling is required. Communication is always the result of a client taking some initiative, i.e. a client sending a message to the server. The server will always respond to this message with a response message, the type of which depends on the message type sent, and on the outcome of the processing the server has done. In particular, it is always possible that the response message from SIRA_PRISE is an error message. Clients that obtain a response from SIRA_PRISE should always check this, prior to processing the response message. There is one exception to the rule that SIRA_PRISE always returns a response, and that is the case where the message sent is the "End Connection Message". SIRA_PRISE has three types of error message, depending on the nature of the error that occurred : the constraint violation message, the SIRA_PRISE runtime error message, and the non-SIRA_PRISE runtime error message.

      The first message the server expects the client to send is the "Session Protocol Negotiation" message.

      The SIRA_PRISE engine responds to this message by verifying the data it gets (e.g. : the HEADER, MAJORVERSION or MINORVERSION fields might indicate a message type and/or version that the server does not recognise), and by selecting the best signing and/or encryption algorithms it will use for this connection from the set of algorithms proposed by the client. The server will also decide on the connection idle time it will allow for the connection. If no error is found, it responds with a "Session Protocol Response" message.

      If the session protocol response indicated that no message signing can be used, then the connection is immediately ready to be used for transactions, or to be ended. If the session protocol response indicated that message signing can indeed be done, the server will now expect the client to identify and authenticate himself. Therefore, the client must now send a "Client Authentication" message.

      If the authentication succeeds, then the server will respond with a "Authentication OK" message. After this message has been received by the client, the connection is ready to be used for transactions, or to be ended.

    2. Ending connections

      Connections that have been created with an idle time > 0 (meaning the connection can still be active on the server side without a transaction having been started on that connection), can explicitly be ended by sending the connection an "End Connection" message.

      If connections are created with a long idle time (with the intention of running multiple transactions on them), then it is presumably required to explicitly close those connections at the point where the client that created them itself ends. Otherwise, the server may retain those connections until their maximum idle time has elapsed, and ultimately cause the server to no longer accept new connections because the server has reached its maximum acceptable connection count (but if the client side has ended, then those connections will obviously not be used any more).

      No response is returned following an End Connection Message. The server will have closed the connection and its associated resources (such as server sockets), and the client is expected to do the same.

    3. Starting transactions on a connection

      Transactions can be started by sending a "Start Transaction" message to the server. "Start Transaction" messages tell the server about the identity of the user starting the transaction. Note that this user identification is a different item than the client identification as discussed in the Client Authentication message. The Client identification is intended to identify the software package that is requesting the connections to the server. The User identification is intended to identify the real natural person (the one who is tapping the keyboard) who is using the software package that is acting as the client. This message also tells the server whether the user has been authenticated by the client, and if not, (or for the case that the server is configured not to trust this client's user authentications), the name of the algorithm used by the user to sign his name, and the signature computed by that algorithm applied to his user ID.

      If the client has identified and authenticated himself to the server (in the Client Authentication message), and the client has authenticated the user, and the server is configured to trust this client's user authentications (this is an attribute of the CLIENTCERTIFICATE relvar), then the server will skip the user authentication step described next, and immediately return a "Transaction Started" message.

      The user authentication step is also skipped if the userid field of the "Start Transaction" message is a zero-length string. In that case, the transaction will be an "anonymous" one, in which case the (server-side) CURRENTUSER relation will be empty.

      The user authentication performed by the server amounts to verifying that a tuple exists in the USER catalog relvar for the given userid, and verifying the signature itself, using the public key that is registered for this userid and the named signature algorithm in the USERCERTIFICATE relvar. If the authentication succeeds, then a "Transaction Started" message is returned, and the transaction started on the connection is ready to receive DML commands.

      After reception of the "Transaction Started" message, the client can send messages to the server which will trigger the execution of DML, commit or rollback the current transaction, start "nested" transactions, and ultimately end the transaction.

    4. Executing DML

      DML can be executed by sending an "Execute DML" message to the server. This message contains the command to be executed, in the syntactic form as defined in the grammar section. The response of the server is a "DML Executed" message. If the DML command was an assignment, then this message will be "empty". The response message only acts as a signal that the database update has been processed successfully. If the DML command was a query, then this response message will contain the result of the query.

    5. Committing and rolling back a Transaction

      Commits and rollbacks can be requested by sending the server a "Commit or Rollback" message. The server responds to this message with a "Committed" message. If the response is an error message, then the transaction must be considered as having been rolled back.

    6. Savepoints and nested transactions

      Starting a "nested" transaction within a running transaction (thereby actually obtaining the effect of a "transaction savepoint") can be requested by sending the server a "StartNestedTransaction" message. The server responds to this message with a "Transaction started" message. This feature is only available when communicating with 1.2 servers.

    7. Ending a Transaction

      A transaction can be ended by sending an "End Transaction" message to the server. This message includes an indication of whether the transaction is to be committed or rolled back. The server responds with a "Transaction Ended" message, holding an indication of whether the transaction was committed or rolled back. As with the response to a "Commit or Rollback" message, an Error Message indicates that the client should regard the transaction as having been rolled back.

    8. Transaction and connection aborts

      SIRA_PRISE takes the initiative to end connections and/or transactions in the following cases :

      • A transaction control command is issued holding an invalid transaction ID. This may be either a "Commit or Rollback" message, or an "End Transaction" message. The only valid transaction IDs the server will allow to be specified are the IDs of all transactions that were started on the connection on which this command is issued, and that have not yet been ended, either explicitly or implicitly. If an invalid transaction ID is specified in a commit or endtransaction message, then the outermost transaction is rolled back and ended, the connection goes to idle state until it either times out or else receives a new StartTransaction message.
      • The connection times out. The maximum allowed idle time for a connection is negotiated between the client and the server during the "session handshake". If a transaction is currently started on a timed-out connection, then SIRA_PRISE rolls back that transaction. SIRA_PRISE then sends an error response to the client and closes its side of the connection (it may occur, however, that the client will not get to see this error response, because of I/O exceptions that arise if and when the client does try to send yet another command after all). 

  3. The SIRA_PRISE monitor connection dialog

    The "handshake" protocol to obtain a monitor connection is identical to the "handshake" procedure on DML connections. That is, the messages involved are the "Session Protocol Negotiation" and "Session Protocol Response" message, and optionally a "Client Authentication" message and "Authentication OK" message. After this message has been received by the client, the monitor connection is ready to be used for processing monitor commands, or to be ended.

    1. Ending monitor connections

      Acquired monitor connections can explicitly be ended by sending the connection an "End Connection" message (this is the same message type that is also used to explicitly end DML connections). Observe that in principle, there should never be any need to send this message to a monitor connection, as monitor connections are always automatically ended after a monitor command has been processed.

    2. Executing monitor commands

      Monitor commands can be executed by sending a "Monitor Command" message. This message includes the user ID of the user issuing the command, any fields needed for user authentication, and the actual monitor command.

      After processing this command, either a "DML Executed" message or an error message is sent to the client, and the monitor connection is closed. The "DML Executed" message is the same message type as the one used to respond to "regular" DML requests, and will contain a relation value depending on the particular monitor command used.