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. |
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.
- 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.
- 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
See conditions of use.
Submit a bug report or feature request.