12 Using the Diameter Ro Interface API for Online Charging

The following chapter describes how to use the Diameter Ro interface API, based on the Oracle WebLogic Server SIP Container Diameter protocol implementation, in your own applications, and contains the following sections:

12.1 Overview of Ro Interface Support

Online charging, also known as credit-based charging, is used to charge prepaid services. A typical example of a prepaid service is a calling card purchased for voice or video. The Ro protocol allows a Charging Trigger Function (CTF) to issue charging events to an Online Charging Function (OCF). The charging events can be immediate, event-based, or session-based.

Oracle WebLogic Server SIP Container provides a Diameter Online Charging Application that deployed applications can use to generate charging events based on the Ro protocol. This enables deployed applications to act as CTF to a configured OCF. The Diameter Online Charging Application uses the base Diameter protocol that underpins both the Rf and Sh applications.

The Diameter Online Charging Application is based on IETF RFC 4006: Diameter Credit Control Application (http://www.ietf.org/rfc/rfc4006.txt). However, the application supports only a subset of the RFC 4006 required for compliance with 3GPP TS 32.299: Telecommunication management; Charging management; Diameter charging applications (http://www.3gpp.org/ftp/Specs/html-info/32299.htm). Specifically, the Oracle WebLogic Server SIP Container Diameter Online Charging Application provides no direct support for service-specific Attribute-Value Pairs (AVPs), but the API that is provided is flexible enough to allow applications to include custom service-specific AVPs in any credit control request.

12.2 Understanding Credit Authorization Models

RFC 4006 defines two basic types of credit authorization models:

  • Credit authorization with unit reservation, and

  • Credit authorization with direct debiting.

Credit authorization with unit reservation can be performed with either event-based or session-based charging events. Credit authorization with direct debiting uses immediate charging events. In both models, the CTF requests credit authorization from the OCF prior to delivering services to the end user. In both models

The sections that follow describe each model in more detail.

12.2.1 Credit Authorization with Unit Determination

RFC 4006 defines both Event Charging with Unit Reservation (ECUR) and Session Charging with Unit Reservation (SCUR). Both charging events are session-based, and require multiple transactions between the CTF and OCF. ECUR begins with an interrogation to reserve units before delivering services, followed by an additional interrogation to report the actual used units to the OCF upon service termination. With SCUR, it is also possible to include one or more intermediate interrogations for the CTF in order to report currently-used units, and to reserve additional units if required. In both cases, the session state is maintained in both the CTF and OCF.

For both ECUR and SCUR, the online charging client implements the "CLIENT, SESSION BASED" state machine described in RFC 4006.

12.2.2 Credit Authorization with Direct Debiting

For direct debiting, Immediate Event Charging (IEC) is used. With IEC, a single transaction is created where the OCF deducts a specific amount from the user's account immediately after completing the credit authorization. After receiving the authorization, the CTF delivers services. This form of credit authorization is a one-time event in which no session state is maintained.

With IEC, the online charging client implements the "CLIENT, EVENT BASED" state machine described in IETF RFC 4006.

12.2.3 Determining Units and Rating

Unit determination refers to calculating the number of non-monetary units (service units, time, events) that can be assigned prior to delivering services. Unit rating refers to determining a price based on the non-monetary units calculated by the unit determination function.

It is possible for either the OCF or the CTF to handle unit determination and unit rating. The decision lies with the client application, which controls the selection of AVPs in the credit control request sent to the OCF.

12.3 Configuring the Ro Application

The RoApplication is packaged as a Diameter application similar to the Sh application used for managing profile data. The Ro Diameter application can be configured and enabled by editing the Diameter configuration file located in DOMAIN_ROOT/config/custom/diameter.xml, or by using the Diameter console extension.

The application init parameter ocs.host specifies the host identity of the OCF. The OCF host must also be configured in the peer table as part of the global Diameter configuration. Alternately, the init parameter ocs.realm can be used to specify more than one OCF host using realm-based routing. The corresponding realm definition must also exist in the global Diameter configuration.

Example 12-1 shows a sample excerpt from diameter.xml that enables Ro with an OCF host name of "myocs.oracle.com."

Example 12-1 Sample Ro Application Configuration (diameter.xml)

  <application>
    <application-id>4</application-id>
    <class-name>com.bea.wcp.diameter.charging.RoApplication</class-name>
    <param>
      <name>ocs.host</name>
      <value>myocs.oracle.com</value>
    </param>
  </application>

Because the RoApplication is based on the Diameter Credit Control Application, its Diameter application id is 4.

12.4 Overview of the Online Charging API

Oracle WebLogic Server SIP Container provides an online charging API to enable any deployed application to act as a CTF and issue online charging events to an OCS through the Ro protocol. All online charging requests use the Diameter Credit-Control-Request (CCR) message. The CC-Request-Type AVP is used to indicate the type of charging used. In the charging API, the CC-Request-Type is represented by the RequestType class in package com.bea.wcp.diameter.cc. Table 12-1 shows the request types associated with different credit authorization models.

Table 12-1 Credit Control Request Types

Type

Description

RequestType Field in com.bea.wcp.diameter.cc.RequestType

IEC

Immediate Event Charging

EVENT_REQUEST

ECUR

Event Charging with Unit Reservation

INITIAL or TERMINATION_REQUEST

SCUR

Session Charging with Unit Reservation

INITIAL, UPDATE, or TERMINATION_REQUEST


For ECUR and SCUR, units are reserved prior to service delivery and committed upon service completion. Units are reserved with INITIAL_REQUEST and committed with a TERMINATION_REQUEST. For SCUR, units can also be updated with UPDATE_REQUEST.

The base diameter package, com.bea.wcp.diameter, contains classes to support the re-authorization requests used in Ro. The com.bea.wcp.diameter.cc package contains classes to support credit-control applications, including Ro applications. com.bea.wcp.diameter.charging directly supports the Ro credit-control application. Table 12-2 summarizes the classes of interest to Ro credit-control.

Table 12-2 Summary of Ro Classes

Class

Description

Package

Charging

Constant definitions

com.bea.wcp.diameter.charging

RoApplication

Online charging application

com.bea.wcp.diameter.charging

RoSession

Online charging session

com.bea.wcp.diameter.charging

CCR

Credit Control Request

com.bea.wcp.diameter.cc

CCA

Credit Control Answer

com.bea.wcp.diameter.cc

ClientSession

Credit control client session

com.bea.wcp.diameter.cc

RequestType

Credit-control request type

com.bea.wcp.diameter.cc

RAR

Re-Auth-Request message

com.bea.wcp.diameter

RAA

Re-Auth-Answer message

com.bea.wcp.diameter


12.5 Accessing the Ro Application

If the Ro application is deployed, then applications deployed on Oracle WebLogic Server SIP Container can obtain an instance of the application from the Diameter node (com.bea.wcp.diameter.Node class). Example 12-2 shows the sample Servlet code used to obtain the Diameter Node and access the Ro application.

Example 12-2 Accessing the Ro Application

private RoApplication roApp;
void init(ServletConfig conf) {
    ServletContext ctx = conf.getServletContext();
    Node node = (Node) ctx.getParameter("com.bea.wcp.diameter.Node");
    roApp = node.getApplication(Charging.RO_APPLICATION_ID);
  }

This code example would make RoApplication available to the Servlet as an instance variable. The instance of RoApplication is safe for use by multiple concurrent threads.

12.6 Implementing Session-Based Charging

The RoApplication can be used to create new sessions for session-based credit authorization. The RoSession class implements the appropriate state machine depending on the credit control type, either ECUR (Event-Based Charging with Unit Reservation) or SCUR (Session-based Charging with Unit Reservation). The RoSession class is also serializable, so it can be stored as a SIP session attribute. This allows the session to be restored when necessary to terminate the session or update credit authorization.

The example in Example 12-3 creates a new RoSession for event-based charging, and sends a CCR request to start the first interrogation. The RoSession instance is saved so that it can be terminated later, after the service has finished.

Note that the RoSession class automatically handles creating session IDs; the application is not required to set the session ID.

Example 12-3 Creating and Using a RoSession

RoSession session = roApp.createSession();
CCR ccr = session.createCCR(RequestType.INITIAL);
CCA cca = ccr.sendAndWait();
sipAppSession.setAttribute("RoSession", session);
...

12.6.1 Handling Re-Auth-Request Messages

The OCS may initiate credit re-authorization by issuing a Re-Auth-Request (RAR) to the CTF. The application can register a session listener for handling this type of request. Upon receiving a RAR, the Diameter subsystem invoke the session listener on the applications corresponding RoSession object. The application must then respond to the OCS with an appropriate RAA message and initiate credit re-authorization to the CTF by sending a CCR with the CC-Request-Type AVP set to the value UPDATE_REQUEST, as described in section 5.5 of RFC 4006 (http://www.ietf.org/rfc/rfc4006.txt).

A session listener must implement the SessionListener interface and be serializable, or it must be an instance of SipServlet. A Servlet can register a listener as follows:

  RoSession session = roApp.createSession();
  session.addListener(new SessionListener() {
    public void rcvMessage(Message msg) {
      System.out.println("Got message: id = " msg.getSession().getId());
    }
  });

Example 12-4 shows sample rcvMessage() code for processing a Re-Auth-Request.

Example 12-4 Managing a Re-Auth-Request

  RoSession session = roApp.createSession();
  session.addListener(new SessionListener() {
  public void rcvMessage(Message msg) {
    Request req = (Request)msg;
    if (req.getCommand() != Command.RE_AUTH_REQUEST) return;
    RoSession session = (RoSession) req.getSession();
    Answer ans = req.createAnswer();
    ans.setResultCode(ResultCode.LIMITED_SUCCESS); // Per RFC 4006 5.5
    ans.send();
    CCR ccr = session.createCCR(Ro.UPDATE_REQUEST);
    ... // Set CCR AVPs according to requested credit re-authorization
    ccr.send();
    CCA cca = (CCA) ccr.waitForAnswer();
  }

In Example 12-4, upon receiving the Re-Auth-Request the application sends an RAA with the result code DIAMETER_LIMITED_SUCCESS to indicate to the OCS that an additional CCR request is required in order to complete the procedure. The CCR is then sent to initiate credit re-authorization.

Note:

Because the Diameter subsystem locks the call state before delivering the request to the corresponding RoSession, the call state remains locked while the handler processes the request.

12.7 Sending Credit-Control-Request Messages

The CCR class represents a Diameter Credit-Control-Request message, and can be used to send credit control requests to the OCF. For both ECUR (Event-Based Charging with Unit Reservation) and SCUR (Session-Based Charging with Unit Reservation), an instance of RoSession is used to create new CCR requests. You can also use RoApplication directly to create CCR messages for IEC (Immediate Event Charging). Example 12-5 shows an example of how to create and send a CCR.

Example 12-5 Creating and Sending a CCR

  CCR ccr = session.createCCR(RequestType.INITIAL);
  ccr.setServiceContextId("sample_id");
  CCA cca = ccr.sendAndWait();

Once a CCR request is created, you can set whatever application- or service-specific AVPs that are required before sending the request using the addAvp() method. Because some of the same AVPs need to be included in each new request for the session, it is also possible to set these AVPs on the session itself. Example 12-6 shows a sample that sets:

  • Subscription-Id to identify the user for the session

  • Service-Identifier to indicate the service requested, and

  • Requested-Service-Unit to specify the units requested.

A custom AVP is also added directly to the CCR request.

Example 12-6 Setting AVPs in the CCR

  session.setSubscriptionId(...);
  session.setServiceIdentifier(...);
  CCR ccr = session.createCCR(RequestType.INITIAL);
  ccr.setRequestedServiceUnit(...);
  ccr.addAvp(CUSTOM_MESSAGE, "This is a test");
  ccr.send();

In this case, the same Subscription-Id and Service-Identifier are added to every new request for the session. The custom AVP "Custom-Message" is added to the message before it is sent out.

12.8 Handling Failures

Applications can examine the Result-Code AVP in CCA error responses from the OCF to detect the cause of a failure and take an appropriate action. Locally-generated errors, such as an unavailable peer or invalid route specification, cause the request send method to throw an IOException to with a detailed message indicating the nature of the failure.

Applications can also use the Diameter Timer Tx value for determining when the OCF fails to respond to a credit authorization request. Timer Tx has a default value of 10 seconds, but can be overridden using the tx.timer init parameter in the RoApplication configuration. Timer Tx starts when a CCR is sent to the OCF. The timer resets after the corresponding CCA is received.

If Tx expires before a corresponding CCA arrives, any call to waitForAnswer immediately returns null to indicate that the request has timed out. An application can then take action according to the value of the Credit-Control-Failure-Handling (CCFH) AVP in the request. See section 5.7, "Failure Procedures" in RFC 4006 (http://www.ietf.org/rfc/rfc4006.txt) for more details.

Example 12-7 terminates the credit control session if timer Tx expires before receiving the CCA. If the CCA is received later by the Diameter subsystem, the message is ignored because the session longer exists.

Example 12-7 Checking for Timer Tx Expiry

  CCR ccr = session.createCCR(RequestType.INITIAL);
  ccr.setCreditControlFailureHandling(RequestType.TERMINATION);
  ccr.send();
  CCA cca = ccr.waitForAnswer();
  if (cca == null) {
    session.terminate();
  }