Before you begin
Read the
JSR289 specification, section 12, which provides detailed information about
the B2BUA operations. The SIP Servlet 1.1 specification defines a helper class,
javax.servlet.sip.B2buaHelper, for creating B2BUA applications. For more information, see the
documentation on the
B2buaHelper methods.
About this task
The B2BUA is a Session Initiation Protocol (SIP) application that sits in the middle of a
SIP call, and forwards requests and responses between two or more SIP dialogs. A typical B2BUA
application manages SIP sessions between two user agents. However, the B2BUA application can also
handle more complex scenarios where it needs to manage responses from different branches of
downstream forking. Downstream forking occurs when the request is split into different branches and
the message is forwarded from the user agent client to the user agent server. The
B2buaHelper class contains all the necessary methods for creating such B2BUA
applications. The behavior of the
B2buaHelper class and the rules that are used to
create new requests are defined in the JSR289 specification, section 12.2. You can use the
B2buaHelper class functions for linking two legs, the incoming call leg and the
outgoing call leg, of the SIP back-to-back user agent call.
- Retrieve the B2buaHelper instance by calling the
SipServletRequest.getB2buaHelper() method.
- After you retrieve this instance, you can create a new SIP request by calling B2buaHelper.createRequest().
private void doInvite(SipServletRequest req) {
B2buaHelper b2buaHelper = req.getB2buaHelper();
SipServletRequest newRequest = b2buaHelper.createRequest(req, true, headerMap);
}
The newRequest that is created is identical to the SipServletRequest
req that is provided as an original request in the first parameter of this method. The
Boolean parameter indicates whether the original request req
and the newRequest are linked. The headerMap provides a map of
non-system headers to override in the newRequest.
- Ensure that the two legs are linked. If you called the createRequest method
with false attribute, you can link the SIP sessions explicitly by
calling:
B2buaHelper.linkSipSessions(session1, session2)
- After the SIP sessions and SIP requests are linked, you can retrieve the linked session by
calling:
SipSession linkedSession = B2buaHelper.getLinkedSession(req.getSession());
Note: In B2BUA forking scenario, the application creates more than one SIP request, so not all SIP
sessions are linked. You must link them explicitly.
- After you receive a response from the User Agent Server (UAS), create a response to its leg.
Check to determine whether a linked session on the response exists and if it does, use the linked
request to create a response to the User Agent Client (UAC).
SipServletRequest linked = b2bHelper.getLinkedSipServletRequest(resp.getRequest());
linked.createResponse(resp.getStatus(),resp.getReasonPhrase()).send();
If there is no linked session that is associated with the response, the application needs to call
B2buaHelper.createResponseToOriginalRequest and create a new derived session, which
is a copy of the SipSession that is associated with the original request.
Note: The JSR289 specification, section 12.5 provides a way to create more than one successful
response to the original request. If there is more than one SipSession that is
associated with the original INVITE message and there is a need to send more than
one successful response to the INVITE message, then use the
B2buaHelper.createResponseToOriginalRequest method.
- If you use the createResponseToOriginalRequest method, ensure that the two
legs are linked. Your application is responsible for linking the new derived session to its pair
session so it can retrieve the linked session for sending subsequent responses on it.