Automatic invalidation of SIP sessions (aka Invalidate When Ready - IWR) in SailFin

This blog explains how the automatic invalidation of SIP sessions work in SailFin container.

To give some brief introduction, following are the ways by which a SIP session can be invalidated in SailFin container:

1. Explicit invalidation by the application itself i.e., by invoking session.invalidate().

2. SAS (SipApplicationSession) expiration which eventually invalidates SAS and all its children, if the application does not extend the SAS expirationTime in sessionExpired listener callback.

3. IWR i.e., Automatic invalidation of sessions, I would call it "container managed invalidation" which is the fastest invalidation and resource cleanup machanism. This type of invalidation happens as soon as the sip dialog terminates (eg., after processing BYE request).  In the rest of the blog I will explain more about how this particular invalidation machanism works and the how the applications can use it and get benefit out of it.

Here are the details of automatic invalidation (IWR):

Section #1. Enabling the automatic invalidation:

(a) If the application is of SSA 1.1 version, then the automatic invalidation is enabled by default. The 1.1 application will have its sip.xml like this:

(b) If the application is of SSA 1.0 version,, then the automatic invalidation can be enabled programatically. This need to be done when processing the initial request, something like this:

(a) After BYE is processed. From a application point of view, it looks something like this:

class UASServlet { // case 1 : UAS

    doNotify(SipServletRequest req) { // incoming NOTITY request.

        if (req.getHeader("Subscription-State").equalsIgnorecase("terminated")) {

            SipSession s = req.getSession();
            s.isReadyToInvalidate(); // would be false;
            s.isValid(); // would be true
            SipServletResponse resp = s.createResponse(<resp-code>);
            resp.send();

            // After resp.send(), the SipSession is no longer valid in all cases,
            // except when <resp-code>=401/407/408.

            // when <resp-code>=401/407/408, the client may re-send the NOTIFY again,
            // so we need to retain the SipSession.
        }

    }
}

class UACServlet { // case 2 : UAC

    doResponse(SipServletResponse resp) {

        String reqMethod = resp.getRequest().getMethod();
        String subscriptionState = resp.getRequest().getHeader("Subscription-State");

        if (reqMethod.equals("NOTIFY") && subscriptionState.equalsIgnorecase("terminated")) { // resp to NOTIFY

            SipSession s = resp.getSession();
            s.isValid(); // would be true;
            s.isReadyToInvalidate(); // would be true;

            // The session would be invalidated immediately after this method finishes, 
            // in all cases except when resp.getStatus() is 401/407/408.

            // when resp.getStatus()=401/407/408, we can send NOTIFY again and expect a response, 
            // so we need to retain the session.
        }
    }
}

That is about the SipSession' invalidation in the simplest possible terms.

Now let us see when javax.servlet.sip.SipApplicationSession gets automatically invalidated. For the SipApplicationSession it is very simple : Automatic invalidation happens when the SipApplicationSession becomes completely EMPTY i.e., when all its child protocol sessions (sip & http) get invalidated & all its servlettimers expire.

Section #3. Controlling the automatic invalidation:

When the session is about to be automatically invalidated, sessionReadyToInvalidate(...) callback is invoked in the listener. In this callback, the application can decide whether it should allow the automatic invalidation or not. For example:

Similar thing can be done in the SipApplicationSessionListener as well.

Also, if you don't implement any of these listeners, then the container assumes that the automatic invalidation is allowed.

Thats a very quick and most simplified description of IWR.