SipApplicationSession (SIP Servlet API 2.0 API)

All Superinterfaces:

AttributeStore
```
public interface SipApplicationSession
extends AttributeStore
```
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

Nested Classes
Modifier and Type	Interface and Description
`static class`	`SipApplicationSession.Protocol` Possible protocols to which sessions contained in the `SipApplicationSession` belong to.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addIndexKey(String indexKey)` Add specified key to the set of index keys of this `SipApplicationSession`.
`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.
`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.
`Iterator<String>`	`getAttributeNames()` Deprecated. As of release 2.0, replaced by `AttributeStore.getAttributeNameSet()`
`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.
`Set<String>`	`getIndexKeys()` Return an immutable `Set` of index keys added to this `SipApplicationSession` object.
`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 valid "protocol" sessions associated with this application session.
`Iterator<?>`	`getSessions(String protocol)` Returns an `Iterator` over all valid "protocol" session objects associated with the specified protocol associated with this application session.
`Set<?>`	`getSessionSet()` Returns an immutable `Set` of all valid "protocol" sessions associated with this application session.
`Set<?>`	`getSessionSet(String protocol)` Returns an immutable `Set` of all valid "protocol" session objects associated with 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.
`Future`	`getTaskFuture(String identityName)` Returns `Future` object of the task with the specified identity name.
`Set<Future>`	`getTaskFutures()` Returns `Future` objects of all submitted or scheduled task belonging to this application session.
`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`	`removeIndexKey(String indexKey)` Remove the specified key from the set of index keys of this `SipApplicationSession`.
`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.

Methods inherited from interface javax.servlet.sip.AttributeStore
clearAttributes, getAttribute, getAttributeNameSet, removeAttribute, setAttribute

- 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:
    
    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:
    
    IllegalStateException - if this application session is not valid
    Since:
    
    1.1
  - 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.
    
    Returns:
    a String identifier for this application session
  - 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
  - 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:
    
    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, and any asynchronous tasks to be cancelled..
    
    Throws:
    
    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.
    3. None of the asynchronous tasks 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
    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:
    
    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:
    
    IllegalStateException - if this application session is not valid
    Since:
    
    1.1
    
    See Also:
    isReadyToInvalidate()
  - getSessions
```
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:
    
    IllegalStateException - if this application session is not valid
  - getSessionSet
```
Set<?> getSessionSet()
```
    Returns an immutable Set of 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:
    Set of set of valid protocol sessions belonging to this application session
    
    Throws:
    
    IllegalStateException - if this application session is not valid
    Since:
    
    2.0
  - getSessions
```
Iterator<?> getSessions(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:
    
    IllegalStateException - if this application session is not valid
    
    NullPointerException - if the protocol is null
    
    IllegalArgumentException - if the protocol is not understood by container.
  - getSessionSet
```
Set<?> getSessionSet(String protocol)
```
    Returns an immutable Set of all valid "protocol" session objects associated with the specified protocol associated with this application session. If the specified protocol is not supported, an empty Set is returned.
    If "SIP" is specified the result will be an Set over the set of valid SipSession objects belonging to this application session. For "HTTP" the result will be a Set of javax.servlet.http.HttpSession objects.
    
    Parameters:
    protocol - a string identifying the protocol name, e.g. "SIP"
    
    Returns:
    Set of all valid protocol sessions of the specified protocol
    
    Throws:
    
    IllegalStateException - if this application session is not valid
    
    NullPointerException - if the protocol is null
    
    IllegalArgumentException - if the protocol is not understood by container.
    Since:
    
    2.0
  - getSipSession
```
SipSession getSipSession(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:
    
    NullPointerException - on null id
    
    IllegalStateException - if this application session is not valid
    Since:
    
    1.1
  - 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
    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:
    
    IllegalArgumentException - if the container doesn't know how to rewrite the specified URI, for example, because it doesn't know the specific scheme
    
    IllegalStateException - if this application session is not valid
  - getAttributeNames
```
@Deprecated
Iterator<String> getAttributeNames()
```
    Deprecated. As of release 2.0, replaced by AttributeStore.getAttributeNameSet()
  - getTimers
```
Collection<ServletTimer> getTimers()
```
    Returns all active timers associated with this application session.
    
    Returns:
    a Collection of ServletTimer objects belonging to this application session
    
    Throws:
    
    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.
    
    Returns:
    the ServletTimer object identified by the id belonging to this application session
    
    Throws:
    
    IllegalStateException - if this application session is not valid
    Since:
    
    1.1
  - getTaskFutures
```
Set<Future> getTaskFutures()
```
    Returns Future objects of all submitted or scheduled task belonging to this application session. Only the tasks that are yet to be completed or still to be run are returned.
    
    Returns:
    a Collection of Future objects of tasks belonging to this application session
    
    Throws:
    
    IllegalStateException - if this application session is not valid
    Since:
    
    2.0
  - getTaskFuture
```
Future getTaskFuture(String identityName)
```
    Returns Future object of the task with the specified identity name. Only a task that is yet to be completed or still to be run is returned. If there is no task matching the criteria, then null is returned. The given identity name must be the value of javax.enterprise.concurrent.ManagedTask.IDENTITY_NAME execution property of the submitted or scheduled task.
    
    Parameters:
    identityName - Identity Name of the task.
    
    Returns:
    a Collection of Future object of task with the specified identity name.
    
    Throws:
    
    IllegalStateException - if this application session is not valid
    
    IllegalArgumentException - if there are more than one task with the specified identity name.
    Since:
    
    2.0
  - 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
```
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.
    
    Parameters:
    url - the URL to be encoded
    
    Returns:
    the resulting URL containing the encoded app session id
    
    Throws:
    
    IllegalStateException - if this application session is not valid
    Since:
    
    1.1
  - addIndexKey
```
void addIndexKey(String indexKey)
```
    Add specified key to the set of index keys of this SipApplicationSession. Application can use SipSessionsUtil.getApplicationSessionIds(String indexKey) to find the Id of the SipApplicationSession. Invoking this method multiple times with the same index key does not have any effect.
    
    Parameters:
    indexKey - A string that act as the index key for retrieving the Id of the SipApplicationSession
    
    Throws:
    
    IllegalStateException - if this method is called on an invalidated SipApplicationSession
    Since:
    
    2.0
    
    See Also:
    SipSessionsUtil.getSipApplicationSessionIds(String)
  - removeIndexKey
```
void removeIndexKey(String indexKey)
```
    Remove the specified key from the set of index keys of this SipApplicationSession. Nothing happens if the set of index keys does not contain the specified index key.
    
    Parameters:
    indexKey - A string that act as the index key for retrieving the Id of the SipApplicationSession
    
    Throws:
    
    IllegalStateException - if this method is called on an invalidated SipApplicationSession
    Since:
    
    2.0
    
    See Also:
    addIndexKey(String)
  - getIndexKeys
```
Set<String> getIndexKeys()
```
    Return an immutable Set of index keys added to this SipApplicationSession object.
    
    Returns:
    Set of of Index Keys. If no index key is added to the SipApplicationSession an empty Set is returned.
    
    Throws:
    
    IllegalStateException - if this method is called on an invalidated SipApplicationSession
    Since:
    
    2.0
    
    See Also:
    addIndexKey(String)

Interface SipApplicationSession

Nested Class Summary

Method Summary

Methods inherited from interface javax.servlet.sip.AttributeStore

Method Detail

getCreationTime

getLastAccessedTime

getExpirationTime

getId

getApplicationName

setExpires

invalidate

isReadyToInvalidate

setInvalidateWhenReady

getInvalidateWhenReady

getSessions

getSessionSet

getSessions

getSessionSet

getSipSession

getSession

encodeURI

getAttributeNames

getTimers

getTimer

getTaskFutures

getTaskFuture

isValid

encodeURL

addIndexKey

removeIndexKey

getIndexKeys