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.

Nested Class Summary

static class

SipApplicationSession.Protocol Possible protocols to which sessions contained in the SipApplicationSession belong to.

Method Summary

void	encodeURI(URI uri) Deprecated. 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.
URL	encodeURL(URL url) Encode specified URL to include the application session ID in a way such that the parameter used to encode the application session ID should be unique across implementations.
String	getApplicationName() Returns the name of the SIP application this SipApplicationSession is associated with.
Object	getAttribute(String name) Returns the object bound with the specified name in this session, or null if no object is bound under the name.
Iterator<String>	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.
long	getExpirationTime() Returns the time in future when this SipApplicationSession will expire.
String	getId() Returns a string containing the unique identifier assigned to this session.
boolean	getInvalidateWhenReady() Returns true if the container will notify the application when this SipApplicationSession is in the ready-to-invalidate state.
long	getLastAccessedTime() Returns the last time an event occurred on this application session.
Object	getSession(String id, SipApplicationSession.Protocol protocol) Returns the session object with the specified id associated with the specified protocol belonging to this application session, or null if not found.
Iterator<?>	getSessions() Returns an Iterator over all "protocol" sessions associated with this application session.
Iterator<?>	getSessions(String protocol) Returns an Iterator over the "protocol" session objects associated of the specified protocol associated with this application session.
SipSession	getSipSession(String id) Returns the SipSession with the specified id belonging to this application session, or null if not found.
ServletTimer	getTimer(String id) Returns the active timer identified by a specific id that is associated with this application session.
Collection<ServletTimer>	getTimers() Returns all active timers associated with this application session.
void	invalidate() Invalidates this application session and unbinds any objects bound to it.
boolean	isReadyToInvalidate() Returns true if this application session is in a ready-to-invalidate state.
boolean	isValid() Returns if this SipApplicationSession is valid, false otherwise.
void	removeAttribute(String name) Removes the object bound with the specified name from this session.
void	setAttribute(String name, 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.
void	setInvalidateWhenReady(boolean invalidateWhenReady) Specifies whether the container should notify the application when the SipApplicationSession is in the ready-to-invalidate state as defined above.

Method Detail

encodeURI

void encodeURI(URI uri)

Deprecated. 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.

encodeURL

URL encodeURL(URL url)

Encode specified URL to include the application session ID in a way such that the parameter used to encode the application session ID should be unique across implementations. The recommended way is to use the java package name of the implementation, like com.acme.appsession. This mechanism can be used by the applications to encode the HTTP URL with the application session Id. This URL can then be sent out through some of out of band mechanism. When the HTTP Request comes back to the converged container with this request, the container must associate the new HttpSession with the encoded Application Session. In case the HTTP request is not a new request but a follow on request already associated with a HTTP Session then the converged containers must use the HTTP session association mechanism to route the request to the right HTTP Session. If that HTTP Session was not associated with the encoded SipApplicationSession in the request then that association MUST occur. This mechanism is similar to how the (deprecated) encodeURI() operates for SIP.

getApplicationName

String getApplicationName()

Returns the name of the SIP application this SipApplicationSession is associated with.

Returns:

name of the SIP application, this SipApplicationSession is associated with

getAttribute

Object getAttribute(String name)

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

getAttributeNames

Iterator<String> getAttributeNames()

Returns an Iterator over the String objects containing the names of all the objects bound to this session. Note: This is a fail-fast iterator and can throw ConcurrentModificationException if the underlying implementation does not allow modification after the iterator is created.

getCreationTime

long getCreationTime()

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

getExpirationTime

long getExpirationTime()

Returns the time in future when this SipApplicationSession will expire. This would be the time of session creation + the expiration time set in milliseconds. For sessions that are set never to expire, this returns 0. For sessions that have already expired this returns The time is returned as the number of milliseconds since midnight January 1, 1970 GMT.

Throws:

IllegalStateException - if this application session is not valid

getId

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. For applications with a method with SipApplicationKey annotation the containers MUST incorporate the return value from that into its Id generation, such that a certain key is consistently associated with one and only one SipApplication instance.

getInvalidateWhenReady

boolean getInvalidateWhenReady()

Returns true if the container will notify the application when this SipApplicationSession is in the ready-to-invalidate state.

Returns:

value of the invalidateWhenReady flag

Throws:

IllegalStateException - if this application session is not valid

setInvalidateWhenReady

void setInvalidateWhenReady(boolean invalidateWhenReady)

Specifies whether the container should notify the application when the SipApplicationSession is in the ready-to-invalidate state as defined above. The container notifies the application using the SipApplicationSessionListener.sessionReadyToInvalidate callback.

Parameters:

invalidateWhenReady - if true, the container will observe this application session and notify the application when it is in the ready-to-invalidate state. The application session is not observed if the flag is false. The default is true for v1.1 applications and false for v1.0 applications.

Throws:

IllegalStateException - if this application session is not valid

getLastAccessedTime

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.

getSessions

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.

getSessions

Iterator<?> getSessions(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.

getSipSession

SipSession getSipSession(String id)

Returns the SipSession with the specified id belonging to this application session, or null if not found.

getSession

Object getSession(String id,
                  SipApplicationSession.Protocol protocol)

Returns the session object with the specified id associated with the specified protocol belonging to this application session, or null if not found.

Parameters:

id - the session id

protocol - an Enum identifying the protocol

Returns:

the corresponding session object or null if none is found.

Throws:

NullPointerException - on null id or protocol

IllegalStateException - if this application session is not valid

getTimer

ServletTimer getTimer(String id)

Returns the active timer identified by a specific id that is associated with this application session.

Parameters:

id -

Returns:

the ServletTimer object identified by the id belonging to this application session

Throws:

IllegalStateException - if this application session is not valid

getTimers

Collection<ServletTimer> getTimers()

Returns all active timers associated with this application session.

invalidate

void invalidate()

Invalidates this application session and unbinds any objects bound to it. The invalidation will cause any timers associated with this application session to be cancelled.

isReadyToInvalidate

boolean isReadyToInvalidate()

Returns true if this application session is in a ready-to-invalidate state. A SipApplicationSession is in the ready-to-invalidate state if the following conditions are met: 1. All the contained SipSessions are in the ready-to-invalidate state. 2. None of the ServletTimers associated with the SipApplicationSession are active.

Returns:

true if the application session is in ready-to-invalidate state, false otherwise

Throws:

IllegalStateException - if this application session is not valid

isValid

boolean isValid()

Returns if this SipApplicationSession is valid, false otherwise. The SipSession can be invalidated by calling the method on it. Also the SipSession can be invalidated by the container when either the associated times out or is invoked.

removeAttribute

void removeAttribute(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.

setAttribute

void setAttribute(String name,
                  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.

setExpires

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. In order to make the SipApplicationSession immortal i.e never expire, setExpires should be called with 0 (or -ve number), again it is upto the container to accept this or not. If the container does accept setting the session to never expire then it returns Integer.MAX_VALUE.