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

gov.nist.javax.sip.stack
Class SIPServerTransaction

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.SIPServerTransaction
All Implemented Interfaces:
ServerTransactionExt, ServerRequestInterface, TransactionExt, Serializable, ServerTransaction, Transaction

public class SIPServerTransaction
extends SIPTransaction
implements ServerRequestInterface, ServerTransaction, ServerTransactionExt

Represents a server transaction. Implements the following state machines.




                                                                      |INVITE
                                                                      |pass INV to TU
                                                   INVITE             V send 100 if TU won't in 200ms
                                                   send response+-----------+
                                                       +--------|           |--------+101-199 from TU
                                                       |        | Proceeding|        |send response
                                                       +------->|           |<-------+
                                                                |           |          Transport Err.
                                                                |           |          Inform TU
                                                                |           |--------------->+
                                                                +-----------+                |
                                                   300-699 from TU |     |2xx from TU        |
                                                   send response   |     |send response      |
                                                                   |     +------------------>+
                                                                   |                         |
                                                   INVITE          V          Timer G fires  |
                                                   send response+-----------+ send response  |
                                                       +--------|           |--------+       |
                                                       |        | Completed |        |       |
                                                       +------->|           |<-------+       |
                                                                +-----------+                |
                                                                   |     |                   |
                                                               ACK |     |                   |
                                                               -   |     +------------------>+
                                                                   |        Timer H fires    |
                                                                   V        or Transport Err.|
                                                                +-----------+  Inform TU     |
                                                                |           |                |
                                                                | Confirmed |                |
                                                                |           |                |
                                                                +-----------+                |
                                                                      |                      |
                                                                      |Timer I fires         |
                                                                      |-                     |
                                                                      |                      |
                                                                      V                      |
                                                                +-----------+                |
                                                                |           |                |
                                                                | Terminated|<---------------+
                                                                |           |
                                                                +-----------+

                                                     Figure 7: INVITE server transaction
                                                         Request received
                                                                         |pass to TU

                                                                         V
                                                                   +-----------+
                                                                   |           |
                                                                   | Trying    |-------------+
                                                                   |           |             |
                                                                   +-----------+             |200-699 from TU
                                                                         |                   |send response
                                                                         |1xx from TU        |
                                                                         |send response      |
                                                                         |                   |
                                                      Request            V      1xx from TU  |
                                                      send response+-----------+send response|
                                                          +--------|           |--------+    |
                                                          |        | Proceeding|        |    |
                                                          +------->|           |<-------+    |
                                                   +<--------------|           |             |
                                                   |Trnsprt Err    +-----------+             |
                                                   |Inform TU            |                   |
                                                   |                     |                   |
                                                   |                     |200-699 from TU    |
                                                   |                     |send response      |
                                                   |  Request            V                   |
                                                   |  send response+-----------+             |
                                                   |      +--------|           |             |
                                                   |      |        | Completed |<------------+
                                                   |      +------->|           |
                                                   +<--------------|           |
                                                   |Trnsprt Err    +-----------+
                                                   |Inform TU            |
                                                   |                     |Timer J fires
                                                   |                     |-
                                                   |                     |
                                                   |                     V
                                                   |               +-----------+
                                                   |               |           |
                                                   +-------------->| Terminated|
                                                                   |           |
                                                                   +-----------+





 

Version:
1.2 $Revision: 1.108 $ $Date: 2009/08/18 02:44:28 $
Author:
M. Ranganathan
See Also:
Serialized Form

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
 boolean ackSeen()
          This is book-keeping for retransmission filter management.
 void disableRetransmissionAlerts()
          Disable retransmission Alerts and cancel associated timers.
 void enableRetransmissionAlerts()
          Enable the timeout retransmit notifications for the ServerTransaction.
 boolean equals(Object other)
           
 SIPServerTransaction getCanceledInviteTransaction()
          TODO -- this method has to be added to the api.
 Dialog getDialog()
          Gets the dialog object of this Transaction object.
 SIPResponse getLastResponse()
          Get the last response.
 SIPResponse getReliableProvisionalResponse()
           
 MessageChannel getResponseChannel()
          Returns this transaction.
 TransactionState getState()
          Return the current transaction state according to the RFC 3261 transaction state machine.
 String getViaHost()
          Get the host to assign for an outgoing Request via header.
 int getViaPort()
          Get the port to assign for the via header of an outgoing message.
 boolean isMessagePartOfTransaction(SIPMessage messageToTest)
          Deterines if the message is a part of this transaction.
 boolean isRetransmissionAlertEnabled()
           
 boolean isTransactionMapped()
          Return true if the transaction is known to stack.
 boolean prackRecieved()
          Cancel the retransmit timer for the provisional response task.
 void processRequest(SIPRequest transactionRequest, MessageChannel sourceChannel)
          Process a new request message through this transaction.
 void releaseSem()
          Release the transaction semaphore.
 void scheduleAckRemoval()
           
 void sendMessage(SIPMessage messageToSend)
          Send a response message through this transactionand onto the client.
 void sendResponse(Response response)
          Sends the Response to a Request which is associated with this ServerTransaction.
 void setAckSeen()
          This is book-keeping for retransmission filter management.
 void setDialog(SIPDialog sipDialog, String dialogId)
          set the dialog object.
 void setInviteTransaction(SIPServerTransaction st)
          The INVITE Server Transaction corresponding to a CANCEL Server Transaction.
 void setMapped(boolean b)
           
 void setOriginalRequest(SIPRequest originalRequest)
          Set the original request.
 void setPendingSubscribe(SIPClientTransaction pendingSubscribeClientTx)
           
 void setRequestInterface(ServerRequestInterface newRequestOf)
          Sets the real RequestInterface 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, getMessageChannel, getMessageProcessor, getMethod, getOriginalRequest, getPeerAddress, getPeerPacketSourceAddress, getPeerPacketSourcePort, getPeerPort, getPort, getRequest, getResponse, getRetransmitTimer, getSipProvider, getSIPStack, getTransactionId, getTransport, getViaHeader, hashCode, isByeTransaction, isCancelTransaction, isInviteTransaction, isReliable, isSecure, isTerminated, passToListener, raiseIOExceptionEvent, removeEventListener, setApplicationData, setBranch, setEncapsulatedChannel, 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
getClass, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface javax.sip.Transaction
getApplicationData, getBranchId, getRequest, getRetransmitTimer, setApplicationData, setRetransmitTimer
 

Method Detail

setRequestInterface

public void setRequestInterface(ServerRequestInterface newRequestOf)
Sets the real RequestInterface this transaction encapsulates.

Parameters:
newRequestOf - RequestInterface to send messages to.

getResponseChannel

public MessageChannel getResponseChannel()
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.

isTransactionMapped

public boolean isTransactionMapped()
Return true if the transaction is known to stack.


processRequest

public void processRequest(SIPRequest transactionRequest,
                           MessageChannel sourceChannel)
Process a new request message through this transaction. If necessary, this message will also be passed onto the TU.

Specified by:
processRequest in interface ServerRequestInterface
Parameters:
transactionRequest - Request to process.
sourceChannel - Channel that received this message.

sendMessage

public void sendMessage(SIPMessage messageToSend)
                 throws IOException
Send a response message through this transactionand onto the client. The response drives the state machine.

Overrides:
sendMessage in class SIPTransaction
Parameters:
messageToSend - Response to process and send.
Throws:
IOException

getViaHost

public String getViaHost()
Description copied from class: SIPTransaction
Get the host to assign for an outgoing Request via header.

Overrides:
getViaHost in class SIPTransaction

getViaPort

public int getViaPort()
Description copied from class: SIPTransaction
Get the port to assign for the via header of an outgoing message.

Overrides:
getViaPort in class SIPTransaction

getLastResponse

public SIPResponse getLastResponse()
Get the last response.

Overrides:
getLastResponse in class SIPTransaction
Returns:
the last response received (for client transactions) or sent (for server transactions).

setOriginalRequest

public void setOriginalRequest(SIPRequest originalRequest)
Set the original request.

Overrides:
setOriginalRequest in class SIPTransaction
Parameters:
originalRequest - Request being handled.

sendResponse

public void sendResponse(Response response)
                  throws SipException
Description copied from interface: ServerTransaction
Sends the Response to a Request which is associated with this ServerTransaction. When an application wishes to send a Response, it creates a Response using the MessageFactory and then passes that Response to this method. The Response message gets sent out on the network via the ListeningPoint information that is associated with the SipProvider of this ServerTransaction.

This method implies that the application is functioning as either a UAS or a stateful proxy, hence the underlying implementation acts statefully. When a UAS sends a 2xx response to an INVITE, the server transaction is transitions to the TerminatedState. The implementation may delay physically removing ServerTransaction record from memory to catch retransmissions of the INVITE in accordance with the reccomendation of http://bugs.sipit.net/show_bug.cgi?id=769 .

ACK Processing and final response retransmission:
If a Dialog is associated with the ServerTransaction then when the UAC sends the ACK ( the typical case for User Agents), the Application ( i.e. Listener ) will see a ServerTransaction corresponding to the ACK and the corresponding Dialog presented to it. The ACK will be presented to the Listener only once in this case. Retransmissions of the OK and filtering of ACK retransmission are the responsibility of the Dialog layer of this specification. However if no Dialog is associated with the INVITE Transaction, the ACK will be presented to the Application with a null Dialog in the RequestEvent and there will be no Dialog associated with the ACK Transaction (i.e. Transaction.getDialog() returns null). In this case (when there is no Dialog associated with the original INVITE or ACK) the Application is responsible for retransmission of the OK for the INVITE if necessary (i.e. if it wants to manage its own dialog layer and function as a User Agent) and for dealing with retransmissions of the ACK. This requires that the three way handshake of an INVITE is managed by the UAS application and not the implementation of this specification.

Note that Responses created via Dialog.createReliableProvisionalResponse(int) should be sent using Dialog.sendReliableProvisionalResponse(Response)

Specified by:
sendResponse in interface ServerTransaction
Parameters:
response - the Response to send to the Request.
Throws:
SipException - if the SipProvider cannot send the Response for any other reason.
See Also:
Response

getState

public TransactionState getState()
Return the current transaction state according to the RFC 3261 transaction state machine. Invite transactions do not have a trying state. We just use this as a pseudo state for processing requests.

Specified by:
getState in interface Transaction
Overrides:
getState in class SIPTransaction
Returns:
the state of the transaction.

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.

equals

public boolean equals(Object other)
Overrides:
equals in class Object

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

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

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.

getReliableProvisionalResponse

public SIPResponse getReliableProvisionalResponse()

prackRecieved

public boolean prackRecieved()
Cancel the retransmit timer for the provisional response task.

Returns:
true if the tx has seen the prack for the first time and false otherwise.

enableRetransmissionAlerts

public void enableRetransmissionAlerts()
                                throws SipException
Description copied from interface: ServerTransaction
Enable the timeout retransmit notifications for the ServerTransaction. This method is invoked by UAs that do want to be alerted by the stack to retransmit 2XX responses but that do NOT want to associate a Dialog. The Default operation is to disable retransmission alerts for the Server Transaction when no Dialog is associated with the Server Transaction, as is common for a Proxy server. When this method is called, the stack will continue to generate Timeout.RETRANSMIT until the application calls Transaction.terminate() or a the listener receives a SipListener.processTransactionTerminated(TransactionTerminatedEvent) callback. Note that the stack calls SipListener.processTransactionTerminated(TransactionTerminatedEvent)asynchronously after it removes the transaction some time after the Transaction state is set to TransactionState.TERMINATED ; after which, it maintains no record of the Transaction.

Specified by:
enableRetransmissionAlerts in interface ServerTransaction
Throws:
SipException - if a Dialog is already associated with the ServerTransaction when the method is called.

isRetransmissionAlertEnabled

public boolean isRetransmissionAlertEnabled()

disableRetransmissionAlerts

public void disableRetransmissionAlerts()
Disable retransmission Alerts and cancel associated timers.


setAckSeen

public void setAckSeen()
This is book-keeping for retransmission filter management.


ackSeen

public boolean ackSeen()
This is book-keeping for retransmission filter management.


setMapped

public void setMapped(boolean b)

setPendingSubscribe

public void setPendingSubscribe(SIPClientTransaction pendingSubscribeClientTx)

releaseSem

public void releaseSem()
Description copied from class: SIPTransaction
Release the transaction semaphore.

Overrides:
releaseSem in class SIPTransaction

setInviteTransaction

public void setInviteTransaction(SIPServerTransaction st)
The INVITE Server Transaction corresponding to a CANCEL Server Transaction.

Parameters:
st - -- the invite server tx corresponding to the cancel server transaction.

getCanceledInviteTransaction

public SIPServerTransaction getCanceledInviteTransaction()
TODO -- this method has to be added to the api.

Specified by:
getCanceledInviteTransaction in interface ServerTransactionExt
Returns:

scheduleAckRemoval

public void scheduleAckRemoval()
                        throws IllegalStateException
Throws:
IllegalStateException

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.