1. Developer Guide
  2. Forking SIP Requests, Dialog Termination, and Session Keep Alive
  3. Forking SIP Requests

Forking SIP Requests

The forking of SIP requests means that multiple dialogs can be established from a single request. When ever multiple dialogs are created due to forking a derived session is created from the original session. Such derived sessions that effectively represent such sibling dialogs belong to a forking context. The ForkingContext interface helps an application to navigate to all such derived sessions. Thus a SipSession and its derived siblings belong to the same forking context.

A ForkingContext is created whenever the first session on a new dialog is created and it remains valid as long as at least one SipSession that belongs to the forking context remains valid. Applications can obtain an instance of a ForkingContext using the SipSession.getForkingContext() method.

When acting as a User Agent (UA), it is possible that an application might want to send a new request on the same forking context, but on a different dialog. In that case such a request establishes a new dialog. An example of such a request is the NOTIFY request as specified in RFC 6665, https://tools.ietf.org/html/rfc6665. SIP servlet applications can create new requests with the same forking Context using the method ForkingContext.createRequest(String method).

Note:

For details on the API described in this section, see the Java SIP Servlet API 2.0 JavaDocs.

Binding Attributes to a ForkingContext

A servlet can bind an object attribute to a ForkingContext by name. Hence ForkingContext is also an attribute store. See the discussion of Attribute Stores in Chapter 7 of JSR-359, https://jcp.org/en/jsr/detail?id=359 for more details.

Creating a Request

When ForkingContext.createRequest() is called, Converged Application Server derives a new session and creates a request using that session. Only NOTIFY requests can be created since this API is only applicable in that scenario. When an application tries to create any other requests, an IllegalArgumentException is thrown. The new derived session is created based upon the first session setup in the forking context.

Cloning Attributes

A ForkingContext supports the flag, enableDerivedSessionAttributeCloning(), for enabling or disabling the cloning of attributes when creating a derived session within the forking context scope. In legacy implementations, when creating a derived session, the attributes in the original session are retrieved and assigned to the new derived session. The new derived session refers to the same attributes object of the original session. When enableDerivedSessionAttributeCloning() is set to true, the attribute values of the original session are cloned, and the derived session refers to a new attributes object. The default value for enableDerivedSessionAttributeCloning() is false.

Terminating Dialogs

When the ForkingContext.terminateDialogs() method is called, Converged Application Server will terminate all SIP sessions of the forking context if they are not explicitly excluded. This method is available for both UA and proxy modes. When ForkingContext.terminateDialogs() is called in proxy mode, the feature proxy send bye will be added to the terminate proxy dialogs.

Max-Breadth Header Support

The Max-Breadth header limits the number of parallel forks that can be made on a Session Initiation Protocol (SIP) request by downstream proxies. Following RFC 5393, https://tools.ietf.org/html/rfc5393, each downstream proxy distributes the Max-Breadth among the active parallel branches so that the outgoing Max-Breadth is the sum of the Max-Breadth header field values in all forwarded requests in the response contexts that have not received a final response.

In Converged Application Server, the application decides the number of times the request is forked in parallel. An application may explicitly set the breadth on the forked requests by using the SipServletRequest.setMaxBreadth() method. Applications may retrieve the forked request by using the ProxyBranch.getRequest() method.

If the received request contains no Max-Breadth header, the container uses 60 as the default value.

In Converged Application Server, the SIP container is configured to automatically check the Max-Breadth header. The associated configuration parameter, Max-Breadth Check Support, is accessible in the Administration Console. The check box entry for Max-Breadth Check Support is selected, by default. You can disable the automatic checking of the Max-Breadth header. To do so, access the General configuration tab for SIP Server in the Domain Structure for the Administration Console and clear the Max-Breadth Check Support check box. See "About Accessing the Administration Console" in Converged Application Server Administrator's Guide.

If a Proxy application does not set the breadth explicitly, Converged Application Server distributes the available breadth evenly to the branches when the application invokes the Proxy.proxyTo() or Proxy.startProxy() methods.

At the time of forking, if the sum of the Max-Breadth values of active parallel branches exceeds the Max-Breadth of the original incoming request, Converged Application Server throws an InsufficientBreadthException. For a proxy, this check is done when the application invokes the Proxy.proxyTo() and Proxy.startProxy() methods. Applications may catch this exception and send an error response (440) or attempt to proxy again after adjusting the breadth.

Max-Breadth is used within Converged Application Server for loop detection.

Note:

For details on the SipServletRequest.setMaxBreadth() method, see the Java SIP Servlet API 2.0 JavaDocs.

Loop Detection

There is a possibility that loops may occur in invoked applications, such as when A proxies to B which proxies back to A. It is important that such loops be detected and handled. Converged Application Server decrements the value of the Max-Forwards header whenever a request is proxied internally, or whenever a request is forwarded by a servlet acting as a Back to Back User Agent (B2BUA).

Converged Application Server also checks the Max-Breadth header to verify whether the request can be proxied in parallel or forwarded to multiple destinations by a servlet acting as a B2BUA in parallel. Converged Application Server generates an InsufficentBreadthException when the Max-Breadth check fails.