Alexandre Mendonça

• 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.

• 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.

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);

}

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);
  
}

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
    ...
  }

// 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;
  }

// 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
  }

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.");
      }
    }
  }
}

• Continue work on the 1.x.y series, providing it with stability and better performance;
• Start a 2.x.y series, where we intend to change several internal components as well as redesigning the API to make it more easy and intuitive to work with, probably also providing a high-level abstraction to the Diameter protocol to provide simple charging. This is something to be discussed among the community to understand the direction to follow