1. Developer Guide
  2. Composing SIP Applications
  3. Application Router Behavior

Application Router Behavior

When Converged Application Server receives an initial request from an external entity, or when an application acts as a User Agent Client (UAC) and sends an initial request with a new routing directive, the application selection process is started fresh. In that case, the Application Router is called with the following information:

  • The SipServletRequest.
  • The new routing directive.

Based on the supplied information, the configuration of which subscriber subscribes to which set of applications, and any other information that it may wish to use, for example, time of day, network condition, or external subscriber profile database, the Application Router returns the following information:

  • The name of the selected application.
  • The subscriber identity that the selected application is to serve.
  • The routing region that the application serves.
  • An array of zero or more routes to push (the routes array).
  • A route modifier that tells the container how to interpret the route.
  • An optional stateInfo serializable object.

The Application Router can return routes to Converged Application Server using its SipApplicationRouterInfo.getRoutes() method. The routes can be external or internal. External routes are used by the Application Router to instruct Converged Application Server to send the request externally. An internal route is returned when the Application Router wishes to modify the popped route header as seen by the application code, through the SipServletRequest.getPoppedRoute() method. When the request is received by Converged Application Server, the request may have had a Route header belonging to Converged Application Server, which it removes and makes available as described in "Popped Route Header". The route modifier returned by the Application Router tells Converged Application Server how to use the routes returned by it and also how the popped route needs to be presented.

The route modifier can be one of the following enum values:

  • ROUTE indicates that SipApplicationRouterInfo.getRoutes() returns valid routes. Converged Application Server decides if they are external or internal. All of the routes returned must be of the same type, so Converged Application Server can make the determination by examining the first route only.
  • ROUTE_FINAL indicates that SipApplicationRouterInfo.getRoutes() returns valid routes. The returned route can contain internal routes, external routes, or both. Converged Application Server pushes all routes returned by the Application Router.
  • ROUTE_BACK directs Converged Application Server to push its own route before pushing the routes obtained from SipApplicationRouterInfo.getRoutes().
  • NO_ROUTE indicates that Application Router is not returning any routes and the SipApplicationRouterInfo.getRoutes() value, if any, should be disregarded.

The behavior of the container with respect to the route modifiers is explained in "Procedure for Routing an Initial Request".

The stateInfo serializable object is useful for the Application Router to store state information from one invocation to the next. An Application Router implementation may choose to put any information in the stateInfo object, and this object is opaque to Converged Application Server and not accessible to the applications. Typically, an Application Router implementation may store information such as subscriber identity, the name of the application last invoked, and a precomputed list of applications that are to be invoked next. Application Router must not change the stateinfo after it is returned to Converged Application Server, and each result returned to Converged Application Server must contain a different stateinfo object.

If the selected application subsequently proxies or sends a new initial request based on the first one with a CONTINUE or REVERSE routing directive, the Application Router is called again. This time, in addition to the SipServletRequest and the routing directive, it is also supplied with the stateInfo object that it previously returned. In this way, the Application Router delegates the maintenance of the application selection state to Converged Application Server, and thus it can be stateless with respect to each initial request it processes.

If the Application Router determines that no application is selected to service a request, it returns null as the name.

Order of Routing Regions

Because proximity of an application to its subscriber confers priority, it is beneficial for the management of feature interaction that originating applications are closest to the caller, and that terminating applications are closest to the callee. This can be satisfied if the following rules are followed:

  • The originating region applications should be invoked first followed by terminating region applications.

  • The applications that service a subscriber are contiguous (that is, no insertion of applications that service other subscribers in between).

On the other hand, it is entirely possible that the Application Router progresses directly to the terminating region if the caller is not a subscriber, or the caller does not subscribe to any applications. It is also possible that the application server does not serve any originating subscribers or has determined through some means that the originating applications have already been invoked and it should only look for terminating applications.

Inter-Container Application Routing

Converged Application Server supports applications distributed across multiple containers. The Application Router may return external routes in its SipApplicationRouterInfo.getRoutes() method that point to other application servers that it wishes the request to be routed to. Converged Application Server then pushes the routes onto the Route header stack of the request and sends the request externally. If this request arrives at another JSR-359 compliant container, it invokes the Application Router residing in that container so that the application selection process may continue. The first Application Router may pass any state information to the second Application Router by embedding it in the Route header. This is in accordance with the cascaded services model (SERL) as the applications can reside on different hosts and still participate in the application composition process.

Note:

Some architectures require that the originating and terminating applications be hosted on different servers. The deployer can easily accomplish this by configuring the Application Routers such that one server hosts only originating applications and the other only terminating applications. Either the subscriber data can be partitioned such that the first server only serves originating users and the second serves terminating users. Alternatively, the Application Routers can collaborate by passing some state information in the Route headers, indicating for example that the first server has already completed the invocation of originating services.

Popped Route Header

On receiving an initial request that contains a SIP Route header (preloaded) or receiving a subsequent request with a Route header (converted from a Record-Route header), Converged Application Server determines if the request is intended for itself (based on local policy, for example IP addresses of interfaces or representative DNS entries). If it is, Converged Application Server removes the Route header before passing it to any application or the Application Router.

A side effect of removing a SIP Route message header before presenting the request to applications (and the Application Router) is that applications do not have access to the SIP Route message header and its associated information. Certain architectures utilize the SIP Route header for transporting application and other related information.

The following methods return the Route header popped by the container:

  • Address getPoppedRoute();

  • Address getInitialPoppedRoute();

If application composition is being used, the values returned by those methods may differ. The getPoppedRoute method returns the route popped before the current application invocation in the composition chain. The getInitialPoppedRoute method returns the route popped by Converged Application Server when it first received the request.

If no header is popped by Converged Application Serer on an initial request, both methods return null.

Both methods return the Route header as an Address, so, parameters added to the Record-Route header using the Proxy.getRecordRouteURI() method should be retrieved not from the popped route Address directly, but from the URI of the popped route Address.