gov.nist.javax.sip.stack
Class SIPClientTransaction

java.lang.Object
  gov.nist.javax.sip.stack.MessageChannel
      gov.nist.javax.sip.stack.SIPTransaction
          gov.nist.javax.sip.stack.SIPClientTransaction

All Implemented Interfaces:

ClientTransaction, Serializable, ServerResponseInterface, Transaction

public class SIPClientTransaction

extends SIPTransaction

implements ServerResponseInterface, ClientTransaction

Represents a client transaction. Implements the following state machines. (From RFC 3261)

                
                 
                  
                   
                   
                   
                                                  |INVITE from TU
                                Timer A fires     |INVITE sent
                                Reset A,          V                      Timer B fires
                                INVITE sent +-----------+                or Transport Err.
                                  +---------|           |---------------+inform TU
                                  |         |  Calling  |               |
                                  +-------->|           |-------------->|
                                            +-----------+ 2xx           |
                                               |  |       2xx to TU     |
                                               |  |1xx                  |
                       300-699 +---------------+  |1xx to TU            |
                      ACK sent |                  |                     |
                   resp. to TU |  1xx             V                     |
                               |  1xx to TU  -----------+               |
                               |  +---------|           |               |
                               |  |         |Proceeding |-------------->|
                               |  +-------->|           | 2xx           |
                               |            +-----------+ 2xx to TU     |
                               |       300-699    |                     |
                               |       ACK sent,  |                     |
                               |       resp. to TU|                     |
                               |                  |                     |      NOTE:
                               |  300-699         V                     |
                               |  ACK sent  +-----------+Transport Err. |  transitions
                               |  +---------|           |Inform TU      |  labeled with
                               |  |         | Completed |-------------->|  the event
                               |  +-------->|           |               |  over the action
                               |            +-----------+               |  to take
                               |              ˆ   |                     |
                               |              |   | Timer D fires       |
                               +--------------+   | -                   |
                                                  |                     |
                                                  V                     |
                                            +-----------+               |
                                            |           |               |
                                            | Terminated|<--------------+
                                            |           |
                                            +-----------+
                   
                                    Figure 5: INVITE client transaction
                   
                   
                                                      |Request from TU
                                                      |send request
                                  Timer E             V
                                  send request  +-----------+
                                      +---------|           |-------------------+
                                      |         |  Trying   |  Timer F          |
                                      +-------->|           |  or Transport Err.|
                                                +-----------+  inform TU        |
                                   200-699         |  |                         |
                                   resp. to TU     |  |1xx                      |
                                   +---------------+  |resp. to TU              |
                                   |                  |                         |
                                   |   Timer E        V       Timer F           |
                                   |   send req +-----------+ or Transport Err. |
                                   |  +---------|           | inform TU         |
                                   |  |         |Proceeding |------------------>|
                                   |  +-------->|           |-----+             |
                                   |            +-----------+     |1xx          |
                                   |              |      ˆ        |resp to TU   |
                                   | 200-699      |      +--------+             |
                                   | resp. to TU  |                             |
                                   |              |                             |
                                   |              V                             |
                                   |            +-----------+                   |
                                   |            |           |                   |
                                   |            | Completed |                   |
                                   |            |           |                   |
                                   |            +-----------+                   |
                                   |              ˆ   |                         |
                                   |              |   | Timer K                 |
                                   +--------------+   | -                       |
                                                      |                         |
                                                      V                         |
                                NOTE:           +-----------+                   |
                                                |           |                   |
                            transitions         | Terminated|<------------------+
                            labeled with        |           |
                            the event           +-----------+
                            over the action
                            to take
                   
                                    Figure 6: non-INVITE client transaction
                   
                   
                   
                   
                  
                 
 

Version:

1.2 $Revision: 1.57 $ $Date: 2006/10/11 17:57:53 $

Author:

M. Ranganathan

See Also:

Serialized Form

Nested Class Summary

class

SIPClientTransaction.TransactionTimer

Field Summary

Fields inherited from class gov.nist.javax.sip.stack.SIPTransaction

CALLING_STATE, COMPLETED_STATE, CONFIRMED_STATE, INITIAL_STATE, PROCEEDING_STATE, TERMINATED_STATE, TRYING_STATE

Method Summary

void	clearState() This is called by the stack after a non-invite client transaction goes to completed state.
Request	createAck() Creates a new Ack message from the Request associated with this client transaction.
Request	createCancel() Creates a new Cancel message from the Request associated with this client transaction.
SIPDialog	getDefaultDialog()
Dialog	getDialog() Gets the dialog object of this transaction object.
SIPDialog	getDialog(String dialogId)
Hop	getNextHop() Reeturn the previously computed next hop (avoid computing it twice).
Via	getOutgoingViaHeader() get the via header for an outgoing request.
MessageChannel	getRequestChannel() Returns this transaction.
String	getViaHost() Get the host of the recipient.
int	getViaPort() Get the port of the recipient.
boolean	isMessagePartOfTransaction(SIPMessage messageToTest) Deterines if the message is a part of this transaction.
void	processResponse(SIPResponse sipResponse, MessageChannel incomingChannel) This method is called prior to dialog assignment.
void	processResponse(SIPResponse transactionResponse, MessageChannel sourceChannel, SIPDialog dialog) Process a new response message through this transaction.
void	sendMessage(SIPMessage messageToSend) Send a request message through this transaction and onto the client.
void	sendRequest() Sends the Request which created this ClientTransaction.
void	setDialog(SIPDialog sipDialog, String dialogId) set the dialog object.
void	setNextHop(Hop hop) Set the next hop ( if it has already been computed).
void	setResponseInterface(ServerResponseInterface newRespondTo) Sets the real ResponseInterface this transaction encapsulates.
void	setState(TransactionState newState) Sets a timeout after which the connection is closed (provided the server does not use the connection for outgoing requests in this time period) and calls the superclass to set state.
void	terminate() Terminate this transaction and immediately release all stack resources associated with it.

Methods inherited from class gov.nist.javax.sip.stack.SIPTransaction

acquireSem, addEventListener, close, doesCancelMatchTransaction, getApplicationData, getBranch, getBranchId, getCSeq, getHost, getKey, getLastResponse, getMessageChannel, getMessageProcessor, getMethod, getOriginalRequest, getPeerAddress, getPeerPacketSourceAddress, getPeerPacketSourcePort, getPeerPort, getPort, getRequest, getResponse, getRetransmitTimer, getSipProvider, getSIPStack, getState, getTransactionId, getTransport, getViaHeader, hashCode, isByeTransaction, isCancelTransaction, isInviteTransaction, isReliable, isSecure, isTerminated, passToListener, raiseIOExceptionEvent, releaseSem, removeEventListener, setApplicationData, setBranch, setEncapsulatedChannel, setOriginalRequest, setPassToListener, setRetransmitTimer

Methods inherited from class gov.nist.javax.sip.stack.MessageChannel

getHostPort, getKey, getKey, getPeerHostPort, getRawIpSourceAddress, getViaHostPort, logResponse, sendMessage

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.sip.Transaction

getApplicationData, getBranchId, getRequest, getRetransmitTimer, getState, setApplicationData, setRetransmitTimer

Method Detail

setResponseInterface

public void setResponseInterface(ServerResponseInterface newRespondTo)

Sets the real ResponseInterface this transaction encapsulates.

Parameters:

newRespondTo - ResponseInterface to send messages to.

getRequestChannel

public MessageChannel getRequestChannel()

Returns this transaction.

isMessagePartOfTransaction

public boolean isMessagePartOfTransaction(SIPMessage messageToTest)

Deterines if the message is a part of this transaction.

Specified by:

isMessagePartOfTransaction in class SIPTransaction

Parameters:

messageToTest - Message to check if it is part of this transaction.

Returns:

True if the message is part of this transaction, false if not.

sendMessage

public void sendMessage(SIPMessage messageToSend)
                 throws IOException

Send a request message through this transaction and onto the client.

Overrides:

sendMessage in class SIPTransaction

Parameters:

messageToSend - Request to process and send.

Throws:

IOException

processResponse

public void processResponse(SIPResponse transactionResponse,
                            MessageChannel sourceChannel,
                            SIPDialog dialog)

Process a new response message through this transaction. If necessary, this message will also be passed onto the TU.

Specified by:

processResponse in interface ServerResponseInterface

Parameters:

transactionResponse - Response to process.

sourceChannel - Channel that received this message.

dialog - -- dialog for this response

sendRequest

public void sendRequest()
                 throws SipException

Description copied from interface: ClientTransaction

Sends the Request which created this ClientTransaction. When an application wishes to send a Request message, it creates a Request from the MessageFactory and then creates a new ClientTransaction from SipProvider.getNewClientTransaction(Request). Calling this method on the ClientTransaction sends the Request onto the network. The Request message gets sent via the ListeningPoint information of the SipProvider that is associated to this ClientTransaction.

This method assumes that the Request is sent out of Dialog. It uses the Router to determine the next hop. If the Router returns a empty iterator, and a Dialog is associated with the outgoing request of the Transaction then the Dialog route set is used to send the outgoing request.

This method implies that the application is functioning as either a UAC or a stateful proxy, hence the underlying implementation acts statefully.

Specified by:

sendRequest in interface ClientTransaction

Throws:

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

See Also:

Request

createCancel

public Request createCancel()
                     throws SipException

Description copied from interface: ClientTransaction

Creates a new Cancel message from the Request associated with this client transaction. The CANCEL request, is used to cancel the previous request sent by this client transaction. Specifically, it asks the UAS to cease processing the request and to generate an error response to that request. A CANCEL request constitutes its own transaction, but also references the transaction to be cancelled. CANCEL has no effect on a request to which a UAS has already given a final response.

Note that both the transaction corresponding to the original request and the CANCEL transaction will complete independently. However, a UAC canceling a request cannot rely on receiving a 487 (Request Terminated) response for the original request, as an RFC 2543 compliant UAS will not generate such a response. Therefore if there is no final response for the original request the application will receieve a TimeoutEvent with Timeout.TRANSACTION and the client should then consider the original transaction cancelled.

• UAC - A UAC should not send a CANCEL request to any request explicitly supported by this specification other than INVITE request. The reason being requests other than INVITE are responded to immediately and sending a CANCEL for a non-INVITE request would always create a race condition. CANCELs are useful as a UAC can not send a BYE request on a dialog until receipt of 2xx final response to the INVITE request. The CANCEL attempts to force a non-2xx response to the INVITE, therefore if a UAC wishes to give up on its call attempt entirely it can send a CANCEL.
• Stateful proxies - A stateful proxy may generate CANCEL requests for:
  • INVITE Requests - A CANCEL can be sent on pending INVITE client transactions based on the period specified in the INVITE's Expires header field elapsing. However, this is generally unnecessary since the endpoints involved will take care of signaling the end of the transaction.
  • Other Requests - An implementation of this specification does not need to support CANCELing non-INVITE transactions.

Specified by:

createCancel in interface ClientTransaction

Returns:

the new cancel Request specific to the Request of this client transaction.

Throws:

SipException - if this method is called to cancel a request that can't be cancelled i.e. ACK.

createAck

public Request createAck()
                  throws SipException

Description copied from interface: ClientTransaction

Creates a new Ack message from the Request associated with this client transaction. This ACK can be used to acknowledge the 2xx response to the request sent by this transaction.

Specified by:

createAck in interface ClientTransaction

Returns:

the new ACK Request specific to the Request of this client transaction.

Throws:

SipException - if this method is called before a final response is received for the transaction.

getViaPort

public int getViaPort()

Get the port of the recipient.

Overrides:

getViaPort in class SIPTransaction

getViaHost

public String getViaHost()

Get the host of the recipient.

Overrides:

getViaHost in class SIPTransaction

getOutgoingViaHeader

public Via getOutgoingViaHeader()

get the via header for an outgoing request.

clearState

public void clearState()

This is called by the stack after a non-invite client transaction goes to completed state.

setState

public void setState(TransactionState newState)

Sets a timeout after which the connection is closed (provided the server does not use the connection for outgoing requests in this time period) and calls the superclass to set state.

Overrides:

setState in class SIPTransaction

Parameters:

newState - New state of this transaction.

terminate

public void terminate()
               throws ObjectInUseException

Description copied from interface: Transaction

Terminate this transaction and immediately release all stack resources associated with it. When a transaction is terminated using this method, a transaction terminated event is sent to the listener. If the transaction is already associated with a dialog, it cannot be terminated using this method. Instead, the dialog should be deleted to remove the transaction.

Specified by:

terminate in interface Transaction

Throws:

ObjectInUseException - if the transaction cannot be terminated as it is associated to a dialog.

processResponse

public void processResponse(SIPResponse sipResponse,
                            MessageChannel incomingChannel)

Description copied from interface: ServerResponseInterface

This method is called prior to dialog assignment.

Specified by:

processResponse in interface ServerResponseInterface

Parameters:

sipResponse -

incomingChannel -

getDialog

public Dialog getDialog()

Description copied from interface: Transaction

Gets the dialog object of this transaction object. A dialog only exists for a transaction when a session is setup between a User Agent Client and a User Agent Server, either by a 1xx Provisional Response for an early dialog or a 200OK Response for a committed dialog.

• If the stack is configured with the AUTOMATIC_DIALOG_SUPPORT property set to ON ( default behavior ) then the following behavior is defined:
  • If the transaction is associated with an existing Dialog or could result in a Dialog being created in the future (ie. the stack is configured to recognize the method as a Dialog creating method or is one of the natively supported dialog creating methods such as INVITE, SUBSCRIBE or REFER), then the implementation must either associate the transaction with the existing Dialog or create a Dialog with null state.
  • If the Transaction is neither dialog creating nor can be associated with an existing dialog, then the implementation must return null when the application issues getDialog on the transaction.
• If the stack is configured with AUTOMATIC_DIALOG property set to OFF then the stack does not automatically create a Dialog for a transaction nor does it maintain an association between dialog and transaction on behalf of the application. Hence this method will return null. It is the responsibility of the application to create a Dialog and associate it with the transaction when the response is sent.

Specified by:

getDialog in interface Transaction

Specified by:

getDialog in class SIPTransaction

Returns:

the Dialog Object of this Transaction object.

See Also:

Dialog

getDialog

public SIPDialog getDialog(String dialogId)

setDialog

public void setDialog(SIPDialog sipDialog,
                      String dialogId)

Description copied from class: SIPTransaction

set the dialog object.

Specified by:

setDialog in class SIPTransaction

Parameters:

sipDialog - -- the dialog to set.

dialogId - -- the dialog id ot associate with the dialog.s

getDefaultDialog

public SIPDialog getDefaultDialog()

setNextHop

public void setNextHop(Hop hop)

Set the next hop ( if it has already been computed).

Parameters:

hop - -- the hop that has been previously computed.

getNextHop

public Hop getNextHop()

Reeturn the previously computed next hop (avoid computing it twice).

Returns:

-- next hop previously computed.