Developing next-generation converged applications with SIP and asynchronous Web services

Learn how you can develop a converged SIP and Web service application that asynchronously provides connectivity between IMS networks and legacy systems. Using a sample TCAP application, this article explains some of the decisions you'll need to make and provides insight into the debugging of converged applications.


Bouna Sall (, Senior Managing Consultant, IBM

Bouna Sall photoBouna Sall is a Senior Managing Consultant at IBM Software Services for WebSphere (ISSW) for Service Providers in Annapolis, Maryland. He has extended experience in application and middleware software, including development, integration, test and support. He has worked on a number of large complex development and system integration projects in the telecommunications industry. Bouna holds an Electrical Engineering degree from the University of Maryland, College Park. You can reach Bouna at

Chris Dacombe (, Accelerated Value Leader/Specialist, IBM

Chris Dacombe photoChris Dacombe is an Accelerated Value Leader/Specialist in the Accelerated Value Program (formerly Premium Support) at IBM. He previously worked in the IBM Software Services for WebSphere (ISSW) Service Provider practice for more than 5 years on the development, deployment and testing of many IMS SIP solutions based on the WebSphere product family. He is a graduate of The City University, London, where he studied Physics and Electronics. You can reach Chris at

Zhijian Pan (, Managing Consultant, IBM

Zhijan Pan photoZhijian Pan is a Managing Consultant at the IBM Annapolis Lab, in the IBM Software Services for WebSphere (ISSW) Service Provider Practice. He has worked on many IMS SIP solutions based on the WebSphere product family. He has a Ph.D. in Computer Science from the University of Maryland, College Park and has written numerous journal publications in computational science and computational creativity. You can reach Zhijian at

17 March 2010

Also available in Chinese Russian


With the growth of technologies such as instant messaging, Internet Protocol (IP) telephony, and video over IP, a new wave of applications are being created combining multiple technologies over IP. To support these technologies, such as Session Initiation Protocol (SIP) and IP Multimedia System (IMS), telecommunication service providers (TSP) need to connect and exchange information between the new IMS networks and legacy systems, such as Transaction Capabilities Application Part (TCAP) and Signaling System #7 (SS7) networks. New converged SIP and Web services applications are being developed to connect the two networks asynchronously.

In this article, we'll use a TCAP application to discuss the best practices and lessons learned when developing production-ready applications. The discussion centers on the following:

  1. What are the advantages and disadvantages of using synchronous versus asynchronous Web services in the TSP network?
  2. How can you develop a next-generation converged application with SIP and Web services?
  3. How do you synchronize SIP and HTTP servlets in a converged application
  4. Should you consider using HTTP Keepalive for best performance when communicating with the remote end?
  5. How can you develop and debug applications during performance load and network reliability testing? This is required for deploying telecommunications carrier-grade applications within the TSP network.

Synchronous versus asynchronous Web services in the service provider network

When developing a converged application, the response messages for Web service calls can be handled by the application synchronously or asynchronously.

However it is not as simple as that. There are two levels at which the distinction can be made. Messaging can be synchronous or asynchronous at the application level, in which case the application code either waits for the response message or returns control immediately and informs the application later by means of a callback when the response is received.

Messaging can also be synchronous or asynchronous at the communications level, in which the container either waits for the low-level responses on "the wire" or continues processing and handles the response when it eventually comes on "the wire" in a different thread.

Thus, there are four possible configurations

  • Synchronous application with synchronous communications
  • Synchronous application with asynchronous communications
  • Asynchronous application with synchronous communications
  • Asynchronous application with asynchronous communications

Communication-level messaging responses

When developing a converged application, the container handles the processing of the communication-level messaging responses. The default behavior is to handle these responses synchronously so that the container waits for the response message and does not continue processing in that thread.

To achieve asynchronous communications you must set the property on the client request context with a boolean value of true. When this property is enabled, WS-Addressing headers that provide additional routing information for the messages are added to the request and response messages. These messages will then be handled by a different thread in the container when received. This frees the current thread, allowing it to process other jobs and not have to wait for the response message

Synchronous Web services application messaging

With synchronous Web services application messaging, the application code blocks while waiting for the response message to be received. This has a number of advantages and disadvantages.

The advantages include

  • Simpler code because there is no need to maintain context, as the message is processed inline.
  • Fewer race conditions because the messages are all handled sequentially in the code with no need for callbacks interrupting the flow.
  • Easier to debug because the messages are all handled sequentially and the flow is not disjointed by callbacks and interrupts.

The disadvantages include

  • Leaving the call hanging can lead to billing issues because the application is unable to process incoming call hang-ups when it is stuck waiting for a response message. The longer the response takes, the more the customer is unfairly charged.
  • More resources are required for lower call volumes due to the synchronous behavior of the application having to wait for each message.

Although simpler, the synchronous method does not provide the robustness or meet the requirements for an application in the TSP network.

Asynchronous Web services application messaging

When developing asynchronous Web services, there are two methods of handling responses: polling and callback.

In the TSP network, it's important that the response to the Web service request is handled immediately after it is received by the container. For that reason, we'll focus on using the callback method in this article. The callback method returns the handle back to the application so that it can keep processing other messages without having to poll for the response message. This method is timelier than the polling method and guarantees that the response is handled immediately. The polling method may have delays due to response availability and polling cycle.

The following code sample shows the use of the callback handler. The container invokes this callback handler when it receives a Web service response from the request sent earlier.

Listing 1. Sample code defining an asynchronous callback handler class
// Define the async callback handler
ServiceCallbackHandler asyncHandler = new ServiceCallbackHandler(param1,param2);
// Start the callback handler 
Future<?> response = AsyncResponseMessage(message, asyncHandler);

// Define the class for the callback handler
public class ServiceCallbackHandler implements AsyncHandler<SendResponse> {	
// Define parameters that can be passed to the callback handler
private int param1 = 0;
private SipApplicationSession param2 = null;		
// Define the callback handler method
	public ServiceCallbackHandler(int param1, SipApplicationSession param2) {
			param1 = dialogId;
			param2 = appSession;

	public void handleResponse(
		Response<SendResponse> response) {
		// Business Login Added Here	

Some of the advantages to the callback method are:

  • The response is processed immediately with no waiting.
  • The application can continue processing and handle more concurrent traffic because resources are not tied up waiting for responses.
  • The application is not blocked waiting for a response. This allows the application to immediately process SIP calls, like hang-up, at any time, and to generate correct billing records.

These advantages are very important in a service provider environment as the customer is being billed for the length of the call and possibly for additional resources and services. Furthermore, it's vital that calls are handled as quickly as possible for customer satisfaction.

The disadvantages of the callback method are:

  • In error conditions, if a response is lost it can leave resources hung
  • The code can be more complicated. There is a need to correlate the sessions to ensure that the response message is associated with the correct call.
  • More error handling and clean-up code is required.
  • The Future object is not serializable, which means that in a highly available environment the handle returned by the callback handler cannot be replicated. This means that when a failover occurs, it's not possible to cancel outstanding callbacks.

These disadvantages make development more difficult, but they don't outweigh the advantages.

Developing next-generation converged applications with SIP and Web services

New telecom applications require access to both legacy and next-generation networks. You can achieve this by developing a converged application that uses the SIP protocol to communicate with the next-generation network and HTTP to access legacy protocols. In this article, we'll use a sample TCAP application to illustrate this. Our application has a SIP interface that provides connectivity to the IMS network and an HTTP interface that talks to TCAP over Web services. Our next-generation application is hosted by WebSphere Application Server Network Deployment and leverages the base capabilities of WebSphere.

In our example, the application is triggered when the application server receives a new SIP call. The application then initiates a TCAP transaction with a TCAP Web service interface.

For the sake of this article, we use a simple call flow, as shown in Figure 1, to simulate a simple TCAP play prompt application. The diagram has been simplified to remove any Session Description Protocol (SDP) and ISDN header handling, intermediate media server SIP messaging, and messaging that might be necessary to simulate other parts of the TCAP exchange, such as simulating additional Begin messages.

Figure 1. Sample SIP/TCAP call flow
Sample SIP/TCAP call flow

Overview of the sample next-generation converged SIP and TCAP application

The application is composed of three main interactions:

  1. Processing the inbound SIP session.
  2. Issuing TCAP request events:
    1. Sending an outbound TCAP Web service request
    2. Processing the inbound TCAP Web service response
  3. Receiving TCAP indication events:
    1. Processing the inbound TCAP Web service request
    2. Sending the outbound TCAP Web service response

We assume that you are familiar with the standard JSR 116 SIP servlet development techniques. It would also be helpful to be familiar with the JSR 11 TCAP specification that describes the TCAP protocol. Both JSRs are available at the Java Community Process web site.

The converged application is composed of two major parts. The first part is a SIP servlet for processing the inbound and outbound SIP messages. The SIP servlet initiates an outbound Web service request as a result of those SIP messages (in this instance, the converged application is acting as a Web services client). The second part is an HTTP servlet that is used to process any inbound Web Service calls (in this instance the converged application is acting as a Web services server). Both components share a common data structure called application data.

Developing the SIP servlet

The SIP servlet was developed using standard JSR 116 SIP servlet programming techniques. For more information on how to develop SIP servlets, refer to the following developerWorks articles: Session Initiation Protocol in WebSphere Application Server V6.1, Part 1 and Part 2.

The init() function is a standard JSR 116 init() function. The core processing of the inbound and outbound SIP messaging is implemented in the standard JSR 116 doInvite() processing block. In this article, we won't describe the actual SIP servlet programming, but will instead concentrate on those aspects that are particular to sending and receiving the TCAP Web services.

The initial step is to process the SIP INVITE message and respond with a 200 OK. The next step is to generate a TCAP BEGIN message with the associated dialog and component parameters. You should write the core application part of the TCAP code by using the TCAP setters and getters (such as setQualityOfService()) to progressively build up a request object.

There are also some parameters that need to be uniquely set for every call, such as the dialogID. To do this, we created a utility method called getNewDialogueId() to generate a unique dialogID for this specific TCAP session. It is the responsibility of the application programmer to write the implementation code that actually generates the unique ID for each call. The dialogID that is generated is stored in the applicationData object as follows: applicationData.setDialogId(utils.getNewDialogId(applicationData));

The next step is to generate an encoded URI that will be used for session affinity later when the application processes Web services requests sent to it from the TCAP interface. You do this by first retrieving the IBMApplicationSession and then calling encodeURI() as shown in Listing 2. With session affinity, messages that are destined for a certain application session are always routed to the same session in a cluster.

Listing 2. Sample code generating an encoded URI that will be used for session affinity
IBMApplicationSession ibmSess = (IBMApplicationSession) appSession;

// Get my HTTP endpont
InetAddress in = InetAddress.getLocalHost();
appEncodedUri =

When deploying the application in a clustered environment, the application should use the IP address of the proxy fronting the application server cluster, instead of the host address (in.getHostAddress()). Furthermore, if the system is configured with a front-end load balancer with MAC forwarding enabled, the application needs to use the loopback address aliasing the load balancer’s virtual IP address to generate the encoded URI. This is especially crucial under failover conditions when WebSphere uses the application session ID in the encoded URI to route requests to the replication peers of the failed application servers.

Sending the outbound request

Now we're ready to send a request, such as the TCAP Begin request. To do this, we'll call the sendWS() method, which is used to set up and send a Web service request to the TCAP interface. This method masks much of the coding that is necessary to create an asynchronous request. It uses JAX-WS to dispatch the asynchronous SOAP request over HTTP and also sets the asynchronous callbackHandler for processing the response, described in Asynchronous Web services application messaging. The TCAP application developer needs to define a callbackHandler to correctly process the asynchronous Web service response messages from the TCAP interface.

We use the encoded URI that we generated earlier to set application session affinity for this particular request, as shown in Listing 3.

Listing 3. Sample code setting the encoded URI in a TCAP request message
// Set the encoded URI in the request message for the specific app session

After sendBegin() has returned, we capture the current state of the TCAP application by setting the state on the applicationData object, which will be stored to the application session context in case of failover, as shown in Listing 4.

Listing 4. Sample code advancing the state of a current call
// Begin was sent, set the state appropriately

Then we save that to the application session, as shown in Listing 5.

Listing 5. Sample code adjusting the attribute of a current call
// Save the application data in the application session
appSession.setAttribute(Constants.APP_DATA, applicationData);

Finally, we start a timer handler, as shown in Listing 6, to handle the scenario where the Web service client callback handler is never called, which will result in a timeout. This handler is responsible for processing the timeout situation and handling it with the correct subsequent TCAP messaging and, if necessary, terminating the call.

Listing 6. Sample code invoking a timer to track the state of a current call
// Start first timer to track the WS response from the TCAP Interface
applicationData.getWSBeginSentWaitingForResponseTimer(), true,

Processing the asynchronous response message

The container invokes the defined callback method when it receives a response for the previously sent request. The response message on the client is processed within the callback handler by implementing the method handleResponse() in the ServiceCallbackHandler class, as described in Asynchronous Web services application messaging.

When this handler is invoked, it first needs to get the current application context. This is done using the dialogID that we used in the request, as shown in Listing 7.

Listing 7. Sample code retrieving a call session associated with a callback
// Retrieve the unique dialog ID from the callback message
dialogID = Integer.toString(response.get().getDialogId());

// Retrieve the correct application session from the context memory
appSession = (SipApplicationSession) sContext.getAttribute(dialogID);
applicationData = (SampleApplicationData) appSession.getAttribute(Constants.APP_DATA);

This handler also includes any necessary processing for tearing down the SIP session if, for example, an ABORT message is received from the TCAP interface. This processing is all based on the current call state that was previously set in the call.

Developing the HTTP servlet

As previously mentioned, the application also acts as a Web services server by implementing an HTTP servlet. Thus, when the TCAP interface receives messages from the TCAP peer, it subsequently sends a new Web service request to the application containing indication events.

Processing the inbound Web service request

When the TCAP interface receives the inbound request (H1) it dispatches a call to the correct application session using the encodedURI that was used in the request. In order for this to happen, the TCAP interface uses the encodedURI that was received earlier in the call scenario (WS1) and sets the endpoint for the outbound request to that value.

To process this message, you need to create the HTTP servlet by extending the javax.servlet.http.HttpServlet class, as follows: public class SampleTCAPHttpApp extends javax.servlet.http.HttpServlet

Like the JSR 116 SIP servlet programming model, the HTTP servlet provides for standard functions like init(), doGet(), doPost(), and so on. In our case, we'll start in the init() function because there are some things that will be needed by all sessions.

First, we need to create a new messageFactory and then a JAXB context, which will be used for processing the SOAP request. There are actually two different JAXB contexts that we use in the sample application. The first is used to read the XML configuration file; the second is used to print the object that is received after de-marshaling the SOAP request.

Listing 8. Sample code creating a new JAXB context for processing the SOAP message
msgFactory = MessageFactory.newInstance();
jbc = JAXBContext.newInstance(new Class[] { 
listener.jain.protocol.ss7.tcap.ObjectFactory.class });
jbcpo = JAXBContext.newInstance("listener.jain.protocol.ss7.tcap");

Next we need to look at the doGet() processing. This function is called when the inbound Web service request from the TCAP interface is received. The first thing we need to do is to get the application session context and subsequently the applicationData that we created during the outbound request stage, as shown in Listing 9.

Listing 9. Sample code retrieving a call session associated with a HTTP/SOAP message
// Retrieve the SipApplication session to get context.
HttpSession httpSession=request.getSession();
IBMSession extSession = (IBMSession)httpSession;
IBMApplicationSession ibmAppSession = extSession.getIBMApplicationSession();
SipApplicationSession appSession = (SipApplicationSession)ibmAppSession ;
SampleApplicationData applicationData = 
	(SampleApplicationData) appSession.getAttribute(Constants.APP_DATA);

Note: With JSR289, the use of these proprietary interfaces to access the application session is no longer necessary.

Now we're able to pass the request to the processReceivedMessage method, which will parse and print out the message, as shown in Listing 10.

Listing 10. Sample code converting a SOAP message into a Java object
// Process received message (parse message, print it and change app state) 
componentAndDialogRequest = processReceivedMessage(request, headers, 
	applicationData, appSession);

At this point the SOAP request has been converted into a Java™ object, and you can use various getters and setters to access the data. Upon exiting from the doGet(), the stack will automatically send an HTTP 200 OK response, completing that HTTP dialog.

We've now processed the message and sent the response, but there may be other application-specific logic that you would want to implement at this point.

Synchronizing SIP and HTTP servlets in a converged application

A typical converged next-generation application interfaces with IMS devices via SIP messages in the front-end, as well as communicates with SS7 network resources via TCAP components embedded in SOAP messages in the back-end, as illustrated in Figure 2. An IMS call initiated from the SIP client typically triggers a sequence of asynchronous TCAP events between the next-generation application and the TCAP stack interface. For example, after the next-generation application sends a Web service call containing a BEGIN TCAP message, the TCAP interface may return an asynchronous callback event back to the application, indicating the results of the BEGIN message after it is processed on the SS7 network. Further, the TCAP interface may also initiate asynchronous Web service calls (such as a CONTINUE TCAP message) back to the application. The application has to track and manage the status of each call based on both SIP and TCAP events described above, and ensure that when an exception occurs (such as a CALLBACK does not arrive within a time limit), appropriate actions are taken to tear down the call and gracefully de-allocate network resources.

Figure 2. A typical converged next-generation application interfacing with both IMS devices and legacy SS7 network resources
Typical converged next-generation application

Figure 3 shows how a typical high-level flow is implemented in our environment. It shows the initiation of a SIP session, followed by multiple Web service requests and responses.

Figure 3. An overview of the state machine of the sample application
Overview of the state machine of the sample application

Here, the converged application tracks and manages each call as a state machine. The S3 event (ACK message from the client) triggers the application to send WS1, the first Web service request event. It will re-transmit WS1 request up to three times if the callback to WS1 is not received in a timely fashion; otherwise, it will send an ABORT to the TCAP interface and tear down the call with the client. When a received callback indicates errors processing the WS1 message, the converged application may also tear down the call. Otherwise, the application tracks whether an inbound asynchronous Web service request (H1 message) arrives within the expected timeframe. If not, the application may also send an ABORT and tear down the call. Otherwise, it may follow with a response to H1, as well as a second outbound Web Service request (WS2), which will be processed in the same fashion as WS1. Such interactions between the converged application and the TCAP interface can repeat many times, until either the client ends the call (via a SIP BYE message), or the SS7 network disconnects the call (via the TCAP END message).

To ensure that the state machine described above functions correctly, it is critical for the converged application to synchronize the SIP and HTTP servlets deployed in the converged WebSphere Application Server container. This is because the instance of the SIP servlet and the instance of the HTTP servlet handling the same call are typically running on different threads. If both servlets are allowed to read and update the same state machine without synchronization, the state machine logic might not work. Let's look at how this issue is handled in our environment:

  • Only the SIP servlet handles SIP events and Web service callbacks
  • Only the SIP servlet can send outbound Web service messages
  • The HTTP servlet handles inbound Web service requests, but it has no direct access to the associated state machine. Instead it obtains a handle to the SIP servlet from the Context Memory. The only way it can update the status or trigger actions to a state machine is by calling the SIP servlet routines via the handle. Remember that this is being executed in the Web container thread. If anything else happens on the SIP container thread, we may encounter a race condition.
  • The SIP servlet routines called by the HTTP servlet are synchronized by the SIP servlet itself.
  • The application uses SipAppliationSession timers in the SIP servlet component of the application. This means the HTTP servlet cannot directly access or control timeout events, but it can do so via the SIP servlet handle.
  • The SIP servlet ensures that a new timeout event cannot be started for the same call, unless no other timeout event is pending or until the pending timeout is cancelled.

Using HTTP Keepalive for better performance

The HTTP protocol has a simple request-response paradigm. When a client decides to communicate with a server it opens a TCP connection to send an HTTP request message to a server. The server then uses the same connection to respond to the client with an HTTP response message. The transaction ends when the TCP socket connection is closed. This scenario is repeated for every HTTP request/response between the client and the server. This approach is slow, not very effective, and causes considerable performance problems.

HTTP Keepalive solves this performance problem by considerably reducing the overhead associated with establishing and tearing down TCP connections. It allows a client to send a number of requests over the same TCP connection without resetting the connection. This is done by sending additional header information in the HTTP request/response messages.

For our sample application, we implemented HTTP Keepalive in the TCAP interface to significantly improve performance. Keepalive is turned on by default in WebSphere.

Debugging applications during performance and network reliability testing

There are special availability, reliability and robustness requirements for developing and deploying telecommunications carrier-grade systems in the TSP network. Among other requirements, the system and application must adhere to the five-nine requirement and be highly available with no single point of failure.

To fully deploy this type of application in the TSP network, a special type of testing known as network reliability is performed on the system. This involves testing the application under a heavy load and simulating various failure conditions. The application must be able to properly handle the failures, while logging useful information about the failure. Furthermore, the application has to fully recover from the failure under constant load.

It's also important to perform extensive load testing under a full load to verify that there is no system or performance degradation over time. This requires execution of load tests of 72 hours or longer.

This testing methodology makes it very difficult to diagnose end debug error conditions, which may be very difficult to reproduce and happen under such high call volumes. Enabling tracing causes adverse effects and is not very effective under high call volume.

Following are some tips to help with debugging:

  1. Make your logging concise so that the minimal amount of information is recorded.
  2. Log message data on error scenarios. When an error occurs, make sure that enough data is logged. One method that works very well is to maintain a history of the last few messages in a circular buffer that can then be dumped when an error condition occurs. It's important to note that the call that fails with an error might not be the cause of the error, which could have happened much earlier. The data stored in memory could include all of the log events that a message would make during its flow. This allows you to see not only the flow of the failed message but also those that came before.
  3. Clean up error conditions. Make sure that when an error occurs you clean up. This can include invalidating sessions, canceling timers, canceling callback handlers or cleaning up any data structures that may need it.
  4. It's easy to forget that timers need clearing. If you're using timers to track events and to make sure messages arrive in a timely manner, it's important to cancel these timers when a message is received.
  5. Pass session information to the async callback handler. This gives you access to additional information that should be logged on a failure condition.
  6. When starting the HTTP and SIP servlets, take care initializing the common application data and starting timers in the Init functions, as either SIP or HTTP servlet may initialize first.
  7. As discussed in Synchronizing SIP and HTTP servlets in a converged application, you must take care to ensure that the SIP and HTTP servlets are correctly synchronized.

Debugging can involve the use of tools such as network packet sniffers to capture network packets. These packets can then be analyzed to view the flow of the message and, most importantly, how long it takes the messages to travel between components. This can show you whether there's a problem with a component taking too long to process a message.

The most difficult part of debugging is tracing a message through the system, as it may have different IDs in different components and these need to be correlated. This leads us back to the point of making your logging concise and logging enough information to trace the call through the system.

Note: The new WebSphere Application Server V7 Feature Pack for Communications Enabled Applications (CEA) has many new features that simplify developing converged applications. One of these features, called converged Web service notification, supports Web services affinity for both outbound and inbound requests. This reduces the complexity of our application as it no longer needs to create bi-directional Web services.


In this article, you've learned how you can use the tooling available with WebSphere Application Server to create and debug a converged application supporting both SIP and Web services. These converged applications enable you to connect older legacy network technologies with the new IP-based network technologies. You learned about the options you might choose depending on your application requirements, including synchronous or asynchronous Web services and the advantages of using HTTP Keepalive for better performance. You should be able to build your application and make design decisions using the lessons learned from our sample TCAP application.


The authors would like to thank Brian Pulito, Nitzan Nissim and Tom Thacher for their valuable reviews, comments, and contributions to this article. We would also like to thank Can P. Boyacigiller and Sreenivasa Pamidala for their contribution to the overall concept described in this article.



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 WebSphere on developerWorks

Zone=WebSphere, SOA and web services
ArticleTitle=Developing next-generation converged applications with SIP and asynchronous Web services