NIST-SIP: The Reference Implementation for JAIN-SIP 1.2

gov.nist.javax.sip.stack
Class SIPClientTransaction

java.lang.Object
  extended by gov.nist.javax.sip.stack.MessageChannel
      extended by gov.nist.javax.sip.stack.SIPTransaction
          extended by gov.nist.javax.sip.stack.SIPClientTransaction
All Implemented Interfaces:
ClientTransactionExt, ServerResponseInterface, TransactionExt, Serializable, ClientTransaction, Transaction

public class SIPClientTransaction
extends SIPTransaction
implements ServerResponseInterface, ClientTransaction, ClientTransactionExt

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.107 $ $Date: 2009/08/04 22:07:07 $
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
auditTag, CALLING_STATE, COMPLETED_STATE, CONFIRMED_STATE, INITIAL_STATE, PROCEEDING_STATE, TERMINATED_STATE, TRYING_STATE
 
Method Summary
 void alertIfStillInCallingStateBy(int count)
          Send a transaction timeout event to the application if Tx is still in Calling state in the given time period ( in base timer interval count ) after sending request.
 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.
 boolean isNotifyOnRetransmit()
           
 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 setNotifyOnRetransmit(boolean notifyOnRetransmit)
          Set this flag if you want your Listener to get Timeout.RETRANSMIT notifications each time a retransmission occurs.
 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, 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.

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

getDialog

public Dialog getDialog()
Description copied from class: SIPTransaction
Gets the dialog object of this Transaction object. This object returns null if no dialog exists. 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.

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).

Specified by:
getNextHop in interface ClientTransactionExt
Returns:
-- next hop previously computed.

setNotifyOnRetransmit

public void setNotifyOnRetransmit(boolean notifyOnRetransmit)
Set this flag if you want your Listener to get Timeout.RETRANSMIT notifications each time a retransmission occurs.

Specified by:
setNotifyOnRetransmit in interface ClientTransactionExt
Parameters:
notifyOnRetransmit - the notifyOnRetransmit to set

isNotifyOnRetransmit

public boolean isNotifyOnRetransmit()
Returns:
the notifyOnRetransmit

alertIfStillInCallingStateBy

public void alertIfStillInCallingStateBy(int count)
Description copied from interface: ClientTransactionExt
Send a transaction timeout event to the application if Tx is still in Calling state in the given time period ( in base timer interval count ) after sending request. The stack will start a timer and alert the application if the client transaction does not transition out of the Trying state by the given interval. This is a "one shot" alert.

Specified by:
alertIfStillInCallingStateBy in interface ClientTransactionExt
Parameters:
count - -- the number of base timer intervals after which an alert is issued.

NIST-SIP: The Reference Implementation for JAIN-SIP 1.2

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