Package org.echarts.servlet.sip.appRouter.DFCRouterImpl

The DFCRouterImpl package contains Java classes to implement an application router that patterns its behavior after the router described in the Distributed Feature Composition (DFC) architecture.

See:
Description

Interface Summary

Address

This interface specifies the abstract concept of an address as considered by the application router implementation.

Class Summary

AddressPattern	The AddressPattern class encapsulates a regular expression that establishes a pattern against which addresses are evaluated for a match.
Application	Represents the DFC abstract notion of an application.
OriginatingAddress	This class represents an originating address as derived from a SipServletRequest.
OriginatingPrecedenceComparator	This class provides a comparator for comparing two originating region applications.
Precedence	The Precedence class represents a container class that holds all the precedence rule sets for both the originating and terminating regions.
PrecedencePair	This class encapsulates a pair of applications with a precedence relationship between them.
PrecedenceRules	This class encapsulates the complete set of precedence rule pairs that dictate the overall partial ordering among applications within a given routing region (either originating or terminating).
RouterConfiguration	This class is a container class holding the overall DFC router configuration.
RouteSet	The RouteSet class represents a mapping between a particular address and the corresponding ordered set of applications to which the address subscribes.
SipApplicationDFCRouterImpl	This class is the top level class that constitutes the Distributed Feature Composition (DFC) Application Router implementation.
SipApplicationDFCRouterProvider	Provider class that instantiate the DFC Application Router.
StateInfo	The StateInfo class represents a set of information that the DFC router implementation wishes to be persistent and associated with an initial request.
Subscription	This class is a wrapper for the set of applications that make up a subscription.
SubscriptionRules	This class provides a mapping between AddressPattern and Subscription objects
TerminatingAddress	Wrapper class defining DFC Router terminating (aka target) address.
TerminatingPrecedenceComparator	This class provides a comparator for comparing two terminating region applications.

Package org.echarts.servlet.sip.appRouter.DFCRouterImpl Description

The DFCRouterImpl package contains Java classes to implement an application router that patterns its behavior after the router described in the Distributed Feature Composition (DFC) architecture. This implementation adheres to the Application Router API as proposed in the SIP Servlet API 1.1 (JSR289) expert group.

As with any application router implementation adhering to the SIP Servlet API 1.1 (SSAPI-1.1), the DFCRouterImpl application router implements the SipApplicationRouter interface. Because this application router operates using a JSR116 adaptation layer, the actual interface implemented here is in the org.echarts.servlet.sip.appRouter package rather than the javax.servlet.sip package as will be the case for a JSR289 compliant container.

The main method in the SipApplicationRouter interface is the getNextApplication() method. The container/adaptation layer calls this method when it receives an initial request and wishes to know what SIP Servlet application to invoke next. The application router supplies the name of the next application along with other important information in the SipApplicationRouterInfo object returned to the container.

At a high level, the DFC application router implementation (hereafter, simply 'application router') works as follows.

1. When initialized, it reads and parses a XML file that provides the application router with its configuration. This file is often called, approuter.xml. It contains sections that define the precedence relationship among SIP Servlet applications along with subscription rules that map address patterns (regular expressions) to list of applications that are to be invoked for addresses matching the patterns. Since SIP URIs are case insensitive, matches are performed in a case-insensitive manner. A sample of such a router configuration file is provided and is named, approuter.sample.xml.
2. When the application router's getNextApplication() method is called by the container, the application router first looks to see if the region is already set. The routing region is one of {ORIGINATING, TERMINATING} where the ORIGINATING region is used for the invocation of the calling party's applications, and the TERMINATING region is used for the called party's applications. The calling party's applications are invoked first so if the region isn't set, the region is set by the application router to ORIGINATING. In DFC, these regions are called the source and target regions.
3. The application router then examines the routing directive as set by the application that created or proxied this initial request. This directive is always either NEW or CONTINUE. For initial requests that newly received by the container, the directive is set to NEW. Otherwise, the last visited application may set the directive to either NEW or CONTINUE. SIP Servlet applications acting as SIP proxies must always set the directive to CONTINUE.
4. If the directive is NEW, the application router builds a new route set. The route set is the ordered list of applications that should be invoked to service the initial request. In the ORIGINATING region, the application router builds the route set by first extracting the SIP message From header value from the message. This address constitutes the originating address and is now compared with the originating region's subscription rules. For each address pattern that matches the originating address, the list of applications named in the subscription rule is added to the route set. After all subscribed applications are assembled, the set is sorted into order according to the originating region precedence rules.
5. In the TERMINATING region, building a route set proceeds in much the same way except that the terminating address is defined to be the Request-URI of the SIP message rather than the contents of the From header and the subscription and precedence rules used are those for the terminating rather than the originating region.
6. Once having built the route set, the application router identifies the first element of the route set as the next application to be invoked. When returning the name of the next application to the container for invocation, the application router also returns a StateInfo object that is opaque state information maintained by the container and passed back to the application router if/when this initial request comes back to the application router. In this implementation, the information stored in the state information is the address (originating or terminating) that was used to build the route set and the remainder of the route set, that is, the originally calculated route set minus the first application name.
7. If the directive is CONTINUE, it means that the application router has seen this initial request previously and the previously stored state information is thus present. Since the route set was previously calculated and was stored in the state information object, the application router may be able to simply identify the next application name from the route set as the next application to be invoked, remove that name from the route set, reset the state information appropriately and be done. However, this optimization is possible only if the relevant address that now appears in the message has not changed since the previous invocation. That is, if routing is happening in the ORIGINATING region, then the value of the From header must be checked to see if it has changed from the last time the application router saw this request. Similarly, if in the TERMINATING region, then the Request-URI must be checked to see if it has changed. The application router is able to check for changes in the originating or terminating address because it also stored the previous address in the state information that it previously passed back to the container to be associated with this request.
8. If the address has changed from when the application router last saw this initial request, then the application router must recalculate the route set based on the new address.
9. At some point in the routing procedure, the application router will determine that the route set is empty and there are therefore no more applications to be invoked. If routing is occurring in the ORIGINATING region when this happens, this application router changes the region to TERMINATING and calculates a new route set in that region. If the routing region is TERMINATING, the application router returns null as the next application name and the container becomes responsible for routing the request externally based on standard SIP protocol request routing.