Back-to-Back User Agent Applications

A back-to-back user agent (B2BUA) is a SIP element that acts as an endpoint for two or more SIP dialogs, forwarding requests and responses between the dialogs. B2BUA applications are extremely common SIP applications, and SIP Servlet 1.1 defines a helper class, javax.servlet.sip.B2buaHelperto simplify the creation of B2BUA applications. B2BUA applications have the potential to break end-to-end communication between endpoints because they sit between two endpoints in a communication chain. Using B2buaHelper minimizes some of the risk of breaking the signaling between two endpoints.

Understanding the B2buaHelper Class

The B2buaHelper class contains all the necessary methods for creating B2BUA applications. It is retrieved by calling SipServerRequest.getB2buaHelper.

Example 1–10 Example of Retrieving B2buaHelper

private void sendInfoToClient(SipServletResponse resp) {
	SipServletRequest req = resp.getRequest();
	B2buaHelper b2buaHelper = req.getB2buaHelper();
	...
}

A typical B2BUA application has two SIP sessions, one for each client. The B2buaHelper class is typically used to create requests that are then forwarded to and from the SIP sessions. retrieve linked sessions.

For a complete list of B2buaHelper's methods, see SIP Servlet 1.1 Javadocs.

Creating Requests with B2buaHelper

Once you've retrieved B2buaHelper, you can use it to link two SIP sessions by creating requests using the createRequest method.

Example 1–11 Creating a Request Using B2buaHelper

SipServletRequest clientRequest = 
		b2buaHelper.createRequest(serverReq, true, headerMap);

The createRequest method takes a SipServletRequest instance of the original request, an optional boolean indicating whether the sessions should be linked, and a java.util.Map<String,java.util.Set> map of headers that will be used instead of the headers in the original request. The From and To headers are the keys in the map. The only headers that can be set using this map are non-system headers and the From, To, and Route headers.

See Example 2–6 for the full method where B2buaHelper is used to create a request that links two sessions.

Retrieving Linked Sessions Using B2buaHelper

Once two client's sessions are linked you can then retrieve the sessions using getLinkedSession.

Example 1–12 Retrieving Linked Sessions Using B2buaHelper

private void sendByeToServer(SipServletRequest clientBye) 
        throws ServletException, IOException {
    B2buaHelper b2buaHelper = clientBye.getB2buaHelper();
    SipSession serverSession = b2buaHelper.getLinkedSession(clientBye.getSession());
    SipServletRequest serverBye = serverSession.createRequest("BYE");
    logger.info("Sending BYE request.\n" + serverBye);
    serverBye.send();
}