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.
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.
MessageChannel	Message channel abstraction for the SIP stack.
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.