public interface DialogActivity extends Dialog
DialogActivity
objects.
DialogActivity
extends the JSIP 1.2 Dialog
interface with some additional
methods to assist SLEE applications.
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 using Dialog.createRequest(String)
and sendRequest(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 using createRequest(javax.sip.message.Request)
and
sendRequest(javax.sip.message.Request)
.
DialogForkedEvent
means that a new dialog has been created by a
downstream proxy forking an INVITE request. The new dialog activity can be retrieved using
DialogForkedEvent.getNewDialog()
.
SleeSipProvider.forwardForkedResponse(javax.sip.ServerTransaction, javax.sip.message.Response)
,
a new dialog activity is returned.
ServerTransaction
activity.
When a B2BUA receives an initial incoming request on a ServerTransaction
, it can create the
incoming dialog activity using SipProvider.getNewDialog(javax.sip.Transaction)
. Then
to forward the initial request, a new outgoing dialog is created using SleeSipProvider.getNewDialog(DialogActivity, boolean)
,
passing the incoming dialog activity as a parameter. The initial request can then be forwarded using
createRequest(javax.sip.message.Request)
and sendRequest(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 outgoing
ClientTransaction
is created using associateServerTransaction(javax.sip.ClientTransaction, javax.sip.ServerTransaction)
.
This must be called immediately after the request is sent. Later when the response arrives, the associated
ServerTransaction
is retrieved using getAssociatedServerTransaction(javax.sip.ClientTransaction)
,
and the response forwarded upstream using createResponse(javax.sip.ServerTransaction, javax.sip.message.Response)
and ServerTransaction.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.
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 calling Dialog.delete()
.
Modifier and Type | Method and Description |
---|---|
void |
associateServerTransaction(ClientTransaction ct,
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.
|
Request |
createRequest(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.
|
Response |
createResponse(ServerTransaction origServerTransaction,
Response receivedResponse)
This method is used to create a
Response that is to be forwarded on this Dialog. |
Object |
getApplicationData()
This method is disallowed in the JSIP 1.2 RA Type.
|
ServerTransaction |
getAssociatedServerTransaction(ClientTransaction ct)
This method is called when a response is received that should be forwarded upstream on
another dialog.
|
ClientTransaction |
sendCancel()
Create and send a CANCEL request for the last INVITE request that was sent on this
dialog.
|
ClientTransaction |
sendRequest(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.
|
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
ClientTransaction sendRequest(Request request) throws SipException
request
- the Request
to be sent on the dialog. This request should have been
created using the dialogClientTransaction
that this request was sent out on.
Note the ClientTransaction
object is not an activity in the SLEE.SipException
- if unable to create the client transaction or send the request.Request createRequest(Request origRequest) throws SipException
origRequest
- the original request received on another dialog.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.SipException
- if unable to create the request.Response createResponse(ServerTransaction origServerTransaction, Response receivedResponse) throws SipException
Response
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
and
getAssociatedServerTransaction
methods,
so that incoming responses can be easily matched with a ServerTransaction
to forward them on.
origServerTransaction
- the ServerTransaction
on the dialog, on which
the newly-created response will be sent on.receivedResponse
- the Response
received on another dialog.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.SipException
- if unable to create the response.void associateServerTransaction(ClientTransaction ct, ServerTransaction st)
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 to
createResponse(javax.sip.ServerTransaction, javax.sip.message.Response)
so the response
can be forwarded upstream.
ct
- the ClientTransaction
which is sending the forwarded request.st
- the original ServerTransaction
that received the request.ServerTransaction getAssociatedServerTransaction(ClientTransaction ct)
ServerTransaction
using the mapping
set up by a previous call to associateServerTransaction(javax.sip.ClientTransaction, javax.sip.ServerTransaction)
.ct
- the ClientTransaction
on which the response was received.ServerTransaction
, or null
if there no associated transaction.ClientTransaction sendCancel() throws SipException
ClientTransaction
activity object, representing the
CANCEL's client transaction. The SBB may obtain the ActivityContextInterface
for this activity and attach to it, if it is interested in the response to the CANCEL.
Otherwise, this activity may be safely ignored.SipException
- if there was no active INVITE client transaction to cancel, or
if there was an error sending the CANCEL request.Object getApplicationData()
SecurityException
.getApplicationData
in interface Dialog
void setApplicationData(Object object)
SecurityException
.setApplicationData
in interface Dialog