javax.sip

Interface ClientTransaction

All Superinterfaces:

Serializable, Transaction

All Known Subinterfaces:

ClientTransactionExt, SIPClientTransaction

All Known Implementing Classes:

SIPClientTransactionImpl

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

Version:

1.2

Author:

BEA Systems, NIST

Method Summary

Methods

Modifier and Type	Method and Description
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.

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

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.