gov.nist.javax.sip.stack

Interface SIPClientTransaction

All Superinterfaces:

ClientTransaction, ClientTransactionExt, Serializable, ServerResponseInterface, SIPTransaction, Transaction, TransactionExt

All Known Implementing Classes:

SIPClientTransactionImpl

public interface SIPClientTransaction
extends ClientTransactionExt, SIPTransaction, ServerResponseInterface

Field Summary

Fields inherited from interface gov.nist.javax.sip.stack.SIPTransaction

CALLING_STATE, COMPLETED_STATE, CONFIRMED_STATE, INITIAL_STATE, PROCEEDING_STATE, T1, TERMINATED_STATE, TIMER_A, TIMER_B, TIMER_F, TIMER_H, TIMER_J, TRYING_STATE

Method Summary

Methods

Modifier and Type	Method and Description
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.
boolean	checkFromTag(SIPResponse sipResponse) Check if the From tag of the response matches the from tag of the original message.
void	cleanUp()
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() Get the default dialog that was originally assigned to the client transaction.
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).
String	getOriginalRequestCallId()
Contact	getOriginalRequestContact()
Event	getOriginalRequestEvent()
String	getOriginalRequestFromTag()
String	getOriginalRequestScheme()
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(int 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	setTerminateDialogOnCleanUp(boolean enabled) will terminate a null state dialog when the transaction terminates Default: true
void	setViaHost(String host) Set the port of the recipient.
void	setViaPort(int port) Set the port of the recipient.
void	stopExpiresTimer() Stop the ExPIRES timer if it is running.
void	terminate() Terminate this transaction and immediately release all stack resources associated with it.

Methods inherited from interface gov.nist.javax.sip.ClientTransactionExt

isSecure

Methods inherited from interface gov.nist.javax.sip.stack.SIPTransaction

acquireSem, addEventListener, cancelMaxTxLifeTimeTimer, close, disableRetransmissionTimer, disableTimeoutTimer, doesCancelMatchTransaction, extractCertIdentities, fireRetransmissionTimer, fireTimeoutTimer, fireTimer, getApplicationData, getAuditTag, getBaseTimerInterval, getBranch, getBranchId, getCipherSuite, getCSeq, getForkId, getHost, getInternalState, getKey, getLastResponse, getLocalCertificates, getMergeId, getMessageChannel, getMessageProcessor, getMethod, getOriginalRequest, getPeerAddress, getPeerCertificates, getPeerPacketSourceAddress, getPeerPacketSourcePort, getPeerPort, getPeerProtocol, getPort, getReleaseReferencesStrategy, getRequest, getResponse, getRetransmitTimer, getSipProvider, getSIPStack, getState, getT2, getT4, getTimerD, getTimerI, getTimerK, getTimerT2, getTimerT4, getTransactionId, getTransport, getViaHeader, hashCode, isByeTransaction, isCancelTransaction, isDialogCreatingTransaction, isInviteTransaction, isReliable, isSecure, isServerTransaction, isTerminated, isTransactionMapped, passToListener, raiseErrorEvent, raiseIOExceptionEvent, releaseSem, removeEventListener, scheduleMaxTxLifeTimeTimer, semRelease, setApplicationData, setAuditTag, setBranch, setCollectionTime, setEncapsulatedChannel, setForkId, setOriginalRequest, setPassToListener, setReleaseReferencesStrategy, setRetransmitTimer, setTimerD, setTimerT2, setTimerT4, setTransactionMapped, startTransactionTimer, testAndSetTransactionTerminatedEvent

Method Detail

setResponseInterface

void setResponseInterface(ServerResponseInterface newRespondTo)

Sets the real ResponseInterface this transaction encapsulates.

Parameters:

newRespondTo - ResponseInterface to send messages to.

getRequestChannel

MessageChannel getRequestChannel()

Returns this transaction.

isMessagePartOfTransaction

boolean isMessagePartOfTransaction(SIPMessage messageToTest)

Deterines if the message is a part of this transaction.

Specified by:

isMessagePartOfTransaction in interface 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

void sendMessage(SIPMessage messageToSend)
                 throws IOException

Send a request message through this transaction and onto the client.

Specified by:

sendMessage in interface SIPTransaction

Parameters:

messageToSend - Request to process and send.

Throws:

IOException

processResponse

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

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

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.

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

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

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.

setViaPort

void setViaPort(int port)

Set the port of the recipient.

setViaHost

void setViaHost(String host)

Set the port of the recipient.

getViaPort

int getViaPort()

Get the port of the recipient.

Specified by:

getViaPort in interface SIPTransaction

getViaHost

String getViaHost()

Get the host of the recipient.

Specified by:

getViaHost in interface SIPTransaction

getOutgoingViaHeader

Via getOutgoingViaHeader()

get the via header for an outgoing request.

clearState

void clearState()

This is called by the stack after a non-invite client transaction goes to completed state.

setState

void setState(int 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.

Specified by:

setState in interface SIPTransaction

Parameters:

newState - New state of this transaction.

terminate

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.

stopExpiresTimer

void stopExpiresTimer()

Stop the ExPIRES timer if it is running.

checkFromTag

boolean checkFromTag(SIPResponse sipResponse)

Check if the From tag of the response matches the from tag of the original message. A Response with a tag mismatch should be dropped if a Dialog has been created for the original request.

Parameters:

sipResponse - the response to check.

Returns:

true if the check passes.

processResponse

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

Dialog getDialog()

Description copied from interface: Transaction

Gets the dialog object of this transaction object. 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.

• If the stack is configured with the AUTOMATIC_DIALOG_SUPPORT property set to ON ( default behavior ) then the following behavior is defined:
  • If the transaction is associated with an existing Dialog or could result in a Dialog being created in the future (ie. the stack is configured to recognize the method as a Dialog creating method or is one of the natively supported dialog creating methods such as INVITE, SUBSCRIBE or REFER), then the implementation must either associate the transaction with the existing Dialog or create a Dialog with null state.
  • If the Transaction is neither dialog creating nor can be associated with an existing dialog, then the implementation must return null when the application issues getDialog on the transaction.
• If the stack is configured with AUTOMATIC_DIALOG property set to OFF then the stack does not automatically create a Dialog for a transaction nor does it maintain an association between dialog and transaction on behalf of the application. Hence this method will return null. It is the responsibility of the application to create a Dialog and associate it with the transaction when the response is sent.

Specified by:

getDialog in interface SIPTransaction

Specified by:

getDialog in interface Transaction

Returns:

the dialog object of this transaction object or null if no dialog exists.

See Also:

Dialog

getDialog

SIPDialog getDialog(String dialogId)

setDialog

void setDialog(SIPDialog sipDialog,
             String dialogId)

Description copied from interface: SIPTransaction

set the dialog object.

Specified by:

setDialog in interface SIPTransaction

Parameters:

sipDialog - -- the dialog to set.

dialogId - -- the dialog id ot associate with the dialog.s

getDefaultDialog

SIPDialog getDefaultDialog()

Description copied from interface: ClientTransactionExt

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.

Specified by:

getDefaultDialog in interface ClientTransactionExt

setNextHop

void setNextHop(Hop hop)

Set the next hop ( if it has already been computed).

Parameters:

hop - -- the hop that has been previously computed.

getNextHop

Hop getNextHop()

Reeturn the previously computed next hop (avoid computing it twice).

Specified by:

getNextHop in interface ClientTransactionExt

Returns:

-- next hop previously computed.

setNotifyOnRetransmit

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

boolean isNotifyOnRetransmit()

Returns:

the notifyOnRetransmit

alertIfStillInCallingStateBy

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.

cleanUp

void cleanUp()

Specified by:

cleanUp in interface SIPTransaction

getOriginalRequestFromTag

String getOriginalRequestFromTag()

Returns:

the originalRequestFromTag

getOriginalRequestCallId

String getOriginalRequestCallId()

Returns:

the originalRequestFromTag

getOriginalRequestEvent

Event getOriginalRequestEvent()

Returns:

the originalRequestFromTag

getOriginalRequestContact

Contact getOriginalRequestContact()

Returns:

the originalRequestFromTag

getOriginalRequestScheme

String getOriginalRequestScheme()

Returns:

the originalRequestFromTag

setTerminateDialogOnCleanUp

void setTerminateDialogOnCleanUp(boolean enabled)

will terminate a null state dialog when the transaction terminates Default: true

Parameters:

enabled -