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.


Method Summary
 java.lang.String encodeURL(java.lang.String url)
          Encodes the specified URL by including this SipApplicationSessions ID in it.
 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.
 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.
 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

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

invalidate

public void invalidate()
Invalidates this application session.
Throws:
java.lang.IllegalStateException - if this method is called on an invalidated session

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

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

encodeURL

public java.lang.String encodeURL(java.lang.String url)
Encodes the specified URL by including this SipApplicationSessions ID in it. An incoming request triggered by activating the encoded URL will be associated with the specified session object.
Parameters:
url - the url to be encoded
Returns:
encoded url
Throws:
java.lang.IllegalArgumentException - if the container doesn't know how to rewrite the specified URL, for example, because it doesn't know the specific scheme

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 method is called on an invalidated session

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 method is called on an invalidated session

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 method is called on an invalidated session

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 method is called on an invalidated session