Building a Telephony Web Application

By: Rauf Qureshi
May 1, 2007

Abstract: This short tutorial shows basic steps involved in putting together a telephony web application. A typical telephony web application provides features that can be accessed via the web as well as via the telephone. The example application provides stock quotes through the web as well as telephony interfaces to registered users. We will examine building the web interface using Java ServerFaces and the telephony interface using VoiceXML. The application uses a Model-View-Controller approach in order to keep the presentation separate from business rules. The presentation layers will be created using Java ServerFaces for the visual and VoiceXML for the audio/spoken interface. Both types of presentations utilize common programming source which consists of java beans and controllers. Hibernate is used for the database persistence. Telephone and web interfaces utilize the common database.

1. Building Blocks

Now that I have given away my thunder in the abstract above, the application in this tutorial was a part of a prototype that I put together not too long ago. This tutorial is based upon lessons learned during that process. Let us examine the building blocks of the telephony/web application under consideration. This application allows registered users to view their stock quotes via the web once signed in. The application retrieves real time (disclaimer: 20 minutes delayed) stock quotes from Yahoo and displays results on the screen. The telephony part of this application announces the stock quote results over the phone by capturing the ANI (calling phone number) and matching it to the existing profiles.

New users can register on the web by following simple links. Once registered, user can create a profile by entering ticker symbols of their favorite stocks that need to be monitored. The telephone number where calls will be made from can also be entered in the profile. The telephony part of the application uses ANI as the authentication mechanism.

1.1 System Architecture: The diagram in Figure 1 below provides a system level overview. A telephony-web application is typically deployed on two separate servers; Application server and a Voice server.

1.1.1 Voice Server: The voice server is responsible for communicating with the user over the telephone and perform telephony tasks. The voice server pulls VoiceXML, grammar and prompt files from the application server over the internet or a dedicated link based upon the requirements. The voice browser in the voice server uses JSP based VoiceXML files to collect speech input from the user over the telephone and presents to the inner guts of the voice server for processing. The voice browser also presents the output to the user in the form of spoken words over the telephone. Note that the voiceXML code itself is neither generated nor stored by the voice server. The voice server fetches the voicexml code from the web application server over the internet. In some cases, voice server and application servers can be co-located in order to reduce dependency on the internet link between the two.

Figure 1. Telephony Web System Architecture - overview

Main components of a voice server are listed below:

• Voice Browser: A voice browser is the human machine interfacing component of any speech driven voice application. A voice browser provides an interface between the caller and the different components of the voice server. Think of the voice browser as an equivalent of the html browser (IE, Firefox). Just like an html browser interprets the application server code and presents to the user and accepts inputs (html forms) from the user for processing by the server, the voice browser interprets the voice server code and presents to the caller over the phone and accepts speech input (VoiceXML forms) for further processing by the server.
  
  From architecture point of view, the main difference between a web and a telephony application is that in a web application, the browser is provided by the client machine. As a result of that, application designer can rely on client resources in using technologies like javascript and flash to present and accept the data. The voice browser, on the other hand, is a part of the server and does not reside on the client, which is the calling device (telephone) for voice applications. The voice application designer has to be careful in utilizing server resources while designing the voice interface. Although voice browsers support javascript, its use should be restricted to cases where a quick computation/validation of the user input is desired. Also, efforts should be made to keep the voice session as short as possible for a given task.


• Speech Recognition Engine: Also called, Automatic Speech Recognition (ASR), the main purpose of a speech recognition engine is to convert human speech into the text form that application can understand. A speech recognition engine interprets callers spoken words and makes decisions based upon the spoken language and application rules defined in the grammar files.
  
  A speech server consists of two types of databases: Phonetic database and Lexicon database. The speech recognition engine breaks down spoken words into small segments called phonemes. Phonetic database is used to convert different qualities of human speech like frequency, pitch, loudness and other characteristics defined in the phonetic database to convert spoken words into phonemes.
  
  The ASR process then converts collection of phonemes into words by using the language database, which defines rules for construction of words and their pronounciations, which are defined by a human language, say US-English. The outcome of this process is a statistical representation of spoken words in the form of text. The text thus obtained may not be a true representation of the spoken utterances. Carefully constructed grammar files come to rescue here. Grammar files are used to convert the representative collection of text into application level variables which are used by the logic of the VoiceXML application.
• Text to Speech: Affectionately called TTS, a Text-to-Speech server provides exactly reverse of the speech recognition process: that is converting text to speech. A TTS server announces text provided by the application to the caller in the form of spoken words. TTS servers are available for different languages and can be configured to announce in male or female voices.

A great amount of effort is spent in usability analysis and voice dialogue building techniques during the course of a telephony web application design, which are out of scope of this tutorial.

1.1.2 Web Application Server: The web application server houses the database and necessary java codes that are used to communicate with the user of the application and perform tasks related to business logic. The web application server in this demo consists of the following:

• Java ServerFaces for the web presentation layer.
• Java controllers and java beans for business rules.
• Hibernate for data persistence.
• MySQL database to store user profiles.
• Apache/Tomcat as application server.
• VoiceXML files for the telephony presentation, dynamically generated using Java ServerPages.
• Grammar files, both static and dynamic. This demo does not use dynamic grammars.
• Voice prompts in the form of wav files.

1.2 Application Architecture: The high level architecture is described in the Figure 2 below: A common database is used to store user profiles and preferences. The application interfaces with the database using Hibernate. Java beans are used to define business rules, while controllers and helper classes use Hibernate data persitence in order to perform database related tasks. Moreover, the presentation layers, which are Java ServerFaces for the web and VoiceXML for the telephony, use controllers in order to present results and process input from the user, both from the web as well as over the phone.

Figure 2. Telephony Web application Architecture - 100 feet view

2. Use Cases

The use cases in this example application are as follows:

• Register new users via the web interface.
• Sign on management for registered users on the web and phone.
• User profile management; add/edit ticker symbols and calling phone number (ANI) on the web
• View updated stock quotes on the web.
• Get updated stock quotes by phone.

Let us examine the java code and database schema which comprise this application. The database schema in this demo is pretty simple. There is only one table JSFVXMLUSERS, which is used to store user profiles. Although database persitence using Hibernate is an overkill for an application comprising of only one table in the database, I wanted to show how Hibernate can be configured and used for this application. Once you get comfortable with the source code, you may add tables and database calls.

One of the main advantages of using Hibernate is that you do not have to worry about the database related java code using JDBC API's. Hibernate also allows you to get away by not having to learn SQL, although some pundits swears against that :-). Seriously, Hibernate provides an easy way to add, remove, update and query database records. You can learn more by visiting Hibernate related pages. There is tons of material out there that can help you in learning and mastering the database persistence using Hibernate. Google is your best friend.

Anyhow, Hibernate uses a configuration file where database specific parameters are defined. Mapping files, which relate database tables to java beans are also defined in the Hibernate configuration file.

Listing 1. Hibernate configuration settings

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
          "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
          "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>
	<session-factory>

		<property name="connection.driver_class">com.mysql.jdbc.Driver</property>
	
		<property name="connection.url">jdbc:mysql://localhost/dbURL</property>
		<property name="connection.username">username</property>
		<property name="connection.password">password</property>

		<!-- JDBC connection pool (use the built-in) -->
		<property name="connection.pool_size">5</property>

		<!-- SQL dialect - This is where type of database is defined-->
		<property name="dialect">org.hibernate.dialect.MySQLMyISAMDialect</property>

		<!-- Echo all executed SQL to stdout -->
		<property name="show_sql">true</property>

		<!-- Drop and re-create the database schema on startup -->
		<property name="hbm2ddl.auto">update</property>

		<property name="cglib.use_reflection_optimizer">false</property>

		<!-- Add below, with full path, the individual mapping files for each table-->
		<mapping resource="user.hbm.xml" />

	</session-factory>
</hibernate-configuration>	
	

Next step is defining a Hibernate Mapping file, which maps columns in the table to the java beans.

Listing 2. Hibernate mapping between the java bean parameters and table columns.

	
	<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
    "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping>

    <class name="com.hunza.jsfvxml.bus.User" table="JSFVXMLUSERS">

        <!-- A 32 hex character is our surrogate key. It's automatically
            generated by Hibernate with the UUID pattern. -->
        <id name="userId" column="USERID">
            <generator class="increment"/>
        </id>

        <property name="email">
            <column name="EMAIL"/>
        </property>
         .....
        <property name="ani">
            <column name="ANI"/>
        </property>

    </class>

</hibernate-mapping>
	

A java bean is used to define parameters for the user, getters and setters. See the listing below:

Listing 3. Java bean representing user properties.

	
package com.hunza.jsfvxml.bus;

public class User {
	/* 	The purpose of this class is to define a bean to represent a user. 
	 */

	private String userName, password, email;
	/*
	 * tickerSymbols is a space separated string consisting of ticker symbols
	 */
	private String tickerSymbols;
	private String ani, firstName;
	private Integer userId;

	// Getters
	public String getUserName()		{ return userName; }
	public String getPassword()		{ return password; }
	public String getEmail()		{ return email;	}
	public String getTickerSymbols()	{ return tickerSymbols;}
	public String getAni()			{ return ani;}
	public String getFirstName()		{ return firstName;}
	public Integer	getUserId()		{ return userId; }

	//Setters
	public void setUserName(String s)	{ this.userName = s; }
	public void setPassword(String s)	{ this.password = s; }
	public void setEmail(String s)		{ this.email = s; }
	public void setUserId(Integer I)	{ this.userId = I;}
	public void setAni(String s)		{ this.ani = s;}
	public void setFirstName(String s)	{ this.firstName = s;}
	public void setTickerSymbols(String S)	{ this.tickerSymbols = S;}
}

A helper class is used by the presentation controller, userController, to manage database related tasks through the database persistence. The helper class sits between the presentation controller and the Hibernate.

Listing 4. Helper class used by the presentation Controller.

	
package com.hunza.jsfvxml.db;

import java.util.*;

import org.hibernate.*;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import com.hunza.jsfvxml.bus.User;
import com.hunza.jsfvxml.Hibernate.HibernateUtil;
import com.hunza.jsfvxml.exceptions.*;

public class UserManager {

  protected final Log  logger = LogFactory.getLog(getClass());
	
	/**
	 * Updates a user record in the database.
	 * @return true if the user is updated successfully
	 * @return false if the user could not be updated.
	 * 
	 */
	
	public boolean updateUser(User user) {
		boolean result = false;

		try {
			logger.debug("Updating user");

			Session session = HibernateUtil.getSession();
			Transaction tx = session.beginTransaction();
			session.update(user);
			tx.commit();
			HibernateUtil.closeSession();
			logger.debug("User updated successfully");
			result = true;
		}	catch (HibernateException ex) {
				logger.error("Error while updating the user: " + ex);
		}
		return result;
	}


	/**
	 * Returns a user in the form of user bean by matching the ANI passed in the
	 * argument to the ANI of the user record in the database.
	 * 
	 * @return - null if user not found. 
	 */
	
	public User findUserByAni(String ani) {
		User user = new User();
		boolean userFound = false;
		List list = new ArrayList();
				
		try {
			logger.debug("Finding user with ANI: " + ani);

			Session session = HibernateUtil.getSession();
			session.beginTransaction();
			list = session.createQuery("from User user where user.ani = '" + ani + "'").list();

			if (list.size() == 1) {
				logger.debug("One user matching the ani");
				user = (User)list.get(0);
				userFound = true;
			}
			else {
				logger.error("There are either more than one users with this ANI..");
				logger.error("or no user was found with the matching ani!");
			}

			HibernateUtil.closeSession();
		}	catch (HibernateException ex) {
				logger.error("Error while getting the user: " + ex);
		}
		
		
		if (userFound) {
			logger.debug("returning user");
			return user;
		}
		else {
			logger.info("user not found!");
			return null;
		}
	}
}

Controllers have dual purpose; well just one! A controller class sits behind the presentation layer; whether via the web or via the telephone and sends the output to the presentation layer and processes the input collected by the presentation layer. A section of the Controller is given below:

Listing 5. Controller class used by the JSF as well as VoiceXML pages.

	

package com.hunza.jsfvxml.web;

import javax.faces.context.FacesContext;
import javax.faces.application.FacesMessage;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import com.hunza.jsfvxml.db.UserManager;
import com.hunza.jsfvxml.bus.User;
import com.hunza.jsfvxml.util.jsfUtils;

public class UserController {

	private User user =  new User();
	private String password2;
	
	protected final Log logger = LogFactory.getLog(getClass());

	/*
	 * UserController initializer that extracts the user from the session, if one exists already.
	 */
	{
		if ( null != FacesContext.getCurrentInstance().getExternalContext().getSessionMap().get("user"))
			this.user = (User)FacesContext.getCurrentInstance().getExternalContext().getSessionMap().get("user");
	}

	public User getUser() {
		return user;
	}
	
	public void setUser(User u) {
		this.user = u;
	}
	
	public String getPassword2() { return password2;}
	public void setPassword2(String s) { this.password2 = s;}


	public String signUp() {
		String result = "failure";
		logger.debug("Entering signUp");
		FacesContext context = FacesContext.getCurrentInstance();
		
		if ( 	null != getUser().getPassword() && 
				null != getPassword2() && 
				!getUser().getPassword().equals(getPassword2())) {
			logger.error("passwords are not identical");	
			FacesMessage message = new FacesMessage("passwords not identical!");
			context.addMessage("signUpForm", message);
			
		}
		
		else if ((new UserManager()).findUser(getUser().getUserName())) {
			logger.info("user already exists!");
			FacesMessage message = new FacesMessage("Email already exists!");
			context.addMessage("signUpForm", message);

		}
		else {
			(new UserManager()).addUser(getUser());
			logger.info("Adding user bean in the session");
			jsfUtils.addToSession("user",getUser());
			result="success";
		}
		return result;
	}
	
	public String logout(){
		logger.debug("Signing out: " + user.getEmail());
		
		logger.info("Removing user bean from the session");
		jsfUtils.removeFromSession("user");
		
		// TODO - clean the session before handing over the control
		return "success";
	}

	/*
	 * Updates the user record in the database. Calls the updateUser() method in the UserManager
	 */
	public String updateUser() {
		if (new UserManager().updateUser(getUser())) {
			logger.info("User updated successfully!");
			return "success";
		}
		else {
			logger.error("User could not be updated!");
			return "failure";
		}
	}
}

The presentation layer for the web is created in Java ServerFaces. A JSF page utilizes JSF tags, which in turn spawns an html file, which is interpreted by the web browsers (Internet Explorer, Firefox etc). The JSF pages collect the user input, check for the input errors based upon the defined rules, display error messages and hand over the collected input to the Controller. JSF pages also present results on the web provided by the controller.

Listing 6. Java ServerFaces - tickers.jsp

	
< f:subview id="tickers">
	< f:loadBundle basename="messages" var="prompts"/>
	< h:form>	

< h:outputText styleClass="resource_selected" value="  You are signed in as: "/>
< h:outputText styleClass="resource_selected" value="#{userController.user.email}"/>
< f:verbatim><br><br></f:verbatim>

		< h:dataTable		id="tickers" 
						value="#{tickerController.tickers}"
						var="ticker"
						rowClasses="oddRow, evenRow" 
						headerClass="tableHeader">
		
			<!--  Ticker Symbol -->
			< h:column>
				< f:facet name="header">
					< h:panelGroup>
						< h:outputText value="Ticker"/>
					</h:panelGroup>  
				</f:facet>
					< h:outputText value="#{ticker.tickerName}"/>
			</h:column>
						
			<!-- Item Price -->
			< h:column>
				< f:facet name="header">
					< h:panelGroup>
							<h:outputText value="Price"/>
					</h:panelGroup>				    	
				</f:facet>
				< h:outputText value="#{ticker.price}"/>
			</h:column>
						
			<!-- Trade Date -->
			< h:column>
				< f:facet name="header">
					< h:panelGroup>
							<h:outputText value="Trade Date"/>
					</h:panelGroup>				    	
				</f:facet>
				< h:outputText value="#{ticker.tradeDate}"/>
			</h:column>
	
		</h:dataTable> 
	</h:form>		
</f:subview>

The presentation layer for the telephony part is created using Java ServerPages, which in turn spawns a VoiceXML file. A VXML file is interpreted by the voice browser. The voice browser collects input from the caller over the phone, validates the input based upon the defined rules, prompts over error messages and hand over the collected input to the Controller. JSP based VoiceXML pages also narrate results on the telephone provided by the controller.

Listing 7. Java ServerPages based voiceXML file

< form id="ticker" scope="dialog">
	< block name="block61">	

		< prompt bargein="true">
			Ticker Symbol <%= ticker.getTickerName() %>
			< break time="500"/>
			Price 
			< say-as interpret-as="currency">$<%= ticker.getPrice() %></say-as>
			
			< break time="500"/>
		</prompt>

	</block>			
</form>

</vxml>

Listing 8. Static grammar files

	
MAINMENU
[LIB_YES_NO:s { < yesno $s > }]
LIB_YES_NO[
[
yes
yeah
yup
sure
okay
correct
right
(?(?yes that's) [right correct])
(?yes it is)
(you got it)
(yes i do)
(yes i would)
(yes it is correct)
]	{ return("yes") }

[
no
nope
incorrect
(no way)
(no it isn't)
(?no[it's that's] not [correct right])
(?no it isn't)
(?no it is not)
(?no it's not)
(no i don't)
(no i do not)
(no i wouldn't)
]	{ return("no") }
]

4. Compiling the Source Code

The source code of this demo application can be downloaded here. source code There is no copyright on the code. Feel free to modify the code. Go ahead and compile and the code. The source code also contains ANT files that can be used to create a war deployment file. After compiling, deploy the application on your favorite Tomcat server. There are a number of developer sites that offer voiceXML development environment. The demo application in this example has been deployed using Voxeo Community. In order to view the application demo, use this link.

5. Accessing the demo

For the web interface, click here. This will take you to the page where you can sign in or sign up and create your profile. For the telephony part, the example application can be accessed by dialing the voice server directly at 407-418-1961.

References and Acknowledgements

The demo tutorial is hosted on Voxeo Community site. There are some neat tutorials on that site for those who wish to dig more.

• All you need to know about VoiceXML, visit VXML Forum pages
• All you need to know about Java ServerPages, there are several resources on the web. I personally benefited from More Servlets , which is a great resource for all.
• All you need to know about Hibernate and Database Persistence, visit Hibernate official website
• All you need to know about Java ServerFaces, visit JSF tutorial website
• All you need to know about putting a VoiceXML application together, visit Voxeo Community pages