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.