NIST SIP Parser and Stack (v1.2) API

Package gov.nist.javax.sip.stack

This package contains the classes for building a SIP stack.

See:
          Description

Interface Summary
ChannelNotifier An object that provides notification back to the application on new channel creates and deletes.
Cleanable This interface must be implemented by object which require periodical cleaning by the Janitor
MessageLogTable A table for remote access of log records.
SIPServerRequestInterface An interface for a genereic message processor for SIP Request messages.
SIPServerResponseInterface An interface for a genereic message processor for SIP Response messages.
SIPStackMessageFactory An interface for generating new requests and responses.
SIPTimerListener Event listener for timeout events.
SIPTransactionEventListener Interface implemented by classes that want to be notified of asynchronous transacion events.
 

Class Summary
DefaultRouter This is the default router.
DialogImpl Tracks dialogs.
HopImpl Routing algorithms return a list of hops to which the request is routed.
IOHandler Class that is used for forwarding SIP requests.
Janitor This class is in charge of periodical cleaning.
MessageChannel Message channel abstraction for the SIP stack.
MessageLogList This class stores a sorted list messages for logging.
MessageProcessor This is the Stack abstraction for the active object that waits for messages to appear on the wire and processes these messages by calling the MessageFactory interface to create a ServerRequest or ServerResponse object.
ServerLog Log file wrapper class.
SIPClientTransaction Represents a client transaction.
SIPServerTransaction Represents a server transaction.
SIPStack This class defines a SIP Stack.
SIPTimerEvent  
SIPTransaction Abstract class to support both client and server transactions.
SIPTransactionErrorEvent An event that indicates that a transaction has encountered an error.
SIPTransactionStack Adds a transaction layer to the SIPStack class.
TCPMessageChannel This is stack for TCP connections.
TCPMessageProcessor Sit in a loop waiting for incoming tcp connections and start a new thread to handle each new connection.
UDPMessageChannel This is the UDP Message handler that gets created when a UDP message needs to be processed.
UDPMessageProcessor Sit in a loop and handle incoming udp datagram messages.
 

Exception Summary
SIPServerException Exception that gets generated when the Stack encounters an error.
 

Package gov.nist.javax.sip.stack Description

This package contains the classes for building a SIP stack. An incoming message is passed through the parser and generates a SIPServerRequestImp or SIPServerResponseImpl. These are interfaces that are implemented by the application. There are two main classes here. SIPStack: is quite simple and stripped down in its goals (for example, it does not provide any transaction support). It is essentially a messaging layer that utilizes the nist-sip parser and defines abstractions for message processing and I/O handling. The transaction layer is provided by SIPTransactionStack.

Operation of SIPStack

An application extends the SIPStack class in this package and is expected to implement the SIPMessageFactory, SIPServerRequest and SIPServerResponse interfaces. The message factory implementation is registered with the SIPStack class on initialization. When a message comes in, the stack calls the NIST-SIP message parser to process the request and then calls the Message Factory Implementation to create a new SIPServerRequest or SIPServerResponse (depending on whether the message was a request or response) and then calls processRequest on the created SIPServerRequest or SIPServerResponse. Here is pseudo-code that illustrates the flow of processing messages (for UDP):

while (true) {
   String messageString = messageChannel.read_incoming_message();
   SIPMessage parsed_message = 
		sipMessageParser.parseSIPMesage(messageString);
   sipMessageFactoryImpl.newSIPServerRequest(parsed_message);
}

The actual code implements the SIPMessageListener interface which has a callback method for erroneous messages. TCP Processing is a bit more complex because of the stream oriented nature of TCP. There is an architected means for dealing with extension headers by an application implementing the ExtensionParser interface that is part of this package. Such extension parsers are registered with the stack by using the SIPStack.registerExtensionParser method which specifies the extension header name and the parser for the extnsion header. If the header parses correctly, the application returns a class that subclasses SIPHeader and that specific to the extension header and if it does not parse correctly, the extension parser may throw a SIPParse exception. Extensions headers that are not recognized by the parser are stored in a list and can be retrieved by the application by calling the getExtensionHeaders method that returns a list of extension headers. Requests routing is handled by the SIPServerRequest handler. A routing algorithm may be specified by implementing the Route interface. A default routing algorithm that just forwards to a hard-coded proxy address is implemented in the DefaultRouter class. The stack supports logging of messages into a log file that can be specified on start-up. The log file is accessable remotely via RMI. The format of the log file is specified in XML. This facility is to be exploited for log file visualization. See tools.traceviewerapp for a visualization tool for log records.

Operation of SIPTransactionStack

SIPTransactionStack, is the stack you need to extend to build transaction-aware components. This implements a transaction layer for the SIP stack according to chapter 17 of RFC 3261. To implement transaction stateful components, you extend the SIPTransactionStack class and not the SIPStack class. To create a client transaction you create a transaction aware MessageChannel for the Hop returned from the router by calling Stack.createMessageChannel. A server transaction is created when an incoming request is fielded by the stack. It is passed to the application using the SIPServerRequest and SIPServerResponse interface which are defined in the gov.nist.javax.sip.stack package. The JAIN SIP statefull transaction layer is derived from the SIPTransactionStack herein. The transaction layer was contributed by Jeff Keyser.


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.