Hunting Sample App using ECharts

In this example I show how to build a more complex sample using the ECharts state machine language. Details about ECharts can be found in http://echarts.org/ and also in one my previous posts in screening sample app with ECharts . The sources for the sample are available in cvs using cvs -d:pserver:[your java.net account]@cvs.dev.java.net:/cvs co sailfin/sailfin-tests and then can be found then in community/samples/hunting, or send an email to me to get them.

It provides the functionality to define a list of alternative Sip URI's in a database which are tried in sequence to connect when a call is received until a successful connection is established.

• The application is triggered only in terminating case via the ECharts application router if the To address matches the specfied pattern in the app router.
• It then connects the call to a mediaserver (MRF) which plays a dialtone or other announcement to the caller.
• When the dialtone is established it sends a INVITE to the original called party of the call.
• When the called party answers with 200 OK it disconnects from the mediaserver and reconnects via REINVITE to the caller. How to setup a mediaserver I will show in a future blog entry.
• If the called party returns a 486 BUSY or 487 NOT REACHABLE it retrieves the next alternative Sip URI from the database and sends INVITE again.
• If no alternative called party is available it stops the dialtone and signals a failure to the caller.

Sip Callflow for Redirect on Busy

The following callflow shows a scenario where the B Party is busy and the call is forwarded to C-Party.

A-Party......Sailfin......B-Party......MRF......C-Party

-INVITE SDPa->.....................................
.............-INVITE-------------------->..........
.............<-200 OK SDPm---------------..........
<-200 OK SDPm-.....................................
-ACK--------->.....................................
.............-ACK----------------------->..........
.............-INVITE SDPa--->......................
.............<-486 BUSY------......................
.............-ACK----------->......................
.............-INVITE SDPa------------------------->
.............<-200 OK SDPc-------------------------
.............-BYE----------------------->..........
<-200 OK SDPc-.....................................
.............<-200 OK--------------------..........
-ACK--------->.....................................
.............-ACK--------------------------------->
..................t a l k i n g....................
-BYE--------->.....................................
.............-BYE--------------------------------->
.............<-200 OK------------------------------
<-200 OK------.....................................

State Machines

A graphical description of the state machines can be found in the downloaded sources in hunting/src/echarts/hunting/ech/doc-files

• The MainFSM machine connects to the MRF to play the dialtone using the ConnectFSM machine. When the dialtone is established it transitions to the HuntingFSM which performs the search and connect for the called party. Finally when the call is successfully established it transitions to the TransparentFSM which handles the talking state of the call and also the turndown at the end.
• The HuntingFSM runs three paralles states.
  The PLAY_DIALTONE state uses the TransparentFSM and monitors the connection to the MRF.
  The CALL state uses the CallFSM to make a connection the called party until it has a successful connection.
  The REINVITE state uses the ReinviteFSM to handle the reinvite to the caller after a successful connection to the B-Party has been established.
• The ConnectFSM machine handles the conenction to the MRF.
• The CallFSM handles connect attempts to the B-Party.
• The SendReinviteFSM handles the reinvite to the caller.
• The TransparentFSM handles the talking state and turndown together with the TransparentHandleRequestFSM.

Screening Sample App - ECharts Details

The following diagram show the structure of the screening application, the diagram is generated by the build process in the echarts/screening/ech/doc-files folder. From the initial state RECEIVE_INVITE either the state PLAY_ANNO is reached (if screening is applied) or the state CONNECT if screening is not applied. When the connection is successfully established the state TALKING becomes active which handles the call until finish.

Screening Sample App using ECharts (Part 1 - Application)

In this example I will show how to build a simple screening application for Sailfin using the ECharts state machine language. The application checks the dialed number and either let the call proceed or plays an announcement to the caller that the call is forbidden. Each user is assigned a screening profile which contains his screening rules consisting of blacklisted numbers and exceptional whitelisted numbers. A call is forbidden if the dialed number is contained in the blacklist but not in the whitelist. A call is allowed if the dialed number is not contained in any list or in the whitelist only.

What is ECharts

According to the description on the ECharts website (http://echarts.org/) it is a state machine-based programming language for event-driven systems derived from the standardized UML stacharts language. ECharts is a hosted language which means that it is dependent on an underlying programming language such as Java.

Benefits of ECharts

• It provides a problem oriented language. State machines are a typical method to describe message processing applications and a language whose paradigm fits to the domain makes application development easier.
• From an application developers point of view your application has to handle only a single call in contrast to the servlet programming model where you have to deal with all calls handled by the servlet in parallel. The session and dialog management is abstracted by the so called box model.
• It allows to build reuseable parts by defining state machines which handle a certain task and can be inserted as a single state in an outer state machine. In the example I will show a Connect machine which builds up a connection to the called party, a Transparent machine which handles the talking state and a PlayAnnouncement machine which plays announcements to the caller.

Prerequisites

1. Get the ECharts 2.2. SDK from http://echarts.org/Downloads.html and unzip it.
2. The ECharts compiler uses Python, if do not have it get it from http://www.python.org/download/
3. If on order to use the documentation generator for state machines on Windows you need graphviz from http://www.graphviz.org/. For some strange reasons I had to directly set the path for the graphviz "dot" program in ech2javadoc to make it working.
4. In the sailfin application server set the following JVM options with the admin console on http://localhost:4848/ by "Application Server->JVM Settings->JVM Options->Add Option".
   -Dorg.echarts.servlet.sip.messagelog=true
   -Dorg.echarts.debugging=true
   -Dorg.echarts.servlet.sip.debugging=true
   -Dorg.echarts.servlet.sip.logdir=${com.sun.aas.instanceRoot}/echlogs
   -Dorg.echarts.system.transitionTimerManager.class=
   org.echarts.servlet.sip.TransitionTimerManager
5. The sources are available in cvs using
   cvs -d:pserver:[your java.net account]@cvs.dev.java.net:/cvs co sailfin/sailfin-tests
   and then can be found then in community/samples/screening, or send an email to peter.c.klein@siemens.com to get them.

Creating the Screening Sample

1. Create a new database with database name "screening" and a new Converged Servlet Application with name screening like in http://petersjb.blogspot.com/2008/01/create-sip-application-for-sailfin.html
2. Add the entity classes for UserData, SceeningProfile and ProviderDataand copy their sources from the downloaded cvs sources.
3. Add the java class for ModelFacade as well as the java class for RegisterSipServlet and copy its sources from the downloaded cvs sources.
4. Add a java class FSMSupport which contains helper functions called by the state machines and copy its sources from the downloaded cvs sources.
5. Add antlr.jar, approuter.jar, echarts.jar and echarts-sipserlet.jar in the /lib folder to the projects libraries.
6. Create a new folder structure echarts/screening/ech in screening/src to hold the echarts sources and copy the *.ech files from the downloaded cvs sources. Add this folder in the project properties to sources.
7. Add to the build.xml file the properties and targets -pre-compile (for ech2java compilation) and -post-compile (for generating state machine documentation) as in the build.xml file in the downloaded sources.
8. Add the EChartsSipServlet and the RegisterSipServlet to the sip.xml as shown in the example code. Note that the state machines themselves are no servlets but are called from the EChartsSipServlet. Also add ModelFacade to web.xml
9. Compile and deploy the application.
10. Setup the data in the database as shown in the filldata.sql file in the
    "scenarios/tc-001-basic-ua" folder.
11. Depending on the dialed number and contents of the screening profile the call will either be connected to the called party or the party defined in the ProviderData.anno attribute.

I the next post I will show the web based admin and some insights how it works.

Notes

The web based admin is already included in the sources but in the moment only viewing works, modify and delete have to be added.