gov.nist.javax.sip.stack
Class DialogImpl

java.lang.Object
  gov.nist.javax.sip.stack.DialogImpl

All Implemented Interfaces:

Dialog, Serializable

public class DialogImpl

extends Object

implements Dialog

Tracks dialogs. A dialog is a peer to peer association of communicating SIP entities. For INVITE transactions, a Dialog is created when a success message is received (i.e. a response that has a To tag). The SIP Protocol stores enough state in the message structure to extract a dialog identifier that can be used to retrieve this structure from the SipStack. Bugs against route set management were reported by Antonis Karydas and Brad Templeton.

Version:

JAIN-SIP-1.1

Author:

M. Ranganathan
This code is in the public domain.

See Also:

Serialized Form

Field Summary

static int	COMPLETED_STATE
static int	CONFIRMED_STATE
static int	EARLY_STATE
static int	TERMINATED_STATE

Method Summary

void	ackReceived(gov.nist.javax.sip.message.SIPRequest sipRequest) Mark that the dialog has seen an ACK.
void	addRoute(gov.nist.javax.sip.message.SIPMessage sipMessage) Extract the route information from this SIP Message and add the relevant information to the route set.
void	addTransaction(SIPTransaction transaction) Add a transaction record to the dialog.
Request	createRequest(String method) Creates a new Request message based on the dialog creating request.
void	delete() This method will release all resources associated with this dialog that are tracked by the Provider.
Object	getApplicationData() Get ptr to opaque application data.
CallIdHeader	getCallId() Returns the Call-ID for this SipSession.
String	getDialogId() Get the id for this dialog.
Transaction	getFirstTransaction() Get the transaction that created this dialog.
SIPTransaction	getLastTransaction() Get the last transaction from the dialog.
Address	getLocalParty() Get the local Address for this dialog.
int	getLocalSequenceNumber() Get the local sequence number (for cseq assignment of outgoing requests within this dialog).
String	getLocalTag() Get local identifier for the dialog.
HopImpl	getNextHop() Get the next hop to which requests in the dialog will be routed to.
Address	getRemoteParty() Returns the Address identifying the remote party.
int	getRemoteSequenceNumber() Get the remote sequence number (for cseq assignment of outgoing requests within this dialog).
String	getRemoteTag() Get peer identifier identifier for the dialog.
Address	getRemoteTarget() Returns the Address identifying the remote target.
Iterator	getRouteSet() Gets the route set for the dialog.
DialogState	getState() Returns the current state of the dialogue.
void	incrementLocalSequenceNumber() Increment the local CSeq # for the dialog.
boolean	isClientDialog() Return true if this is a client dialog.
boolean	isSecure() Returns true if this Dialog is secure i.e. if the request arrived over TLS, and the Request-URI contained a SIPS URI, the "secure" flag is set to TRUE.
boolean	isServer() Return true if is server.
void	printTags() Debugging print for the dialog.
void	resendAck() Resend the last ack.
void	sendAck(Request request) Sends ACK Request to the remote party of this Dialogue.
void	sendRequest(ClientTransaction clientTransactionId) Sends a Request to the remote party of this dialog.
void	setApplicationData(Object applicationData) Set ptr to app data.
void	setDefaultRoute(Route defaultRoute) Set the default route (the default next hop for the proxy or the proxy address for the user agent).
void	setDialogId(String dialogId) Set the dialog identifier.
void	setLocalTag(String mytag) Set local tag for the transaction.
void	setRemoteTag(String hisTag) Set the remote tag.
void	setStack(SIPTransactionStack sipStack) Set the stack address.
void	setState(int state) Set the state for this dialog.
void	setUser(String user) Set the user name for the default route.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EARLY_STATE

public static final int EARLY_STATE

See Also:

Constant Field Values

CONFIRMED_STATE

public static final int CONFIRMED_STATE

See Also:

Constant Field Values

COMPLETED_STATE

public static final int COMPLETED_STATE

See Also:

Constant Field Values

TERMINATED_STATE

public static final int TERMINATED_STATE

See Also:

Constant Field Values

Method Detail

setApplicationData

public void setApplicationData(Object applicationData)

Set ptr to app data.

Specified by:

setApplicationData in interface Dialog

Parameters:

applicationData - the new object containing application specific data.

getApplicationData

public Object getApplicationData()

Get ptr to opaque application data.

Specified by:

getApplicationData in interface Dialog

Returns:

the object representation of the application specific data.

getNextHop

public HopImpl getNextHop()
                   throws SipException

Get the next hop to which requests in the dialog will be routed to.

Returns:

the next hop to which to send the outbound request.

Throws:

SipException

isClientDialog

public boolean isClientDialog()

Return true if this is a client dialog.

Returns:

true if the transaction that created this dialog is a client transaction and false otherwise.

setState

public void setState(int state)

Set the state for this dialog.

Parameters:

state - is the state to set for the dialog.

printTags

public void printTags()

Debugging print for the dialog.

ackReceived

public void ackReceived(gov.nist.javax.sip.message.SIPRequest sipRequest)

Mark that the dialog has seen an ACK.

getFirstTransaction

public Transaction getFirstTransaction()

Get the transaction that created this dialog.

Specified by:

getFirstTransaction in interface Dialog

Returns:

the Transaction that created the Dialog.

getRouteSet

public Iterator getRouteSet()

Gets the route set for the dialog. When acting as an User Agent Server the route set MUST be set to the list of URIs in the Record-Route header field from the request, taken in order and preserving all URI parameters. When acting as an User Agent Client the route set MUST be set to the list of URIs in the Record-Route header field from the response, taken in reverse order and preserving all URI parameters. If no Record-Route header field is present in the request or response, the route set MUST be set to the empty set. This route set, even if empty, overrides any pre-existing route set for future requests in this dialog.

Requests within a dialog MAY contain Record-Route and Contact header fields. However, these requests do not cause the dialog's route set to be modified.

The User Agent Client uses the remote target and route set to build the Request-URI and Route header field of the request.

Specified by:

getRouteSet in interface Dialog

Returns:

an Iterator containing a list of route headers to be used for forwarding. Empty iterator is returned if route has not been established.

setStack

public void setStack(SIPTransactionStack sipStack)

Set the stack address. Prevent us from routing messages to ourselves.

setDefaultRoute

public void setDefaultRoute(Route defaultRoute)

Set the default route (the default next hop for the proxy or the proxy address for the user agent).

Parameters:

defaultRoute - is the default route to set.

setUser

public void setUser(String user)

Set the user name for the default route.

Parameters:

user - is the user name to set for the default route.

addRoute

public void addRoute(gov.nist.javax.sip.message.SIPMessage sipMessage)

Extract the route information from this SIP Message and add the relevant information to the route set.

Parameters:

sipMessage - is the SIP message for which we want to add the route.

setDialogId

public void setDialogId(String dialogId)

Set the dialog identifier.

isServer

public boolean isServer()

Return true if is server.

Specified by:

isServer in interface Dialog

Returns:

true if is server transaction created this dialog.

getDialogId

public String getDialogId()

Get the id for this dialog.

Specified by:

getDialogId in interface Dialog

Returns:

the string identifier for this dialog.

addTransaction

public void addTransaction(SIPTransaction transaction)

Add a transaction record to the dialog.

Parameters:

transaction - is the transaction to add to the dialog.

setRemoteTag

public void setRemoteTag(String hisTag)

Set the remote tag.

Parameters:

hisTag - is the remote tag to set.

getLastTransaction

public SIPTransaction getLastTransaction()

Get the last transaction from the dialog.

incrementLocalSequenceNumber

public void incrementLocalSequenceNumber()

Increment the local CSeq # for the dialog. This is useful for if you want to create a hole in the sequence number i.e. route a request outside the dialog and then resume within the dialog.

Specified by:

incrementLocalSequenceNumber in interface Dialog

getRemoteSequenceNumber

public int getRemoteSequenceNumber()

Get the remote sequence number (for cseq assignment of outgoing requests within this dialog).

Specified by:

getRemoteSequenceNumber in interface Dialog

Returns:

local sequence number.

getLocalSequenceNumber

public int getLocalSequenceNumber()

Get the local sequence number (for cseq assignment of outgoing requests within this dialog).

Specified by:

getLocalSequenceNumber in interface Dialog

Returns:

local sequence number.

getLocalTag

public String getLocalTag()

Get local identifier for the dialog. This is used in From header tag construction for all outgoing client transaction requests for this dialog and for all outgoing responses for this dialog. This is used in To tag constuction for all outgoing transactions when we are the server of the dialog. Use this when constucting To header tags for BYE requests when we are the server of the dialog.

Specified by:

getLocalTag in interface Dialog

Returns:

the local tag.

getRemoteTag

public String getRemoteTag()

Get peer identifier identifier for the dialog. This is used in To header tag construction for all outgoing requests when we are the client of the dialog. This is used in From tag construction for all outgoing requests when we are the Server of the dialog. Use this when costructing From header Tags for BYE requests when we are the server of the dialog.

Specified by:

getRemoteTag in interface Dialog

Returns:

the remote tag (note this is read from a response to an INVITE).

setLocalTag

public void setLocalTag(String mytag)

Set local tag for the transaction.

Parameters:

mytag - is the tag to use in From headers client transactions that belong to this dialog and for generating To tags for Server transaction requests that belong to this dialog.

delete

public void delete()

This method will release all resources associated with this dialog that are tracked by the Provider. Further references to the dialog by incoming messages will result in a mismatch. Since dialog destruction is left reasonably open ended in RFC3261, this delete method is provided for future use and extension methods that do not require a BYE to terminate a dialogue. The basic case of the INVITE and all dialogues that we are aware of today it is expected that BYE requests will end the dialogue.

Specified by:

delete in interface Dialog

getCallId

public CallIdHeader getCallId()

Returns the Call-ID for this SipSession. This is the value of the Call-ID header for all messages belonging to this session.

Specified by:

getCallId in interface Dialog

Returns:

the Call-ID for this Dialogue

getLocalParty

public Address getLocalParty()

Get the local Address for this dialog.

Specified by:

getLocalParty in interface Dialog

Returns:

the address object of the local party.

getRemoteParty

public Address getRemoteParty()

Returns the Address identifying the remote party. This is the value of the To header of locally initiated requests in this dialogue when acting as an User Agent Client.

This is the value of the From header of recieved responses in this dialogue when acting as an User Agent Server.

Specified by:

getRemoteParty in interface Dialog

Returns:

the address object of the remote party.

getRemoteTarget

public Address getRemoteTarget()

Returns the Address identifying the remote target. This is the value of the Contact header of recieved Responses for Requests or refresh Requests in this dialogue when acting as an User Agent Client

This is the value of the Contact header of recieved Requests or refresh Requests in this dialogue when acting as an User Agent Server. Bug fix sent in by Steve Crossley.

Specified by:

getRemoteTarget in interface Dialog

Returns:

the address object of the remote target.

getState

public DialogState getState()

Returns the current state of the dialogue. The states are as follows:

• Early - A dialog is in the "early" state, which occurs when it is created when a provisional response is recieved to the INVITE Request.
• Confirmed - A dialog transitions to the "confirmed" state when a 2xx final response is received to the INVITE Request.
• Completed - A dialog transitions to the "completed" state when a BYE request is sent or received by the User Agent Client.
• Terminated - A dialog transitions to the "terminated" state when it can be garbage collection.

Independent of the method, if a request outside of a dialog generates a non-2xx final response, any early dialogs created through provisional responses to that request are terminated. If no response arrives at all on the early dialog, it also terminates.

Specified by:

getState in interface Dialog

Returns:

a DialogState determining the current state of the dialog.

See Also:

DialogState

isSecure

public boolean isSecure()

Returns true if this Dialog is secure i.e. if the request arrived over TLS, and the Request-URI contained a SIPS URI, the "secure" flag is set to TRUE.

Specified by:

isSecure in interface Dialog

Returns:

true if this dialogue was established using a sips URI over TLS, and false otherwise.

sendAck

public void sendAck(Request request)
             throws SipException

Sends ACK Request to the remote party of this Dialogue.

Specified by:

sendAck in interface Dialog

Parameters:

request - - the new ACK Request message to send.

Throws:

SipException - if implementation cannot send the ACK Request for any other reason

createRequest

public Request createRequest(String method)
                      throws SipException

Creates a new Request message based on the dialog creating request. This method should be used for but not limited to creating Bye's, Refer's and re-Invite's on the Dialog. The returned Request will be correctly formatted that is it will contain the correct CSeq header, Route headers and requestURI (derived from the remote target). This method should not be used for Ack, that is the application should create the Ack from the MessageFactory. If the route set is not empty, and the first URI in the route set contains the lr parameter (see Section 19.1.1), the UAC MUST place the remote target URI into the Request-URI and MUST include a Route header field containing the route set values in order, including all parameters. If the route set is not empty, and its first URI does not contain the lr parameter, the UAC MUST place the first URI from the route set into the Request-URI, stripping any parameters that are not allowed in a Request-URI. The UAC MUST add a Route header field containing the remainder of the route set values in order, including all parameters. The UAC MUST then place the remote target URI into the Route header field as the last value.

Specified by:

createRequest in interface Dialog

Parameters:

method - the string value that determines if the request to be created.

Returns:

the newly created Request message on this Dialog.

Throws:

SipException - if the Dialog is not yet established.

sendRequest

public void sendRequest(ClientTransaction clientTransactionId)
                 throws TransactionDoesNotExistException,
                        SipException

Sends a Request to the remote party of this dialog. This method implies that the application is functioning as UAC hence the underlying SipProvider acts statefully. This method is useful for sending Bye's for terminating a dialog or Re-Invites on the Dialog for third party call control.

This methods will set the From and the To tags for the outgoing request and also set the correct sequence number to the outgoing Request and associate the client transaction with this dialog. Note that any tags assigned by the user will be over-written by this method.

The User Agent must not send a BYE on a confirmed INVITE until it has received an ACK for its 2xx response or until the server transaction timeout is received.

When the retransmissionFilter is true, that is the SipProvider takes care of all retransmissions for the application, and the SipProvider can not deliver the Request after multiple retransmits the SipListener will be notified with a TimeoutEvent when the transaction expires.

Specified by:

sendRequest in interface Dialog

Parameters:

clientTransactionId - - the new ClientTransaction object identifying this transaction, this clientTransaction should be requested from SipProvider.getNewClientTransaction(Request)

Throws:

TransactionDoesNotExistException - if the serverTransaction does not correspond to any existing server transaction.

SipException - if implementation cannot send the Request for any reason.

resendAck

public void resendAck()
               throws SipException

Resend the last ack.

Throws:

SipException