JBoss.orgCommunity Documentation

Chapter 3. Application Router

3.1. Default Application Router
3.1.1. Role of the Application Router
3.1.2. JBoss Communications 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 JBoss Communications Sip Servlets container by the Default Application Router. The following sections describe the Default Application Router, and how other JSR 289 compliant Application Router implementations 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.

JBoss Communications 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 JBoss Communications 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)..

    JBoss Communications 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 mapping 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 JBoss Communications-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 optional 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. If it does not, it is skipped.

      For 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 with a From Header with a SIP URI that 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.