JSIP API v1.2
November 2006

javax.sip
Interface ClientTransaction

All Superinterfaces:
java.io.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

Author:
BEA Systems, NIST

Method Summary
 Request createAck()
          Deprecated. 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.
 void sendRequest()
          Sends the Request which created this ClientTransaction.
 
Methods inherited from interface javax.sip.Transaction
getApplicationData, getBranchId, getDialog, getRequest, getRetransmitTimer, getState, setApplicationData, setRetransmitTimer, 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.

createAck

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

JSIP API v1.2
November 2006

If you have any comments, please mail them to JAIN-SIP-INTEREST@java.sun.com after subscribing at http://archives.java.sun.com
Copyright - 2006 BEA Systems and Sun Microsystems