About Back to Back User Agents

There is no Internet Engineering Task Force (IETF) standard that defines how a B2BUA behaves; however, it is largely assumed to be an entity that receives a request, upstream, as a User Agent Server (UAS) and relays it as a new request based on the received request downstream as a User Agent Client (UAC). Effectively, the application relays the request downstream.

From a SIP servlet perspective, an application is considered a B2BUA if it indicates the routing directive as CONTINUE.

Example 9-1 illustrates explicit linking.

Example 9-1 B2BUA Routing

        +------------------------------------------+
        |                                          |
  req1  | req2 = factory.createRequest(appSession, |  req2
------->| "INVITE", req1.getFrom(), req1.getTo()); |--------->
        | // Copy headers and content from req1... |
        | req2.setRoutingDirective(CONTINUE, req1);|
        | req2.send();                             |
        +------------------------------------------+

Navigating Between the UAC and UAS Sides of a B2BUA

A common behavior of a B2BUA is to forward the requests and responses received on the UAS side of the B2BUA to the UAC side and back again. Since both UAS and UAC sides of the B2BUA contain their own SipSession objects, while receiving a request or response on one side, an application often needs to navigate to a SipSession on the other side. To facilitate this, applications can store session IDs of the peer session as an attribute in the SipSession as shown in Example 9-2.

Example 9-2 Linking SIP Sessions

public void linkSessions(SipSession s1, SipSession s2) {
  s1.setAttribute(LINKED_SESSION_ID, s2.getId());
  s2.setAttribute(LINKED_SESSION_ID, s1.getId());
}

The linked sessions can then be retrieved by using the stored attributes as shown in Example 9-3.

Example 9-3 Retrieving Linked SIP Sessions

private SipSession retrieveOtherSession(SipSession s) {
  String otherSessionId = (String) s.getAttribute(LINKED_SESSION_ID);
  return s.getApplicationSession().getSipSession(otherSessionId);
}

Many times, the UAC and UAS sides of the B2BUA need to access the SipServletRequest on the other side. To facilitate this, applications may store the request IDs of the SipServletRequest in each other as shown in Example 9-4.

Example 9-4 Linking Requests

@Bye
protected void handleBye(SipServletRequest bye1) throws IOException {
  SipSession otherSession = retrieveOtherSession(bye1.getSession());
  SipServletRequest bye2 = otherSession.createRequest("BYE");
  linkRequests(bye1, bye2);
  bye2.send();
}
private void linkRequests(SipServletRequest r1, SipServletRequest r2) {
  r1.setAttribute(LINKED_REQUEST_ID, r2.getId());
  r2.setAttribute(LINKED_REQUEST_ID, r1.getId());
}

When needed, the requests can then be accessed from the session, if they are active as shown in Example 9-5.

Example 9-5 Retrieving Requests

@SuccessResponse @Bye
protected void byeResponse(SipServletResponse r1) throws IOException {
  SipServletRequest request = retriveLinkedRequest(r1.getRequest());
  SipServletResponse r2 = request.createResponse(r1.getStatus(),
    r1.getReasonPhrase());
  r2.send();
}
private SipServletRequest retriveLinkedRequest(SipServletRequest r1) {
  String requestId = (String) r1.getAttribute(LINKED_REQUEST_ID);
  SipSession session = retrieveOtherSession(r1.getSession());
  return session.getActiveRequest(requestId);
}

ACK and PRACK Handling in B2BUA

To forward an ACK request, the B2BUA needs to access the servlet on the other side and the application needs to access final response. The application can retrieve the final response of the INVITE request by using the SipServletRequest.getFinalResponse() method. When an ACK request arrives, B2BUA first retrieves the INVITE method from the other side by using the SipSession.getActiveInvite(UAMode) method and then accesses the final response from SipServletRequest as shown in Example 9-6.

Example 9-6 B2BUA Relaying ACK

@Ack
protected void handleAck(SipServletRequest uasAck) throws IOException {
  SipSession uacSession = retrieveOtherSession(uasAck.getSession());
  SipServletRequest uacInvite = uacSession.getActiveInvite(UAMode.UAC);
  SipServletRequest uacAck = uacInvite.getFinalResponse().createAck();
  uacAck.send();
}

For reliable provisional responses, B2BUA may establish a relationship between an incoming reliable provisional response with the one relayed by the B2BUA. This can be done by saving the reliable sequence number (RSeq) and the request ID as attributes in the response as shown in Example 9-7.

Example 9-7 Linking Reliable Provisional Responses

@ProvisionalResponse
void provisionalResponse(SipServletResponse r1) throws Exception {
  SipServletRequest request = retriveLinkedRequest(r1.getRequest());
  SipServletResponse r2 = request.createResponse(r1.getStatus());
  if (r1.isReliableProvisional()) {
    String respId = r1.getProvisionalResponseId();
    r2.setAttribute(LINKED_RELIABLE_RESPONSE_ID, respId);
    r2.sendReliably();
  }
}

The linked provisional response may then be retrieved when the B2BUA forwards a PRACK as shown in Example 9-8.

Example 9-8 Forwarding a PRACK

@Prack
void handlePrack(SipServletRequest prack) throws Exception {
  SipServletResponse r1 = prack.getAcknowledgedResponse();
  SipSession session = retrieveOtherSession(prack.getSession());
  String respId = (String) r1.getAttribute(LINKED_RELIABLE_RESPONSE_ID);
  SipServletResponse r2 =
  session.getUnacknowledgedProvisionalResponse(respId);
  r2.createPrack().send();
}

B2BUA and Forking

When an INVITE request is forked downstream, one request may receive responses on different dialogs (derived sessions). Each response causes a transaction branch and is represented in the SipServlet API by the InviteBranch interface.

A B2BUA forwards such responses on different branches as a UAS to create a new InviteBranch using the SipServletRequest.createInviteBranch() method as shown in Example 9-9.

Example 9-9 Sending a Response on a Particular Branch

@Invite
void handleInviteResponse(SipServletResponse r1) throws IOException {
  InviteBranch branch = r1.getSession().getActiveInviteBranch();
  if (branch != null) {
    SipSession uasSession = retrieveOtherSession(r1.getSession());
    if (uasSession == null) {
      SipServletRequest req =
      retreiveLinkedRequest(r1.getRequest());
      branch = req.createInviteBranch();
    }
    SipServletResponse r2 =
    branch.createResponse(r1.getStatus(), r1.getReasonPhrase());
    r2.send();
  }
}

One SipServletRequest may result in more than one branch. Therefore, when there are circumstances where a B2BUA needs to access a particular branch, the B2BUA must use the corresponding InviteBranch object. For example, while relaying an ACK message, the B2BUA may access the final response from the InviteBranch object as shown in Example 9-10.

Example 9-10 Relaying an ACK on a Particular Branch

@Ack
protected void handleAck(SipServletRequest uasAck) throws IOException {
  SipSession uacSession = retrieveOtherSession(uasAck.getSession());
  InviteBranch branch = uacSession.getActiveInviteBranch();
  if (branch != null) {
    SipServletResponse response = branch.getFinalResponse();
    response.createAck().send();
  }
}

Although non-INVITE requests can also be forked, the absence of ACK and PRACK messages make their call flow much simpler. Similarly, non-INVITE requests do not support sending responses on more than one dialog from the UAS. Thus, the SIP Servlet API does not provide an API equivalent to the InviteBranch for non-INVITE requests.