JAIN-SIP 2.0 API

javax.sip
Interface ClientTransaction

All Superinterfaces:
Serializable, Transaction

public interface ClientTransaction
extends Transaction

A client transaction is used by a User Agent Client application to send Request messages to a User Agent Server application. The client transaction is also used to match Responses from the User Agent Server to fire Response events to the SipListener for a specific client transaction. This interfaces enables an application to send a Request's statefully. A new client transaction is generated by the application calling the SipProvider.getNewClientTransaction(Request) method.

A client transaction of the transaction layer is represented by a finite state machine that is constructed to process a particular request under the covers of a stateful SipProvider. The transaction layer handles application-layer retransmissions, matching of responses to requests, and application-layer timeouts. Any task that a User Agent Client accomplishes takes place using a series of transactions.

The client transaction must be unique within the underlying implementation. A common way to create this value is to compute a cryptographic hash of the To tag, From tag, Call-ID header field, the Request-URI of the request received (before translation), the topmost Via header, and the sequence number from the CSeq header field, in addition to any Proxy-Require and Proxy-Authorization header fields that may be present. The algorithm used to compute the hash is implementation-dependent.

For the detailed client transaction state machines refer to Chapter 17 of RFC 3261, the allowable transitions are summarized below:

Invite Transaction:
Calling --> Proceeding --> Completed --> Terminated

Non-Invite Transaction:
Trying --> Proceeding --> Completed --> Terminated

Since:
1.1
Version:
2.0
Author:
Oracle inc., NIST

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.
 Request createAck()
          Deprecated. WARNING: Implementations may throw OperationNotSupportedException. Since v1.2. As a transaction that received a 2xx response terminates immediately, it cannot be used for creating the corresponding ACK. If this transaction created a dialog, the Dialog.createAck(long) method should be used. Otherwise the stack will automatically create and send the ACK for non-2xx responses that need to be acknowledged. That is the application should never need to use this method.
 Request createCancel()
          Creates a new Cancel message from the Request associated with this client transaction.
 Dialog getDefaultDialog()
          Get the default dialog that was originally assigned to the client transaction.
 Hop getNextHop()
          Get the next hop that was computed by the routing layer.
 boolean isSecure()
          Return true if this Client Transaction is a secure transport.
 void sendRequest()
          Sends the Request which created this ClientTransaction.
 void setNotifyOnRetransmit(boolean flag)
          Notify on retransmission from the client transaction side.
 
Methods inherited from interface javax.sip.Transaction
extractCertIdentities, getApplicationData, getBranchId, getCipherSuite, getDialog, getHost, getLocalCertificates, getPeerAddress, getPeerCertificates, getPeerPort, getPort, getRequest, getRetransmitTimer, getSipProvider, getState, getTimerD, getTimerT2, getTimerT4, getTransport, setApplicationData, setReleaseReferences, setRetransmitTimer, setTimerD, setTimerT2, setTimerT4, terminate
 

Method Detail

sendRequest

void sendRequest()
                 throws SipException
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.

Throws:
SipException - if the SipProvider cannot send the Request for any reason.
See Also:
Request

createCancel

Request createCancel()
                     throws SipException
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.

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.

setNotifyOnRetransmit

void setNotifyOnRetransmit(boolean flag)
Notify on retransmission from the client transaction side. The listener will get a notification on retransmission when this flag is set. When set the client transaction listener will get a Timeout.RETRANSMIT event on each retransmission.

Parameters:
flag - -- the flag that indicates whether or not notification is desired.
Since:
2.0

alertIfStillInCallingStateBy

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

Parameters:
count - -- the number of base timer intervals after which an alert is issued.
Since:
2.0

getNextHop

Hop getNextHop()
Get the next hop that was computed by the routing layer. when it sent out the request. This allows you to route requests to the SAME destination if required ( for example if you get an authentication challenge ).

Since:
2.0

isSecure

boolean isSecure()
Return true if this Client Transaction is a secure transport.

Since:
2.0

getDefaultDialog

Dialog getDefaultDialog()
Get the default dialog that was originally assigned to the client transaction. This will differ from the dialog that is assigned to the transaction when a forked response comes in. This method is useful for UACs that have to deal with forked responses.

Since:
2.0

createAck

Request createAck()
                  throws SipException
Deprecated. WARNING: Implementations may throw OperationNotSupportedException. Since v1.2. As a transaction that received a 2xx response terminates immediately, it cannot be used for creating the corresponding ACK. If this transaction created a dialog, the Dialog.createAck(long) method should be used. Otherwise the stack will automatically create and send the ACK for non-2xx responses that need to be acknowledged. That is the application should never need to use this method.

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.

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.

JAIN-SIP 2.0 API


See conditions of use.
Submit a bug report or feature request.