SOAP Session Management
SOAP web services are inherently stateless and thus do not maintain sessions. However, it is often useful to maintain a session between a web client and the web service that it uses. The Caché SOAP support provides a way for you to do this. This chapter includes the following topics:
Overview of SOAP Sessions
You can maintain a session between a web client and a Caché web service. This support consists of the following tools:
CSP session management, which is described in the book Using Caché Server Pages (CSP).
The Caché SOAP session header, which is a simple proprietary header.
The overall flow is as follows:
The web client sends an initial message to the web service. This message does not include the Caché SOAP session header.
The web service receives the message and starts a new CSP session.
When the web service sends its reply, it adds the Caché SOAP session header to the message.
When the web client receives the reply, it must detect the SOAP session header and extract the session cookie. Then when the web client sends another message, it must use the cookie to create a SOAP session header in that message.
If the client is a Caché web client, the session cookie is saved automatically in the SessionCookie property of web client. Also, the client instance automatically creates the SOAP session header and includes it in all messages that it sends.
This step also happens automatically for .NET web clients, if the same client instance is used for all SOAP messages in the session. You may need further code for other client platforms.
The web service receives the next reply, continues the CSP session, and includes the SOAP session header again when it responds.
It is not necessary to include a method to log out. The CSP session times out after a brief interval (the timeout period for the web application). See the book Using Caché Server Pages (CSP).
In order to use Caché support for SOAP sessions, you must be using a Caché web service.
If the web client is based on Caché, only one step is needed to enable SOAP session support. In your web service class, set the SOAPSESSION parameter equal to 1.
If you are using a third-party tool to create the web client, you are responsible for detecting the Caché SOAP session header element in the initial response and ensuring that the web client includes this header element in all requests during the life of the session. This header element has the following format:
<csp:CSPCHD xmlns:csp="http://www.intersystems.com/SOAPheaders"><id>value of CSPCHD token</id></csp:CSPCHD>Copy code to clipboard
Using Session Information
The process of using session information is the same as it is with other CSP pages. Namely, the web service can use a variable named %session, which is an instance of %CSP.Session. Properties of this object contain system information and any information you choose to add. Some of the commonly used properties are as follows:
SessionID — Unique identifier of this session.
EndSession — Normally this equals 0. Set this property to 1 in order to end the session.
Data — Caché multidimensional array intended to hold any custom data.
NewSession — Equals 1 if this is new session.
AppTimeout — Specifies the timeout value for the session, in seconds.
The %session object provides many other properties, as well as some methods for tasks related to sessions. For further details, see the class documentation for %CSP.Session and see the book Using Caché Server Pages (CSP).