NIST SIP Parser and Stack (v1.2) API

gov.nist.javax.sip.stack
Class SIPStack

java.lang.Object
  |
  +--gov.nist.javax.sip.stack.SIPStack
Direct Known Subclasses:
SIPTransactionStack

public abstract class SIPStack
extends Object

This class defines a SIP Stack. In order to build a SIP server (UAS/UAC or Proxy etc.) you need to extend this class and instantiate it in your application. After you have done so, call createMessageProcessor to create message processors and then start these message processors to get the stack the process messages. This will start the necessary threads that wait for incoming SIP messages. A general note about the handler structures -- handlers are expected to returnResponse for successful message processing and throw SIPServerException for unsuccessful message processing.

Author:
M. Ranganathan
Acknowledgement: Marc Bednarek added code in support of firewall. Jeff Keyser suggested that MessageProcessors be accessible and applications should have control over message processors. This code is in the public domain. IPv6 Support added by Emil Ivov (emil_ivov@yahoo.com)
Network Research Team (http://www-r2.u-strasbg.fr))
Louis Pasteur University - Strasbourg - France

Field Summary
static int DEFAULT_PORT
          Default UDP port (5060)
 
Constructor Summary
SIPStack()
          Default constructor.
SIPStack(SIPStackMessageFactory messageFactory, String stackAddress, String stackName)
          Construcor for the stack.
SIPStack(SIPStackMessageFactory messageFactory, String stackAddress, String stackName, ChannelNotifier notifier)
          Construcor for the stack.
 
Method Summary
 void addMessageProcessor(MessageProcessor newMessageProcessor)
          Adds a new MessageProcessor to the list of running processors for this SIPStack and starts it.
 MessageChannel createMessageChannel(Hop nextHop)
          Creates a new MessageChannel for a given Hop.
 MessageProcessor createMessageProcessor(int port, String transport)
          Creates the equivalent of a JAIN listening point and attaches to the stack.
 void exportServerLog(String logRootName, int rmiPort, int lifetime)
          Export the Server Log for Access via RMI.
 String getBadMessageLog()
          Get the file name of the bad message log.
 Hop getDefaultRoute()
          Get the default route.
 Route getDefaultRouteHeader()
          Get the route header corresponding to the default route.
 String getHostAddress()
          Get my address.
 MessageProcessor getMessageProcessor(String transport)
          Get a message processor for the given transport.
 MessageProcessor[] getMessageProcessors()
          Gets an array of running MessageProcessors on this SIPStack.
 Hop getNextHop()
          Get the default next hop from the router.
 Iterator getNextHop(gov.nist.javax.sip.message.SIPRequest sipRequest)
          Get the default route string.
 int getPort(String transport)
          get port of the message processor (based on the transport).
 Route getRouteHeader(Hop hop)
          Get the route header for this hop.
 Router getRouter()
          Get the router algorithm.
 String getStackFunction()
          Get the stack function.
 String getStackName()
          Get the Stack name.
 boolean isAlive()
          return the status of the toExit flag.
 boolean isTransportEnabled(String transport)
          Return true if a transport is enabled.
 boolean isTransportEnabled(String transport, int port)
          Return true if the transport is enabled for a given port.
 void logBadMessage(String message)
          Log a bad message (invoked when a parse exception arises).
 void removeMessageProcessor(MessageProcessor oldMessageProcessor)
          Removes a MessageProcessor from this SIPStack.
 void setHostAddress(String stackAddress)
          Set my address.
 void setMaxConnections(int nconnections)
          Set the max # of simultaneously handled TCP connections.
 void setRouter(Router router)
          Set the router algorithm.
 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 setStackMessageFactory(SIPStackMessageFactory messageFactory)
          Set the server Request and response factories.
 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()
          Make the stack close all accept connections and return.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_PORT

public static final int DEFAULT_PORT
Default UDP port (5060)

See Also:
Constant Field Values
Constructor Detail

SIPStack

public SIPStack(SIPStackMessageFactory messageFactory,
                String stackAddress,
                String stackName,
                ChannelNotifier notifier)
         throws UnknownHostException
Construcor for the stack. Registers the request and response factories for the stack.

Parameters:
messageFactory - User-implemented factory for processing messages.
stackAddress - -- IP address or host name of the stack.
stackName - -- descriptive name for the stack.
notifier - -- Callback that gets invoked when a channel is closed. This is used primarily to notify when a tcp connection is closed.

SIPStack

public SIPStack(SIPStackMessageFactory messageFactory,
                String stackAddress,
                String stackName)
         throws UnknownHostException
Construcor for the stack. Registers the request and response factories for the stack.

Parameters:
messageFactory - User-implemented factory for processing messages.
stackAddress - -- IP address or host name of the stack.
stackName - -- descriptive name for the stack.

SIPStack

public SIPStack()
Default constructor.

Method Detail

logBadMessage

public void logBadMessage(String message)
Log a bad message (invoked when a parse exception arises).

Parameters:
message - is a string that contains the bad message to log.

getBadMessageLog

public String getBadMessageLog()
Get the file name of the bad message log.

Returns:
the file where bad messages are logged.

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). Caution: If the user-defined function called by the processing thread blocks, then the entire server will block. This feature was requested by Lamine Brahimi (IBM Zurich).


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. Caution: If the user-defined function called by the processing thread blocks, then the entire server will block.


setMaxConnections

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


getNextHop

public Iterator getNextHop(gov.nist.javax.sip.message.SIPRequest sipRequest)
Get the default route string.

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

setStackMessageFactory

public void setStackMessageFactory(SIPStackMessageFactory messageFactory)
Set the server Request and response factories.

Parameters:
messageFactory - User-implemented factory for processing messages.

setStackName

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

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

exportServerLog

public void exportServerLog(String logRootName,
                            int rmiPort,
                            int lifetime)
Export the Server Log for Access via RMI.

Parameters:
logRootName - - the root name to assign to the log.
rmiPort - - the rmi port for the rmi registry (usually 1099)
lifetime - - the number of seconds to hold on to the log.

getStackName

public String getStackName()
Get the Stack name.

Returns:
name of the stack.

setHostAddress

public void setHostAddress(String stackAddress)
                    throws UnknownHostException
Set my address.

Parameters:
stackAddress - -- A string containing the stack address.
UnknownHostException

getHostAddress

public String getHostAddress()
Get my address.

Returns:
hostAddress - my host address.

getNextHop

public Hop getNextHop()
Get the default next hop from the router.


getPort

public int getPort(String transport)
get port of the message processor (based on the transport). If multiple ports are enabled for the same transport then the first one is retrieved.

Parameters:
transport - is the transport for which to get the port.

isTransportEnabled

public boolean isTransportEnabled(String transport)
Return true if a transport is enabled.

Parameters:
transport - is the transport to check.

isTransportEnabled

public boolean isTransportEnabled(String transport,
                                  int port)
Return true if the transport is enabled for a given port.

Parameters:
transport - transport to check
port - port to check transport at.

setRouter

public void setRouter(Router router)
Set the router algorithm.

Parameters:
router - A class that implements the Router interface.

getRouter

public Router getRouter()
Get the router algorithm.

Returns:
Router router

getDefaultRoute

public Hop getDefaultRoute()
Get the default route.


getStackFunction

public String getStackFunction()
Get the stack function. A descriptive name that gives you the function of the stack.


getRouteHeader

public Route getRouteHeader(Hop hop)
Get the route header for this hop.

Returns:
the route header for the hop.

getDefaultRouteHeader

public Route getDefaultRouteHeader()
Get the route header corresponding to the default route.


isAlive

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

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

stopStack

public void stopStack()
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.


addMessageProcessor

public void addMessageProcessor(MessageProcessor newMessageProcessor)
                         throws IOException
Adds a new MessageProcessor to the list of running processors for this SIPStack and starts it. You can use this method for dynamic stack configuration. Acknowledgement: This code is contributed by Jeff Keyser.

IOException

removeMessageProcessor

public void removeMessageProcessor(MessageProcessor oldMessageProcessor)
Removes a MessageProcessor from this SIPStack. Acknowledgement: Code contributed by Jeff Keyser.

Parameters:
oldMessageProcessor -

getMessageProcessors

public MessageProcessor[] getMessageProcessors()
Gets an array of running MessageProcessors on this SIPStack. Acknowledgement: Jeff Keyser suggested that applications should have access to the running message processors and contributed this code.

Returns:
an array of running message processors.

getMessageProcessor

public MessageProcessor getMessageProcessor(String transport)
Get a message processor for the given transport.


createMessageProcessor

public MessageProcessor createMessageProcessor(int port,
                                               String transport)
                                        throws IOException
Creates the equivalent of a JAIN listening point and attaches to the stack.

IOException

createMessageChannel

public MessageChannel createMessageChannel(Hop nextHop)
                                    throws UnknownHostException
Creates a new MessageChannel for a given Hop.

Parameters:
nextHop - Hop to create a MessageChannel to.
Returns:
A MessageChannel to the specified Hop, or null if no MessageProcessors support contacting that Hop.
Throws:
UnknwonHostException - If the host in the Hop doesn't exist.
UnknownHostException

NIST SIP Parser and Stack (v1.2) API

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