Search
The Open Source SLEE and SIP Server

Mobicents Sip Servlets

Default Application Router

This page is obsolete : More detailed and better looking installation instructions are available from the Mobicents Sip Servlets User Guide

Role of the Application router

The Application Router is called by the container to select a SIP servlet application to service an initial request.
It embodies the logic used to choose which applications to invoke.
An Application Router is required for a container to function, but it is a separate logical entity from the container.  The Application Router is solely responsible for application selection and must not implement application logic.
For example, the Application Router cannot modify a request or send a response.

The Application Router implements the SipApplicationRouter interface, which defines the API between the container and the Application Router.  There is no direct interaction between the Application Router and applications.
It is also important to note that, besides the information passed by the container, the Application Router is free to make use of any other information or data stores.  How it accesses that information and what information it makes use of is a matter of its implementation and is not defined in the Sip Servlets 1.1 specification.

The role of the deployer is defined in the Servlet API :

The deployer in a SIP servlet environment controls application composition by defining and deploying the Application Router implementation.  Giving the deployer control over application composition is desirable because it is the deployer who is most aware of and responsible for the totality of services provided to his or her subscribers. Furthermore, this specification intentionally allows the Application Router implementation to consult arbitrary information or data stores.  This is because the deployer maintains subscriber information and this information is often private and valuable.

Default Application Router

Mobicents Sip Servlets provides an implementation of the Default Application Router (DAR) as defined per Sip Servlets 1.1 specification, Appendix C.

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.ar.dar.configuration".
    In the case of Mobicents Sip Servlets, it is also possible to configure it through the server.xml configuration file (See the Configuration Section for more details) or the (See the sip servlets managment console
  • The properties file is first read by the container when it loads up.
  • The properties file is refreshed each time an application is deployed/undeployed.
  • The properties 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 SipApplicationRouterInfo object.

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

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

    ALL: (sip-router-info-5), (sip-router-info-6)..

    Note: starting from Mobicents Sip Servlets version 1.0, There is a special keyword called ALL here (taht is specific to Mobicents Sip Servlets) allowing a mapping between a sip-router-info data and all methods supported by the container (INVITE, REGISTER, SUBSCRIBE, etc...) to save time for the configuration of an app that listen to all incoming methods. If both the ALL and a specific method are defined in the DAR file, the specific method takes precedence oever the ALL, and ALL is called when there is no applications to server for the specific method anymore.

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

  • The name of the application as known to the container. (read as is present in the app-name tag of the sip.xml deployment descriptor of the application or the @SipApplication annotation)
  • 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" (Currently this information is not used by the DAR to make routing decisions)
  • A SIP URI indicating the route as returned by the Application Router, it can be an empty string. (this can be used to route the request externally)
  • A route modifier which can be any one of the strings "ROUTE", "ROUTE_BACK" or "NO_ROUTE" (to be used in conjunction with the above route to route a request externally)
    • a string representing in which orders the applications should be invoked (starts at 0). This will be removed later on and the position of sip-router-info data will be the order

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.

Routing of SIP Messages to applications

Initial Requests and Application Selection Process

Initial Requests are requests that can essentialy be dialog creating ("INVITE", "REGISTER", "SUBSCRIBE", "OPTIONS", "MESSAGE", "NOTIFY", "PUBLISH", "REFER" ) and not part of an already existing dialog. (There is some other corner cases that you can check in the Sip Servlets 1.1 specification, Appendix B Definition of an Initial Request )

Those Initial requests are routed to applications deployed in the container according to the Sip Servlets 1.1 specification, Section 15.4.1 Procedure for Routing an Initial Request.
Here is a quick summary by the example of the routing (through the Default Application Router) of an INVITE to two applications deployed in the container. Those 2 applications are a Location Service and a Call Blocking application :

The DAR file will look like this for those 2 applications to be invoked in the order

INVITE: ("LocationService", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "0"), ("CallBlocking", "DAR:To", "TERMINATING", "","NO_ROUTE", "1")

a new INVITE (not a re-INVITE) arrives at the container . Since it is a dialog creating request and the INVITE is not part of any dialog, the Application Router is called.
It will see that the first application to invoke is the LocationService so it will return that information to the container (along with the rest of the sip-router-info data) so that the container knows which application to invoke.
The container then invokes the LocationService that proxies the INVITE (which is considered essentially as a new INVITE see Sip Servlets 1.1 Specification, Section 15.2.2 Sending an Initial Request) to the known IP Address of the registered user for the Request URI.\

Since the INVITE has been proxied, the container will invoke the Application Router for the proxied INVITE to see if any more applications are interested into it. It will see that the second application to invoke is the CallBlocking application so it will return that information to the container (along with the rest of the sip-router-info data) so that the container knows which application to invoke.  The container will route the INVITE within the container to the next application in the chain, The Call Blocking application will decide that the user calling is black listed so it will reject the call with a Forbidden response. Since the Call Blocking acted as a UAS the Application Selection Process is stopped. (the container will not invoke the application router anymore for this INVITE).

So now the path that the INVITE has taken (ie LocationService, CallBlocking) is called the application path. the Routing of the responses will now occur which brings us to the next section

Please note that we took the assumption of a request coming to the server, but applications can act as UAC and also generate initial requests on their own.
In such cases, no entry in the dar file is needed for the given application initiating the request to be able to route it to ohter applications in the container or outside.

Response Routing

Responses always follow the reverse of the path taken by the corresponding request.
In our case the Forbidden response will first go back to LocationService then back to the caller. This is true for responses to both initial and subsequent requests.  The application path is a logical concept and as such may or may not be explicitly represented within containers.

Let's say the Call Blocking application now instead of sending a Forbidden response allowed the call and proxied the INVITE to the same Request URI chosen by the Location Service. Then when the callee sends back the 200 OK Response, this response goes back the same way through the application path, so in our case Call Blocking, then Location Service, then back to the caller.

An important note here with regard to that second scenario that according to the Sip Servlets 1.1 specification, Sections 15.1.2 The Role of Applications and 15.1.4 Application Independence, the Call Blocking application cannot just do nothing with the request and expect the container to route the request in its place (either to a next application in chain if another one is present or to the outside world if none is present).\ The Application has to do something with request (either proxy it or act as a UAS).

Subsequent Requests

Subsequent requests are all requests that are not Initial.

Now let's keep the second scenario in mind where the Call Blocking application allowed the call. So the caller has received the 200 OK response back. Now according to the SIP specification (RFC 3261), it sends an ACK. The ACK arrives at the container and is not a dialog creating request and is already part of an ongoing dialog (early dialog) so the request is detected as a Subsequent request and will follow the application path created by the initial request. So the ACK will go through Location Service, Call Blocking and then to the callee.

Limitations

It is not possible to filter out the requests based on some headers to target specific applications, like if From Header user domain part is equals to sip-servlets.org call Application 1 and if not called Application 2.

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 real world deployments, the Application Router shall play an extremely important role in application orchestration and composition.  It is likely to make use of complex rules and diverse data repositories.
The DAR is intended to be a very simple implementation that is available as part of the reference implementation, and could be used instead of a real world Application Router.

So far we didn't had requests for a more elaborated Application Router but if you need one you can either open an issue see the feedback page or look at the DFC Application Router from ECharts .

Mobicents Sip Servlets