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

gov.nist.javax.sip.stack
Class SIPTransactionStack

java.lang.Object
  extended by gov.nist.javax.sip.stack.SIPTransactionStack
All Implemented Interfaces:
SIPTransactionEventListener, EventListener
Direct Known Subclasses:
SipStackImpl

public abstract class SIPTransactionStack
extends Object
implements SIPTransactionEventListener

This is the sip stack. It is essentially a management interface. It manages the resources for the JAIN-SIP implementation. This is the structure that is wrapped by the SipStackImpl.

Version:
1.2 $Revision: 1.116 $ $Date: 2009/08/19 03:14:21 $
Author:
M. Ranganathan
See Also:
SipStackImpl

Field Summary
static int BASE_TIMER_INTERVAL
           
static int CONNECTION_LINGER_TIME
           
 boolean logStackTraceOnMessageSend
           
 
Method Summary
 void addExtensionMethod(String extensionMethod)
          Add an extension method.
 void addTransaction(SIPClientTransaction clientTransaction)
          Add a new client transaction to the set of existing transactions.
 void addTransaction(SIPServerTransaction serverTransaction)
          Add a new server transaction to the set of existing transactions.
 String auditStack(Set activeCallIDs, long leakedDialogTimer, long leakedTransactionTimer)
          Audits the SIP Stack for leaks
 boolean checkBranchId()
          Flag that reqests checking of branch IDs on responses.
 SIPClientTransaction createClientTransaction(SIPRequest sipRequest, MessageChannel encapsulatedMessageChannel)
          Creates a client transaction that encapsulates a MessageChannel.
 SIPDialog createDialog(SIPClientTransaction transaction, SIPResponse sipResponse)
          Create a Dialog given a client tx and response.
 SIPDialog createDialog(SIPTransaction transaction)
          Create a dialog and add this transaction to it.
 MessageChannel createMessageChannel(SIPRequest request, MessageProcessor mp, Hop nextHop)
          Creates a client transaction to handle a new request.
 MessageChannel createRawMessageChannel(String sourceIpAddress, int sourcePort, Hop nextHop)
          Creates a new MessageChannel for a given Hop.
 SIPServerTransaction createServerTransaction(MessageChannel encapsulatedMessageChannel)
          Creates a server transaction that encapsulates a MessageChannel.
 void disableLogging()
          For debugging -- allows you to disable logging or enable logging selectively.
 void enableLogging()
          Globally enable message logging ( for debugging)
 SIPTransaction findCancelTransaction(SIPRequest cancelRequest, boolean isServer)
          Get the transaction to cancel.
 SIPServerTransaction findMergedTransaction(SIPRequest sipRequest)
          See if there is a pending transaction with the same Merge ID as the Merge ID obtained from the SIP Request.
 SIPServerTransaction findPendingTransaction(SIPRequest requestReceived)
          Finds a pending server transaction.
 SIPClientTransaction findSubscribeTransaction(SIPRequest notifyMessage, ListeningPointImpl listeningPoint)
          Find a matching client SUBSCRIBE to the incoming notify.
 SIPTransaction findTransaction(SIPMessage sipMessage, boolean isServer)
          Find the transaction corresponding to a given request.
 int getActiveClientTransactionCount()
          Get the count of client transactions that is not in the completed or terminated state.
 AddressResolver getAddressResolver()
          get the address resolver interface.
 int getClientTransactionTableSize()
          Get the size of the client transaction table.
 SIPDialog getDialog(String dialogId)
          Return the dialog for a given dialog ID.
 Collection<Dialog> getDialogs()
          This method is slated for addition to the next spec revision.
 Collection<Dialog> getDialogs(DialogState state)
           
 String getHostAddress()
          Deprecated.  
 Dialog getJoinDialog(JoinHeader joinHeader)
          Get the Join Dialog from the stack.
 int getMaxMessageSize()
          Maximum size of a single TCP message.
 NetworkLayer getNetworkLayer()
          Return the network layer (i.e. the interface for socket creation or the socket factory for the stack).
 Hop getNextHop(SIPRequest sipRequest)
          Get the default route string.
 int getReceiveUdpBufferSize()
          Size of the receive UDP buffer.
 Dialog getReplacesDialog(ReplacesHeader replacesHeader)
          Get the Replaced Dialog from the stack.
 SIPServerTransaction getRetransmissionAlertTransaction(String dialogId)
          Retrieve a transaction from our table of transactions with pending retransmission alerts.
 Router getRouter()
           
 Router getRouter(SIPRequest request)
          Get the router algorithm.
 int getSendUdpBufferSize()
          Size of the send UDP buffer.
 gov.nist.core.ServerLogger getServerLogger()
          Server log is the place where we log messages for the signaling trace viewer.
 gov.nist.core.StackLogger getStackLogger()
          Get the logger.
 gov.nist.core.ThreadAuditor getThreadAuditor()
          get the thread auditor object
 Timer getTimer()
           
 boolean isAlive()
          return the status of the toExit flag.
 boolean isCancelClientTransactionChecked()
           
 boolean isDialogCreated(String method)
          Return true if extension is supported.
 boolean isEventForked(String ename)
          Return true if a given event can result in a forked subscription.
 boolean isLoggingEnabled()
          Return true if logging is enabled for this stack.
 boolean isLooseDialogValidation()
          Delegate some dialog validation to the application.
 boolean isNon2XXAckPassedToListener()
           
 boolean isRemoteTagReassignmentAllowed()
           
 boolean isRfc2543Supported()
           
 void mapTransaction(SIPServerTransaction transaction)
          Map a Server transaction (possibly sending out a 100 if the server tx is an INVITE).
 ServerRequestInterface newSIPServerRequest(SIPRequest requestReceived, MessageChannel requestMessageChannel)
          Handles a new SIP request.
 SocketAddress obtainLocalAddress(InetAddress dst, int dstPort, InetAddress localAddress, int localPort)
          Creates and binds, if necessary, a socket connected to the specified destination address and port and then returns its local address.
 void printDialogTable()
          Print the dialog table.
 void putDialog(SIPDialog dialog)
          Put a dialog into the dialog table.
 void putInMergeTable(SIPServerTransaction sipTransaction, SIPRequest sipRequest)
          Put this into the merge request table.
 void putPendingTransaction(SIPServerTransaction tr)
          Put a transaction in the pending transaction list.
 void removeDialog(SIPDialog dialog)
          Remove the dialog from the dialog table.
 void removeDialog(String dialogId)
          Remove the dialog given its dialog id.
 void removeFromMergeTable(SIPServerTransaction tr)
          Remove a transaction from the merge table.
 void removePendingTransaction(SIPServerTransaction tr)
          Remove a pending Server transaction from the stack.
 void removeTransaction(SIPTransaction sipTransaction)
          Remove transaction.
 void setAddressResolver(AddressResolver addressResolver)
          Set the address resolution interface
 void setLogRecordFactory(LogRecordFactory logRecordFactory)
          Set the logger factory.
 void setLooseDialogValidation(boolean looseDialogValidation)
          Set to true if you want to delegate some dialog validation to the application.
 void setMaxConnections(int nconnections)
          Set the max # of simultaneously handled TCP connections.
 void setNon2XXAckPassedToListener(boolean passToListener)
           
 void setReceiveUdpBufferSize(int receiveUdpBufferSize)
          Size of the receive UDP buffer.
 void setSendUdpBufferSize(int sendUdpBufferSize)
          Size of the send UDP buffer.
 void setSingleThreaded()
          Set the flag that instructs the stack to only start a single thread for sequentially processing incoming udp messages (thus serializing the processing).
 void setStackLogger(gov.nist.core.StackLogger stackLogger)
           
 void setStackName(String stackName)
          Set the descriptive name of the stack.
 void setThreadPoolSize(int size)
          Set the thread pool size for processing incoming UDP messages.
 void setTimer(Timer timer)
           
 void stopStack()
          Stop stack.
 void transactionErrorEvent(SIPTransactionErrorEvent transactionErrorEvent)
          Invoked when an error has ocurred with a transaction.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BASE_TIMER_INTERVAL

public static final int BASE_TIMER_INTERVAL
See Also:
Constant Field Values

CONNECTION_LINGER_TIME

public static final int CONNECTION_LINGER_TIME
See Also:
Constant Field Values

logStackTraceOnMessageSend

public boolean logStackTraceOnMessageSend
Method Detail

obtainLocalAddress

public SocketAddress obtainLocalAddress(InetAddress dst,
                                        int dstPort,
                                        InetAddress localAddress,
                                        int localPort)
                                 throws IOException
Creates and binds, if necessary, a socket connected to the specified destination address and port and then returns its local address.

Parameters:
dst - the destination address that the socket would need to connect to.
dstPort - the port number that the connection would be established with.
localAddress - the address that we would like to bind on (null for the "any" address).
localPort - the port that we'd like our socket to bind to (0 for a random port).
Returns:
the SocketAddress that this handler would use when connecting to the specified destination address and port.
Throws:
IOException

disableLogging

public void disableLogging()
For debugging -- allows you to disable logging or enable logging selectively.


enableLogging

public void enableLogging()
Globally enable message logging ( for debugging)


printDialogTable

public void printDialogTable()
Print the dialog table.


getRetransmissionAlertTransaction

public SIPServerTransaction getRetransmissionAlertTransaction(String dialogId)
Retrieve a transaction from our table of transactions with pending retransmission alerts.

Parameters:
dialogId -
Returns:
-- the RetransmissionAlert enabled transaction corresponding to the given dialog ID.

isDialogCreated

public boolean isDialogCreated(String method)
Return true if extension is supported.

Returns:
true if extension is supported and false otherwise.

addExtensionMethod

public void addExtensionMethod(String extensionMethod)
Add an extension method.

Parameters:
extensionMethod - -- extension method to support for dialog creation

putDialog

public void putDialog(SIPDialog dialog)
Put a dialog into the dialog table.

Parameters:
dialog - -- dialog to put into the dialog table.

createDialog

public SIPDialog createDialog(SIPTransaction transaction)
Create a dialog and add this transaction to it.

Parameters:
transaction - -- tx to add to the dialog.
Returns:
the newly created Dialog.

createDialog

public SIPDialog createDialog(SIPClientTransaction transaction,
                              SIPResponse sipResponse)
Create a Dialog given a client tx and response.

Parameters:
transaction -
sipResponse -
Returns:

removeDialog

public void removeDialog(SIPDialog dialog)
Remove the dialog from the dialog table.

Parameters:
dialog - -- dialog to remove.

getDialog

public SIPDialog getDialog(String dialogId)
Return the dialog for a given dialog ID. If compatibility is enabled then we do not assume the presence of tags and hence need to add a flag to indicate whether this is a server or client transaction.

Parameters:
dialogId - is the dialog id to check.

removeDialog

public void removeDialog(String dialogId)
Remove the dialog given its dialog id. This is used for dialog id re-assignment only.

Parameters:
dialogId - is the dialog Id to remove.

findSubscribeTransaction

public SIPClientTransaction findSubscribeTransaction(SIPRequest notifyMessage,
                                                     ListeningPointImpl listeningPoint)
Find a matching client SUBSCRIBE to the incoming notify. NOTIFY requests are matched to such SUBSCRIBE requests if they contain the same "Call-ID", a "To" header "tag" parameter which matches the "From" header "tag" parameter of the SUBSCRIBE, and the same "Event" header field. Rules for comparisons of the "Event" headers are described in section 7.2.1. If a matching NOTIFY request contains a "Subscription-State" of "active" or "pending", it creates a new subscription and a new dialog (unless they have already been created by a matching response, as described above).

Parameters:
notifyMessage -
Returns:
-- the matching ClientTransaction with semaphore aquired or null if no such client transaction can be found.

findTransaction

public SIPTransaction findTransaction(SIPMessage sipMessage,
                                      boolean isServer)
Find the transaction corresponding to a given request.

Parameters:
sipMessage - request for which to retrieve the transaction.
isServer - search the server transaction table if true.
Returns:
the transaction object corresponding to the request or null if no such mapping exists.

findCancelTransaction

public SIPTransaction findCancelTransaction(SIPRequest cancelRequest,
                                            boolean isServer)
Get the transaction to cancel. Search the server transaction table for a transaction that matches the given transaction.


findPendingTransaction

public SIPServerTransaction findPendingTransaction(SIPRequest requestReceived)
Finds a pending server transaction. Since each request may be handled either statefully or statelessly, we keep a map of pending transactions so that a duplicate transaction is not created if a second request is recieved while the first one is being processed.

Parameters:
requestReceived -
Returns:
-- the pending transaction or null if no such transaction exists.

findMergedTransaction

public SIPServerTransaction findMergedTransaction(SIPRequest sipRequest)
See if there is a pending transaction with the same Merge ID as the Merge ID obtained from the SIP Request. The Merge table is for handling the following condition: If the request has no tag in the To header field, the UAS core MUST check the request against ongoing transactions. If the From tag, Call-ID, and CSeq exactly match those associated with an ongoing transaction, but the request does not match that transaction (based on the matching rules in Section 17.2.3), the UAS core SHOULD generate a 482 (Loop Detected) response and pass it to the server transaction.


removePendingTransaction

public void removePendingTransaction(SIPServerTransaction tr)
Remove a pending Server transaction from the stack. This is called after the user code has completed execution in the listener.

Parameters:
tr - -- pending transaction to remove.

removeFromMergeTable

public void removeFromMergeTable(SIPServerTransaction tr)
Remove a transaction from the merge table.

Parameters:
tr - -- the server transaction to remove from the merge table.

putInMergeTable

public void putInMergeTable(SIPServerTransaction sipTransaction,
                            SIPRequest sipRequest)
Put this into the merge request table.

Parameters:
sipTransaction - -- transaction to put into the merge table.

mapTransaction

public void mapTransaction(SIPServerTransaction transaction)
Map a Server transaction (possibly sending out a 100 if the server tx is an INVITE). This actually places it in the hash table and makes it known to the stack.

Parameters:
transaction - -- the server transaction to map.

newSIPServerRequest

public ServerRequestInterface newSIPServerRequest(SIPRequest requestReceived,
                                                  MessageChannel requestMessageChannel)
Handles a new SIP request. It finds a server transaction to handle this message. If none exists, it creates a new transaction.

Parameters:
requestReceived - Request to handle.
requestMessageChannel - Channel that received message.
Returns:
A server transaction.

createMessageChannel

public MessageChannel createMessageChannel(SIPRequest request,
                                           MessageProcessor mp,
                                           Hop nextHop)
                                    throws IOException
Creates a client transaction to handle a new request. Gets the real message channel from the superclass, and then creates a new client transaction wrapped around this channel.

Parameters:
nextHop - Hop to create a channel to contact.
Throws:
IOException

createClientTransaction

public SIPClientTransaction createClientTransaction(SIPRequest sipRequest,
                                                    MessageChannel encapsulatedMessageChannel)
Creates a client transaction that encapsulates a MessageChannel. Useful for implementations that want to subclass the standard

Parameters:
encapsulatedMessageChannel - Message channel of the transport layer.

createServerTransaction

public SIPServerTransaction createServerTransaction(MessageChannel encapsulatedMessageChannel)
Creates a server transaction that encapsulates a MessageChannel. Useful for implementations that want to subclass the standard

Parameters:
encapsulatedMessageChannel - Message channel of the transport layer.

getClientTransactionTableSize

public int getClientTransactionTableSize()
Get the size of the client transaction table.

Returns:
-- size of the ct table.

addTransaction

public void addTransaction(SIPClientTransaction clientTransaction)
Add a new client transaction to the set of existing transactions. Add it to the top of the list so an incoming response has less work to do in order to find the transaction.

Parameters:
clientTransaction - -- client transaction to add to the set.

removeTransaction

public void removeTransaction(SIPTransaction sipTransaction)
Remove transaction. This actually gets the tx out of the search structures which the stack keeps around. When the tx


addTransaction

public void addTransaction(SIPServerTransaction serverTransaction)
                    throws IOException
Add a new server transaction to the set of existing transactions. Add it to the top of the list so an incoming ack has less work to do in order to find the transaction.

Parameters:
serverTransaction - -- server transaction to add to the set.
Throws:
IOException

transactionErrorEvent

public void transactionErrorEvent(SIPTransactionErrorEvent transactionErrorEvent)
Invoked when an error has ocurred with a transaction.

Specified by:
transactionErrorEvent in interface SIPTransactionEventListener
Parameters:
transactionErrorEvent - Error event.

stopStack

public void stopStack()
Stop stack. Clear all the timer stuff. Make the stack close all accept connections and return. This is useful if you want to start/stop the stack several times from your application. Caution : use of this function could cause peculiar bugs as messages are prcessed asynchronously by the stack.


putPendingTransaction

public void putPendingTransaction(SIPServerTransaction tr)
Put a transaction in the pending transaction list. This is to avoid a race condition when a duplicate may arrive when the application is deciding whether to create a transaction or not.


getNetworkLayer

public NetworkLayer getNetworkLayer()
Return the network layer (i.e. the interface for socket creation or the socket factory for the stack).

Returns:
-- the registered Network Layer.

isLoggingEnabled

public boolean isLoggingEnabled()
Return true if logging is enabled for this stack.

Returns:
true if logging is enabled for this stack instance.

getStackLogger

public gov.nist.core.StackLogger getStackLogger()
Get the logger.

Returns:
--the logger for the sip stack. Each stack has its own logger instance.

getServerLogger

public gov.nist.core.ServerLogger getServerLogger()
Server log is the place where we log messages for the signaling trace viewer.

Returns:
-- the log file where messages are logged for viewing by the trace viewer.

getMaxMessageSize

public int getMaxMessageSize()
Maximum size of a single TCP message. Limiting the size of a single TCP message prevents flooding attacks.

Returns:
the size of a single TCP message.

setSingleThreaded

public void setSingleThreaded()
Set the flag that instructs the stack to only start a single thread for sequentially processing incoming udp messages (thus serializing the processing). Same as setting thread pool size to 1.


setThreadPoolSize

public void setThreadPoolSize(int size)
Set the thread pool size for processing incoming UDP messages. Limit the total number of threads for processing udp messages.

Parameters:
size - -- the thread pool size.

setMaxConnections

public void setMaxConnections(int nconnections)
Set the max # of simultaneously handled TCP connections.

Parameters:
nconnections - -- the number of connections to handle.

getNextHop

public Hop getNextHop(SIPRequest sipRequest)
               throws SipException
Get the default route string.

Parameters:
sipRequest - is the request for which we want to compute the next hop.
Throws:
SipException

setStackName

public void setStackName(String stackName)
Set the descriptive name of the stack.

Parameters:
stackName - -- descriptive name of the stack.

getHostAddress

public String getHostAddress()
Deprecated. 

Get my address.

Returns:
hostAddress - my host address or null if no host address is defined.

getRouter

public Router getRouter(SIPRequest request)
Get the router algorithm.

Returns:
Router router

getRouter

public Router getRouter()

isAlive

public boolean isAlive()
return the status of the toExit flag.

Returns:
true if the stack object is alive and false otherwise.

createRawMessageChannel

public MessageChannel createRawMessageChannel(String sourceIpAddress,
                                              int sourcePort,
                                              Hop nextHop)
                                       throws UnknownHostException
Creates a new MessageChannel for a given Hop.

Parameters:
sourceIpAddress - - Ip address of the source of this message.
sourcePort - - source port of the message channel to be created.
nextHop - Hop to create a MessageChannel to.
Returns:
A MessageChannel to the specified Hop, or null if no MessageProcessors support contacting that Hop.
Throws:
UnknownHostException - If the host in the Hop doesn't exist.

isEventForked

public boolean isEventForked(String ename)
Return true if a given event can result in a forked subscription. The stack is configured with a set of event names that can result in forked subscriptions.

Parameters:
ename - -- event name to check.

getAddressResolver

public AddressResolver getAddressResolver()
get the address resolver interface.

Returns:
-- the registered address resolver.

setAddressResolver

public void setAddressResolver(AddressResolver addressResolver)
Set the address resolution interface

Parameters:
addressResolver - -- the address resolver to set.

setLogRecordFactory

public void setLogRecordFactory(LogRecordFactory logRecordFactory)
Set the logger factory.

Parameters:
logRecordFactory - -- the log record factory to set.

getThreadAuditor

public gov.nist.core.ThreadAuditor getThreadAuditor()
get the thread auditor object

Returns:
-- the thread auditor of the stack

auditStack

public String auditStack(Set activeCallIDs,
                         long leakedDialogTimer,
                         long leakedTransactionTimer)
Audits the SIP Stack for leaks

Returns:
Audit report, null if no leaks were found

setNon2XXAckPassedToListener

public void setNon2XXAckPassedToListener(boolean passToListener)

isNon2XXAckPassedToListener

public boolean isNon2XXAckPassedToListener()
Returns:
the non2XXAckPassedToListener

getActiveClientTransactionCount

public int getActiveClientTransactionCount()
Get the count of client transactions that is not in the completed or terminated state.

Returns:
the activeClientTransactionCount

isRfc2543Supported

public boolean isRfc2543Supported()

isCancelClientTransactionChecked

public boolean isCancelClientTransactionChecked()

isRemoteTagReassignmentAllowed

public boolean isRemoteTagReassignmentAllowed()

getDialogs

public Collection<Dialog> getDialogs()
This method is slated for addition to the next spec revision.

Returns:
-- the collection of dialogs that is being managed by the stack.

getDialogs

public Collection<Dialog> getDialogs(DialogState state)
Returns:
-- the collection of dialogs matching the state that is being managed by the stack.

getReplacesDialog

public Dialog getReplacesDialog(ReplacesHeader replacesHeader)
Get the Replaced Dialog from the stack.

Parameters:
replacesHeader - -- the header that references the dialog being replaced.

getJoinDialog

public Dialog getJoinDialog(JoinHeader joinHeader)
Get the Join Dialog from the stack.

Parameters:
joinHeader - -- the header that references the dialog being joined.

setTimer

public void setTimer(Timer timer)
Parameters:
timer - the timer to set

getTimer

public Timer getTimer()
Returns:
the timer

isLooseDialogValidation

public boolean isLooseDialogValidation()
Delegate some dialog validation to the application.

Returns:

setLooseDialogValidation

public void setLooseDialogValidation(boolean looseDialogValidation)
Set to true if you want to delegate some dialog validation to the application.

Parameters:
looseDialogValidation -

getReceiveUdpBufferSize

public int getReceiveUdpBufferSize()
Size of the receive UDP buffer. This property affects performance under load. Bigger buffer is better under load.

Returns:

setReceiveUdpBufferSize

public void setReceiveUdpBufferSize(int receiveUdpBufferSize)
Size of the receive UDP buffer. This property affects performance under load. Bigger buffer is better under load.


getSendUdpBufferSize

public int getSendUdpBufferSize()
Size of the send UDP buffer. This property affects performance under load. Bigger buffer is better under load.

Returns:

setSendUdpBufferSize

public void setSendUdpBufferSize(int sendUdpBufferSize)
Size of the send UDP buffer. This property affects performance under load. Bigger buffer is better under load.


setStackLogger

public void setStackLogger(gov.nist.core.StackLogger stackLogger)
Parameters:
stackLogger - the stackLogger to set

checkBranchId

public boolean checkBranchId()
Flag that reqests checking of branch IDs on responses.

Returns:

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.