Introduction
A couple of months ago, the Mobicents Diameter Team decided to start a series of educational posts regarding Diameter development using Mobicents Diameter solution.
- Explaining some basics of the Diameter protocol such as Diameter Nodes, Realms, Applications, Messages, AVPs, Sessions and all those fundamental concepts that hopefully helps to make sense out of this;
- A step-by-step example on how to create server and client instances for a Diameter Application (a fictitious Application was used to exemplify) using Mobicents Diameter. It includes detailed code explanation and it's a good read as a preparation for this one if you're new on the subject.
In this second post, we will learn how easy it is to create an Offline Charging Application using Mobicents Diameter. Also, for those not familiar with what is Offline Charging (and Online Charging as well) a brief introduction will be provided.
Fasten your seatbelt, the ride is about to begin!
Offline and Online Charging. What's that about?
Online Charging is the name used by 3GPP for pre-paid charging in the IMS scope. It is the charging which occurs in real-time, where the service cost is deducted from the user balance (which has been previously loaded by the user) while the service is going on. In IMS this is the Ro interface, and is defined by
3GPP TS 32.299 (and extending
RFC 4006 - Diameter Credit Control Application).
On the other hand, Offline Charging is the 3GPP name for post-paid charging, where the provided services are not paid at the time of their usage but rather in a periodic manner, such as at the end of each month. However, while the service is on course, it's usage is logged as a Call Detail Record (CDR) that will be processed later by a Billing system. This corresponds to the IMS interface Rf, defined also by
3GPP TS 32.299 (inheriting from Diameter Base Accounting in
RFC 3588).
The CDR generation is the responsibility of an Offline Charging Server.
Please keep in mind that while we are using the Online/Offline terminology introduced by 3GPP for IMS, this post does not intend to focus on IMS details, and so, we will only use the Diameter Base Accounting Application, allowing to simplify the exchanged messages and provide a more straightforward tutorial.
The Messages and AVPs
The messages exchanged for offline charging, as defined in RFC 3588 - Section 9.7, are only two: Accounting-Request (ACR) and Accounting-Answer (ACA), with Command-Code 271.
While only a pair of Request/Answer is defined, it can be used with different purposes, depending on the value of the Accounting-Record-Type AVP (code 480). This AVP can have the following values:
- EVENT_RECORD (1) - Defines that this is charging for a one-time event, such as a sent SMS;
- START_RECORD (2) - In a service with a measurable length (eg: voice call) this value defines that such service has started;
- INTERIM_RECORD (3) - In a service with the above characteristics, this ACR type provides cumulative accounting information;
- STOP_RECORD (4) - This is used to inform that a service with measurable length has terminated and to provide cumulative accounting information regarding it.
Another meaningful AVP is the Acct-Interim-Interval AVP (code 85) where it is specified the interval at which intermediate records should be produced, by sending ACR messages with Accounting-Record-Type set to INTERIM_RECORD. The absence of it, or a value of 0, means that no intermedite records are needed.
An important note is that Base Accounting does not define any service-specific AVPs, as it is not intended to be a usable Application but rather the base for the ones being defined. As such, we will 'abuse' from User-Name AVP, and piggyback the Subscription and Service identifiers into it, in the form "
.@mobicents.org".
Putting it all together!
Assuming you already know how to configure and set up the stack in your Java project (which has been explained by Bartosz on the
first post of these educational series), let's start by defining the interface for our Charging Client enabler, to be used by the applications:
package org.mobicents.diameter.simulator.client;
public interface OfflineChargingClient {
// Accounting-Record-Type Values --------------------------------------------
static final int ACCOUNTING_RECORD_TYPE_EVENT = 1;
static final int ACCOUNTING_RECORD_TYPE_START = 2;
static final int ACCOUNTING_RECORD_TYPE_INTERIM = 3;
static final int ACCOUNTING_RECORD_TYPE_STOP = 4;
/**
* Sends an Accounting-Request with Accounting-Record-Type set to "2" and the
* corresponding Subscription-Id and Service-Id AVPs filled accordingly.
*
* @param subscriptionId the String value to be used for Subscription-Id AVP
* @param serviceId the String value to be used for Service-Id AVP
* @throws Exception
*/
public abstract void startOfflineCharging(String subscriptionId, String serviceId)
throws Exception;
/**
* Sends an Accounting-Request with Accounting-Record-Type set to "3" and the
* corresponding Subscription-Id and Service-Id AVPs filled accordingly.
*
* @param subscriptionId the String value to be used for Subscription-Id AVP
* @param serviceId the String value to be used for Service-Id AVP
* @throws Exception
*/
public abstract void updateOfflineCharging(String subscriptionId, String serviceId)
throws Exception;
/**
* Sends an Accounting-Request with Accounting-Record-Type set to "4" and the
* corresponding Subscription-Id and Service-Id AVPs filled accordingly.
*
* @param subscriptionId the String value to be used for Subscription-Id AVP
* @param serviceId the String value to be used for Service-Id AVP
* @throws Exception
*/
public abstract void terminateOfflineCharging(String subscriptionId, String serviceId)
throws Exception;
/**
* Sends an Accounting-Request with Accounting-Record-Type set to "1" and the
* corresponding Subscription-Id and Service-Id AVPs filled accordingly.
*
* @param subscriptionId the String value to be used for Subscription-Id AVP
* @param serviceId the String value to be used for Service-Id AVP
* @throws Exception
*/
public abstract void eventOfflineCharging(String subscriptionId, String serviceId)
throws Exception;
/**
* Sets the listener to receive the callbacks from this charging client.
* @param listener an OfflineChargingClientListener implementor to be the listener
*/
public abstract void setListener(OfflineChargingClientListener listener);
}
Also, we will need the applications to implement the Listener interface, in order to receive the callbacks from the Offline Charging Enabler. The interface to be implemented is quite simple, with only one method for the callback:
package org.mobicents.diameter.simulator.client;
/**
* Listener interface to be implemented by applications
* wanting to have Offline Accounting
*/
public interface OfflineChargingClientListener {
/**
* Callback method invoked by Offline Charging Client to deliver answers
*
* @param subscriptionId the String value identifying the user
* @param serviceId the String value identifying the service
* @param sessionId a String value identifying the accounting session
* @param accountingRecordType the type of Accounting Record the answer refers to
* @param accountingRecordNumber the Accounting Record number the answer refers to
* @param resultCode the Result-Code value obtained from the answer
* @param acctInterimInterval the interval in seconds to send updates
*/
public void offlineChargingAnswerCallback(String subscriptionId,
String serviceId, String sessionId, int accountingRecordType,
long accountingRecordNumber, long resultCode, long acctInterimInterval);
}
The implementation for the OfflineChargingClient (not complete, just the basics to understanding) is the following:
public class OfflineChargingClientImpl implements OfflineChargingClient,
NetworkReqListener, EventListener<Request, Answer>,
StateChangeListener<AppSession>, ClientAccSessionListener {
// Application Id -----------------------------------------------------------
private static final ApplicationId ACCOUNTING_APPLICATION_ID =
ApplicationId.createByAccAppId(0, 3);
// Configuration Values -----------------------------------------------------
private static final String SERVER_HOST = "127.0.0.1";
private static String REALM_NAME = "mobicents.org";
private SessionFactory sessionFactory;
private AccSessionFactoryImpl accountingSessionFactory;
private OfflineChargingClientListener listener;
private ConcurrentHashMap<String, ClientAccSession> acctSessions =
new ConcurrentHashMap<String, ClientAccSession>();
private ConcurrentHashMap<String, Integer> acctRecNumberMap =
new ConcurrentHashMap<String, Integer>();
public OfflineChargingClientImpl() throws Exception {
// Initalize Stack
...
}
At this point we just define some constants, configuration values and variables to be used later. We define two maps to allow us to keep sessions and Accounting-Record-Number values stored in the enabler. This could be moved client-side if desired.
We will next define some auxiliary methods to assit in common operations, such as creating Accounting-Requests, retrieving the appropriate Accounting-Record-Number, etc.
// Aux Methods --------------------------------------------------------------
/**
* Gets an accounting record number for the specified user+service id
* @param identifier the user+service identifier
* @param isStart indicates if it's an initial record, which should be set to 0
* @return the accounting record number to be used in the AVP
*/
private int getAccountingRecordNumber(String sessionId, boolean isStart) {
// An easy way to produce unique numbers is to set the value to 0 for
// records of type EVENT_RECORD and START_RECORD, and set the value to 1
// for the first INTERIM_RECORD, 2 for the second, and so on until the
// value for STOP_RECORD is one more than for the last INTERIM_RECORD.
int accRecNumber = 0;
if(!isStart) {
accRecNumber = acctRecNumberMap.get(sessionId);
accRecNumber = accRecNumber++;
}
acctRecNumberMap.put(sessionId, accRecNumber);
return accRecNumber;
}
/**
* Creates an Accounting-Request with the specified data.
*
* @param session the session to be used for creating the request
* @param accRecordType the type of Accounting Record (Event, Start, Interim, Stop)
* @param username the value to be used in the User-Name AVP
* @return an AccountRequest object with the needed AVPs filled
* @throws InternalException
*/
private AccountRequest createAccountingRequest(ClientAccSession session,
int accRecordType, int accRecNumber, String username) throws InternalException {
AccountRequest acr = new AccountRequestImpl(session, accRecordType, accRecNumber,
REALM_NAME, SERVER_HOST);
// Let's 'abuse' from User-Name AVP and use it for identifying user@service
AvpSet avps = acr.getMessage().getAvps();
avps.addAvp(Avp.USER_NAME, username, false);
return acr;
}
/**
* Method for creating and sending an Accounting-Request
*
* @param identifier the user+service identifier to be used in the User-Name AVP
* @param accRecType the type of Accounting Record (Event, Start, Interim, Stop)
* @throws Exception
*/
private void sendAccountingRequest(ClientAccSession session, String identifier,
int accRecType, int accRecNumber) throws Exception {
// Create Accounting-Request
AccountRequest acr = createAccountingRequest(session, accRecType, accRecNumber,
identifier);
// Send it
session.sendAccountRequest(acr);
}
/**
* Aux method for generating a unique identifier from subscription and service ids
* @param subscriptionId the subscription id to be used
* @param serviceId the service id to be used
* @return the generated unique identifier
*/
private String getIdentifier(String subscriptionId, String serviceId) {
return subscriptionId + "." + serviceId + "@" + REALM_NAME;
}
And finally we can do the real implementation for the Offline Charging Client which, hopefully, became a bit simpler.
// Offline Charging Client Implementation -----------------------------------
public void setListener(OfflineChargingClientListener listener) {
this.listener = listener;
}
public void startOfflineCharging(String subscriptionId, String serviceId)
throws Exception {
// Create new session to send start record
ClientAccSession session = (ClientAccSession) accountingSessionFactory.
getNewSession(null, ClientAccSession.class, ACCOUNTING_APPLICATION_ID,
new Object[]{});
// Store it in the map
acctSessions.put(session.getSessionId(), session);
// Get the account record number
int accRecNumber = getAccountingRecordNumber(session.getSessionId(), true);
sendAccountingRequest(session, getIdentifier(subscriptionId, serviceId),
ACCOUNTING_RECORD_TYPE_START, accRecNumber);
}
public void interimOfflineCharging(String subscriptionId, String serviceId,
String sessionId) throws Exception {
// Fetch existing session to send interim record
ClientAccSession session = this.acctSessions.get(sessionId);
// Get the account record number
int accRecNumber = getAccountingRecordNumber(session.getSessionId(), false);
sendAccountingRequest(session, getIdentifier(subscriptionId, serviceId),
ACCOUNTING_RECORD_TYPE_INTERIM, accRecNumber);
}
public void stopOfflineCharging(String subscriptionId, String serviceId,
String sessionId) throws Exception {
// Fetch existing session (and remove it from map) to send stop record
ClientAccSession session = this.acctSessions.remove(sessionId);
// Get the account record number (and remove)
int accRecNumber = getAccountingRecordNumber(session.getSessionId(), false);
this.acctRecNumberMap.remove(session.getSessionId());
sendAccountingRequest(session, getIdentifier(subscriptionId, serviceId),
ACCOUNTING_RECORD_TYPE_STOP, accRecNumber);
}
public void eventOfflineCharging(String subscriptionId, String serviceId)
throws Exception {
// Create new session to send event record
ClientAccSession session = (ClientAccSession) accountingSessionFactory.
getNewSession(null, ClientAccSession.class, ACCOUNTING_APPLICATION_ID,
new Object[]{});
// No need to store Session or Accounting-Record-Number as it's a one-shot.
sendAccountingRequest(session, getIdentifier(subscriptionId, serviceId),
ACCOUNTING_RECORD_TYPE_EVENT, 0);
}
// Client Acc Session Listener Implementation -------------------------------
public void doAccAnswerEvent(ClientAccSession appSession, AccountRequest request,
AccountAnswer answer) throws InternalException, IllegalDiameterStateException,
RouteException, OverloadException {
// Extract interesting AVPs
AvpSet acaAvps = answer.getMessage().getAvps();
String subscriptionId = null;
String serviceId = null;
try {
String username = acaAvps.getAvp(Avp.USER_NAME).getUTF8String();
// It's in form subscription.service@REALM_NAME
String[] identifiers = username.replaceFirst("@" + REALM_NAME, "").split("\\.");
subscriptionId = identifiers[0];
serviceId = identifiers[1];
}
catch (Exception e) {
e.printStackTrace();
}
// Get the session-id value
String sessionId = appSession.getSessionId();
// We must be able to get this, it's mandatory
int accRecType = -1;
try {
accRecType = answer.getAccountingRecordType();
}
catch (Exception e) {
e.printStackTrace();
}
// We must be able to get this, it's mandatory
long accRecNumber = -1L;
try {
accRecNumber = answer.getAccountingRecordNumber();
}
catch (Exception e) {
e.printStackTrace();
}
// If we can't get it we'll fallback to DIAMETER_UNABLE_TO_COMPLY (5012)
long resultCode = 5012L;
try {
resultCode = answer.getResultCodeAvp().getUnsigned32();
}
catch (AvpDataException e) {
e.printStackTrace();
}
// Here we fallback to 0, it means the same as omitting
long acctInterimInterval = 0;
try {
acctInterimInterval = acaAvps.getAvp(Avp.ACCT_INTERIM_INTERVAL).getUnsigned32();
}
catch (AvpDataException e) {
e.printStackTrace();
}
// Invoke the callback to deliver the answer
listener.offlineChargingAnswerCallback(subscriptionId, serviceId, sessionId,
accRecType, accRecNumber, resultCode, acctInterimInterval);
}
public void doOtherEvent(AppSession appSession, AppRequestEvent request,
AppAnswerEvent answer) throws InternalException, IllegalDiameterStateException,
RouteException, OverloadException {
// We can ignore this
}
Given the above implementation of what can be seen as the enabler for offline charging, now our Example Application should implement the following state machine using the enabler:
So let's get our hands dirty with the example application implementation, which should implement the above specified listener interface:
package org.mobicents.diameter.simulator.client;
import static org.mobicents.diameter.simulator.client.OfflineChargingClient.*;
public class ExampleApplication implements OfflineChargingClientListener {
// Internal Client State Machine --------------------------------------------
private static final int STATE_IDLE = 0;
private static final int STATE_START_ACR_SENT = 2;
private static final int STATE_START_ACA_SUCCESS = 4;
private static final int STATE_INTERIM_ACR_SENT = 6;
private static final int STATE_INTERIM_ACA_SUCCESS = 8;
private static final int STATE_STOP_ACR_SENT = 10;
private static final int STATE_STOP_ACA_SUCCESS = 12;
private static final int STATE_EVENT_ACR_SENT = 14;
private static final int STATE_EVENT_ACA_SUCCESS = 16;
private static final int STATE_END = 18;
private static final int STATE_ERROR = 99;
private int currentState = STATE_IDLE;
public static void main(String[] args) throws Exception {
ExampleApplication app = new ExampleApplication(new OfflineChargingClientImpl());
app.occ.startOfflineCharging("", "");
}
private OfflineChargingClient occ;
public ExampleApplication(OfflineChargingClient occ) {
this.occ = occ;
occ.setListener(this);
}
public void offlineChargingAnswerCallback(String subscriptionId, String serviceId,
String sessionId, int accountingRecordType, long accountingRecordNumber,
long resultCode, long acctInterimInterval) {
// Handle the EVENT situation
if(accountingRecordType == ACCOUNTING_RECORD_TYPE_EVENT) {
if(this.currentState == STATE_EVENT_ACR_SENT) {
if(resultCode == 2001) {
this.currentState = STATE_EVENT_ACA_SUCCESS;
System.out.println("(((o))) Event Offline Charging for user '"+ subscriptionId +
"' and service '" + serviceId + "' completed! (((o)))");
// and now just to be correct...
this.currentState = STATE_END;
}
}
else {
this.currentState = STATE_ERROR;
throw new RuntimeException("Unexpected message received.");
}
}
// Handle START / INTERIM / STOP situation
else {
switch(this.currentState) {
// Receiving an Answer at any of these states is an error
case STATE_IDLE:
case STATE_EVENT_ACA_SUCCESS:
case STATE_START_ACA_SUCCESS:
case STATE_INTERIM_ACA_SUCCESS:
case STATE_STOP_ACA_SUCCESS:
// At any of these states we don't expect to receive an ACA, move to error.
this.currentState = STATE_ERROR;
break;
// We've sent ACR EVENT
case STATE_START_ACR_SENT:
if(accountingRecordType == ACCOUNTING_RECORD_TYPE_START) {
if(resultCode >= 2000 && resultCode < 3000) {
// Our event charging has completed successfully. We're done!
System.err.println("(((o))) Offline Charging for user '" + subscriptionId +
"' and service '" + serviceId + "' started... (((o)))");
if(acctInterimInterval > 0) {
try {
// Let's sleep until next interim update...
Thread.sleep(acctInterimInterval * 1000);
// We send an update at the correct time
occ.interimOfflineCharging(subscriptionId, serviceId, sessionId);
}
catch (Exception e) {
this.currentState = STATE_ERROR;
throw new RuntimeException("Unable to schedule/send interim update.", e);
}
}
}
else {
// It failed
System.err.println("(((x))) Offline Charging for user '" + subscriptionId +
"' and service '" + serviceId + "' failed with Result-Code="+ resultCode +
"! (((x)))");
}
}
else {
this.currentState = STATE_ERROR;
throw new RuntimeException("Unexpected message received.");
}
break;
// We've sent ACR START
case STATE_INTERIM_ACR_SENT:
if(accountingRecordType == ACCOUNTING_RECORD_TYPE_INTERIM) {
if(resultCode >= 2000 && resultCode < 3000) {
// Our offline charging has started successfully...
System.out.println("(((o))) Offline Charging for user '" + subscriptionId +
"' and service '" + serviceId + "' updated... (((o)))");
if(acctInterimInterval > 0) {
try {
// Let's sleep until next interim update...
Thread.sleep(acctInterimInterval);
// We send an update at the correct time
occ.interimOfflineCharging(subscriptionId, serviceId, sessionId);
}
catch (Exception e) {
this.currentState = STATE_ERROR;
throw new RuntimeException("Unable to schedule/send interim update.", e);
}
}
}
else {
// It failed, let's warn the application
System.out.println("(((x))) Offline Charging for user '" + subscriptionId +
"' and service '" + serviceId + "' failed to start with Result-Code=" +
resultCode + "! (((x)))");
}
}
else {
this.currentState = STATE_ERROR;
throw new RuntimeException("Unexpected message received.");
}
break;
case STATE_STOP_ACR_SENT:
if(accountingRecordType == ACCOUNTING_RECORD_TYPE_INTERIM) {
if(resultCode >= 2000 && resultCode < 3000) {
// Our offline charging has started successfully...
System.out.println("(((o))) Offline Charging for user '" + subscriptionId +
"' and service '" + serviceId + "' stopped! (((o)))");
}
else {
// It failed, let's warn the application
System.out.println("(((x))) Offline Charging for user '" + subscriptionId +
"' and service '" + serviceId + "' failed to stop with Result-Code=" +
resultCode + "! (((x)))");
}
}
else {
this.currentState = STATE_ERROR;
throw new RuntimeException("Unexpected message received.");
}
break;
default:
this.currentState = STATE_ERROR;
throw new RuntimeException("Unexpected message received.");
}
}
}
}
As it can be seen it turns to be really simple to implement such Application using Offline Charging in this way. The above application also provides an enhancement, which is to automatically wait and send the interim ACR updates (lines 73-85 and 107-119). That obviously is a design choice, which can be changed if control over that behavior is intended.
Conclusion
As this article was meant to demonstrate it's simple to add Offline Accounting to your applications using Mobicents Diameter solution. Several options (and scenarios) were simplified in order to keep the example easier to understand and follow the steps, as well as to give a better understanding of the Mobicents Diameter solution, while still rendering a completely functional solution.
You can learn more about Mobicents Diameter at http://www.mobicents.org/diameter/.
