Application Composition with the DFC-AR
Written by Eric Cheung   

In this first part of a three part posting, I use a simple example to illustrate how to compose multiple applications with the DFC Application Router on the open-source SailFin container. This will explain some of the concepts of application selection and composition in SIP Servlet 1.1 (JSR289), as well as highlight the features and advantages of the DFC-AR.

In the SIP Servlet model, multiple applications can be invoked in a chain to provide a composite service. The process of application selection is controlled by a component called the Application Router (AR). Containers must allow the deployer to plug in different AR implementations. I have been running the SailFin container with ECharts for SIP Servlets applications, and replacing the built-in AR with the DFC Application Router. This is working rather nicely, so thought I will share my experience.

DFC stands for Distributed Feature Composition and represents a large body of work on feature interaction management done by Michael Jackson and Pamela Zave. The DFC-AR offers features such as address-based subscription and precedence relationship between applications, and is designed to be simple yet powerful and flexible. This paper presented at ICC 2008 provides details of the DFC-AR.

Application Composition Part 1 Figure

In the first example, the user Bob subscribes to three applications:

Reroute Upon Failure (RR): Initially, RR acts as a B2BUA and just passes a received INVITE onwards. If RR receives an error response, it sends the INVITE to an alternative SIP address.  For example, RR may reroute the call to a voice mail server.

Conditional Call Failure (CCF): If configured to do so, CCF rejects an incoming INVITE with the configured error response code. Otherwise, it acts as proxy and simply proxies the INVITE onwards. For example, CCF can be used for a Do-Not-Disturb service.

No Answer Timeout (NAT):  Initially, NAT acts as a B2BUA and passes an incoming INVITE onwards. It starts a timer when it receives the first 180 Ringing response from the callee.  If the timer expires before it receives a 200 OK response, NAT sends a 480 Temporarily Unavailable response to the caller, and sends CANCEL to the callee.

All three are terminating region applications, which means they are invoked to serve Bob when Bob is receiving a call. They are not invoked when Bob is placing a call. Together, they provide a composite service to Bob: Bob can set up RR to forward call to voicemail if he steps away and cannot answer a call, or if he does not want to be disturbed and activates CCF. On the other hand, each application is optional and replaceable. For example, Bob may upgrade CCF with a more sophisticated version that accesses his Calendar application to automatically reject calls when Bob is in an important meeting.

In this first posting, we will set up SailFin to use the DFC Application Router, instead of the built-in default alphabetical router. The following has been tested with SailFin promoted build b42.

Step 1

Add the following additional JVM options to SailFin.  The easiest method is by editing <install_home>/sailfin/domains/domain1/config/domain.xml file, by adding <jvm-options> elements in the <java-config> section (<install_home> is the directory where you have installed SailFin). Alternatively you can use asadmin or the web admin interface.

-Dorg.echarts.system.transitionTimerManager.class=org.echarts.servlet.sip.TransitionTimerManager
-Dorg.echarts.servlet.sip.logdir=${com.sun.aas.instanceRoot}/e4sslogs
-Dorg.echarts.servlet.sip.debugging=true
-Dorg.echarts.debugging=true
-Dorg.echarts.servlet.sip.messagelog=true
-Djava.util.logging.config.file=logging.properties

See ECharts for SIP Servlets Manual Sec 5.2 Runtime Properties for details. The file logging.properties should be in <install_home>/sailfin/domains/domain1/config/. Make sure to restart the domain after changing the JVM options. Also remember to create the e4sslogs directory under <install_home>/sailfin/domains/domain1/.

Step 2 

Download and unpack the SailFin-specific ECharts for SIP Servlets SDK v2.5-prerelease.  Set the EDK_HOME environment variable to the top-level directory. e.g.

> cd /home/cheung
> unzip EChartsSipServlet_DK_2.5-prerelease.zip
> export EDK_HOME=/home/cheung/EChartsSipServlet_DK_2.5-prerelease

Copy javaee.jar and ssa-api.jar from the SailFin <install_home>/sailfin/lib/ to $EDK_HOME/lib. Also put sip-sdp.jar into the same directory (see $EDK_HOME/README-requirements.txt for details).

Step 3

Build the WAR files for the three applications, and then deploy them. The source code is included in the features/ directory.

> cd $EDK_HOME/features/rerouteUponFailure/test
> ant fatsar
> asadmin deploy rerouteUponFailureTest.war 

Repeat for ccf/test and noAnswerTimeout/test.

Step 4

The DFC-AR reads a static configuration file approuter.xml to determine how to select applications. $EDK_HOME/etc/approuter.sample.xml documents the format of this configuration file. For this example, an appropriate approuter.xml is included in the DK. Copy $EDK_HOME/examples/composition1/approuter.xml to <install_home>/sailfin/domains/domain1/config.

Step 5

Deploy the DFC-AR to replace the built-in alphabetical AR.  There is a prebuilt JAR file in the DK at $EDK_HOME/lib/dfcar.jar. SailFin knows that it is an AR because of the MANIFEST file.

> asadmin deploy dfcar.jar

Now when Alice calls Bob, the container calls the DFC-AR.  DFC-AR examines the From header of the INVITE request and discovers that the caller is Alice. As specified by approuter.xml, Alice does not subscribe to any originating applications. The DFC-AR therefore examines the Request-URI of the INVITE request and discovers that the callee is Bob. This time, approuter.xml specifies that Bob have RR, CCF, and NAT applications in this order. Therefore DFC-AR returns RR to the container. In e4sslogs/monitor-SipApplicationDFCRouterImpl.log, the following line shows what the DFC-AR returns to the container:

INFO: AR returning /rerouteUponFailureTest, 
SipApplicationRoutingRegion : label type TERMINATING,
sip: Bob @192.0.0.9, null, NO_ROUTE,
Taddress=sip%3ABob%40192.0.0.9;
route-set=/rerouteUponFailureTest%/ccfTest%/noAnswerTimeoutTest

RR acts as B2BUA and sends an INVITE with the default CONTINUE routing directive, and does not modify the Request-URI. When the container calls DFC-AR, because the callee address (i.e. the Request-URI) has not changed, DFC-AR selects the next application, which is CCF. Again, the following line in the log shows what it returns:

INFO: AR returning /ccfTest,
SipApplicationRoutingRegion : label Terminating Region type TERMINATING,
sip:Bob @192.0.0.9, null, NO_ROUTE,
Taddress=sip%3ABob%40135.0.0.9;route-set=/ccfTest%/noAnswerTimeoutTest

CCF acts as proxy and again does not modify the Request-URI.  This time, DFC-AR returns:

INFO: AR returning /noAnswerTimeoutTest,
SipApplicationRoutingRegion : label Terminating Region type TERMINATING,
sip:Bob @192.0.0.1, null, NO_ROUTE,
Taddress=sip%3ABob%40192.0.0.1;route-set=/noAnswerTimeoutTest

Finally, NAT acts as B2BUA and sends INVITE with the default CONTINUE routing directive, and does not modify the Request-URI. Because there are no more applications, DFC-AR returns null, and the container sends the request externally:

INFO: AR returning null, 
SipApplicationRoutingRegion : label Terminating Region type TERMINATING,
sip:Bob @192.0.0.1, null, NO_ROUTE,
Taddress=sip%3ABob%40192.9.0.1; route-set=

This example illustrates several aspects of the DFC-AR operations:

  • Users subscribe to applications, in either the originating or terminating regions. In this example, the <application-mapping> section of approuter.xml specifies that if the Request-URI matches the regular expression sip:bob.*, then these three applications match. i.e. Bob subscribes to these three applications.
  • There is a precedence ordering of applications. The <precedence> section of approuter.xml specifies the ordering.
  • The CONTINUE routing directive and no change in the subscriber address (Request-URI in this case) indicates to the DFC-AR to invoke the next application.

By default, none of the three applications take any action other than continuing the call. Therefore, in this example the call between Alice and Bob simply proceeds with no application involvement. In the next part, we will configure the applications to act, and we will see how their operations may interact, and what new application selection behavior will result.

Update on 2008/10/09: The Final Release (FR) of JSR 289 was made available on 2008/08/21. Unfortunately, the final API is slightly different from the one SailFin b42 assumed, so the ECharts for SIP Servlets SDK v2.5-prerelease which was specifically intended for SailFin b42 would not work on newer JSR289-compliant SIP servlet containers, including the more recent builds of SailFin.

We have performed the necessary code changes to use the JSR 289 FR API, and tested it against SailFin b52 and Oracle Communications Converged Application Server 4.0 successfully.

While we work on a new release, interested parties may obtain the source code directly from the subversion repository and build an ECharts for SIP Servlets SDK that works on containers compliant to JSR 289 FR.  Please see the following README files for details:

 

Discuss this article on the forums. (4 posts)

Last Updated ( Thursday, 09 October 2008 )