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.

<?xml version="1.0"?>
<sip-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.jcp.org/xml/ns/sipservlet http://www.jcp.org/xml/ns/sipservlet/sip-app_1_1.xsd"
 version="1.1">
.....
</sip-app>

doInvite/doSubscribe/doRefer(SipServletRequest req) { // initial request.
        req.getApplicationSession().setInvalidateWhenReady(true);
        req.getSession().setInvalidateWhenReady(true);
}

public class UASServlet { // case 1 : UAS

    doBye(SipServletRequest req) { // incoming BYE request.

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

        // After the 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 might resend the BYE again, 
        // so we need to retain the SipSession.
    }

} 

public class UACServlet { // case 2 : UAC

    doResponse(SipServletResponse resp) { 

        if (resp.getRequest().getMethod().equals("BYE")) { // repsonse to BYE.

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

            // The SipSession 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 BYE again and expect a response, 
            // so we need to retain the SipSession.
        }
    }
}

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.
        }
    }
}

class NonRecordRoutingProxy {

    protected void doInvite(SipServletRequest req)
            throws ServletException, IOException {
        SipSession s = req.getSession();
        if (req.isInitial()) {
            Proxy proxy = req.getProxy();
            proxy.setRecordRoute(false);
            proxy.setSupervised(true);
            proxy.proxyTo(req.getRequestURI());
        }

        // After this method returns, SipSession is invalidated immediately.

    }
}

class UACServlet { // we are the Caller.

    doErrorResponse(SipServletResponse resp) {

        SipServletRequest req = resp.getRequest();
        int statusCode = resp.getStatus();

        if ((req == INVITE / SUBSCRIBE / REFER) && (300 <= status <= 699)) { // error response for INITIAL request.

            // The session will be invalidated immediately after this method returns.

        }
    }
} 

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

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:

class SipSessionListenerImpl implements SipSessionListener {

    sessionReadyToInvalidate(SipSessionEvent e) {

        SipSession s = e.getSession();

        // invoke s.setInvalidateWhenReady(false) to disallow automatic invalidation 
        // i.e., SipSession will NOT be invalidated after this method returns.

        // do nothing, to allow the automatic invalidation 
        // i.e, the SipSession will be invalidated when this method returns.
    }
}

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.