gov.nist.javax.sip.stack
Class SIPTransactionStack

java.lang.Object
  gov.nist.javax.sip.stack.SIPTransactionStack

All Implemented Interfaces:

EventListener, SIPTransactionEventListener

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.61 $ $Date: 2006/11/02 21:17:54 $

Author:

M. Ranganathan

See Also:

SipStackImpl

Field Summary

static int	BASE_TIMER_INTERVAL
static int	CONNECTION_LINGER_TIME

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.
SIPClientTransaction	createClientTransaction(SIPRequest sipRequest, MessageChannel encapsulatedMessageChannel) Creates a client transaction that encapsulates a MessageChannel.
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(int sourcePort, Hop nextHop) Creates a new MessageChannel for a given Hop.
Server	createServerHeaderForStack() Create a standard Server header for the stack (i.e. one that takes the stack name as a product token) and return it.
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.
AddressResolver	getAddressResolver() get the address resolver interface.
SIPDialog	getDialog(String dialogId) Return the dialog for a given dialog ID.
Iterator	getDialogs() This is for debugging.
String	getHostAddress() Deprecated.
gov.nist.core.LogWriter	getLogWriter() Get the logger.
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.
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.
ServerLog	getServerLog() Server log is the place where we log messages for the signaling trace viewer.
gov.nist.core.ThreadAuditor	getThreadAuditor() get the thread auditor object
boolean	isAlive() return the status of the toExit flag.
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.
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.
void	printDialogTable() Print the dialog table.
void	putDialog(SIPDialog dialog) Put a dialog into the dialog 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	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	setMaxConnections(int nconnections) Set the max # of simultaneously handled TCP connections.
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	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	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

Method Detail

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.

getDialogs

public Iterator getDialogs()

This is for debugging.

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.

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.

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.

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.

getLogWriter

public gov.nist.core.LogWriter getLogWriter()

Get the logger.

Returns:

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

getServerLog

public ServerLog getServerLog()

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.

createServerHeaderForStack

public Server createServerHeaderForStack()

Create a standard Server header for the stack (i.e. one that takes the stack name as a product token) and return it.

Returns:

Server header for the stack. The server header is used in automatically generated responses.

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(int sourcePort,
                                              Hop nextHop)
                                       throws UnknownHostException

Creates a new MessageChannel for a given Hop.

Parameters:

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.

getThreadAuditor

public gov.nist.core.ThreadAuditor getThreadAuditor()

get the thread auditor object

Returns:

-- the thread auditor of the stack