SIP Sessions (The SIP Servlet Tutorial)

The SIP Servlet Tutorial

SIP Sessions

SIP servlets, like HTTP servlets, are stateless, meaning that they do not store data across requests. SIP sessions allow SIP servlets to associate SIP messages with data stored by the SIP container. This allows an application to provide functionality across a number of discreet requests, and associating that series of requests with a single client.

The javax.servlet.sip.SipSession interface is SIP the equivalent of javax.servlet.http.HttpSession interface. Instances of SipSession store SIP session data and associate SIP user-agents so that they may communicate in a multiple-request dialog.

Many SIP applications, however, use multiple protocols (for example, a converged web and SIP application uses both HTTP and SIP sessions), provide functionality across dialogs (for example, a teleconferencing application involving multiple user-agents), or are used in concert with other applications for a single VOIP call. The type of data stored in an instance of SipSession does not cover these complicated use-cases. The javax.servlet.sip.SipApplicationSession interface defines methods for storing protocol information for both SIP and other protocols (for example, HTTP), and storing session data for the entire application. SipApplicationSession instances represent application instances, and the all the data and protocol information needed to provide the functionality in an application.

`SipApplicationSession` Methods

SipApplicationSession defines a number of methods for managing application sessions and session data.

`SipApplicationSession` Data Methods

Storing and retrieving session data is accomplished by using the following methods:

Table 1–7 SipApplicationSession Data Methods


Method	Description
`getAttributes(String id)`	Returns the object bound to the specified ID. Returns null if no such object ID exists.
`getAttributeNames()`	Returns an `Iterator` over the String IDs of the objects bound to this application session.
`setAttribute(String name, java.lang.Object attribute)`	Binds an object to the session using the specified String as the object's ID for later retrieval.
`removeAttribute(String name)`	Removes an object from the session by specifying the bound object's ID.

`SipApplicationSession` Protocol Methods

Instances of SipApplicationSession typically have multiple protocol sessions contained within the application session. Such protocol sessions are called child sessions. The following table lists the methods defined in SipApplicationSession for managing child sessions:

Table 1–8 Child Session Methods in SipApplicationSession


Method	Description
`getSessions()`	Retrieves an `Iterator` over all valid child protocol sessions.
`getSessions(String protocol)`	Retrieves an `Iterator` over all valid child sessions for a particular protocol. For example, passing SIP to `getSessions` will return all SIP protocol sessions.
`getSipSession(String id)`	Retrieves a particular session by its ID.
`getSession(String id, String protocol)`	Retrieves a particular session associated with the specified protocol by its ID.

`SipApplicationSession` Lifecycle Methods

The following table lists the methods defined in SipApplicationSession for managing the SIP application session lifecycle:

Table 1–9 SipApplicationSession Lifecycle Methods


Method	Description
`getCreationTime()`	Returns the time that the `SipApplicationSession` instance was created as a `long` value representing the number of milliseconds since midnight January 1, 1970 GMT.
`getExpirationTime()`	Returns the time that the `SipApplicationSession` will expire as a `long` value representing the number of milliseconds since midnight January 1, 1970 GMT.
`getInvalidateWhenReady()`	Returns a boolean value specifying whether the container will notify the application when the `SipApplicationSession` instance is ready to be invalidated.
`getLastAccessedTime()`	Returns the time that the `SipApplicationSession` instance was last accessed as a `long` value representing the number of milliseconds since midnight January 1, 1970 GMT.
`setInvalidateWhenReady(boolean invalidateWhenReady)`	Tells the container to notify the application when the `SipApplicationSession` instance is ready to be invalidated.
`invalidate()`	Explicitly invalidates the SIP application session and unbinds any objects bound to the session.
`isReadyToInvalidate()`	Returns a boolean value specifying whether the `SipApplicationSession` instance is ready to be invalidated.
`isValid()`	Returns a boolean value specifying whether the `SipApplicationSession` instance is valid.
`setExpires(int deltaMinutes)`	Extends the time of expiry for the `SipApplicationSession` instance by the number of minutes specified by `deltaMinutes`. If `deltaMinutes` is 0 or a negative number, the session will never expire. Returns an `int` value of the number of minutes by which the session was extended. If it returns 0, the session was not extended.

Using `SipSessionsUtil` to Manage SIP Sessions

The SipSessionsUtil interface defines utility methods for managing SIP sessions in a converged application. Use the javax.annotations.Resource annotation to inject the container's SipSessionsUtil implementation class in your SIP servlets:

Example 1–6 Example of Injecting `SipSessionsUtil` into a Class

@Resource
SipSessionsUtil sipSessionsUtil;

You may also manually look up SipSessionsUtil through the servlet context.

Example 1–7 Example of Looking Up `SipSessionsUtil`

SipSessionsUtil sipSessionsUtil = 
	(SipSessionsUtil) getServletContext().
		getAttribute("javax.servlet.sip.SipSessionsUtil");

For more information, see the SIP Servlet 1.1 Javadocs

SIP Sessions

SipApplicationSession Methods

SipApplicationSession Data Methods

SipApplicationSession Protocol Methods

SipApplicationSession Lifecycle Methods

Using SipSessionsUtil to Manage SIP Sessions

Example 1–6 Example of Injecting SipSessionsUtil into a Class