SIP Dialog Termination
An application may terminate a Session Initiation Protocol (SIP) dialog using the SipSession.terminateDialog method at any time. If the application is acting as a SIP user agent on the SipSession, and if the SipSession corresponds to an established SIP dialog, or a dialog-establishing transaction is pending, terminateDialog method call instructs the container to send the appropriate SIP messages to terminate the dialog, otherwise the call results in a no-op.
Note:
SIP dialogs are only created by the INVITE, REFER, and SUBSCRIBE methods, and, therefore, terminateDialog only affects dialogs created by these methods. For any other session, the method call will result in an IllegalStateException.Once the terminateDialog method is called, the application cannot send any more messages in the SipSession. Any attempt to do so will cause IllegalStateException to be thrown by the SipServletMessage.send() method. Furthermore, the container will not invoke the application's SipServlet service() or doXXX() methods from that point on. When the dialog is terminated, the app is notified by the current SipSessionListener.sessionReadyToInvalidate() method.
An application may terminate all dialogs belong to a forking context using ForkingContext.terminateDialogs() method. The container will also terminate all derived sessions that belong to the same ForkingContext, created after executing this method. For more information, see "Forking SIP Requests".
Note:
This method will not terminate dialogs that belong to a proxy application.In certain cases, an application may wish to modify the outgoing SIP message that the container is sending in order to terminate a dialog. For example, the application may want to add a Reason header to a BYE method, or a message content to a NOTIFY method. There are also cases where the application may wish to be notified of incoming SIP messages. The application may provide a listener using the following method:
SipSession.terminateDialog(AutomaticProcessingListener listener)
The AutomaticProcessingListener should not make changes to message that subvert the RFCs and container behavior in terminating the dialog. Oracle also recommends that applications do not throw any exceptions during the execution of AutomaticProcessingListener. Any exception thrown by the application will be ignored by the SIP servlet container.
Table 10-1 describes the AutomaticProcessingListener methods.
Table 10-1 AutomaticProcessingListener Methods
| Method Name | Description |
|---|---|
|
outgoingRequest(request) |
This method is invoked before Converged Application Server sends a SIP request. The application may modify the request in-place. |
|
outgoingResponse(response) |
This method is invoked before the Converged Application Server sends a SIP response. The application may modify the response in-place. |
|
incomingRequest(request) |
This method is invoked when the Converged Application Server receives a SIP request. |
|
incomingResponse(response) |
This method is invoked when the Converged Application Server receives a SIP response. |
Note:
For details on the API described in this section, see the Java SIP Servlet API 2.0 JavaDocs.
Terminating Proxy Dialogs
As defined in RFC 3261, https://www.ietf.org/rfc/rfc3261.txt, a SIP proxy must
not create and send requests in an established dialog. However, some 3GPP applications
need this ability (see 3GPP TS 24.229, http://www.3gpp.org/dynareport/24229.htm, section
5.2.8.1.2 Release of an existing session). To support that use case, a separate method
is provided so that an application can terminate proxy dialogs.
Note:
Given the way that this method breaks RFC 3261, this method should be used with caution and any application that uses it should be carefully tested. 3GPP specifications also require a way where the termination messages are sent for either one side of the proxy or both.
If the SipSession corresponds to an established SIP dialog, or a dialog-establishing transaction is pending, the methods in Table 10-2 instruct the container to send the appropriate SIP messages to terminate the dialog.
Table 10-2 Proxy Dialog Termination Methods
| Method Name | Description |
|---|---|
|
terminateProxiedDialog(direction) |
Terminates the proxied dialog by sending appropriate messages in the direction specified. For example, if the direction is UAC, Converged Application Server will send BYE message to terminate an INVITE dialog in the direction of UAC. |
|
terminateProxiedDialog(direction, listener) |
Terminates the proxied dialog by sending appropriate messages in the direction specified. Applications may intercept messages during termination. |
|
terminateProxiedDialog() |
Terminates the proxied dialog by sending appropriate messages in both directions. |
|
terminateProxiedDialog(listener) |
Terminates the proxied dialog by sending appropriate messages in both the directions. Applications may intercept messages during termination. |
Note:
An application should invoke the first two terminateProxiedDialog methods only when it find using some other means that other side of the specified direction will not respond. Any message on the other side may be ignored by Converged Application Server.
Notes on Container Behavior
Converged Application Server uses the following RFCs as guidelines for correct dialog termination behavior:
- RFC 3261,
https://www.ietf.org/rfc/rfc3261.txt - RFC 6665 (for SUBSCRIBE),
https://tools.ietf.org/html/rfc6665 - RFC 3515 (for REFER),
https://www.ietf.org/rfc/rfc3515.txt - RFC 5057 (multiple dialogs),
https://tools.ietf.org/html/rfc5057 - RFC 5407 (race states),
https://tools.ietf.org/html/rfc5407 - RFC 6026 (an update to RFC 3261),
https://tools.ietf.org/html/rfc6026
The following sections provide examples of Converged Application Server behavior in terminating SIP dialogs based on those RFCs. In the examples, the terms UA, UAC and UAS should be understood to mean the Converged Application Server acting on behalf of an UA application that has called SipSession.terminateDialog(). Similarly, when a proxy dialog is being terminated using SipSession.terminateProxiedDialog(), these terms corresponds to the direction(s) in which the messages are being sent.
INVITE Dialog
Keep in mind the following INVITE dialog points:
-
When a dialog is in its early state, a caller UA must send CANCEL to terminate the dialog. (While RFC3261 allows sending CANCEL or BYE, RFC 5407 section 2 says UAC MAY send BYE, but not recommended, so Converged Application Server sends a CANCEL request.). The callee UA can send an error as a final response.
-
The callee's UA must not send a BYE on a confirmed dialog until it has received an ACK for its 2xx response or until the server transaction times out. (See RFC3261 sec 15, and RFC6026).
-
When a UA receives a BYE, it must respond to any pending requests received for that dialog with a 487 response (RFC3261 sec 15.1.2).
-
While not specified explicitly, a UA should respond to any pending requests before sending BYE. Converged Application Server sends a 487 response code when responding to pending requests.
-
Various race conditions as described by RFC5407, for example when a requests have arrived after a UA has sent BYE, are responded to.
SUBSCRIBE Dialog
Keep in mind the following SUBSCRIBE dialog points:
-
A SUBSCRIBE dialog can be created explicitly by subscriber sending SUBSCRIBE.
-
A SUBSCRIBE dialog can also be created implicitly by REFER.
-
A subscription is destroyed when a UA acting as notifier sends a NOTIFY request with a "Subscription-State" of "terminated". If the dialog is not otherwise in use, the SIP dialog is terminated.
-
A UA acting as a subscriber cannot explicitly terminate a subscription. A UA acting as subscriber may send a SUBSCRIBE request with an "Expires" header of 0 in order to trigger the notifier to send a NOTIFY request that destroys the subscription.
Multiple Dialogs
Keep in mind the following points when using multiple dialogs:
-
It is possible for a dialog to have multiple usages (RFC 5057). For the purpose of dialog termination, in order to terminate the dialog the UA must terminate each of those usages independently in order to terminate the entire dialog.
-
The order in which messages are sent to terminate the usages is not important. For example, the UA may need to send BYE and NOTIFY to terminate the INVITE and SUBSCRIBE usages in a dialog respectively, and the UA may send these messages in either order.