SipApplicationSession

The SipApplicationSession interface represents an application instance in a SIP Servlet environment. It acts as a store for application-related data and provides access to associated protocol sessions, such as SipSession and HttpSession objects, which represent point-to-point signaling relationships. This interface enables applications to manage session data and interact with signaling and protocol layers.
@SipApplicationKey annotation defines the logic for grouping SIP requests into the same SipApplicationSession.

Nested class:

SipApplicationSession.Protocol
The SipApplicationSession.Protocol is an enum that defines the possible protocols associated with the sessions contained in a SipApplicationSession. For more details, refer to the Description.

Methods:

encodeURI
void encodeURI(URI uri)
The method encodes the ID of the associated SipApplicationSession into the specified URI. This allows the application to associate future requests triggered by the encoded URI with the current application session. This mechanism can be used to correlate otherwise independent events. For example, embedding a URI with the session information in an outgoing message ensures that future requests triggered by the URI are linked to the same session.
Containers must support rewriting for SIP and SIPS URIs.
When rewriting SIP or SIPS URIs, the container may modify the host, port, or transport protocol fields based on its local listen points.
This method is deprecated as it may disrupt application composition. It is recommended to use the SipApplicationKey mechanism.
Parameters:
uri: The URI to encode with the SipApplicationSession ID.
Exceptions:
java.lang.IllegalArgumentException is thrown if the container cannot rewrite the specified URI (e.g., due to an unsupported URI scheme).
java.lang.IllegalStateException is thrown if the SipApplicationSession is not valid.

encodeURL
java.net.URL encodeURL(java.net.URL url)
The method encodes the specified HTTP URL to include the associated application session ID. This allows the application session to be identified and associated with subsequent HTTP requests returning to the container. The encoded session ID parameter is recommended to use a unique identifier, such as the Java package name of the implementation.
This mechanism allows the application to link HTTP requests with the SIP application session, ensuring proper routing and association when requests return to the container. If the incoming HTTP request is already associated with an HTTP session, the container ensures that the SipApplicationSession association occurs as well.
This method is conceptually similar to the (deprecated) encodeURI() method for SIP, but specifically operates on HTTP URLs.
The container ensures proper routing and session association for both new and follow-up HTTP requests that include the encoded URL.
Parameters:
url: The HTTP URL to encode with the application session ID.
Returns:
The resulting URL containing the encoded application session ID.
Exceptions:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

getApplicationName
java.lang.String getApplicationName()
The method retrieves the name of the SIP application associated with the current SipApplicationSession.
Returns:
The name of the SIP application this SipApplicationSession is associated with.

getAttribute
java.lang.Object getAttribute(java.lang.String name)
The method retrieves the object associated with the specified name in the current SipApplicationSession. If no object is bound to the given name, the method returns null.
Parameters:
name: The name of the attribute to retrieve.
Returns:
The object bound with the specified name in this session, or null if no object is associated with the name.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

getAttributeNames
java.util.Iterator<java.lang.String> getAttributeNames()
The method provides an Iterator over the names of all objects bound to the current SipApplicationSession. The names are returned as String objects.
This is a fail-fast iterator, meaning it may throw a ConcurrentModificationException if modifications are made to the session after the iterator is created.
Returns:
An Iterator over the String objects containing the names of all objects bound to this session.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

getCreationTime
long getCreationTime()
The method retrieves the time at which the current SipApplicationSession was created. The time is represented as the number of milliseconds since midnight, January 1, 1970, GMT.
Returns:
The creation time of the session, expressed in milliseconds since January 1, 1970, GMT.
Exception:
java.lang.IllegalStateException is thrown if the session has been invalidated.

getExpirationTime
long getExpirationTime()
The method retrieves the expiration time of the current SipApplicationSession. The expiration time is calculated as the session creation time plus the expiration duration set for the session.
If the session is set to never expire, this method returns 0. If the session has already expired, this method returns Long.MIN_VALUE. The time is represented as the number of milliseconds since January 1, 1970, GMT.
Returns:
The future time when the session will expire, expressed in milliseconds since January 1, 1970, GMT.
Returns 0 if the session is set never to expire.
Long.MIN_VALUE if the session has already expired.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

getId
java.lang.String getId()
The method retrieves the unique identifier assigned to the current SipApplicationSession. This identifier is assigned by the servlet container and its format is implementation-dependent. For applications using the @SipApplicationKey annotation, containers must incorporate the return value from the annotated method into the ID generation process, ensuring a consistent association between a specific key and a single SipApplication instance.
Returns:
A unique identifier for this SipApplicationSession.

getInvalidateWhenReady
boolean getInvalidateWhenReady()
The method checks whether the container will notify the application when the current SipApplicationSession enters the ready-to-invalidate state.
Returns:
true if the container will notify the application when the session is ready to be invalidated, false otherwise.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

getLastAccessedTime
long getLastAccessedTime()
The method retrieves the time of the last event that occurred on this SipApplicationSession (Incoming and outgoing requests, incoming responses). Application actions, such as getting or setting session attributes, do not affect the last accessed time.
The time is represented as the number of milliseconds since January 1, 1970, GMT.
Returns:
The timestamp of the last client event associated with this session, expressed in milliseconds since January 1, 1970, GMT.

getSession
java.lang.Object getSession(java.lang.String id,
                            SipApplicationSession.Protocol protocol)
The method retrieves a session object associated with the specified session ID and protocol for the current SipApplicationSession. If no matching session is found, the method returns null.
Parameters:
id: The unique identifier of the session.
protocol: An enumeration identifying the protocol for the session.
Returns:
The session object associated with the given id and protocol, or null if no session matches the criteria.
Exceptions:
java.lang.NullPointerException is thrown if either id or protocol is null.
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

getSessions
java.util.Iterator<?> getSessions()
The method provides an Iterator over all valid protocol sessions associated with the current SipApplicationSession. These sessions may include different types of protocol sessions, such as SipSession and javax.servlet.http.HttpSession objects.
Returns:
An Iterator over the set of valid protocol sessions belonging to the application session.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

getSessions
java.util.Iterator<?> getSessions(java.lang.String protocol)
The method retrieves an Iterator over all valid protocol session objects associated with the specified protocol within the current SipApplicationSession.
Supported Protocols:

• "SIP": Returns an Iterator over valid SipSession objects.
• "HTTP": Returns an Iterator over valid javax.servlet.http.HttpSession objects.

If the protocol is unsupported, an empty Iterator is returned.
Parameters:
protocol: The name of the protocol (e.g., "SIP", "HTTP") to filter the sessions.
Returns:
An Iterator over all valid protocol sessions for the specified protocol.
Exceptions:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.
java.lang.NullPointerExceptionis thrown if the protocol is null.
java.lang.IllegalArgumentExceptionis thrown if the specified protocol is not understood by the container.

getSipSession
SipSession getSipSession(java.lang.String id)
The method retrieves a SipSession object associated with the specified session ID within the current SipApplicationSession. If no matching session is found, the method returns null.
Parameters:
id: The unique identifier of the SipSession.
Returns:
The corresponding SipSession with the specified ID, or null if no session is found.
Exceptions:
java.lang.NullPointerException is thrown if the id is null.
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

getTimer
ServletTimer getTimer(java.lang.String id)
The method retrieves an active ServletTimer object associated with the specified timer ID within the current SipApplicationSession.
Parameters:
id: The unique identifier of the timer.
Returns:
The ServletTimer object corresponding to the specified ID, or null if no such timer exists.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

getTimers
java.util.Collection<ServletTimer> getTimers()
The method retrieves all active ServletTimer objects associated with the current SipApplicationSession.
Returns:
A collection of all active ServletTimer objects belonging to this SipApplicationSession.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

invalidate
void invalidate()
The method invalidates the current SipApplicationSession, unbinding any objects associated with it. Additionally, all timers linked to this session are canceled as a result of the invalidation.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is already invalid.

isReadyToInvalidate
boolean isReadyToInvalidate()
The method checks whether the current SipApplicationSession is in a ready-to-invalidate state. The session is considered ready to invalidate if:

• all associated SipSession objects are in the ready-to-invalidate state.
• none of the ServletTimer objects linked to the session are active.

Returns:
true if the SipApplicationSession is in the ready-to-invalidate state, false otherwise.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

isValid
boolean isValid()
The method checks whether the current SipApplicationSession is still valid. A SipApplicationSession becomes invalid when:

• It is explicitly invalidated using the invalidate() method.
• Its invalidateWhenReady flag is set to true, and the session transitions to the ready-to-invalidate state.
• The container invalidates it due to a timeout or when the associated SipSession is invalidated.

Returns:
true if the session is valid, false otherwise.

removeAttribute
void removeAttribute(java.lang.String name)
The method removes the object bound to the specified name from the current SipApplicationSession. If no object is bound with the given name, the method does nothing.
Parameters:
name: The name of the attribute to be removed from the session.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

setAttribute
void setAttribute(java.lang.String name,
                  java.lang.Object attribute)
The method binds an object to the current SipApplicationSession using the specified name. If an object with the same name is already bound to the session, it is replaced with the new object.
Parameters:
name: The name to which the object is bound; must not be null.
attribute: The object to be bound; must not be null.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.
java.lang.NullPointerException is thrown if either the name or the attribute is null.

setExpires
int setExpires(int deltaMinutes)
The method sets the expiration time for the current SipApplicationSession. This method allows servlets to programmatically extend the lifetime of an application session. It can be invoked during session expiration notifications (e.g., SipApplicationSessionListener.sessionExpired) to extend the session lifetime.
The server determines whether to grant or deny the request based on its policy. Passing a value of 0 or a negative number requests that the session never expires, but it is up to the container to fulfill this request.
Attempts to extend the lifetime of an already invalidated session will always fail. If the container accepts the session as immortal, it will return Integer.MAX_VALUE.
Parameters:
deltaMinutes: The number of minutes by which to extend the session's lifetime. Passing 0 or a negative value requests the session to never expire (subject to server acceptance).
Returns:
The actual number of minutes by which the session lifetime was extended. Returns 0 if the request was denied or if the session was not extended.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.

setInvalidateWhenReady
void setInvalidateWhenReady(boolean invalidateWhenReady)
The method specifies whether the container should notify the application when the SipApplicationSession enters the "ready-to-invalidate" state. When enabled, the container uses the SipApplicationSessionListener.sessionReadyToInvalidate callback to notify the application.
The ready-to-invalidate state indicates that the application session has met all the conditions for being safely invalidated by the container.
Parameters:
invalidateWhenReady:
    If true, the container observes this session and notifies the application when it enters the ready-to-invalidate state.
    If false, the container does not observe the session for this state.
Default behavior:
For v1.1 applications: true.
For v1.0 applications: false.
Exception:
java.lang.IllegalStateException is thrown if the SipApplicationSession is no longer valid.