All classes in the Diameter base protocol API reside in the com.bea.wcp.diameter package. Table 1-1 describes the key classes, interfaces, and exceptions in this package.

In addition to these base Diameter classes, accounting-related classes are stored in the com.bea.wcp.diameter.accounting package, and credit-control-related classes are stored in com.bea.wcp.diameter.cc. See Using the Diameter Ro Interface API for Online Charging and Using the Diameter Rf Interface Application for Offline Charging for more information about classes in these packages.

In order to access a Diameter application, a deployed application (such as a SIP Servlet) must obtain the Diameter Node instance and request the application. Example 1-10 shows the sample code used to access the Rf application.

ServletContext sc = getServletConfig().getServletContext();
Node node = sc.getAttribute("com.bea.wcp.diameter.Node");
RfApplication rfApp = (RfApplication) node.getApplication(Charging.RF_APPLICATION_ID);

All Diameter applications must extend either the base Application class or, for client applications, the ClientApplication class. The model for creating a Diameter application is similar to that for implementing Servlets in the following ways:

• Diameter applications override the init() method for initialization tasks.

• Initialization parameters configured for the application in diameter.xml are made available to the application.

• A session factory is used to generate new application sessions.

Diameter applications must also implement the getId() method to return the proper application ID. This ID is used to deliver Diameter messages to the correct application.

Applications can optionally implement rcvRequest() or rcvAnswer() as needed. By default, rcvRequest() answers with UNABLE_TO_COMPLY, and rcvRequest() drops the Diameter message.

Example 1-11 shows a simple Diameter client application that does not use sessions.

public class TestApplication extends ClientApplication {
  protected void init() {
    log("Test application initialized.");
  }
  public ApplicationId getId() {
    return ApplicationId.BASE_ACCOUNTING;
  }
  public void rcvRequest(Request req) throws IOException {
    log("Got request: " + req.getHopByHopId());
    req.createAnswer(ResultCode.SUCCESS).send();
  }
}

Applications that perform session-based handling must extend the base Session class to provide application-specific behavior for managing requests and answering messages. If you extend the base Session class, you must implement either rcvRequest() or rcvAnswer(), and may implement both methods.

The base Application class is used to generate new Session objects. After a session is created, all session-related messages are delivered directly to the session object. The Converged Application Server container automatically generates the session ID and encodes the ID in each message. Session attributes are supported much in the same fashion as attributes in SipApplicationSession.

Example 1-12 shows a simple Diameter session implementation.

public class TestSession extends Session {
  public TestSession(TestApplication app) {
    super(app);
  }
  public void rcvRequest(Request req) throws IOException {
    getApplication().log("rcvReuest: " + req.getHopByHopId());
    req.createAnswer(ResultCode.SUCCESS).send();
  }
}

public class TestApplication extends Application {
  ...
  public TestSession createSession() {
    return new TestSession(this);
  }
}

TestSession session = testApp.createSession();
Request req = session.creatRequest();
req.sent();

The base Message class is used for both Request and Answer message types. A Message always includes an application ID, and optionally includes a session ID. By default, messages are handled in the following manner:

1. The message bytes are parsed.

2. The application and session ID values are determined.

3. The message is delivered to a matching session or application using the following rules:

   1. If the Session-Id AVP is present, the associated Session is located and the session's rcvMessage() method is called.

   2. If there is no Session-Id AVP present, or if the session cannot be located, the Diameter application's rcvMessage() method is called.

   3. If the application cannot be located, an UNABLE_TO_DELIVER response is generated.

The message type is determined from the Diameter command code. Certain special message types, such as RAR, RAA, ACR, ACA, CCR, and CCA, have getter and setter methods in the Message object for convenience.

Attribute Value Pair (AVP) is a method of encapsulating information relevant to the Diameter message. AVPs are used by the Diameter base protocol, the Diameter application, or a higher-level application that employs Diameter.

The Avp class represents a Diameter attribute-value pair. You can create new AVPs with an attribute value in the following way:

Avp avp = new Avp(Attribute.ERROR_MESSAGE, "Bad request");

You can also specify the attribute name directly, as in:

Avp avp = new Avp("Error-Message", "Bad request");

The value that you specify must be valid for the specified attribute type.

To create a grouped AVP, use the AvpList class, as in:

AvpList avps = new AvpList();
avps.add(new Avp("Event-Timestamp", 1234));
avps.add(new Avp("Vendor-Id", 1111));

The Diameter API enables you to create converged applications that utilize both SIP and Diameter functionality. A SIP Servlet can access an available Diameter application through the Diameter Node, as shown in Example 1-13.

ServletContext sc = getServletConfig().getServletContext();
Node node = (Node) sc.getAttribute("com.bea.wcp.diameter.Node");
RfApplication rfApp = (RfApplication) node.getApplication(Charging.RF_APPLICATION_ID);

Session session = app.createSession();
session.setListener(new SessionListener() {
  public void rcvMessage(Message msg) {
    if (msg.isRequest()) System.out.println("Got request!");
  }
});