Transaction (jain-sip-ri 1.2.299 API)

All Superinterfaces:

Serializable

All Known Subinterfaces:

ClientTransaction, ClientTransactionExt, ServerTransaction, ServerTransactionExt, SIPClientTransaction, SIPServerTransaction, SIPTransaction, TransactionExt

All Known Implementing Classes:

SIPClientTransactionImpl, SIPServerTransactionImpl, SIPTransactionImpl
```
public interface Transaction
extends Serializable
```
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.

Version:

1.2

Author:

BEA Systems, NIST

See Also:
TransactionState

Method Summary

Methods
Modifier and Type	Method and Description
`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.
`Dialog`	`getDialog()` Gets the dialog object of this transaction object.
`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.
`TransactionState`	`getState()` Returns the current state of the transaction.
`void`	`setApplicationData(Object applicationData)` This method allows applications to associate application context with the transaction.
`void`	`setRetransmitTimer(int retransmitTimer)` Sets the value of the retransmit timer to the newly supplied timer value.
`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.
    - 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

Interface Transaction

Method Summary

Method Detail

getDialog

getState

getRetransmitTimer

setRetransmitTimer

getBranchId

getRequest

setApplicationData

getApplicationData

terminate