Tutorial:SipSessions and Dialogs
A SipSession can be roughly considered the representation of a SIP dialog. As such, it maintains dialog state and can be used to create subsequent requests inside a dialog via its createRequest(method). However a couple of differences between SipSessions a SIP dialogs are worth a mention.
One is that unlike what happens with SIP dialogs, UACs can use a SipSession to create "subsequent" requests before the underlying dialog has been stablished or even after a non-2xx final response has arrived. Those requests will have the same CallId, From and To headers and an incremented CSeq value. That makes the SipSession state machine slightly different to that of the SIP dialog.
The second difference is that even if requests are sent without an underlying dialog (it is the case for OPTIONS or REGISTER) they have to be bound to a SipSession.
All messages belonging to the same dialog will have the same associated SipSession. When a message arrives to the servlet for processing, its SipSession can be retrieved via the getSession method. Objects can be stored and retrieved from the SipSession using the setAttribute(java.lang.String name,java.lang.Object attribute) and getAttribute(java.lang.String name) methods.
Another important feature of the SipSession is that it allows to set a particular servlet as the handler of the rest of messages inside the dialog. This is achieved with a call to the method setHandler(servletName). This capability is useful for layering, allowing to separate service logic among differents servlets.