org.mobicents.servlet.sip.router

Class DefaultApplicationRouter

java.lang.Object

org.mobicents.servlet.sip.router.DefaultApplicationRouter

All Implemented Interfaces:

SipApplicationRouter, ManageableApplicationRouter

public class DefaultApplicationRouter
extends Object
implements SipApplicationRouter, ManageableApplicationRouter

Implementation of the default application router as defined per JSR 289 Appendix C

As an application router component is essential for the functioning of the container the following application router logic SHOULD be available with every container compliant with this specification. The container implementations MAY chose to provide a much richer application router component. For the purpose of this discussion the application router defined in this appendix is termed as Default Application Router (DAR).

The Application Router and the Container have a simple contract defined by the SipApplicationRouter interface.
The DAR MUST implement all the methods of that interface as described in this document.

The DAR Configuration File
The DAR works off a simple configuration text file which is modeled as a Java properties file:

• The properties file MUST be made available to the DAR and the location/content of this file MUST be accessible from a hierarchical URI which itself is to be supplied as a system property "javax.servlet.sip.dar"
• The propeties file has a simple format in which the name of the property is the SIP method and the value is a simple comma separated stringified value for the SipRouterInfo object.

         INVITE: (sip-router-info-1), (sip-router-info-2)..
         SUBSCRIBE:  (sip-router-info-3), (sip-router-info-4)..
   

• The properties file is first read by the DAR when the init() is first called on the DAR. The arguments passed in the init() are ignored.
• The properties file is refreshed each time applicationDeployed() or applicationUndeployed() is called, similar to init the argument of these two invocations are ignored, these callbacks act just as a trigger to read the file afresh.

The sip-router-info data that goes in the properties file is a stringified version of the SipRouterInfo object. It consists of the following information :

• The name of the application as known to the container
• The identity of the subscriber that the DAR returns. It can return any header in the SIP request using the DAR directive DAR:SIP_HEADER e.g "DAR:From" would return the sip uri in From header. Or alternatively it can return any string.
• The routing region, one of the strings "ORIGINATING", "TERMINATING" or "NEUTRAL"
• A SIP URI indicating the route as returned by the application route, it can be an empty string.
• A route modifier which can be any one of the strings "ROUTE", "NO_ROUTE", or "CLEAR_ROUTE"
• A string representing stateInfo. As stateInfo is for application router's internal use only, what goes in this is up to the individual DAR implementations. As a hint the stateInfo could contain the index into the list of sip-router-info that was returned last.

Following is an example of the DAR configuration file:

  INVITE: ("OriginatingCallWaiting", "DAR:From", "ORIGINATING", "",
  "NO_ROUTE", "0"), ("CallForwarding", "DAR:To", "TERMINATING", "",
  NO_ROUTE", "1")
 

In this example the DAR is setup to invoke two applications on INVITE request one each in the originating and the terminating half. The applications are identified by their names as defined in the application deployment descriptors and used here. The subscriber identity returned in this case is the URI from the From and To header respectively for the two applications. The DAR does not return any route to the container and maintains the invocation state in the stateInfo as the index of the last application in the list.

The DAR Operation
The key interaction point between the Container and the Application Router is the method

 SipApplicationRouterInfo getNextApplication(SipServletRequest initialRequest, SipApplicationRoutingRegion region,
         SipApplicationRoutingDirective directive, java.lang.String stateInfo);
 

This method is invoked when an initial request is received by the container. When this method is invoked on DAR it will make use of the stateInfo and the initialRequest parameters and find out what SIP method is in the request. Next it will create the object SipApplicationRouterInfo from the sip-router-info information in the properties file, starting from the first in the list. The stateInfo could contain the index of the last sip-router-info returned so on next invocation of getNextApplication the DAR proceeds to the next sip-router- info in the list. The order of declaration of sip-router-info becomes the priority order of invocation.

As you would notice this is a minimalist application router with no processing logic besides the declaration of the application order. It is expected that in the real world deployments the application router shall play an extremely important role in application orchestration and composition and shall make use of complex rules and diverse data repositories. The DAR is specified as being a very simple implementation that shall be available as part of the reference implementation of this specification and can be used in place of an application router.

Constructor Summary

Constructors

Constructor and Description
DefaultApplicationRouter() Default Constructor

Method Summary

Methods

Modifier and Type	Method and Description
void	applicationDeployed(List<String> newlyDeployedApplicationNames)
void	applicationUndeployed(List<String> undeployedApplicationNames)
void	configure(Object configuration)
void	destroy()
Map<String,List<? extends SipApplicationRouterInfo>>	getConfiguration()
Object	getCurrentConfiguration()
SipApplicationRouterInfo	getNextApplication(SipServletRequest initialRequest, SipApplicationRoutingRegion region, SipApplicationRoutingDirective directive, SipTargetedRequestInfo targetedRequestInfo, Serializable stateInfo)
void	init() load the configuration file as defined in appendix C of JSR289
void	init(Properties properties)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultApplicationRouter

public DefaultApplicationRouter()

Default Constructor

Method Detail

applicationDeployed

public void applicationDeployed(List<String> newlyDeployedApplicationNames)

Specified by:

applicationDeployed in interface SipApplicationRouter

applicationUndeployed

public void applicationUndeployed(List<String> undeployedApplicationNames)

Specified by:

applicationUndeployed in interface SipApplicationRouter

destroy

public void destroy()

Specified by:

destroy in interface SipApplicationRouter

getNextApplication

public SipApplicationRouterInfo getNextApplication(SipServletRequest initialRequest,
                                          SipApplicationRoutingRegion region,
                                          SipApplicationRoutingDirective directive,
                                          SipTargetedRequestInfo targetedRequestInfo,
                                          Serializable stateInfo)

Specified by:

getNextApplication in interface SipApplicationRouter

init

public void init()

load the configuration file as defined in appendix C of JSR289

Specified by:

init in interface SipApplicationRouter

init

public void init(Properties properties)

Specified by:

init in interface SipApplicationRouter

configure

public void configure(Object configuration)

Specified by:

configure in interface ManageableApplicationRouter

getCurrentConfiguration

public Object getCurrentConfiguration()

Specified by:

getCurrentConfiguration in interface ManageableApplicationRouter

getConfiguration

public Map<String,List<? extends SipApplicationRouterInfo>> getConfiguration()

Specified by:

getConfiguration in interface ManageableApplicationRouter