Java Doc for Dialog.java in  » 6.0-JDK-Modules » Java-Advanced-Imaging » javax » sip » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A dialog is identified at each User Agent with a dialog Id, which consists of a Call-Id value, a local tag and a remote tag. The dialog Id at each User Agent involved in the dialog is not the same. Specifically, the local tag at one User Agent is identical to the remote tag at the peer User Agent. The tags are opaque tokens that facilitate the generation of unique dialog Ids.

A dialog contains certain pieces of data needed for further message transmissions within the dialog. This data consists of:

• Dialog Id - used to identify the dialog.
• Local sequence number - used to order requests from the User Agent to its peer.
• Remote sequence number - used to order requests from its peer to the User Agent.
• Local URI - the address of the local party.
• Remote URI - the address of the remote party.
• Remote target - the address from the Contact header field of the request or response or refresh request or response.
• "secure" boolean - determines if the dialog is secure i.e. use the sips: scheme.
• Route set - an ordered list of URIs. The route set is the list of servers that need to be traversed to send a request to the peer.

Invite Dialog States:
Null --> Early --> Confirmed --> Terminated

Other Dialog-creating Requests Dialog States (ie. SUBSCRIBE):
Null --> Confirmed --> Terminated.

The Listener MUST ACK the 2xx response associated with an INVITE dialog. Retransmissions of the ACK in response to subsequent INVITE requests are handled by the dialog layer. If a listener does not ACK a 2XX response immediately, the implementation will terminate the Dialog automatically and remove it from the stack when the listener completes its execution.

The dialog layer MUST respond with an automatic error response when RFC3261 specifies that the User Agent MUST respond with a certain error. This does not apply for successful responses like 200 OK. The error condition relates directly to the dialog layer and the SipListener can add no meaningful information to the response. Such a response can be constructed and sent entirely by the dialog layer on behalf of the SipListener. Under such circumstances, it makes sense to let the dialog support handle the response and not bother the SipListener with it. The SipListener will not be notified with the RequestEvent upon which the Response was sent on its behalf by the Dialog layer. However, if no Dialog is registered for the transaction either automatically or under application control, then the SipListener is expected to generate and send the appropriate (error) response.

For example: In RFC3261 Chapter 14 a User Agent Server that receives a second INVITE before it sends the final response to a first INVITE with a lower CSeq sequence number on the same dialog MUST return a 500 (Server Internal Error) response to the second INVITE and MUST include a Retry-After header field with a randomly chosen value of between 0 and 10 seconds. In this release of this specification, the implementation handles retransmissions of Responses that are specified as being handled by the UA core, if there is an associated Dialog for a given transaction. If there is no associated Dialog for a given transaction, the application will be alerted to perform the retransmissions required by the UA core if desired. Applications should explicitly request such alerts see ServerTransaction.enableRetransmissionAlerts . Once enabled the SipProvider will deliver retransmission timer events to the Listener with a Timeout.RETRANSMIT notification. The SipListener can then retransmit the Response as necessary, see SipListener.processTimeout(TimeoutEvent) .

For INVITE Client Transactions:

• UAC ACKs first 2xx response
• Additional 2xx responses will be ACKed automatically if a Dialog is asssociated with the response
• Additional 2xx responses will be presented to the listener if no dialog is associated with the response. In such a case the listener is expected to ACK the 2xx response.

• Application sends first 2xx response ServerTransaction.sendResponse(Response) .
• If a Dialog is not associated with a ServerTransaction, and if the application explicitly requests to be notified of such timeouts (see ServerTransaction.enableRetransmissionAlerts the SipListener is periodically alerted to retransmit 2xx responses for the ServerTransaction.
• If a Dialog is associated with a ServerTransaction then the implementation takes care of retransmitting final responses until the ACK is received i.e. the SipListener will receive no notifications to retransmit responses.

• Either the application or the dialog layer sends the first response
• Retransmissions of 300-699 responses from the INVITE Server Transaction are handled by the transaction layer independent of existence of an associated Dialog.

• The application sends a reliable provisional Response to an Invite Dialog using javax.sip.Dialog.sendReliableProvisionalResponse(Response)
• The Stack takes care of retransmitting the provisional response with exponentially increasing intervals until a PRACK is received or the Transaction times out.

Multiple 2xx responses may arrive at the UAC for a single INVITE request due to a forking proxy. Each response is distinguished by the tag parameter in the TO header field, and each represents a distinct Dialog, with a distinct Dialog identifier. In this case the first 2xx terminates the original INVITE additional 2xx responses will be presented to the SipListener as a ResponseEvent with null Client Transaction ID but with a valid and distinct Dialog. The Listener is expected to ACK the 2xx response - otherwise the Dialog is terminated after a timeout period. Note that unless automatic dialog creation is explictly disabled, the 2xx ResponseEvent will always contain a Dialog whether or not the outgoing INVITE was sent through a ClientTransaction or statelessly via a SipProvider.
author:
   BEA Systems, NIST
version:
   1.2

• RequestURI
• FromHeader
• ToHeader
• CallIdHeader
• RouteHeaders
• RAckHeader

All other headers including any Authentication related headers, and record route headers should be assigned by the application to the generated request. The assignment of the topmost via header for the outgoing request may be deferred until the application creates a ClientTransaction to send the request out. This method does not increment the dialog sequence number.
Parameters:
  relResponse - the reliable provisional response that should result in aprack reques. the newly created Request message on this Dialog.
throws:
  SipException - if the Method of the transaction that created the Dialog orRefeshing the Dialog is not an INVITE ( for exampleSUBSCRIBE).
throws:
  DialogDoesNotExistException - if the Dialog is not yet established (i.e. dialog stateequals null) or is terminated.
since:
   1.2

• RequireHeader
• RSeqHeader

since:
   1.2
Parameters:
  statusCode - the new integer of the statusCode value of this Message. the newly created Response object.
throws:
  InvalidArgumentException - when an invalid status code or request method is supplied.
throws:
  SipException - when the Dialog is not a server dialog or if thismethod is called after a final response is sent to theServerTransactin that created the Dialog.

• RequestURI
• FromHeader
• ToHeader
• CallIdHeader
• RouteHeaders

All other headers including any Authentication related headers, and record route headers should be assigned by the application to the generated request. The assignment of the topmost via header for the outgoing request may be deferred until the application creates a ClientTransaction to send the request out. This method does not increment the dialog sequence number. This method may not be used for creating PRACK or ACK. Implementations should throw SipException if this method is called for creating ACK or PRACK.
Parameters:
  method - the string value that determines if the request to be created. the newly created Request message on this Dialog.
throws:
  SipException - if the Dialog is not yet established (i.e. dialog stateequals null) or is terminated or if the method is invoked forACK or PRACK.

• User Agent Client - the Call-Id value of the dialog Id is set to the Call-Id of the message, the remote tag is set to the tag in the To field of the message, and the local tag is set to the tag in the From field of the message.
• User Agent Server - the Call-Id value of the dialog Id is set to the Call-Id of the message, the remote tag is set to the tag in the From field of the message, and the local tag is set to the tag in the To field of the message.

This is the value of the To header of received responses in this dialog when acting as an User Agent Server. the address object of the local party.

Requests within a dialog MUST contain strictly monotonically increasing and contiguous CSeq sequence numbers (increasing-by-one) in each direction (excepting ACK and CANCEL, whose numbers equal the requests being acknowledged or cancelled). Therefore, if the local sequence number is not empty, the value of the local sequence number MUST be incremented by one, and this value MUST be placed into the CSeq header field. If the local sequence number is empty, an initial value MUST be chosen. the value of the local sequence number, returns zero ifnot set.
since:
   v1.2

Requests within a dialog MUST contain strictly monotonically increasing and contiguous CSeq sequence numbers (increasing-by-one) in each direction (excepting ACK and CANCEL, whose numbers equal the requests being acknowledged or cancelled). Therefore, if the local sequence number is not empty, the value of the local sequence number MUST be incremented by one, and this value MUST be placed into the CSeq header field. If the local sequence number is empty, an initial value MUST be chosen. Dialog.getLocalSeqNumber()
See Also:   Dialog.getLocalSeqNumber() the integer value of the local sequence number, returns zero ifnot set.

This is the value of the From header of recieved responses in this dialog when acting as an User Agent Server. the address object of the remote party.

If the remote sequence number is empty, it MUST be set to the value of the sequence number in the CSeq header field value in the request. If the remote sequence number was not empty, but the sequence number of the request is lower than the remote sequence number, the request is out of order and MUST be rejected with a 500 (Server Internal Error) response. If the remote sequence number was not empty, and the sequence number of the request is greater than the remote sequence number, the request is in order. the value of the remote sequence number, return zero ifnot set.
since:
   v1.2

If the remote sequence number is empty, it MUST be set to the value of the sequence number in the CSeq header field value in the request. If the remote sequence number was not empty, but the sequence number of the request is lower than the remote sequence number, the request is out of order and MUST be rejected with a 500 (Server Internal Error) response. If the remote sequence number was not empty, and the sequence number of the request is greater than the remote sequence number, the request is in order. Dialog.getRemoteSeqNumber()
See Also:   Dialog.getRemoteSeqNumber() the integer value of the remote sequence number, return zero ifnot set.

This is the value of the Contact header of received target refresh Requests Requests in this dialog when acting as an User Agent Server. the address object of the remote target.

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. an Iterator over a list of route headers to be used forforwarding.

• 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.
• Terminated - A dialog transitions to the "terminated" state for all other reasons or if no response arrives at all on the dialog.

• Null - refers to a state that is not terminated.
• Terminated - when the Application deletes the Dialog or if no response arrives at all.

since:
   1.2
Parameters:
  relResponse - -the reliable provisional response
throws:
  SipException - if implementation cannot send the Request for any reason(e.g. because another reliable response is still pending).

This method implies that the application is functioning as UAC hence the underlying SipProvider acts statefully. This method is useful for sending Bye's to terminate a dialog or Re-Invites/Refers on the Dialog for third party call control, call hold etc.

This method will set the From and the To tags for the outgoing request. This method increments the dialog sequence number and sets the correct sequence number to the outgoing Request and associates the client transaction with this dialog. Note that any tags assigned by the user will be over-written by this method. If the caller sets no RouteHeader in the Request to be sent out, the implementation of this method will add the RouteHeader from the routes that are mantained in the dialog. If the caller sets the RouteHeader's, the implementation will leave the route headers unaltered. This allows the application to manage its own route set if so desired.

The User Agent traditionally 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.

A Dialog may be created by an INVITE request and subsequently SUBSCRIBE/NOTIFY are sent withing that Dialog. In this case the application may call Dialog.terminateOnBye to prevent the Dialog from Terminating upon reciept of a BYE.
Parameters:
  clientTransaction - -the new ClientTransaction object identifying this transaction,this clientTransaction should be requested fromSipProvider.getNewClientTransaction(Request)
throws:
  TransactionDoesNotExistException - if the clientTransaction does not correspond to any existingclient transaction.
throws:
  SipException - if implementation cannot send the Request for any reason.