JBoss.orgCommunity Documentation

Chapter 3. Application Router

3.1. Default Application Router
3.1.1. Role of the Application Router
3.1.2. Mobicents Default Application Router
3.1.3. Limitations of the Default Application Router
3.2. DFC Application Router
3.2.1. Description of DFC Application Router
3.2.2. Installing the DFC Application Router

Application Routing is performed within the Mobicents Sip Servlets container by the Default Application Router. The following sections describe the Default Application Router, and how other Application Router implementations compliant with the JSR 289 specification can be installed.

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 does not implement application logic. For example, the Application Router cannot modify a request or send a response.

There is no direct interaction between the Application Router and applications, only between the SIP Servlets Container and the Application Router.

The SIP Servlets container is responsible for passing the required information to the Application Router within the initial request so the Application Router can make informed routing decisions. Except for the information passed by the container, the Application Router is free to make use of any other information or data stores. It is up to the individual implementation how the Application Router makes use of the information or data stores.

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 the deployer is solely responsible for the services available to subscribers.

Furthermore, the SIP Servlets 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.

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

The Default Application Router (DAR) obtains its operational parameters from a configuration text file that is modeled as a Java properties file. The configuration file contains the information needed by the Application Router to select which SIP Servlet application will handle an incoming initial request.

In the case of Mobicents SIP Servlets, it is also possible to configure the DAR through the server.xml configuration file (see Example 2.2, “Configuring the Service Element in the Container's server.xml” and Section 1.2, “Working with the SIP Servlets Management Console”).

The properties file has the following characteristics and requirements:

  • It must be made available to the DAR.

  • It must allow the contents and file structure to be accessible from a hierarchical URI supplied as a system property javax.servlet.sip.ar.dar.configuration.

  • It is first read by the container when it loads up and is refreshed each time an application is deployed and undeployed.

  • It has a simple format in which the name of the property is the SIP method and the value is a comma-separated string 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)..

    Mobicents SIP Servlets defines a new keyword called ALL. The keyword allows mapping between the sip-router-info data, and all methods supported by the container (for example, INVITE, REGISTER, SUBSCRIBE). This maping can save time when configuring an application that listens to all incoming methods.

Note

If ALL, and a specific method are defined in the DAR file, the specific method takes precedence over ALL. When the specific method no longer has applications to serve, ALL is enabled again.

The sip-router-info data specified in the properties file is a string value version of the SipApplicationRouterInfo object. It consists of the following information:

  • The name of the application as known to the container. The application name can be obtained from the <app-name> element of the sip.xml deployment descriptor of the application, or the @SipApplication annotation.

  • The identity of the subscriber that the DAR returns. The DAR can return any header in the SIP request using the DAR directive DAR:SIP_HEADER. For example, DAR:From would return the SIP URI in the From header. The DAR can alternatively return any string from the SIP request.

  • The routing region, which consists of one of the following strings: ORIGINATING, TERMINATING or NEUTRAL. This information is not currently used by the DAR to make routing decisions.

  • A SIP URI indicating the route as returned by the Application Router, which can be used to route the request externally. The value may be an empty string.

  • A route modifier, which consists of one of the following strings: ROUTE, ROUTE_BACK or NO_ROUTE. The route modifier is used in conjunction with the route information to route a request externally.

  • A string representing the order in which applications must be invoked (starts at 0). The string is removed later on in the routing process, and substituted with the order positions of sip-router-info data.

  • An optional string that contains Mobicents-specific parameters. Currently, only the DIRECTION and REGEX parameters are supported.

    .

    Note

    The field can contain unsupported key=value properties that may be supported in future releases. The unsupported properties will be ignored during parsing, until support for the attributes is provided.

    The syntax is demonstrated in Example 3.1, “DIRECTION Example”.

    • The DIRECTION parameter specifies whether an application serves external(INBOUND) requests or initiates (OUTBOUND) requests.

      If an application is marked DIRECTION=INBOUND, it will not be called for requests initiated by applications behaving as UAC. To mark an application as UAC, specify DIRECTION=INBOUND in the optinal parameters in the DAR.

      Applications that do not exist in the DAR list for the container are assumed to be OUTBOUND. Because undefined applications are incapable of serving external requests, they must have self-initiated the request. The Sip Servlets Management Console can be used to specify the DIRECTION parameter.

    • The REGEX parameter specifies a regular expression to be matched against the initial request passed to the Application Router.

      If the regular expression matches a part of the initial request, the application is called otherwise it is skipped.

      By example in the following sip-router-info data :

      INVITE: ("org.mobicents.servlet.sip.testsuite.SimpleApplication", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "0", "REGEX=From:.*sip:.*@sip-servlets\.com")

      , only incoming initial requests having a From Header whose the SIP URI belongs to the sip-servlets.com domain will be passed to the SimpleApplication.



Initial Requests are those that can essentially be dialog creating (such as, INVITE, SUBSCRIBE and NOTIFY), and not part of an already existing dialog.

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.

Example 3.3. INVITE Routing

The following example describes how the DAR routes an INVITE to two applications deployed in a container. The applications in this example are a Location Service and a Call Blocking application.

In the example, the assumption of a request coming to the server is described. However, applications can act as a UAC, and generate initial requests on their own. For routing purposes, it is not necessary for the specified application initiating the request to have an entry in the DAR file.

The DAR file contains the required information for the two applications to be invoked in the correct order.

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

Processing occurs in the following order:

  1. A new INVITE (not a re-INVITE) arrives at the container.

    The INVITE is a dialog creating request, and is not part of any dialog.

  2. The Application Router is called.

    From the INVITE information, the first application to invoke is the Location Service.

  3. The Application Router returns the application invocation order information to the container (along with the rest of the sip-router-info data) so the container knows which application to invoke.

  4. The container invokes the LocationService that proxies the INVITE.

    The proxied INVITE is considered as a new INVITE to the known IP Address of the registered user for the Request URI

    For further information regarding INVITE handling, refer to "Section 15.2.2 Sending an Initial Request" in the SIP Servlets 1.1 Specification.

  5. Because the INVITE has been proxied, the container invokes the Application Router for the proxied INVITE to see if any more applications are interested in the event.

  6. From the proxied invite, the Application Router determines that the second application to invoke is the Call Blocking application.

  7. The Application Router returns information regarding the Call Blocking application to the container (along with the rest of the sip-router-info data) so the container knows which application to invoke.

  8. The container routes the INVITE for the Call Blocking application to the next application in the chain.

  9. The Call Blocking application determines that the user that initiated the call is black listed. The application rejects the call with a "Forbidden" response.

  10. Because the Call Blocking application acts as a UAS, the Application Selection Process is stopped for the original INVITE.

The path the INVITE has taken (that is, LocationService to CallBlocking) is called the application path. The Routing of the responses will now occur as explained in the next section.