NIST-SIP: The Reference Implementation for JAIN-SIP 1.2

gov.nist.javax.sip.stack
Class SIPTransaction

java.lang.Object
  extended by gov.nist.javax.sip.stack.MessageChannel
      extended by gov.nist.javax.sip.stack.SIPTransaction
All Implemented Interfaces:
TransactionExt, Serializable, Transaction
Direct Known Subclasses:
SIPClientTransaction, SIPServerTransaction

public abstract class SIPTransaction
extends MessageChannel
implements Transaction, TransactionExt

Abstract class to support both client and server transactions. Provides an encapsulation of a message channel, handles timer events, and creation of the Via header for a message.

Version:
1.2 $Revision: 1.62 $ $Date: 2009/07/29 20:38:13 $
Author:
Jeff Keyser, M. Ranganathan
See Also:
Serialized Form

Field Summary
 long auditTag
           
static TransactionState CALLING_STATE
          CALLING State.
static TransactionState COMPLETED_STATE
          Completed state.
static TransactionState CONFIRMED_STATE
          Confirmed state.
static TransactionState INITIAL_STATE
          Initialized but no state assigned.
static TransactionState PROCEEDING_STATE
          Proceeding state.
static TransactionState TERMINATED_STATE
          Terminated state.
static TransactionState TRYING_STATE
          Trying state.
 
Method Summary
 boolean acquireSem()
          A given tx can process only a single outstanding event at a time.
 void addEventListener(SIPTransactionEventListener newListener)
          Adds a new event listener to this transaction.
 void close()
          Close the encapsulated channel.
 boolean doesCancelMatchTransaction(SIPRequest requestToTest)
          A method that can be used to test if an incoming request belongs to this transction.
 Object getApplicationData()
          Get the application data associated with this transaction.
 String getBranch()
          Gets the current setting for the branch parameter of this transaction.
 String getBranchId()
          Returns a unique branch identifer that identifies this transaction.
 long getCSeq()
          Get the Sequence number of the request used to create the transaction.
abstract  Dialog getDialog()
          Gets the dialog object of this Transaction object.
 String getHost()
          Get the host of this message channel.
 String getKey()
          Generate a key which identifies the message channel.
 SIPResponse getLastResponse()
          Get the last response.
 MessageChannel getMessageChannel()
          Returns the message channel used for transmitting/receiving messages for this transaction.
 MessageProcessor getMessageProcessor()
          Get the message processor.
 String getMethod()
          Get the method of the request used to create this transaction.
 SIPRequest getOriginalRequest()
          Gets the request being handled by this transaction.
 String getPeerAddress()
          Get the peer address of the machine that sent us this message.
 InetAddress getPeerPacketSourceAddress()
           
 int getPeerPacketSourcePort()
           
 int getPeerPort()
          Get the sender port ( the port of the other end that sent me the message).
 int getPort()
          Get port of this message channel.
 Request getRequest()
          Get the original request but cast to a Request structure.
 Response getResponse()
          Get the JAIN interface response
 int getRetransmitTimer()
          Returns the current value of the retransmit timer in milliseconds used to retransmit messages over unreliable transports.
 SipProviderImpl getSipProvider()
          Return the SipProvider for which the transaction is assigned.
 SIPTransactionStack getSIPStack()
          Get the SIPStack object from this message channel.
 TransactionState getState()
          Gets the current state of this transaction.
 String getTransactionId()
          Get the transaction Id.
 String getTransport()
          Get transport string of this message channel.
 Via getViaHeader()
          Returns the Via header for this channel.
 String getViaHost()
          Get the host to assign for an outgoing Request via header.
 int getViaPort()
          Get the port to assign for the via header of an outgoing message.
 int hashCode()
          Hashcode method for fast hashtable lookup.
 boolean isByeTransaction()
          Return a flag that states if this is a BYE transaction.
 boolean isCancelTransaction()
          Return true if the transaction corresponds to a CANCEL message.
 boolean isInviteTransaction()
          Returns a flag stating whether this transaction is for an INVITE request or not.
abstract  boolean isMessagePartOfTransaction(SIPMessage messageToTest)
          Tests a message to see if it is part of this transaction.
 boolean isReliable()
          Get whether this channel is reliable or not.
 boolean isSecure()
          Return true if this is a secure channel.
 boolean isTerminated()
          Tests if this transaction has terminated.
 boolean passToListener()
          Set true to pass the request up to the listener.
 void raiseIOExceptionEvent()
          Raise an IO Exception event - this is used for reporting asynchronous IO Exceptions that are attributable to this transaction.
 void releaseSem()
          Release the transaction semaphore.
 void removeEventListener(SIPTransactionEventListener oldListener)
          Removed an event listener from this transaction.
 void sendMessage(SIPMessage messageToSend)
          Process the message through the transaction and sends it to the SIP peer.
 void setApplicationData(Object applicationData)
          Set the application data pointer.
 void setBranch(String newBranch)
          Sets the Via header branch parameter used to identify this transaction.
abstract  void setDialog(SIPDialog sipDialog, String dialogId)
          set the dialog object.
 void setEncapsulatedChannel(MessageChannel messageChannel)
          Set the encapsuated channel.
 void setOriginalRequest(SIPRequest newOriginalRequest)
          Sets the request message that this transaction handles.
 void setPassToListener()
          Set the passToListener flag to true.
 void setRetransmitTimer(int retransmitTimer)
          Sets the value of the retransmit timer to the newly supplied timer value.
 void setState(TransactionState newState)
          Changes the state of this transaction.
 
Methods inherited from class gov.nist.javax.sip.stack.MessageChannel
getHostPort, getKey, getKey, getPeerHostPort, getRawIpSourceAddress, getViaHostPort, logResponse, sendMessage, sendMessage
 
Methods inherited from class java.lang.Object
equals, getClass, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface javax.sip.Transaction
terminate
 

Field Detail

auditTag

public long auditTag

INITIAL_STATE

public static final TransactionState INITIAL_STATE
Initialized but no state assigned.


TRYING_STATE

public static final TransactionState TRYING_STATE
Trying state.


CALLING_STATE

public static final TransactionState CALLING_STATE
CALLING State.


PROCEEDING_STATE

public static final TransactionState PROCEEDING_STATE
Proceeding state.


COMPLETED_STATE

public static final TransactionState COMPLETED_STATE
Completed state.


CONFIRMED_STATE

public static final TransactionState CONFIRMED_STATE
Confirmed state.


TERMINATED_STATE

public static final TransactionState TERMINATED_STATE
Terminated state.

Method Detail

getBranchId

public String getBranchId()
Description copied from interface: Transaction
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.

Specified by:
getBranchId in interface Transaction
Returns:
the new branch that uniquely identifies this transaction.

setOriginalRequest

public void setOriginalRequest(SIPRequest newOriginalRequest)
Sets the request message that this transaction handles.

Parameters:
newOriginalRequest - Request being handled.

getOriginalRequest

public SIPRequest getOriginalRequest()
Gets the request being handled by this transaction.

Returns:
-- the original Request associated with this transaction.

getRequest

public Request getRequest()
Get the original request but cast to a Request structure.

Specified by:
getRequest in interface Transaction
Returns:
the request that generated this transaction.

isInviteTransaction

public final boolean isInviteTransaction()
Returns a flag stating whether this transaction is for an INVITE request or not.

Returns:
-- true if this is an INVITE request, false if not.

isCancelTransaction

public final boolean isCancelTransaction()
Return true if the transaction corresponds to a CANCEL message.

Returns:
-- true if the transaciton is a CANCEL transaction.

isByeTransaction

public final boolean isByeTransaction()
Return a flag that states if this is a BYE transaction.

Returns:
true if the transaciton is a BYE transaction.

getMessageChannel

public MessageChannel getMessageChannel()
Returns the message channel used for transmitting/receiving messages for this transaction. Made public in support of JAIN dual transaction model.

Returns:
Encapsulated MessageChannel.

setBranch

public final void setBranch(String newBranch)
Sets the Via header branch parameter used to identify this transaction.

Parameters:
newBranch - New string used as the branch for this transaction.

getBranch

public final String getBranch()
Gets the current setting for the branch parameter of this transaction.

Returns:
Branch parameter for this transaction.

getMethod

public final String getMethod()
Get the method of the request used to create this transaction.

Returns:
the method of the request for the transaction.

getCSeq

public final long getCSeq()
Get the Sequence number of the request used to create the transaction.

Returns:
the cseq of the request used to create the transaction.

setState

public void setState(TransactionState newState)
Changes the state of this transaction.

Parameters:
newState - New state of this transaction.

getState

public TransactionState getState()
Gets the current state of this transaction.

Specified by:
getState in interface Transaction
Returns:
Current state of this transaction.

isTerminated

public final boolean isTerminated()
Tests if this transaction has terminated.

Returns:
Trus if this transaction is terminated, false if not.

getHost

public String getHost()
Description copied from class: MessageChannel
Get the host of this message channel.

Specified by:
getHost in interface TransactionExt
Overrides:
getHost in class MessageChannel
Returns:
host of this messsage channel.

getKey

public String getKey()
Description copied from class: MessageChannel
Generate a key which identifies the message channel. This allows us to cache the message channel.

Specified by:
getKey in class MessageChannel

getPort

public int getPort()
Description copied from class: MessageChannel
Get port of this message channel.

Specified by:
getPort in interface TransactionExt
Overrides:
getPort in class MessageChannel
Returns:
Port of this message channel.

getSIPStack

public SIPTransactionStack getSIPStack()
Description copied from class: MessageChannel
Get the SIPStack object from this message channel.

Specified by:
getSIPStack in class MessageChannel
Returns:
SIPStack object of this message channel

getPeerAddress

public String getPeerAddress()
Description copied from class: MessageChannel
Get the peer address of the machine that sent us this message.

Specified by:
getPeerAddress in interface TransactionExt
Specified by:
getPeerAddress in class MessageChannel
Returns:
a string contianing the ip address or host name of the sender of the message.

getPeerPort

public int getPeerPort()
Description copied from class: MessageChannel
Get the sender port ( the port of the other end that sent me the message).

Specified by:
getPeerPort in interface TransactionExt
Specified by:
getPeerPort in class MessageChannel
Returns:
the port of the upstream/downstream hop from which this message was initially received

getPeerPacketSourcePort

public int getPeerPacketSourcePort()
Specified by:
getPeerPacketSourcePort in class MessageChannel

getPeerPacketSourceAddress

public InetAddress getPeerPacketSourceAddress()
Specified by:
getPeerPacketSourceAddress in class MessageChannel

getTransport

public String getTransport()
Description copied from class: MessageChannel
Get transport string of this message channel.

Specified by:
getTransport in interface TransactionExt
Specified by:
getTransport in class MessageChannel
Returns:
Transport string of this message channel.

isReliable

public boolean isReliable()
Description copied from class: MessageChannel
Get whether this channel is reliable or not.

Specified by:
isReliable in class MessageChannel
Returns:
True if reliable, false if not.

getViaHeader

public Via getViaHeader()
Returns the Via header for this channel. Gets the Via header of the underlying message channel, and adds a branch parameter to it for this transaction.

Overrides:
getViaHeader in class MessageChannel
Returns:
a via header for outgoing messages sent from this channel.

sendMessage

public void sendMessage(SIPMessage messageToSend)
                 throws IOException
Process the message through the transaction and sends it to the SIP peer.

Specified by:
sendMessage in class MessageChannel
Parameters:
messageToSend - Message to send to the SIP peer.
Throws:
IOException

addEventListener

public void addEventListener(SIPTransactionEventListener newListener)
Adds a new event listener to this transaction.

Parameters:
newListener - Listener to add.

removeEventListener

public void removeEventListener(SIPTransactionEventListener oldListener)
Removed an event listener from this transaction.

Parameters:
oldListener - Listener to remove.

getDialog

public abstract Dialog getDialog()
Gets the dialog object of this Transaction object. This object returns null if no dialog exists. 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.

Specified by:
getDialog in interface Transaction
Returns:
the Dialog Object of this Transaction object.
See Also:
Dialog

setDialog

public abstract void setDialog(SIPDialog sipDialog,
                               String dialogId)
set the dialog object.

Parameters:
sipDialog - -- the dialog to set.
dialogId - -- the dialog id ot associate with the dialog.s

getRetransmitTimer

public int getRetransmitTimer()
Returns the current value of the retransmit timer in milliseconds used to retransmit messages over unreliable transports.

Specified by:
getRetransmitTimer in interface Transaction
Returns:
the integer value of the retransmit timer in milliseconds.

getViaHost

public String getViaHost()
Get the host to assign for an outgoing Request via header.

Specified by:
getViaHost in class MessageChannel

getLastResponse

public SIPResponse getLastResponse()
Get the last response. This is used internally by the implementation. Dont rely on it.

Returns:
the last response received (for client transactions) or sent (for server transactions).

getResponse

public Response getResponse()
Get the JAIN interface response


getTransactionId

public String getTransactionId()
Get the transaction Id.


hashCode

public int hashCode()
Hashcode method for fast hashtable lookup.

Overrides:
hashCode in class Object

getViaPort

public int getViaPort()
Get the port to assign for the via header of an outgoing message.

Specified by:
getViaPort in class MessageChannel

doesCancelMatchTransaction

public boolean doesCancelMatchTransaction(SIPRequest requestToTest)
A method that can be used to test if an incoming request belongs to this transction. This does not take the transaction state into account when doing the check otherwise it is identical to isMessagePartOfTransaction. This is useful for checking if a CANCEL belongs to this transaction.

Parameters:
requestToTest - is the request to test.
Returns:
true if the the request belongs to the transaction.

setRetransmitTimer

public void setRetransmitTimer(int retransmitTimer)
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. Take the gateway proxy as an example. The internal intranet is likely to be reatively uncongested and the endpoints will be relatively close. The external network is the general Internet. This functionality allows different retransmit times for either side.

Specified by:
setRetransmitTimer in interface Transaction
Parameters:
retransmitTimer - - the new integer value of the retransmit timer in milliseconds.

close

public void close()
Close the encapsulated channel.

Specified by:
close in class MessageChannel

isSecure

public boolean isSecure()
Description copied from class: MessageChannel
Return true if this is a secure channel.

Specified by:
isSecure in class MessageChannel

getMessageProcessor

public MessageProcessor getMessageProcessor()
Description copied from class: MessageChannel
Get the message processor.

Overrides:
getMessageProcessor in class MessageChannel

setApplicationData

public void setApplicationData(Object applicationData)
Set the application data pointer. This is un-interpreted by the stack. This is provided as a conveniant way of keeping book-keeping data for applications. Note that null clears the application data pointer (releases it).

Specified by:
setApplicationData in interface Transaction
Parameters:
applicationData - -- application data pointer to set. null clears the applicationd data pointer.

getApplicationData

public Object getApplicationData()
Get the application data associated with this transaction.

Specified by:
getApplicationData in interface Transaction
Returns:
stored application data.

setEncapsulatedChannel

public void setEncapsulatedChannel(MessageChannel messageChannel)
Set the encapsuated channel. The peer inet address and port are set equal to the message channel.


getSipProvider

public SipProviderImpl getSipProvider()
Return the SipProvider for which the transaction is assigned.

Specified by:
getSipProvider in interface TransactionExt
Returns:
the SipProvider for the transaction.

raiseIOExceptionEvent

public void raiseIOExceptionEvent()
Raise an IO Exception event - this is used for reporting asynchronous IO Exceptions that are attributable to this transaction.


acquireSem

public boolean acquireSem()
A given tx can process only a single outstanding event at a time. This semaphore gaurds re-entrancy to the transaction.


releaseSem

public void releaseSem()
Release the transaction semaphore.


passToListener

public boolean passToListener()
Set true to pass the request up to the listener. False otherwise.


setPassToListener

public void setPassToListener()
Set the passToListener flag to true.


isMessagePartOfTransaction

public abstract boolean isMessagePartOfTransaction(SIPMessage messageToTest)
Tests a message to see if it is part of this transaction.

Returns:
True if the message is part of this transaction, false if not.

NIST-SIP: The Reference Implementation for JAIN-SIP 1.2

A product of the NIST/ITL Advanced Networking Technologies Division.
See conditions of use.
Submit a bug report or feature request.