This section introduces the following aspects of Tamino's session handling mechanism.
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.
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.
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.