Interface DialogActivity
-
- All Superinterfaces:
javax.sip.Dialog
,Serializable
public interface DialogActivity extends javax.sip.Dialog
Dialog activities in the JSIP 1.2 RA Type are represented usingDialogActivity
objects.DialogActivity
extends the JSIP 1.2Dialog
interface with some additional methods to assist SLEE applications.Dialog Creation
There are several possible ways to create new dialog activities:SipProvider.getNewDialog(javax.sip.Transaction)
: This method creates a dialog activity when an initial request is received, or is about to be sent. This is defined in JAIN SIP 1.2.SleeSipProvider.getNewDialog(javax.sip.address.Address, javax.sip.address.Address)
: This is a convenience method for creating a new client dialog easily using only from and to addresses. The RA automatically generates the initial dialog state. An initial request can then be easily generated and sent usingDialog.createRequest(String)
andsendRequest(javax.sip.message.Request)
.SleeSipProvider.getNewDialog(DialogActivity, boolean)
: This method is useful for B2BUA applications. A new client dialog is created based on an incoming dialog. Requests can then be forwarded between dialogs usingcreateRequest(javax.sip.message.Request)
andsendRequest(javax.sip.message.Request)
.- Receiving a
DialogForkedEvent
means that a new dialog has been created by a downstream proxy forking an INVITE request. The new dialog activity can be retrieved usingDialogForkedEvent.getNewDialog()
. - Finally, when a forked response is forwarded upstream using
SleeSipProvider.forwardForkedResponse(javax.sip.ServerTransaction, javax.sip.message.Response)
, a new dialog activity is returned.
Mid-dialog Requests
Incoming requests that match an active dialog activity will be fired on the dialog activity. In this way a dialog-stateful SBB can attach to the dialog's activity context and automatically receive all subsequent mid-dialog requests. Requests that do not match any active dialog will be fired on aServerTransaction
activity.Forwarding Requests and Responses
A common type of SIP application is the Back-To-Back User Agent (B2BUA), which must forward requests between different dialogs. Several methods are provided to simplify writing SLEE B2BUA applications.When a B2BUA receives an initial incoming request on a
ServerTransaction
, it can create the incoming dialog activity usingSipProvider.getNewDialog(javax.sip.Transaction)
. Then to forward the initial request, a new outgoing dialog is created usingSleeSipProvider.getNewDialog(DialogActivity, boolean)
, passing the incoming dialog activity as a parameter. The initial request can then be forwarded usingcreateRequest(javax.sip.message.Request)
andsendRequest(javax.sip.message.Request)
The response to the forwarded request will be received on the dialog activity. In order to simplify response forwarding, an "association" between the incoming
ServerTransaction
and outgoingClientTransaction
is created usingassociateServerTransaction(javax.sip.ClientTransaction, javax.sip.ServerTransaction)
. This must be called immediately after the request is sent. Later when the response arrives, the associatedServerTransaction
is retrieved usinggetAssociatedServerTransaction(javax.sip.ClientTransaction)
, and the response forwarded upstream usingcreateResponse(javax.sip.ServerTransaction, javax.sip.message.Response)
andServerTransaction.sendResponse(javax.sip.message.Response)
. See the example B2BUA SBB included in this distribution.Note: The terms "incoming" and "outgoing" are only used here to describe the flow of the initial request on the two dialogs. After the dialogs are established, requests can be sent in either direction.
Dialog Termination
Dialog activities are automatically ended when a dialog-terminating request is sent or received on the dialog. For dialogs initiated by INVITE, the dialog-terminating request is a BYE. For dialogs initiated with SUBSCRIBE, the dialog-terminating request is a NOTIFY with the "Subscription-State: terminated" header.If the dialog's initial request fails or times out, the dialog is automatically ended. If the RA receives a CANCEL for an INVITE-initiated dialog, the RA will generate a 487 response and terminate the dialog.
An application can end a dialog activity at any time using
Dialog.delete()
. This ends the dialog activity in the SLEE, without sending any messages on the dialog. If an application needs to signal the the other party that the dialog is ending, it must send a dialog-terminating request (such as BYE) rather than callingDialog.delete()
.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
associateServerTransaction(javax.sip.ClientTransaction ct, javax.sip.ServerTransaction st)
When forwarding requests between dialogs, as a B2BUA would do, it is necessary to create an association between the client transaction, which is forwarding the request, and the server transaction, on which the original request was received.javax.sip.message.Request
createRequest(javax.sip.message.Request origRequest)
This method is used to create a Request that will be sent on this Dialog, where the original Request has been received on an incoming Dialog.javax.sip.message.Response
createResponse(javax.sip.ServerTransaction origServerTransaction, javax.sip.message.Response receivedResponse)
This method is used to create aResponse
that is to be forwarded on this Dialog.Object
getApplicationData()
This method is disallowed in the JSIP 1.2 RA Type.javax.sip.ServerTransaction
getAssociatedServerTransaction(javax.sip.ClientTransaction ct)
This method is called when a response is received that should be forwarded upstream on another dialog.javax.sip.ClientTransaction
sendCancel()
Create and send a CANCEL request for the last INVITE request that was sent on this dialog.javax.sip.ClientTransaction
sendRequest(javax.sip.message.Request request)
Convenience method to create a client transaction and send a request in one operation.void
setApplicationData(Object object)
This method is disallowed in the JSIP 1.2 RA Type.-
Methods inherited from interface javax.sip.Dialog
createAck, createPrack, createReliableProvisionalResponse, createRequest, delete, getCallId, getDialogId, getFirstTransaction, getLocalParty, getLocalSeqNumber, getLocalSequenceNumber, getLocalTag, getRemoteParty, getRemoteSeqNumber, getRemoteSequenceNumber, getRemoteTag, getRemoteTarget, getRouteSet, getState, incrementLocalSequenceNumber, isSecure, isServer, sendAck, sendReliableProvisionalResponse, sendRequest, terminateOnBye
-
-
-
-
Method Detail
-
sendRequest
javax.sip.ClientTransaction sendRequest(javax.sip.message.Request request) throws javax.sip.SipException
Convenience method to create a client transaction and send a request in one operation.- Parameters:
request
- theRequest
to be sent on the dialog. This request should have been created using the dialog- Returns:
- the new
ClientTransaction
that this request was sent out on. Note theClientTransaction
object is not an activity in the SLEE. - Throws:
javax.sip.SipException
- if unable to create the client transaction or send the request.
-
createRequest
javax.sip.message.Request createRequest(javax.sip.message.Request origRequest) throws javax.sip.SipException
This method is used to create a Request that will be sent on this Dialog, where the original Request has been received on an incoming Dialog. This scenario is common for B2BUA applications.- Parameters:
origRequest
- the original request received on another dialog.- Returns:
- a new
Request
to be sent on the dialog. This will be a copy of the original request, with the correct dialog-specific headers for this dialog. - Throws:
javax.sip.SipException
- if unable to create the request.
-
createResponse
javax.sip.message.Response createResponse(javax.sip.ServerTransaction origServerTransaction, javax.sip.message.Response receivedResponse) throws javax.sip.SipException
This method is used to create aResponse
that is to be forwarded on this Dialog. This is typically performed when a B2BUA application receives a response from one Dialog and wishes to forward the response on another Dialog.This method is intended to be used in conjunction with the
associateServerTransaction
andgetAssociatedServerTransaction
methods, so that incoming responses can be easily matched with aServerTransaction
to forward them on.- Parameters:
origServerTransaction
- theServerTransaction
on the dialog, on which the newly-created response will be sent on.receivedResponse
- theResponse
received on another dialog.- Returns:
- a new
Response
to be sent on the dialog. This will be a copy of the original response, with the correct dialog-specific headers for this dialog. - Throws:
javax.sip.SipException
- if unable to create the response.
-
associateServerTransaction
void associateServerTransaction(javax.sip.ClientTransaction ct, javax.sip.ServerTransaction st)
When forwarding requests between dialogs, as a B2BUA would do, it is necessary to create an association between the client transaction, which is forwarding the request, and the server transaction, on which the original request was received. This is so that when a response arrives on the client transaction, it can be forwarded upstream on the original server transaction.A B2BUA application should call this method when forwarding a request on a dialog, so that later when it needs to forward the response, it can easily get the original server transaction using
getAssociatedServerTransaction(javax.sip.ClientTransaction)
, and pass this tocreateResponse(javax.sip.ServerTransaction, javax.sip.message.Response)
so the response can be forwarded upstream.- Parameters:
ct
- theClientTransaction
which is sending the forwarded request.st
- the originalServerTransaction
that received the request.
-
getAssociatedServerTransaction
javax.sip.ServerTransaction getAssociatedServerTransaction(javax.sip.ClientTransaction ct)
This method is called when a response is received that should be forwarded upstream on another dialog. It retrieves the originalServerTransaction
using the mapping set up by a previous call toassociateServerTransaction(javax.sip.ClientTransaction, javax.sip.ServerTransaction)
.- Parameters:
ct
- theClientTransaction
on which the response was received.- Returns:
- the original
ServerTransaction
, ornull
if there no associated transaction.
-
sendCancel
javax.sip.ClientTransaction sendCancel() throws javax.sip.SipException
Create and send a CANCEL request for the last INVITE request that was sent on this dialog. This method may be used for cancelling initial INVITEs or re-INVITEs. This method does not directly affect the dialog state. The CANCEL should cause the downstream server to send a 487 response to the INVITE, which will automatically end the dialog if the INVITE was the initial request.- Returns:
- A
ClientTransaction
activity object, representing the CANCEL's client transaction. The SBB may obtain theActivityContextInterface
for this activity and attach to it, if it is interested in the response to the CANCEL. Otherwise, this activity may be safely ignored. - Throws:
javax.sip.SipException
- if there was no active INVITE client transaction to cancel, or if there was an error sending the CANCEL request.
-
getApplicationData
Object getApplicationData()
This method is disallowed in the JSIP 1.2 RA Type. SBBs must use CMP fields instead. Invoking this method will throw aSecurityException
.- Specified by:
getApplicationData
in interfacejavax.sip.Dialog
-
setApplicationData
void setApplicationData(Object object)
This method is disallowed in the JSIP 1.2 RA Type. SBBs must use CMP fields instead. Invoking this method will throw aSecurityException
.- Specified by:
setApplicationData
in interfacejavax.sip.Dialog
-
-