JAIN-SIP 2.0 API

javax.sip
Interface Transaction

All Superinterfaces:
Serializable
All Known Subinterfaces:
ClientTransaction, ServerTransaction

public interface Transaction
extends Serializable

This interface represents an abstraction for a SIP transaction. Transactions are a fundamental component of SIP. A transaction is a request sent by a client transaction to a server transaction, along with all responses to that request sent from the server transaction back to the client transactions. User agents contain a transaction layer, as do stateful proxies. Stateless proxies do not contain a transaction layer. This specification provides the capabilities to allow either the SipProvider or SipListener to handle transactional functionality.

This interface represents a generic transaction interface defining the methods common between client and server transactions.

Since:
1.1
Version:
2.0
Author:
Oracle Inc., NIST
See Also:
TransactionState

Method Summary
 List<String> extractCertIdentities()
          Extract identities from certificates exchanged over TLS, based on IETF guidelines
 Object getApplicationData()
          Returns the application data associated with the transaction.This specification does not define the format of this application specific data.
 String getBranchId()
          Returns a unique branch identifer that identifies this transaction.
 String getCipherSuite()
          Return the Cipher Suite that was used for the SSL handshake.
 Dialog getDialog()
          Gets the dialog object of this transaction object.
 String getHost()
          return the ip address on which this message was initially received
 Certificate[] getLocalCertificates()
          Get the certificate(s) that were sent to the peer during handshaking.
 String getPeerAddress()
          Returns the IP address of the peer IP address (upstream/downstream) hop from which this message was initially received.
 Certificate[] getPeerCertificates()
           
 int getPeerPort()
          Returns the port of the peer port (upstream/downstream hop) from which this message was initially received.
 int getPort()
          return the port on which this message was initially received
 Request getRequest()
          Returns the request that created this transaction.
 int getRetransmitTimer()
          Returns the current value of the retransmit timer in milliseconds used to retransmit messages over unreliable transports for this transaction.
 SipProvider getSipProvider()
          Get the Sip Provider associated with this transaction.
 TransactionState getState()
          Returns the current state of the transaction.
 int getTimerD()
          gets the value of Timer D (in ms)
 int getTimerT2()
          Retrieve the value of Timer T2 (in ms)
 int getTimerT4()
          Retrieve the value of Timer T4 (in ms)
 String getTransport()
          Returns the name of the protocol with which this message was initially received
 void setApplicationData(Object applicationData)
          This method allows applications to associate application context with the transaction.
 void setReleaseReferences(boolean releaseReferences)
          Provide a hint to the stack to release all references that it no longer needs.
 void setRetransmitTimer(int retransmitTimer)
          Sets the value of the retransmit timer to the newly supplied timer value.
 void setTimerD(int interval)
          Sets the value of Timer D (in ms)
 void setTimerT2(int interval)
          Sets the value of Timer T2 (in ms)
 void setTimerT4(int interval)
          Sets the value of Timer T4 (in ms)
 void terminate()
          Terminate this transaction and immediately release all stack resources associated with it.
 

Method Detail

getDialog

Dialog getDialog()
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.

Returns:
the dialog object of this transaction object or null if no dialog exists.
See Also:
Dialog

getState

TransactionState getState()
Returns the current state of the transaction. Returns the current TransactionState of this Transaction or null if a ClientTransaction has yet been used to send a message.

Returns:
a TransactionState object determining the current state of the transaction.

getRetransmitTimer

int getRetransmitTimer()
                       throws UnsupportedOperationException
Returns the current value of the retransmit timer in milliseconds used to retransmit messages over unreliable transports for this transaction.

Returns:
the integer value of the retransmit timer in milliseconds.
Throws:
UnsupportedOperationException - if this method is not supported by the underlying implementation.

setRetransmitTimer

void setRetransmitTimer(int retransmitTimer)
                        throws UnsupportedOperationException
Sets the value of the retransmit timer to the newly supplied timer value. The retransmit timer is expressed in milliseconds and its default value is 500ms. This method allows the application to change the transaction retransmit behavior for different networks. For example the gateway proxy, the internal intranet is likely to be relatively uncongested and the endpoints will be relatively close. The external network is the general Internet. This functionality allows different retransmit times for either side.

Parameters:
retransmitTimer - - the new integer value of the retransmit timer in milliseconds.
Throws:
UnsupportedOperationException - if this method is not supported by the underlying implementation.

getBranchId

String getBranchId()
Returns a unique branch identifer that identifies this transaction. The branch identifier is used in the ViaHeader. The uniqueness property of the branch ID parameter to facilitate its use as a transaction ID, was not part of RFC 2543. The branch ID inserted by an element compliant with the RFC3261 specification MUST always begin with the characters "z9hG4bK". These 7 characters are used as a magic cookie, so that servers receiving the request can determine that the branch ID was constructed to be globally unique. The precise format of the branch token is implementation-defined. This method should always return the same branch identifier for the same transaction.

Returns:
the new branch that uniquely identifies this transaction.

getRequest

Request getRequest()
Returns the request that created this transaction. The transaction state machine needs to keep the Request that resulted in the creation of this transaction while the transaction is still alive. Applications also need to access this information, e.g. a forking proxy server may wish to retrieve the original Invite request to cancel branches of a fork when a final Response has been received by one branch.

Returns:
the Request message that created this transaction.

setApplicationData

void setApplicationData(Object applicationData)
This method allows applications to associate application context with the transaction. This specification does not define the format of this data, this the responsibility of the application and is dependent on the application. This capability may be useful for proxy servers to associate the transaction to some application state. The context of this application data is un-interpreted by the stack.

Parameters:
applicationData - - un-interpreted application data.
Since:
v1.2

getApplicationData

Object getApplicationData()
Returns the application data associated with the transaction.This specification does not define the format of this application specific data. This is the responsibility of the application.

Returns:
application data associated with the transaction by the application.
Since:
v1.2

terminate

void terminate()
               throws ObjectInUseException
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.

Throws:
ObjectInUseException - if the transaction cannot be terminated as it is associated to a dialog.
Since:
v1.2

getSipProvider

SipProvider getSipProvider()
Get the Sip Provider associated with this transaction.

Since:
2.0

getPeerAddress

String getPeerAddress()
Returns the IP address of the peer IP address (upstream/downstream) hop from which this message was initially received. Will be null when the client transaction is first created.

Returns:
the IP address of the peer IP address (upstream/downstream) hop from which this message was initially received
Since:
2.0

getPeerPort

int getPeerPort()
Returns the port of the peer port (upstream/downstream hop) from which this message was initially received. Will be undefined when the client transaction is first created.

Returns:
the port of the peer port from which this message was initially received
Since:
2.0

getTransport

String getTransport()
Returns the name of the protocol with which this message was initially received

Returns:
the name of the protocol with which this message was initially received
Since:
2.0

getHost

String getHost()
return the ip address on which this message was initially received

Returns:
the ip address on which this message was initially received
Since:
2.0

getPort

int getPort()
return the port on which this message was initially received

Returns:
the port on which this message was initially received
Since:
2.0

getCipherSuite

String getCipherSuite()
                      throws UnsupportedOperationException
Return the Cipher Suite that was used for the SSL handshake.

Returns:
Returns the cipher suite in use by the session which was produced by the handshake.
Throws:
UnsupportedOperationException - if this is not a secure transaction.
Since:
2.0

getLocalCertificates

Certificate[] getLocalCertificates()
                                   throws UnsupportedOperationException
Get the certificate(s) that were sent to the peer during handshaking.

Returns:
the certificate(s) that were sent to the peer during handshaking.
Throws:
UnsupportedOperationException - if this is not a secure transaction.
Since:
2.0

getPeerCertificates

Certificate[] getPeerCertificates()
                                  throws SSLPeerUnverifiedException
Returns:
the identity of the peer which was identified as part of defining the session.
Throws:
SSLPeerUnverifiedException
UnsupportedOperationException - if this is not a secure transaction.
Since:
2.0

extractCertIdentities

List<String> extractCertIdentities()
                                   throws SSLPeerUnverifiedException
Extract identities from certificates exchanged over TLS, based on IETF guidelines

Returns:
list of authenticated identities
Throws:
SSLPeerUnverifiedException
Since:
2.0

setReleaseReferences

void setReleaseReferences(boolean releaseReferences)
Provide a hint to the stack to release all references that it no longer needs. After this method is called, the stack may release references that it no longer needs. This will include the reference to the Response, Dialogs, any unused timers etc. This will significantly reduce memory consumption under high load. This is an optimization. An implementation of this specification is free to do nothing when this method is called by the application.

Parameters:
releaseReferences -
Since:
2.0

getTimerT2

int getTimerT2()
Retrieve the value of Timer T2 (in ms)

Returns:
T2 value (in ms)
Since:
2.0

setTimerT2

void setTimerT2(int interval)
Sets the value of Timer T2 (in ms)

Parameters:
interval - value of Timer T2 (in ms)
Since:
2.0

getTimerT4

int getTimerT4()
Retrieve the value of Timer T4 (in ms)

Returns:
T4 value (in ms)
Since:
2.0

setTimerT4

void setTimerT4(int interval)
Sets the value of Timer T4 (in ms)

Parameters:
interval - value of Timer T4 (in ms)
Since:
2.0

getTimerD

int getTimerD()
gets the value of Timer D (in ms)

Since:
2.0

setTimerD

void setTimerD(int interval)
Sets the value of Timer D (in ms)

Parameters:
interval - value of Timer D (in ms)
Since:
2.0

JAIN-SIP 2.0 API


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