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. has potential to break application composition instead of this use the SipApplicationKey mechanism as described in section 15.11.2 in the SIP Servlet specification document.
java.net.URL	encodeURL(java.net.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.
java.lang.String	getApplicationName() Returns the name of the SIP application this SipApplicationSession is associated with.
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<java.lang.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.
java.lang.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.
java.lang.Object	getSession(java.lang.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.
java.util.Iterator<?>	getSessions() Returns an Iterator over all valid "protocol" sessions associated with this application session.
java.util.Iterator<?>	getSessions(java.lang.String protocol) Returns an Iterator over all valid "protocol" session objects associated with the specified protocol associated with this application session.
SipSession	getSipSession(java.lang.String id) Returns the SipSession with the specified id belonging to this application session, or null if not found.
ServletTimer	getTimer(java.lang.String id) Returns the active timer identified by a specific id that is associated with this application session.
java.util.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(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.
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

getCreationTime

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

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

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 Long.MIN_VALUE The time is returned as the number of milliseconds since midnight January 1, 1970 GMT.

Returns:

a long representing the time in future when this session will expire expressed in milliseconds since 1/1/1970 GMT.

Throws:

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

Since:

1.1

getId

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

Returns:

a String identifier for this application session

getApplicationName

java.lang.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

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.

Parameters:

deltaMinutes - the number of minutes that the lifetime of this SipApplicationSession is extended with, if this param is 0 (or negative) then the session never expires

Returns:

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

Throws:

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

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.

Throws:

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

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:

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

Since:

1.1

See Also:

SipSession.isReadyToInvalidate()

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:

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

Since:

1.1

See Also:

isReadyToInvalidate(), SipApplicationSessionListener.sessionReadyToInvalidate(SipApplicationSessionEvent ev)

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:

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

Since:

1.1

See Also:

isReadyToInvalidate()

getSessions

java.util.Iterator<?> getSessions()

Returns an Iterator over all valid "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 valid protocol sessions belonging to this application session

Throws:

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

getSessions

java.util.Iterator<?> getSessions(java.lang.String protocol)

Returns an Iterator over all valid "protocol" session objects associated with 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 valid 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 all valid protocol sessions of the specified protocol

Throws:

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

java.lang.NullPointerException - if the protocol is null

java.lang.IllegalArgumentException - if the protocol is not understood by container.

getSipSession

SipSession getSipSession(java.lang.String id)

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

Parameters:

id - the SipSession id

Returns:

the corresponding SipSession, or null if none is found.

Throws:

java.lang.NullPointerException - on null id

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

Since:

1.1

getSession

java.lang.Object getSession(java.lang.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:

java.lang.NullPointerException - on null id or protocol

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

Since:

1.1

encodeURI

void encodeURI(URI uri)

Deprecated. has potential to break application composition instead of this use the SipApplicationKey mechanism as described in section 15.11.2 in the SIP Servlet specification document.

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

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

java.util.Iterator<java.lang.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.

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

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

java.lang.NullPointerException - if the name or attribute is null.

removeAttribute

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

java.util.Collection<ServletTimer> 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

getTimer

ServletTimer getTimer(java.lang.String id)

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

Returns:

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

Throws:

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

Since:

1.1

isValid

boolean isValid()

Returns if this SipApplicationSession is valid, false otherwise. The SipSession can be invalidated by calling the method SipSession.invalidate() on it or if its invalidateWhenReady flag is true and it transitions to the ready-to-invalidate state. Also the SipSession can be invalidated by the container when either the associated SipApplicationSession times out or invalidate() is invoked.

Returns:

boolean true if the session is valid, false otherwise.

Since:

1.1

encodeURL

java.net.URL encodeURL(java.net.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.

Parameters:

url - the URL to be encoded

Returns:

the resulting URL containing the encoded app session id

Throws:

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

Since:

1.1