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.