Package net.java.slee.resource.sip

Interface DialogActivity

All Superinterfaces:

Dialog, Serializable

public interface DialogActivity
extends Dialog

Dialog activities in the JSIP 1.2 RA Type are represented using DialogActivity objects. DialogActivity extends the JSIP 1.2 Dialog interface with some additional methods to assist SLEE applications.

Dialog Creation

There are several possible ways to create new dialog activities:

1. 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.
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).
3. 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).
4. 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 using DialogForkedEvent.getNewDialog().
5. 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 a ServerTransaction 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 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.

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 calling Dialog.delete().

Method Summary

Modifier and Type	Method	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.

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

ClientTransaction sendRequest(Request request)
                       throws SipException

Convenience method to create a client transaction and send a request in one operation.

Parameters:

request - the Request 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 the ClientTransaction object is not an activity in the SLEE.

Throws:

SipException - if unable to create the client transaction or send the request.

createRequest

Request createRequest(Request origRequest)
               throws 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:

SipException - if unable to create the request.

createResponse

Response createResponse(ServerTransaction origServerTransaction,
                        Response receivedResponse)
                 throws SipException

This method is used to create a 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.

Parameters:

origServerTransaction - the ServerTransaction on the dialog, on which the newly-created response will be sent on.

receivedResponse - the Response 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:

SipException - if unable to create the response.

associateServerTransaction

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. 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 to createResponse(javax.sip.ServerTransaction, javax.sip.message.Response) so the response can be forwarded upstream.

Parameters:

ct - the ClientTransaction which is sending the forwarded request.

st - the original ServerTransaction that received the request.

getAssociatedServerTransaction

ServerTransaction getAssociatedServerTransaction(ClientTransaction ct)

This method is called when a response is received that should be forwarded upstream on another dialog. It retrieves the original ServerTransaction using the mapping set up by a previous call to associateServerTransaction(javax.sip.ClientTransaction, javax.sip.ServerTransaction).

Parameters:

ct - the ClientTransaction on which the response was received.

Returns:

the original ServerTransaction, or null if there no associated transaction.

sendCancel

ClientTransaction sendCancel()
                      throws 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 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.

Throws:

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 a SecurityException.

Specified by:

getApplicationData in interface 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 a SecurityException.

Specified by:

setApplicationData in interface Dialog