javax.servlet.sip
Interface SipApplicationSession

public interface SipApplicationSession

Represents application instances. The SipApplicationSession interface acts as a store for application data and provides access to contained protocol sessions, e.g. SipSession and HttpSession objects representing point-to-point signaling relationships.

Method Summary

void	encodeURI(URI uri) Encodes the ID of this SipApplicationSession into the specified URI.
java.lang.Object	getAttribute(java.lang.String name) Returns the object bound with the specified name in this session, or null if no object is bound under the name.
java.util.Iterator	getAttributeNames() Returns an Iterator over the String objects containing the names of all the objects bound to this session.
long	getCreationTime() Returns the time when this session was created, measured in milliseconds since midnight January 1, 1970 GMT.
java.lang.String	getId() Returns a string containing the unique identifier assigned to this session.
long	getLastAccessedTime() Returns the last time an event occurred on this application session.
java.util.Iterator	getSessions() Returns an Iterator over all "protocol" sessions associated with this application session.
java.util.Iterator	getSessions(java.lang.String protocol) Returns an Iterator over the "protocol" session objects associated of the specified protocol associated with this application session.
java.util.Collection	getTimers() Returns all active timers associated with this application session.
void	invalidate() Invalidates this application session.
void	removeAttribute(java.lang.String name) Removes the object bound with the specified name from this session.
void	setAttribute(java.lang.String name, java.lang.Object attribute) Binds an object to this session, using the name specified.
int	setExpires(int deltaMinutes) Sets the time of expiry for this application session.

Method Detail

getCreationTime

public long getCreationTime()

Returns the time when this session was created, measured in milliseconds since midnight January 1, 1970 GMT.

Returns:

a long specifying when this session was created, expressed in milliseconds since 1/1/1970 GMT

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

getLastAccessedTime

public long getLastAccessedTime()

Returns the last time an event occurred on this application session. For SIP, incoming and outgoing requests and incoming responses are considered events. The time is returned as the number of milliseconds since midnight January 1, 1970 GMT.

Actions that applications take, such as getting or setting a value associated with the session, do not affect the access time.

Returns:

a long representing the last time the client sent a request associated with this session, expressed in milliseconds since 1/1/1970 GMT

getId

public java.lang.String getId()

Returns a string containing the unique identifier assigned to this session. The identifier is assigned by the servlet container and is implementation dependent.

Returns:

a String identifier for this application session

setExpires

public int setExpires(int deltaMinutes)

Sets the time of expiry for this application session.

This allows servlets to programmatically extend the lifetime of application sessions. This method may be invoked by an application in the notification that the application session has expired: SipApplicationSessionListener.sessionExpired. If the server is willing to extend the session lifetime it returns the actual number of minutes the session lifetime has been extended with, and the listener will be invoked about session expiry again at a later time.

This helps applications clean up resources in a reasonable amount of time in situations where it depends on external events to complete an application session. Being able to extend session lifetime means the application is not forced to choose a very high session lifetime to begin with.

It is entirely up to server policy whether to grant or deny the applications request to extend session lifetime. Note that any attempt to extend the lifetime of an explicitly invalidated application session, one for which setExpires(int) has been invoked, will always fail.

Parameters:

deltaMinutes - the number of minutes that the lifetime of this SipApplicationSession is extended with

Returns:

actual number of minutes the lifetime of this session has been extended with, or 0 if wasn't extended

Throws:

java.lang.IllegalArgumentException - if the argument is less than 1

java.lang.IllegalStateException - if this application session is not valid

invalidate

public void invalidate()

Invalidates this application session. This will cause any timers associated with this application session to be cancelled.

Throws:

java.lang.IllegalStateException - if this application session is not valid

getSessions

public java.util.Iterator getSessions()

Returns an Iterator over all "protocol" sessions associated with this application session. This may include a mix of different types of protocol sessions, e.g. SipSession and javax.servlet.http.HttpSession objects.

Returns:

Iterator over set of protocol session belonging to this application session

Throws:

java.lang.IllegalStateException - if this application session is not valid

getSessions

public java.util.Iterator getSessions(java.lang.String protocol)

Returns an Iterator over the "protocol" session objects associated of the specified protocol associated with this application session. If the specified protocol is not supported, an empty Iterator is returned.

If "SIP" is specified the result will be an Iterator over the set of SipSession objects belonging to this application session. For "HTTP" the result will be a list of javax.servlet.http.HttpSession objects.

Parameters:

protocol - a string identifying the protocol name, e.g. "SIP"

Returns:

Iterator over protocol sessions of the specified protocol

Throws:

java.lang.IllegalStateException - if this application session is not valid

encodeURI

public void encodeURI(URI uri)

Encodes the ID of this SipApplicationSession into the specified URI. The container must then be prepared to associate this application session with an incoming request which was triggered by activating the encoded URI.

In the case of SIP and SIPS URIs, the container may also rewrite the host, port, and transport protocol components of the URI based on its knowledge of local listen points. When doing so it should take existing settings as a hint as to which listen point to select when it has more than one.

This method allow applications to correlate events which would otherwise be treated as being independent, that is, as belonging to different application sessions. For example, an application might send an instant message with an HTML body to someone. The IM body may then contain a SIP URI pointing back to the SIP servlet container and the application session in which the IM was generated, thus ensuring that an INVITE triggered by the IM recipient triggering that URI is associated with this application session when received by the container.

Containers are required to support rewriting of SIP and SIPS URIs.

Parameters:

uri - the uri to be encoded

Throws:

java.lang.IllegalArgumentException - if the container doesn't know how to rewrite the specified URI, for example, because it doesn't know the specific scheme

java.lang.IllegalStateException - if this application session is not valid

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Returns the object bound with the specified name in this session, or null if no object is bound under the name.

Parameters:

name - a string specifying the name of the object

Returns:

the object with the specified name

Throws:

java.lang.IllegalStateException - if this application session is not valid

getAttributeNames

public java.util.Iterator getAttributeNames()

Returns an Iterator over the String objects containing the names of all the objects bound to this session.

Returns:

an Iterator over the String objects specifying the names of all the objects bound to this session

Throws:

java.lang.IllegalStateException - if this application session is not valid

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object attribute)

Binds an object to this session, using the name specified. If an object of the same name is already bound to the session, the object is replaced.

Parameters:

name - the name to which the object is bound; cannot be null

attribute - the object to be bound; cannot be null

Throws:

java.lang.IllegalStateException - if this application session is not valid

removeAttribute

public void removeAttribute(java.lang.String name)

Removes the object bound with the specified name from this session. If the session does not have an object bound with the specified name, this method does nothing.

Parameters:

name - the name of the object to remove from this session

Throws:

java.lang.IllegalStateException - if this application session is not valid

getTimers

public java.util.Collection getTimers()

Returns all active timers associated with this application session.

Returns:

a Collection of ServletTimer objects belonging to this application session

Throws:

java.lang.IllegalStateException - if this application session is not valid