Developing an offline charging application using the IBM WebSphere IP Multimedia Subsystem (IMS) Connector

This article describes how you can develop an offline charging application using the Rf interface in IBM® WebSphere® IP Multimedia Subsystem (IMS) Connector V6.2, presents a sample asynchronous offline charging adapter to enable multi-threaded throughput of the Rf client, and discusses performance tuning based on the Rf interface.

Share:

Ling Li (liling@cn.ibm.com), IT Specialist, WSO2 Inc

Author photoLing Li is a software engineer working on IBM Service Delivery Platform solution development. He is much experienced in service governance and IP Multimedia Subsystem (IMS).


developerWorks Contributing author
        level

22 April 2009

Introduction

IBM WebSphere IP Multimedia Subsystem Connector V6.2 (hereafter referred to as WebSphere IMS Connector) is an important component of the IBM Service Delivery Platform for Telecommunications. In the IP Multimedia Subsystem (IMS) architecture, the WebSphere IMS Connector connects SIP applications with IMS core elements and provides functions of offline charging (through the Rf interface), online charging (Ro interface), and subscriber profile management (Sh interface).

This article describes how to develop an offline charging application, leveraging the Rf interface in WebSphere IMS Connector V6.2. An asynchronous offline charging adapter that implements an asynchronous callback interface to enable multi-threaded throughput of the Rf client is then presented. This discussion concludes with a look at performance tuning with WebSphere IMS Connector.

This article assumes a basic understanding of the IP Multimedia Subsystem, Diameter protocol, Java™ programming, and Web services standards.


WebSphere IMS Connector overview

IBM WebSphere software delivers a high performance IMS service execution platform on which you can deploy your own IMS applications. WebSphere IMS Connector is the infrastructure of this platform, as shown in Figure 1.

Figure 1. Service execution platform
Figure 1. Service execution platform

WebSphere IMS Connector builds on top of the converged Session Initiation Protocol (SIP)/HTTP container that IBM WebSphere Application Server V6.1 provides. WebSphere IMS Connector delivers pre-built interfaces for connecting applications that are built on top of WebSphere Application Server with IMS core elements in a telecom operator environment. Figure 2 illustrates this architecture.

Figure 2. WebSphere IMS Connector architecture
Figure 2. WebSphere IMS Connector architecture

WebSphere IMS Connector implements the Diameter protocol stack and interfaces (namely the Diameter Enabler) for communication with one or more IMS-based billing and subscriber management systems. Diameter protocol is the next generation Authentication, Authorization and Accounting (AAA) protocol defined in RFC 3588. The Diameter Enabler contains:

  • Sh interface: Supports Home Subscriber Server (HSS) based subscriber profile management.
  • Rf interface: Supports offline charging for post-paid billing models.
  • Ro interface: Supports online charging for pre-paid/credit billing models (new in V6.2).

These interfaces provide Web service access for Diameter interactions, which reduces programming model complexity. In addition, WebSphere IMS Connector provides an SIP-based IMS Service Control (ISC) interface that enables interaction with the Call Session Control Function (CSCF) in the IMS control plane.

Next, an introduction of the Rf charging interface.


Rf charging interface

Offline charging is used for post-paid billing network services. The Rf interface is a Diameter application level protocol, defined in 3GPP TS132.260 and TS132.299, that enables IMS clients to send and receive accounting information. In WebSphere IMS Connector, the Rf charging interface is implemented as a Web service that interfaces with Diameter Enabler to send and receive Diameter messages to a Charging Collection Function (CCF), as shown in Figure 3. The Diameter Enabler is capable of receiving Web service requests and converting them into Diameter request packets.

Figure 3. Diameter Rf charging interface
Figure 3. Diameter Rf charging interface

The Rf charging Web service is a collection of Web service methods that use a SOAP over HTTP request and response interface. These Web services are stateless and many threads can access them simultaneously. You can develop offline charging applications that connect through the Rf charging Web service interface to send and receive accounting information to a CCF, without knowing the detail Diameter base protocol.

The Rf interface supports both event-based and session-based charging, which are two offline charging events defined in the 3GPP specifications. The reporting of offline charging events to the CCF is managed through the Diameter Accounting Request (ACR) message. Based on information held in the ACR, the CCF generates the Charging Data Records (CDR), which are consumed by the billing system. An operation result code is returned in the Accounting Answer (ACA) that indicates whether the transaction was successful or not.

Rf supports four ACR event types, listed in Table 1.

Table 1. Rf ACR event types
EventDescription
STARTStarts an offline accounting session.
INTERIMUpdates an offline accounting session.
STOPStops an offline accounting session.
EVENTIssues a one-time offline accounting event.

A session-based accounting request uses START, INTERIM, and STOP requests. During a session, the client might report multiple INTERIM requests depending on the session lifecycle. An event-based accounting request uses an EVENT request. The choice of using session charging versus event charging will depend on the applications using this interface. For example, purchasing one book would use the EVENT command.


Developing Rf applications

You can use any J2EE™ IDE tools, such as IBM Rational® Application Developer, to develop Rf applications. Additionally, the IBM WebSphere Telecom Toolkit for Rational Application Developer contains libraries, examples, and javadocs to help you develop a telecom application. The example in this article uses Eclipse.

Import libraries

As a Web service client, an Rf application can be built within almost any J2EE application. For simplicity, the example used in this article develops an Rf application as a thin client. To create an Rf thin client, you need to create a Java project and import all required Diameter Enabler libraries to the build path, as shown in Figure 4.

Figure 4. Import Diameter Enabler libraries
Figure 4. Import Diameter Enabler libraries

The com.ibm.ws.webservices.thinclient_6.1.0.jar file is a run time library for a standalone Web service client. The JAR file is located in the {WAS_HOME}/runtimes directory. The other JAR files are Diameter Enabler libraries, which are included in WebSphere IMS Connector product packaging (and also in the WebSphere Telecom Toolkit).

Rf Web service API

The Rf interface is comprised of a number of Web service methods and classes. These classes are used to encapsulate the information in the request arguments and result values. The Java classes used by the Rf Web service are defined in these packages: com.ibm.diameter.rf.util, com.ibm.diameter.charging, and com.ibm.diameter.packet. Table 2 lists the main classes used by the Rf interface.

Table 2. Rf classes
ClassDescription
RfAccountingInfoA simple representation of the Diameter ACR, including all needed information to manage an accounting session or event.
interimRfAccountingA simple representation of the Diameter ACA, including all the pertinent information for managing an accounting session or event.
ServiceInformationA member of RfAccountingInfo, acting as a container for service-specific 3GPP accounting information.

In addition, the Rf accounting Web service defines three methods for managing an offline charging session and an eventRfAccounting method for issuing a one-time offline charging event. Specifically, the rawAccounting method is used to make the same types of requests as the other four methods by using raw attribute value pairs (AVP). This raw interface is very useful when customized AVPs need to be used. These five methods are shown in Table 3.

Table 3. Rf Web service methods
MethodDescription
startRfAccountingStarts an offline accounting session.
interimRfAccountingUpdates an offline accounting session.
stopRfAccountingStops an offline accounting session.
eventRfAccountingIndicates an offline accounting event.
rawAccountingIssues a user defined accounting request.

Building an accounting object

Before issuing session-based accounting, you first need to build an RfAccountingInfo object. Listing 1 shows sample code that creates an object that only contains base accounting information. In this code:

  • The sessionID created by the getRfSessionID method is a unique identifier for one accounting session.
  • The recordNumber starts with 0 and increases by 1 with every send of a Diameter message.
  • The destinationRealm determines the CCF to which the Diameter message will be sent.
  • The acctUser indentifies the available user in CCF.

Beyond these, there are some optional parameters which should only be set as needed to ensure the correct generation of CDRs.

Listing 1. Create a base accounting object
// some base accounting information
private static final String destinationRealm="ibm.com";
private static final String acctUser="test@ibm.com";
private String sessionID;
private int recordNumber=0;

// build a base accounting information object
public RfAccountingInfo buildAccInfo() {
   RfAccountingInfo acct = new RfAccountingInfo();
   acct.setAccountingRecordNumber(new Integer(recordNumber++));
   acct.setDestinationRealm(destinationRealm);
   acct.setEVENTTimestamp(new Long(System.currentTimeMillis()));
   acct.setUserName(acctUser);
   if(sessionID==null)
      acct.setSessionId(getRfSessionID());
   else
      acct.setSessionId(sessionID);
   return acct;
}

Implementing session-based charging

For session-based charging requests, an application first uses DiameterRfService_SEIServiceLocator to get the Diameter Rf service endpoint interface. The application can then use the DiameterRfService_SEI object to create one or more charging requests. By the way, if the global security in WebSphere IMS Connector is turned on, you should populate the user name and password into the DiameterRfService_SEI object. The first charging request must be an ACR START command, followed by zero or more ACR INTERIM commands. The accounting session ends with an ACR STOP command. Upon receipt of the corresponding ACA STOP command, the Diameter Enabler automatically terminates the accounting session. The same session ID is must be used for each request associated with an accounting session.

Listing 2 shows sample code used to start, update, and terminate session-based accounting.

Listing 2. Session-based accounting
// Create a new locator
DiameterRfService_SEIServiceLocator locator = new DiameterRfService_SEIServiceLocator();
// Set the userid/password
String user = null;
String password = null;
URL endpointURL =
   new URL("http://localhost:9080/DHADiameterRfWebService/services/DiameterRfService");
// Get Rf service
DiameterRfService_SEI service = locator.getDiameterRfService(endpointURL);
// Apply the user and password
if ((null != user) && (null != password)) {
   ((Stub) service)._setProperty(Stub.USERNAME_PROPERTY, user);
   ((Stub) service)._setProperty(Stub.PASSWORD_PROPERTY, password);
}
// Issue a session based accounting
RfAccountingInfo acrInfo = buildAccInfo();
service.startRfAccounting(acrInfo);
// Update the accounting session
for(int i = 0; i < numberOfIntervals; i ++) {
   Thread.sleep(acctINTERIMInterval);
   RfAccountingInfo acrInfo = buildAccInfo();
   service.interimRfAccounting(acrInfo);
}
// STOP the accounting session
RfAccountingInfo acrInfo = buildAccInfo();
service.stopRfAccounting(acrInfo);

Implementing asynchronous Rf adapter

In WebSphere IMS Connector, all Rf Web service methods are synchronous request and response interfaces. In other words, when invoking an Rf Web service call, the client has to wait until it gets the response. The latency is dependent upon the processing speed of Diameter Enabler and the backend CCF. These synchronous methods would be sufficient for many use cases. However, if latency is critical, you should leverage an asynchronous Rf adapter wherein the application is asynchronously notified when a response is received from the Diameter Enabler. The asynchronous Rf adapter is described in detail in this section.

Architectural overview

The asynchronous Rf adapter is used to asynchronously receive messages delivered to the session. It contains one configurable singleton thread pool in which threads are used to invoke Rf Web service calls and receive the answers. As shown in Figure 5, each client attached to the Rf adapter has its own work item queue. All accounting requests from the same client are stored in the current client’s work item queue. The queue is synchronized by ReentrantLock, which makes sure each accounting request in the queue is retrieved and removed if and only if its precursor request has been completely processed. In other words, it is a First-Out-First-Done queue. This is a key point because accounting requests in one session must be sent sequentially; for example, first a START request, then zero or more INTERIM requests, and finally a STOP request. Thanks to the Rf adapter, Rf applications can send an accounting request asynchronously and receive the answer by a notification. The adapter enables multi-threaded throughput, and dramatically improves the performance of Rf clients.

Figure 5. Asynchronous Rf adapter
Figure 5. Asynchronous Rf adapter

Implementing a Diameter handler

To implement the asynchronous Rf adapter, a series of classes (Figure 6) provides general support for the First-Out-First-Done queue and singleton thread pool.

Figure 6. Rf adapter classes
Figure 6. Rf adapter classes

In the figure:

  • DiameterListener interface demands a diameterCallback function for receiving Diameter event notification.
  • DiameterEvent interface demands a getWorkResult function for accessing the result of asynchronous Diameter request.
  • AsyncDiameter class maintains a singleton ThreadPoolExecutor used to process the Diameter requests asynchronously. You can configure the executor by the constructors, such as pool size, buffer queue length, and so on. In order to safely use threads in servlet and EJB components, WebSphere Application Server provides an asynchronous bean to create pooled and daemon threads to run J2EE business logic. Therefore, you can use WorkManager instead of ThreadPoolExecutor if need be.
  • DiameterWork class defines an asynchronous Diameter request work unit that is submitted to the AsyncDiameter thread pool. This class implements the Runnable and DiameterEvent interface and takes charge of invoking the Rf Web services according to the request type at run time.

In addition, there are two support classes: DiameterMessage is used to contain the accounting information, and DiameterConfig is used to store all configurable properties needed by the Rf adapter.

The Rf adapter’s core class, DiameterHandler, contains these items of interest:

  • diameterQueue field
  • reentrantLock field
  • setListener method
  • sendDiameter method

As shown below, diameterQueue and reentrantLock maintain a First-Out-First-Done queue in each DiameterHandler instance for serializing the Diameter requests:

private LinkedList<DiameterMessage> diameterQueue=new LinkedList<DiameterMessage>();
private ReentrantLock reentrantLock=new ReentrantLock();

To use the asynchronous adapter, an application needs to register an instance of DiameterListener in order to asynchronously receive messages delivered to the session:

DiameterHandler dh=new DiameterHandler();
dh.setListener(this);

This code builds an instance of DiameterMessage and then sends the Diameter message asynchronously:

RfAccountingInfo acrInfo=dh.buildAccInfo();
DiameterMessage dm=new DiameterMessage(AccountingRecordType.START,acrInfo);
dh.sendDiameter(dm);

The entire sample Rf adapter JAR file is available for download. You can include it as a Java library so you can use it in J2SE™ or J2EE applications.

Usage example

To use the asynchronous adapter, the client class must first implement DiameterListener, register the listener in an instance of DiameterHandler, and then send the Diameter message asynchronously. You also need to modify some properties in the DiameterConfig class to suit your run time environment. The sample code used to issue an asynchronous session-based accounting is illustrated in Listing 3.

Listing 3. Asynchronous session-based accounting
public class SampleClient implements DiameterListener{

   public static void main(String[] args) throws Exception {
      System.out.println("-------client start--------");
      SampleClient client=new SampleClient();
      DiameterHandler dh=new DiameterHandler();
      dh.setListener(client);

      // start offline accounting
      RfAccountingInfo acrInfo=dh.buildAccInfo();
      DiameterMessage dm=null;
      dm=new DiameterMessage(AccountingRecordType.START_OFFLINE_ACCOUNTING,acrInfo);
      dh.sendDiameter(dm);
      Thread.sleep(DiameterConfig.ACCOUNT_INTERIM_INTERVAL);

      // interim offline accounting
      acrInfo=dh.buildAccInfo();
      dm=new DiameterMessage(AccountingRecordType.INTERIM_OFFLINE_ACCOUNTING,acrInfo);
      dh.sendDiameter(dm);
      Thread.sleep(DiameterConfig.ACCOUNT_INTERIM_INTERVAL);

      // stop offline accounting
      acrInfo=dh.buildAccInfo();
      dm=new DiameterMessage(AccountingRecordType.STOP_OFFLINE_ACCOUNTING,acrInfo);
      dh.sendDiameter(dm);
      System.out.println("-------client end----------");
   }

   public void diameterCallback(DiameterEvent event) {
      RfAccountingResults aca=event.getWorkResult();
      System.out.println(aca);
   }
}

This code first sends a Diameter START message to start an offline accounting session, and then sends an INTERIM message to update the session without waiting for the START request’s response. Finally, a STOP message is sent to terminate the session. The corresponding Diameter response is output by the diameterCallback method asynchronously.


Performance tuning

For performance tuning Rf Web services in WebSphere IMS Connector, there are two important properties in the Diameter Enabler Rf interface configuration file Diameter_Rf.properties, which is located in {was_profile_root}/properties:

  • The value of conx.maxPendingQueueLength indicates the number of Diameter requests stored in the pending queue before rejecting new requests. The default value is 30. If you are designing a high throughput system, you should increase this value to 15000 or above.
  • The value of conx.packetTimeout indicates the number of seconds that a request message will remain on the pending queue waiting for a response before Diameter Enabler removes it and notifies the application of a timeout. You should set this value substantially higher than the expected average response time. For example, you can use 60 instead of the default value 30.

A large queue and high packet timeout will take up a greater amount of memory, depending on the sizes of messages. You might need to increase the JVM heap size of WebSphere IMS Connector to 1 GB. However, a smaller JVM heap is better in terms of the garbage collection latency. You can use a vertical or horizontal scale to reduce the average latency.

In addition, DiameterThreadPool is a thread pool used to process the inbound Web service messages, and DiameterWorkManager is an asynchronous bean used to process the outbound Web service messages. You might need to optimize them in the WebSphere Application Server administrative console according to the run time workload.


Summary

The information in this article is meant to help you better understand the IBM WebSphere IMS Connector and how to program offline accounting applications using the Rf interface. More important, you can now implement a sample asynchronous Rf adapter to enable multi-threaded throughput of the Rf client.


Download

DescriptionNameSize
Code sampleDiameterRfAdapter.jar5 KB

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=384192
ArticleTitle=Developing an offline charging application using the IBM WebSphere IP Multimedia Subsystem (IMS) Connector
publish-date=04222009