|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 |
---|
long getCreationTime()
java.lang.IllegalStateException
- if this method is called on an invalidated sessionlong getLastAccessedTime()
Actions that applications take, such as getting or setting a value associated with the session, do not affect the access time.
long getExpirationTime()
Long.MIN_VALUE
The time is returned as the number of milliseconds since midnight January 1, 1970 GMT.java.lang.IllegalStateException
- if this application session is not validjava.lang.String getId()
String
identifier for this application sessionjava.lang.String getApplicationName()
SipApplicationSession
is associated with.SipApplicationSession
is associated withint setExpires(int deltaMinutes)
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
.
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 expiresjava.lang.IllegalStateException
- if this application session is not validvoid invalidate()
java.lang.IllegalStateException
- if this application session is not validboolean isReadyToInvalidate()
SipApplicationSession
is in the ready-to-invalidate state if the following conditions are met:
java.lang.IllegalStateException
- if this application session is not validSipSession.isReadyToInvalidate()
void setInvalidateWhenReady(boolean invalidateWhenReady)
SipApplicationSessionListener.sessionReadyToInvalidate
callback.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.java.lang.IllegalStateException
- if this application session is not validisReadyToInvalidate()
, SipApplicationSessionListener.sessionReadyToInvalidate(SipApplicationSessionEvent ev)
boolean getInvalidateWhenReady()
SipApplicationSession
is in the ready-to-invalidate state.java.lang.IllegalStateException
- if this application session is not validisReadyToInvalidate()
java.util.Iterator<?> getSessions()
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.Iterator
over set of valid protocol sessions belonging to this application sessionjava.lang.IllegalStateException
- if this application session is not validjava.util.Iterator<?> getSessions(java.lang.String protocol)
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.
protocol
- a string identifying the protocol name, e.g. "SIP"Iterator
over all valid protocol sessions of the specified protocoljava.lang.IllegalStateException
- if this application session is not validjava.lang.NullPointerException
- if the protocol
is nulljava.lang.IllegalArgumentException
- if the protocol
is not understood by container.SipSession getSipSession(java.lang.String id)
SipSession
with the specified id belonging to this application session, or null if not found.id
- the SipSession
idSipSession
, or null if none is found.java.lang.NullPointerException
- on null id
java.lang.IllegalStateException
- if this application session is not validjava.lang.Object getSession(java.lang.String id, SipApplicationSession.Protocol protocol)
id
- the session idprotocol
- an Enum identifying the protocoljava.lang.NullPointerException
- on null id
or protocol
java.lang.IllegalStateException
- if this application session is not validvoid encodeURI(URI uri)
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.
uri
- the uri to be encodedjava.lang.IllegalArgumentException
- if the container doesn't know how to rewrite the specified URI, for example, because it doesn't know the specific schemejava.lang.IllegalStateException
- if this application session is not validjava.lang.Object getAttribute(java.lang.String name)
name
- a string specifying the name of the objectjava.lang.IllegalStateException
- if this application session is not validjava.util.Iterator<java.lang.String> getAttributeNames()
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.
Iterator
over the String
objects specifying the names of all the objects bound to this sessionjava.lang.IllegalStateException
- if this application session is not validvoid setAttribute(java.lang.String name, java.lang.Object attribute)
name
- the name to which the object is bound; cannot be nullattribute
- the object to be bound; cannot be nulljava.lang.IllegalStateException
- if this application session is not validjava.lang.NullPointerException
- if the name
or attribute
is null.void removeAttribute(java.lang.String name)
name
- the name of the object to remove from this sessionjava.lang.IllegalStateException
- if this application session is not validjava.util.Collection<ServletTimer> getTimers()
Collection
of ServletTimer
objects belonging to this application sessionjava.lang.IllegalStateException
- if this application session is not validServletTimer getTimer(java.lang.String id)
ServletTimer
object identified by the id belonging to this application sessionjava.lang.IllegalStateException
- if this application session is not validboolean isValid()
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.java.net.URL encodeURL(java.net.URL url)
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. url
- the URL to be encodedjava.lang.IllegalStateException
- if this application session is not valid
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1996, 2010, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
Java SIP Servlet API 1.1 Reference
Part Number E17883-01