Session Handling

This section introduces the following aspects of Tamino's session handling mechanism.

Session Context

Requests sent to Tamino can be executed either inside or outside a session context. A session context is established via the _connect command and the usage of the session is restricted to the user who established it. A session allows you to group several commands issued in multiple requests as a transaction which is then either committed or rolled back using the command _commit or _rollback. A session can contain multiple transactions. A session context is also required if you use a query cursor that spans several requests.

If a request is executed outside a session context it is executed in a separate transaction. If execution ends successfully, the transaction is committed. Otherwise, the transaction is rolled back.

Session ID and Session Key

The way in which requests are associated with sessions depends on the request. Tamino supports the following types of request (these are described in more detail in subsequent sections):

Each request belonging to a session causes Tamino to return two values, namely the session ID and the session key. A unique session ID is returned in the response to the _connect command and remains unchanged for all requests belonging to that session. Tamino generates a new session key in response to each request sent to Tamino.

There are two ways in which these values are returned to the client:

  • Using the HTTP extension headers X-INO-Sessionid and X-INO-Sessionkey, which are always returned.

  • Using the attributes ino:sessionid and ino:sessionkey. These attributes are returned only for requests that use X-Machine commands for which the response is embedded in an <ino:response> wrapper element. See also the section Example of a response to the _connect command later in this document.

The values for the session ID and session key attributes returned in a request's response must be sent to Tamino in the follow-up request for the same session. Again, there are two ways of passing the session ID and session key to Tamino:

  • Using the HTTP extension headers X-INO-Sessionid and X-INO-Sessionkey in requests that use either plain URL addressing or X-Machine commands.

  • Using the _sessionid and _sessionkey parameters in requests that use X-Machine commands.

For more information, see the section The HTTP header fields X-INO-Sessionid and X-INO-Sessionkey later in this document.

Queueing a Follow-Up Request

When using a multi-threaded streaming application, it is possible to issue a follow-up request before the response from the previous request has been fully received (once the new session key is known). The follow-up request should be issued in a separate thread so that the previous request's reply can reach completion. Tamino will queue the follow-up request until the previous one is completed in the following cases:

  • The server XML parameter queue next request is set to "yes" (the default value) and the session connection parameter does not override it.

  • The parameter _QueueNextRequest on the session's _connect command is set to "yes".

In addition to a normal completion of a previous request, a previous request is considered complete when any of the following conditions is met:

  • The stream is closed before reading all of the previous request's reply.

  • The stream is read to completion (i.e. end of file is reached).

  • A timeout for sending the complete reply occurs.