NIST SIP Parser and Stack (v1.2) API

gov.nist.javax.sip.stack
Class DialogImpl

java.lang.Object
  |
  +--gov.nist.javax.sip.stack.DialogImpl
All Implemented Interfaces:
Dialog

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.

Version:
JAIN-SIP-1.1
Author:
M. Ranganathan
This code is in the public domain.

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(Route route, boolean top)
          Add a route to the dialog.
 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.
 void delete()
          This method will release all resources associated with this dialog that are tracked by the Provider.
 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.
 GenericURI getOriginalRequestURI()
          Generate a request URI from the top of the route list.
 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.
 String getUser()
          Get the user name for the dialog.
 int incrementLocalSequenceNumber()
          Increment the local CSeq # for the dialog.
 int incrementRemoteSequenceNumber()
          Increment the Remote 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.
 boolean recordRouteEnabled()
          Return true if record routing is enabled for this dialog
 void sendAck(Request request)
          Sends ACK Request to the remote party of this Dialogue.
 void sendRequest(ClientTransaction clientTransactionId, Request dialogRequest)
          Sends a Request to the remote party of this dialog.
 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

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.

recordRouteEnabled

public boolean recordRouteEnabled()
Return true if record routing is enabled for this dialog


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. This is the first dialog that is not cancelled on the list of transactions managed by this dialog. This depends on the tag assignment.

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.


addRoute

public void addRoute(Route route,
                     boolean top)
Add a route to the dialog.

Parameters:
route - is the route to add to the dialog.

getOriginalRequestURI

public GenericURI getOriginalRequestURI()
Generate a request URI from the top of the route list.

Returns:
a request uri generated from the top of the route list.

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.


getUser

public String getUser()
Get the user name for the dialog.


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.


incrementRemoteSequenceNumber

public int incrementRemoteSequenceNumber()
Increment the Remote cseq # for the dialog.

Returns:
the incremented remote sequence number.

incrementLocalSequenceNumber

public int incrementLocalSequenceNumber()
Increment the local CSeq # for the dialog.

Returns:
the incremented local sequence number.

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.

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: 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. This method implies that the application is functioning as User Agent Client hence the underlying SipProvider acts statefully. This method should only be used for an INVITE transactions, all ACK's to non-INVITE transactions should use the SipProviderImpl.sendRequest(ClientTransaction, Request) method.

When the SipStackImpl.getRetransmissionFilter() is true, that is the SipProvider takes care of all retransmissions for the application, if the the SipProvider can not deliver the Request after multiple retransmits due to the transaction expiring the SipListener will be notified with a TimeoutEvent.

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

sendRequest

public void sendRequest(ClientTransaction clientTransactionId,
                        Request dialogRequest)
                 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 SipStack.getRetransmissionFilter() 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:
dialogRequest - - the new Request message to send.
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.

NIST SIP Parser and Stack (v1.2) API

A product of the NIST/ITL Advanced Networking Technologies Division.
See conditions of use.
Get the latest distribution.
Submit a bug report or feature request.