SipApplicationSession objects are no longer in use and are therefore eligible for garbage collection. The mechanism provided is known as SipApplicationSession invalidation. An application session becomes invalidated in one of three ways:
1. The SipApplicationSession expires and the container subsequently invalidates it.
2. A servlet explicitly invalidates it by invoking the invalidate() method.
3. A servlet marks the SipApplicationSession to be invalidated and the container invalidates it when the SipApplicationSession is in the ready-to-invalidate state as described in
7.1.2.2.2 Invalidate When Ready Mechanism.
For reasons of performance, it is recommended that applications explicitly invalidate SipApplicationSession and SipSession objects as soon as possible. Note: It would be unfortunate if applications were to force creation of an application session just so that they can invalidate it. The getApplicationSession(boolean create) method can be used with a false argument to avoid forcing creation of the session object.
When used, an application session expiration timer ensures that application sessions will eventually become eligible for container invalidation regardless of whether an application explicitly invalidates them. Servlets can register for application session timeout notifications using the SipApplicationSessionListener interface. In the sessionExpired() callback method, the application may request an extension of the application session lifetime by invoking setExpires() on the timed out SipApplicationSession giving as an argument the number of minutes until the session expires again. The container may grant the extension of session lifetime, grant it with a modified timeout value, or reject it. The ability to accept with a different timeout value allow containers to apply their own policies on application session lifetime and timeouts. A container might for example choose to enforce a maximum total lifetime for application sessions. A SipApplicationSession object is said to be expired when its expiration timer is no longer active. An expired SipApplicationSession is not invalid until the container explicitly invalidates it.
The ability to extend session lifetime is useful to applications because it allows them to not use an unrealistically high expiration timer value in cases where application lifetime depends on some “external” event, that is, an event unknown to the servlet container.
7.1.2.1 SipApplicationSession Timer Operation and
SipApplicationSession Expiration
When a SipApplicationSession is created, the SipApplicationSession timer starts if the the timeout value specified by the session-timeout parameter in the deployment descriptor or @SipApplication(sessionTimeout) annotation is set to a positive number. If not specified, the default timeout value is set to 3 minutes.Explicit invalidation of the
SipApplicationSession leads to cancellation of the application session timer. If the session timeout value is 0 or less, then an application session timer never starts for the
SipApplicationSession object and the container does not consider the object to ever have expired. However, if a the session timeout value was set to 0 or less, and a servlet subsequently calls the setExpires() method on a SipApplicationSession object, it is left up to container implementation whether to accept that request and start an expiration timer for the
SipApplicationSession or to reject the setExpires() call by returning 0. If the container accepts the setExpires() request thereby starting an expiration timer, then it becomes the container's responsibility to invalidate the SipApplicationSession when it expires if the application neglects to do so.
A SipApplicationSession expires in one of two ways:
1. Container rejects an application session lifetime extension by returning 0 to a setExpires() call.
2. The application’s SipApplicationSessionListener implementation chooses not to call setExpires() on the SipApplicationSession object inside the sessionExpired() callback.
If the application session timer is active and the expiration timeout is reached, then the sessionExpired() method of any SipApplicationSessionListener implementation is called.
7.1.2.2 SipApplicationSession Invalidation
There are two ways in which a SipApplicationSession can be invalidated:
1. Explicit invalidation Mechanism 2. Invalidate When Ready Mechanism
Once a SipApplicationSession object is invalidated by either the application or the container, it may no longer be used. All references to the object should be removed by the container and applications as soon as possible thus enabling invalidated SipApplicationSession objects to
S i p A p p l i c a t i o n S e s s i o n
be garbage collected. The container MUST invoke the listener callback sessionDestroyed() if a listener exists for both SipSessions and SipApplicationSessions when they are destroyed.
7.1.2.2.1 Explicit Invalidation Mechanism
An application may invalidate a SipApplicationSession at any time using the invalidate() method. On explicit invalidation, the container MUST purge all state for that
SipApplicationSession from its memory. This includes the application state stored in the SipApplicationSession as well as all the contained protocol session objects. The container will also invoke Future.cancel(false) for all asynchronously submitted tasks as specified in section16.3.2 Executing tasks asynchronously.
The invalidate() method will throw an IllegalStateException if the SipApplicationSession object has already been invalidated. Invalidating a
SipApplicationSession using the invalidate() method causes all the protocol sessions contained within it to be explicitly invalidated by the container. Explicit invalidation of SipSession objects is described in 7.2.4.1 SipSession Invalidation.
7.1.2.2.2 Invalidate When Ready Mechanism
The explicit invalidation mechanism described above causes containers to invalidate SipSessions immediately, which could result in partially invalidated application paths and orphaned sessions in other network entities participating in the dialog.
This specification provides a new mechanism for invalidation that applications can use to circumvent the above drawbacks called the "Invalidate When Ready" mechanism. A SipApplicationSession is said to be in a 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 tass submitted as specified in16.3.2 Executing tasks asynchronously is active.
A SipApplicationSession transitions into the ready-to-invalidate state when the following conditions are met:
1. The last protocol session belonging to the SipApplicationSession is invalidated
3. The last asynchronous task submitted as specified in the section16.3.2 Executing tasks asynchronously is completed
A SipSession is in the ready-to-invalidate state if it can be explicitly invalidated such that the SIP state is terminated cleanly across all the SIP network entities participating in the dialog. Refer to 7.2.4.2 Important Semantics for details on when container determines a SipSession is in the ready-to-invalidate state.
This specification introduces new methods to help applications invalidate SipApplicationSessions cleanly. The methods introduced are:
1. isReadyToInvalidate() - returns true if the SipApplicationSession is in the ready-to-invalidate state and false otherwise.
2. setInvalidateWhenReady(boolean flag) - allows applications to indicate to the container to notify it when the SipApplicationSession is in the ready-to-invalidate state. The container notifies the application using the
SipApplicationSessionListener.sessionReadyToInvalidate(SipApplicationSe ssionEvent se) callback method.
3. getInvalidateWhenReady() - returns true if the container will notify the application when the SipApplicationSession is in the ready-to-invalidate state.
An application willing to invalidate a SipApplicationSession cleanly could use the callback mechanism to perform any application clean up before the SipApplicationSession gets invalidated by the container.
Servlets can register for sessionReadyToInvalidate notifications on the
SipApplicationSessionListener interface. In the sessionReadyToInvalidate callback method, an application may choose to invalidate the SipApplicationSession or perform any other cleanup activities. If the application does not explicitly invalidate the
SipApplicationSession in the callback or has not defined a listener, the container will invalidate the SipApplicationSession.
Applications may also use the callback to call setInvalidateWhenReady(false) to indicate to the container to not observe this SipApplicationSession anymore. In this case, the containers MUST not invalidate the SipApplicationSession after the callback. Applications could then either rely on explicit invalidation mechanism or again call
setInvalidateWhenReady(true). This parallels the expiry callback mechanism defined above in 7.1.2.1 SipApplicationSession Timer Operation and SipApplicationSession Expiration. The firing of the SipApplicationSession expiry timer influences the lifetime of a
S i p S e s s i o n
with invalidateWhenReady(true). If the SipApplicationSession times out when it is not yet ready to be invalidated state, an application could detect it in the sessionExpired callback of the SipApplicationSessionListener and extend the lifetime of the