Using core telecom network features to develop web applications: Part 1. Web services method

Traditionally, building telecommunications applications implied dealing with telecom network complexities and having technical skills on telecom protocols, such as SMPP, MLP, and Parlay. This article describes how a third-party application developer can build web applications by using core telecom features that are available in the service provider's network. It also explains other approaches, including how to use the REST and web services capabilities included in the IBM® WebSphere® Telecom Web Services Server (TWSS) to build telecom applications with ease.

Raghunath Nair (raghunath.nair@in.ibm.com), Principal Software Engineer, I.B.M.

author photoRaghunath E. Nair is a principal software engineer in the IBM India Software Lab, in Bangalore. He joined IBM in 2006. His most recent role has been in design, development, and support of software for telecom for IBM WebSphere software, including IBM WebSphere TWSS and IBM WebSphere IMS Connector. His areas of expertise are middleware integration, SOA, web services, and telecom. He co-authored Using WebSphere Message Broker as an ESB with WebSphere Process Server in the IBM Redbooks series and has a Bachelor of Technology degree in Electronics and Communications from the University of Calicut.



Chandrashekar Naik (chandrashekar@in.ibm.com), Staff Software Engineer, I.B.M.

author photoChandrashekar B. Naik is a staff software engineer in the IBM India Software Lab. He joined IBM in 2004 and has experience in software design, development, and testing. His areas of expertise include Java, J2EE, and web services programming, including WebSphere Application Server, Telecom Web Services Server, Mobile Portal Accelerator, pervasive computing, and WebSphere software for telecom. He currently focuses on development, support, and testing of WebSphere Telecom Web Services Server. Chandrashekar is also a Sun-Certified Programmer and has a Bachelor of Engineering degree in Computer Science from Visveswaraiah Technological University, Belgaum.



22 March 2011

Also available in Chinese Russian Vietnamese

Introduction to the IBM WebSphere Telecom Web Services Server

IBM® WebSphere® Telecom Web Services Server, Version 7.1, provides telecom service providers ways to expose network functionality through RESTful bindings (based on the evolving OneAPI specifications) in addition to SOAP-based web services access. Together, the web service and RESTful interfaces provide easy access to service capabilities in a technology-independent way, using programming languages.

To complement the RESTful offerings in the Telecom Web Services Server, Dojo widgets have been provided for Terminal Location, SMS, and Payment services in the WebSphere Telecom Toolkit. These widgets can be easily embedded in a web page to create Web 2.0 style applications.


How the server fits into the telecom industry

Communication service providers are facing stiff competition to increase average revenue per user (ARPU) and to reduce churn. There is an urgent need to leverage the providers' existing network capabilities (including legacy infrastructure, such as signaling systems) and expose them for use by third-party applications in an easy and controllable fashion.

Figure 1. TWSS in the telecom Infrastructure
Telecom Applications accessing Network capabilities through TWSS

Larger view of Figure 1.

As Figure 1 illustrates, the primary goal of the WebSphere Telecom Web Services Server (TWSS) is to open telecommunications services as consumable web services, as well as REST style URIs. Third-party application providers benefit by leveraging these APIs to create value-added services for customers, thereby eliminating the need to know the protocol-level programming. This reduces the barrier of entry for medium-sized Third Party Application providers that do not have employees with extensive skill sets but want to create innovative composite telecom services for their customers. For example, a policy-driven service exposure ensures that the service is customizable for different Service Level Agreements (SLAs) for different customer categories.


Architecture of the Telecom Web Services Server

This section briefly describes the architecture of IBM WebSphere Telecom Web Services Server (TWSS), which has three components:

  • Access Gateway (AG)
  • Service Policy Manager (SPM)
  • Service Implementations

Access Gateway

The Access Gateway provides a policy-driven, traffic monitoring, message capture, authorization, and management capabilities. These services are provided at the application layer, and are enforced for each web service request using knowledge of the requester, target service, and invoked operation. The Access Gateway provides flexibility for the construction of tailored message processing logic, in accordance with your enterprise's network policies. This logic can be customized to meet your network requirements. The services implemented in the Service Implementation layer of TWSS are not directly exposed to the third-party applications. Instead, they are made available through the Telecom Web Services Server Access Gateway, which runs on IBM WebSphere Enterprise Service Bus.

The AG implementation follows the Service Component Architecture (SCA) component model. The Access Gateway implementation comprises of mediation primitives which are small, goal driven pieces of message processing logic that can be combined and rearranged together in any desired order to create mediation flows.

See IBM Telecom Web Services Access Gateway Information Center v7.1 for details. There is a link to it in the Resources section.

Service Policy Manager

As the previous section explained, the Access Gateway component is policy-driven, which means that the behavior of mediation primitives in the Access Gateway mediation flows are governed by configured policies. The Service Policy Manager provides management, storage, and retrieval functions for this policy configuration data and the runtime data used to customize service delivery for a given requester.

See the Service Policy Manager section of the IBM WebSphere Telecom Web Services Server, Version 7.1 Information Center for details. There is a link to it in the Resources section.

Service Implementations

The Service Implementations (SI) actually hosts or implements the numerous services which need to be accessed by the third-party applications. These service implementations can be broadly categorized into the following kinds:

  • Web service implementations that operate over SIP/IMS
  • Web service implementations based on IBM® WebSphere® software
  • Web service implementations based on the Direct Connect protocols
  • Web service implementations based on Parlay

See the Web Service Implementations of the IBM WebSphere Telecom Web Services Server Version 7.1 Information Center for more about the available services under each category. There is a link to it in the Resources section.

REST support in TWSS 7.1

From TWSS v7.1 onward, some of the service implementations are available through simpler REST (Representational State Transfer) interfaces apart from standard web services. This is based on the GSMA OneAPI (Open Network Enabler API) v0.9 specification, which is a set of specifications for network operators for exposing their network capabilities to third-party application developers. There is a link to it in the Resources section. As of TWSS 7.1, the following operations are supported through REST:

Terminal Location

  • getLocation

Payment

  • chargeAmount
  • refundAmount

SMS

  • sendSms
  • getSmsDeliveryStatus
  • getReceivedSms


See REST-style access using HTTP in the IBM WebSphere Telecom Web Services Server, Version 7.1 Information Center for details on each of the above operations. There is a link to it in the Resources section.

The rest of this article focuses on the different ways in which the network capabilities exposed by IBM TWSS can be used to develop telecom applications.


Scenario 1. Create a telecom application with web services

This scenario demonstrates how to develop a telecom application by using the Short Message Service (SMS) and Terminal Location web services exposed by TWSS.

The use case

  1. Debbie registers as a subscriber to a third-party application, GeoAlert, where she has registered for a location-based reminder service that reminds her when she is near a particular geographical area.
  2. Upon receiving the request, the GeoAlert application starts a geographical notification using the Parlay X Terminal Location web service. GeoAlert requests the Terminal Location web service to send a notification at a particular URL when Debbie enters the specified area
  3. When Debbie enters the specified area, a location notification is triggered. GeoAlert is notified at the URL specified while starting the geographical notification. This URL is typically called the "Catcher URL," or simply Catcher.
  4. Upon receiving the location notification, GeoAlert sends an SMS (reminder message) to Debbie.

Develop the web application

Follow these steps to begin developing the application:

  1. Generate TerminalLocationNotificationManager web service client
    This serves as a web service client to invoke the Parlay X Terminal Location web service. The client invokes the startGeographicalNotification operation of TerminalLocationNotificationManager interface
  2. Develop TerminalLocationNotification web service implementation
    This serves as a web service Catcher (to receive the notifications triggered). This web service endpoint is set while triggering the startGeographicalNotification, such that it serves as a Catcher application to receive the notifications. To accomplish our use case we will be sending an SMS (reminder) message from this web service implementation, upon receiving the notification.
  3. Test your application
    These steps demonstrate how to test the application developed, using IBM WebSphere Telecom Toolkit.

Tools

  • IBM Rational Application Developer Version 7.5.1. We use this for all of the steps, because it simplifies the generation of client and web service implementation.
  • IBM WebSphere Telecom Toolkit Version 7. Toolkit will be installed into Rational Application Developer. It enables third-party application developers to quickly build and test rich applications involving SMS, MMS, Location, Presence and Call control. It also provides a platform to develop Proof of Technology (demos), evaluate solutions and explore the various capabilities offered. It also serves as a simulator for IBM WebSphere Telecom Web Services Server.

Generate a TerminalLocationNotificationManager web service client

  1. Start Rational Application Developer, and create a new Java project called StartNotificationClient.
  2. Create a folder named WSDL under the Java project.
  3. Download and copy the Parlay X 2.1 Terminal Location WSDL files to the WSDL folder that you created. To download, see the Parlay X 2.1 Specifications. There is a link to it in the Resources section.
  4. Locate parlayx_terminal_location_notification_manager_service_2_3.wsdl in the WSDL folder, right-click and, from the drop-down menus, select Web Services > Generate Client.
Figure 2. Generate Terminal Location Notification Manager Client
Generate Web service client from WSDL using Rational Application Developer

Larger view of Figure 2.

  1. Make sure that you select these options:
    • Web service runtime: IBM WebSphere JAX-RPC
    • Client project: StartNotificationClient
Figure 3. Select the web service runtime option
Configuration settings for Web Service Client

Larger view of Figure 3.

  1. Click Finish.
  2. Now, create a Java class under the com.ibm.client package called StartNotificationClient.java.

Note: The entire Java code is provided as a Project Interchange in the Downloads section. Make sure that StartNotificationClient project's build path has a reference to the com.ibm.ws.webservices.thinclient_7.0.0.jar file available in <RAD75Home>\runtimes\base_v7\runtimes.

Code Listing 1 shows sample code for the StartNotificationClient.java package, which actually invokes the startGeographicalNotification operation of the Terminal Location service. This piece of code, in effect, starts monitoring the location of Debbie. The code in Listing 1 creates the different objects required by the startGeographicalNotification operation.

Listing 1. StartNotificationClient.java – Setting the parameters
// Subscriber sends location information in the form of Latitude and Longitude
String address = args[0];
float fLat = (float) Float.parseFloat(args[1]);
float fLong = (float) Float.parseFloat(args[2]);

/*Setting the Reference object. Reference specifies the endpoint where the 
location notification need to sent by the terminal location web service */
	
SimpleReference reference = new SimpleReference();
URI endpoint = 
new URI("http://localhost:9081/TestWeb/services/TerminalLocationNotification");
reference.setEndpoint(endpoint);
reference.setInterfaceName("TerminalLocation");
reference.setCorrelator("DemoCorr"+Calendar.getInstance().getTimeInMillis());
		
//Converting the address to URI. 
URI[] addresses = new URI[1];
addresses[0]=new URI(address);
			
//Setting the radius and accuracy
float fRad = (float) 5.0;
float tAcc= (float) 100.0;
	
/*Setting the criteria.
ENTERING - Triggers the notification when subscriber enters the region specified 
by Latitude, Longitude and Radius
LEAVING - Triggers the notification when subscriber leaves the region specified 
by Latitude, Longitude and Radius */

EnteringLeavingCriteria crt = new EnteringLeavingCriteria("Entering");
			
//CheckImmediate specifies, if the location of subscriber needs to checked immediately
boolean chkImm = false;
	
//The frequency of the notification
TimeMetric freq = new TimeMetric();
freq.setMetric(new TimeMetrics("Millisecond"));
freq.setUnits(10000);

The code in Listing 2 shows how the startGeographicalNotification web service operation is invoked.

Listing 2. StartNotificationClient.java – Invoking the operation
//Obtain TL Manager Proxy
TerminalLocationNotificationManagerProxy tlProxy = 
new TerminalLocationNotificationManagerProxy();
			
//Set the endpoint where the Terminal Location Notification Manager web service
tlProxy.setEndpoint(url);
			
//Obtain the TL Manager
TerminalLocationNotificationManager  tlMgr = 
tlProxy.getTerminalLocationNotificationManager();
			
//Invoke the startGeographicalNotification
System.out.println("Calling the web service");
tlMgr.startGeographicalNotification(reference, addresses, 
fLat, fLong, fRad, tAcc, crt, chkImm, freq);

Note:
If there are unresolved classes, for example EnteringLeavingCriteria, change the visibility of the class to public.

Develop TerminalLocationNotification web service implementation

For receiving notifications, the GeoAlert must implement the Terminal Location Notification web service, and this implementation will be used as a Catcher to receive the notifications triggered.

  1. Create a dynamic web project, and call it TLCatcherWeb.
  2. Ensure that the Add project to an EAR check box is selected with EAR Project Name being TLCatcherWebEAR.
  3. Download and copy the Parlay X 2.1 Terminal Location WSDL files into the TLCatcherWeb > WebContent > WEB-INF > wsdl folder. To download, see Parlay X 2.1 Specifications. There is a link to it in the Resources section.
  4. Locate the parlayx_terminal_location_notification_service_2_2.wsdl file in the WSDL folder, right-click it and, from the drop-down menus, select Web Services > Generate JavaBean skeleton.
Figure 4. Generate JavaBean skeleton
Selections from three menus, as described

Larger view of Figure 4.

  1. Make sure that you select the following options for these fields (see Figure 5):
    • Web service runtime: IBM WebSphere JAX-RPC
    • Service project: TLCatcherWeb
    • Service EAR project: TLCatcherWebEAR
Figure 5. Configuration settings
Web service configuration dialog window

Larger view of Figure 5.

  1. Click Finish. After clicking Finish, if you are prompted for server startup, click Cancel.
  2. The skeleton bean created in the previous step contains a set of methods that correspond to the operations described in the Terminal Location Notification WSDL. When the bean is created, a skeleton for each method is provided, as Listing 3 shows.
Listing 3. Terminal Location Notification skeleton code
package org.csapi.www;
public class TerminalLocationNotificationBindingImpl 
implements org.csapi.www.TerminalLocationNotification{
	
//This operation is invoked on a successful location notification
public void locationNotification(java.lang.String correlator, 
org.csapi.www.LocationData[] data, 
org.csapi.www.EnteringLeavingCriteria criteria) throws java.rmi.RemoteException {
}

//This operation is invoked on a location notification error
public void locationError(java.lang.String correlator, java.net.URI address, 
org.csapi.www.ServiceError reason) throws java.rmi.RemoteException {
}

//This operation is invoked upon location notification end
public void locationEnd(java.lang.String correlator) throws java.rmi.RemoteException {
}
}

When a Location Notification is received, fulfilling Debbie's criteria, the GeoAlert application sends an SMS reminder message to Debbie's mobile phone. To accomplish this, the service needs to implement the sendSMS client within the locationNotification operation and invoke the sendSMS operation.

  1. To generate the SMS client, download and the copy parlayx_sms_send_service_2_2.wsdl file into the WSDL folder, right-click, and select > Web Services > Generate Client. To download please, please see the Parlay X 2.1 Specifications. There is a link to it in the Resources section.
  2. Make sure that you select these options:
    • Web service runtime: IBM WebSphere JAX-RPC
    • Client project: TLCatcherWeb
    • Client EAR project: TLCatcherWebEAR
Figure 6. Web service client configuration
Web service client dialog window

Larger view of Figure 6.

This will create a package structure with stubs for the sendSMS operation.

The locationNotification method in the TerminalLocationNotificationBindingImpl class is the one that gets invoked or notified when Debbie's criteria is satisfied. According to the use case defined, GeoAlert sends a reminder to Debbie through SMS. Listing 3 shows sample code for invoking the sendSMS operation of Short Message Service.

Listing 4. Terminal Location Notification sample code
//This operation is invoked on a successful location notification
public void locationNotification(java.lang.String correlator, 
org.csapi.www.LocationData[] data, 
org.csapi.www.EnteringLeavingCriteria criteria)
throws java.rmi.RemoteException {
      	
String smsResp = "";
		
/*Fetch the address from the LocationData element. 
Later use this address for sendSms operation */
URI[] addresses = new URI[1];
addresses[0] = data[0].getAddress();
		
/*Fetch the Location Info in the form of Latitude and Longitude.
Send this information in the SMS message to the subscriber*/
float lat = data[0].getCurrentLocation().getLatitude();
float lon = data[0].getCurrentLocation().getLongitude();
	
//Set the URL where Send SMS web service is running
String url = "http://localhost:9081/ParlayX21Web/services/SendSms";
		
try{
//Obtain SendSMS proxy
SendSmsProxy smsProxy = new SendSmsProxy();
		
//Set endpoint where web service is running
smsProxy.setEndpoint(url);
System.out.println("---Endpoint set---");
		
//Obtain the service handler
SendSms smsSvc = smsProxy.getSendSms();
System.out.println("---Handle to Service obtained. Invoking Web Service---");
		
//Compose the SMS message
String msg = "Hello Customer, Greetings from Location Based Reminder App. " +
"You have reached the Location where you had set a reminder. " +
"Your current location is Latitude = " + lat +
"Longitude = " + lon;
		
//Invoke sendSms operation of Short Message Service
smsResp= smsSvc.sendSms(addresses, "LocationBasedReminderAPP", null, msg, null);
System.out.println("---Sent Web Service request---");
}
catch(Exception e)
{	
}
}

When the locationNotification method is invoked, it sends an SMS message to Debbie's mobile device.


Test the application on the WebSphere Telecom Toolkit

To test the application that you developed, download and use the IBM WebSphere Telecom toolkit. There is a link to it in the Resources section. This free toolkit enables third-party application developers to quickly build and test rich applications involving SMS, MMS, Location, Presence, and Call control. It also provides a platform to develop proof of technology demonstrations, to evaluate solutions, and to explore the various capabilities offered.

See IBM Education Assistant - WebSphere Telecom Toolkit for more details. There is a link to it in the Resources section.

Notes:

  • WebSphere Application Server v7 profile has been created in the Rational Application Developer runtimes
  • IBM WebSphere Telecom Toolkit v7.1 is installed on Rational Application Developer v7.5.1

Deploy and run the Telecom Web Services Simulator

  1. Create a WebSphere Application Server v7 profile in Rational Application Developer.
  2. Start the WebSphere server.
  3. Right-click the server, and select Deploy Telecom Web Services Simulator (see Figure 7). This deploys an application called WSSimulatorEAR.
Figure 7. Deploy Telecom Web Services Simulator
Deploy Telecom Web Services Simulator on WebSphere Application Server using Rational Application Developer

Larger view of Figure 7.

  1. After deployment has finished, right-click the server (see Figure 8), and select Run Telecom Web Services Simulator Client.
Figure 8. Run Telecom Web Services Simulator client
Project Explorer and Java tab views

Larger view of Figure 8.

There are six runtime views that display all of the simulator configuration and runtime data: Activity, Call, Device, Group, Presence, and Map. See the IBM Education Assistant – WebSphere Telecom Toolkit configuration for more information on each of these views.


Deploy the application

StartNotificationClient is a stand-alone Java application.

The EAR project, TLCatcherWebEAR, needs to be deployed on a server runtime. For this purpose, use WebSphere Application Server 7 as the runtime engine for this application.

  1. Right-click on WebSphere Application Server 7 (WAS 7), select Add and Remove Projects.
  2. In the Add and Remove Projects window, add TLCatcherWebEAR.
  3. Click Finish.

Now the Terminal Location Notification Web Service (Catcher) is deployed and running.

Test your application

Before testing the GeoAlert application functionality, verify the following: -

  1. Run the Java class StartNotificationClient, providing the following arguments:
    • arg1: subscriber_phone_number. This number should exist in the Telecom Web Services Simulator. For example, tel:+1-2225552003
    • arg2: latitude. For example, 0.03
    • arg3: longitude. For example, 0.002

    Example: java StartNotificationClient tel:+1-2225552003 0.03 0.002
  2. Make sure that the latitude and longitude passed as parameter are in the vicinity of the Map view in the simulator.
    Note: To get the latitude and longitude of a particular location in the map, drag any of the icons to the particular place, and the co-ordinates for that location will be displayed, as in Figure 9.
  3. Go to the Map view of the simulator. Choose subscriber Debbie (tel:+1-2225552003) by choosing her icon, which is a mobile phone graphic.
Figure 9. Map view of the Telecom Web Services Simulator
Text box by icon shows Debbie's info, coordinates

Larger view of Figure 9.

Upon receiving the request from Debbie, GeoAlert starts the Geographical Notification on Debbie's account. The stand-alone Java application that you developed kicks offs the geographical notification.

Notification Started can be verified in the Map view of the toolkit simulator, as shown in Figure 10.

Note:
If the circular notification area does not appear, click Debbie's mobile phone icon.

Figure 10. Notification set up for Debbie
Map view shows Notification area set up for Debbie

Larger view of Figure 10.

  1. Switch to the Activity view of the simulator, and verify that the notification activity has been created under Brown Motors > Debbie.
Figure 11. Activity view showing the notification created for Debbie
View shows list of Brown Motors subscribers

Larger view of Figure 11.

  1. Switch back to the Map view.

Now Debbie goes shopping and enters the notification area that she wants to be reminded about when she is nearby. In the toolkit, you can simulate this event by dragging Debbie's phone icon inside of the notification ring.

Figure 12. Debbie enters the specified area
Map view showing Debbie in the notification area

Larger view of Figure 12.

After Debbie enters the notification ring, a locationNotification is triggered by the Terminal Location web service. The notification triggered is caught by the GeoAlert Catcher application that you developed earlier (TLCatcherWebEAR), so the Catcher sends an SMS message to Debbie as a reminder. Notice that you invoke the sendSMS operation in the locationNotification method of the Catcher.

  1. Switch back to the Activity view, and verify that Debbie has received the SMS reminder.
Figure 13. Reminder sent to Debbie
Activity view shows the SMS

Larger view of Figure 13.

Project Interchange with sample code
Ensure that the StartNotificationClient project's build path has a reference to the com.ibm.ws.webservices.thinclient_7.0.0.jar file that is available in RAD75Home\runtimes\base_v7\runtimes.

Download

DescriptionNameSize
Source code for Scenario 1TWSS_Usage_Sample_PI.zip115KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, Industries, DevOps
ArticleID=642496
ArticleTitle=Using core telecom network features to develop web applications: Part 1. Web services method
publish-date=03222011