11.1 Diameter Protocol Packages

The sections that follow provide an overview of the base Diameter protocol packages, classes, and programming model used for developing client and server-side Diameter applications. See also the following sections for information about using the provided Diameter protocol applications in your SIP Servlets:

11.2 Overview of the Diameter API

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

Table 11-1 Key Elements of the Diameter Base Protocol API

Category

Element

Description

Diameter Node

Node

A class that represents a Diameter node implementation. A diameter node can represent a client- or server-based Diameter application, as well as a Diameter relay agent.

Diameter Applications

Application, ClientApplication

A class that represents a basic Diameter application. ClientApplication extends Application for client-specific features such as specifying destination hosts and realms. All Diameter applications must extend one of these classes to return an application identifier. The classes can also be used directly to create new Diameter sessions.

ApplicationId

A class that represents the Diameter application ID. This ID is used by the Diameter protocol for routing messages to the appropriate application. The ApplicationId corresponds to one of the Auth-Application-Id, Acct-Application-Id, or Vendor-Specific-Application-Id AVPs contained in a Diameter message.

Session

A class that represents a Diameter session. Applications that perform session-based handling must extend this class to provide application-specific behavior for managing requests and answering messages.

Message Processing

Message, Request, Answer

The Message class is a base class used to represent request and answer message types. Request and Answer extend the base class.

Command

A class that represents a Diameter command code.

RAR, RAA

These classes extend the Request and Answer classes to represent re-authorization messages.

ResultCode

A class that represents a Diameter result code, and provides constant values for the base Diameter protocol result codes.

AVP Handling

Attribute

A class that provides Diameter attribute information.

Avp, AvpList

Classes that represent one or more attribute-value pairs in a message. AvpList is also used to represent AVPs contained in a grouped AVP.

Type

A class that defines the supported AVP datatypes.

Error Handling

DiameterException

The base exception class for Diameter exceptions.

MessageException

An exception that is raised when an invalid Diameter message is discovered.

AvpException

An exception that is raised when an invalid AVP is discovered.

Supporting Interfaces

Enumerated

An enum value that implements this interface can be used as the value of an AVP of type INTEGER32, INTEGER64, or ENUMERATED.

SessionListener

An interface that applications can implement to subscribe to messages delivered to a Diameter session.

MessageFactory

An interface that allows applications to override the default message decoder for received messages, and create new types of Request and Answer objects.

The default decoding process begins by decoding the message header from the message bytes using an instance of MessageFactory. This is done so that an early error message can be generated if the message header is invalid. The actual message AVPs are decoded in a separate step by calling decodeAvps. AVP values are fully decoded and validated by calling validate, which in turn calls validateAvp for each partially-decoded AVP in the message.

11.2.1 File Required for Compiling Application Using the Diameter API

The following jar files are part of the Diameter API that we expose. To compile against this API, access this file from the following locations:

The wlssdiameter.jar file is located at the following location: MIDDLEWARE_HOME/server/lib/wlss/.

11.3 Working with Diameter Nodes

A diameter node is represented by the com.bea.wcp.diameter.Node class. A Diameter node may host one or more Diameter applications, as configured in the diameter.xml file. 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 11-1 shows the sample code used to access the Rf application.

11.4 Implementing a Diameter Application

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:

11.5 Working with Diameter Sessions

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

11.6 Working with Diameter Messages

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:

The message bytes are parsed.

The application and session ID values are determined.

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

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

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

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.

11.6.1 Sending Request Messages

Either a Session or Application can originate and receive request messages. Requests are generated using the createRequest() method. You must supply a command code for the new request message. For routing purposes, the destination host or destination realm AVPs are also generally set by the originating session or application.

Received answers can be obtained using Request.getAnswer(). After receiving an answer, you can use getSession() to obtain the relevant session ID and getResultCode() to determine the result. You can also use Answer.getRequest() to obtain the original request message.

Requests can be sent asynchronously using the send() method, or synchronously using the blocking sendAndWait() method. Answers for requests that were sent asynchronously are delivered to the originating session or application. You can specify a request timeout value when sending the message, or can use the global request-timeout configuration element in diameter.xml. An UNABLE_TO_DELIVER result code is generated if the timeout value is reached before an answer is delivered. getResultCode() on the resulting Answer returns the result code.

11.6.2 Sending Answer Messages

New answer messages are generated from the Request object, using createAnswer(). All generated answers should specify a ResultCode and an optional Error-Message AVP value. The ResultCode class contains pre-defined result codes that can be used.

Answers are delivered using the send() method, which is always asynchronous (non-blocking).

11.6.3 Creating New Command Codes

A Diameter command code determines the message type. For instance, when sending a request message, you must supply a command code.

The Command class represents pre-defined commands codes for the Diameter base protocol, and can be used to create new command codes. Command codes share a common name space based on the code itself.

The define() method registers a new Command, or returns a previous command definition if one was already defined. Commands can be compared using the reference equality operator (==).

11.7 Working with AVPs

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.

11.7.1 Creating New Attributes

You can create new attributes to extend your Diameter application. The Attribute class represents an AVP attribute, and includes the AVP code, name, flags, optional vendor ID, and type of attribute. The class also maintains a registry of defined attributes. All attributes share a common namespace based on the attribute code and vendor ID.

Table 11-1 lists the available attribute types and describes how they are mapped to Java types.

The define() method registers a new attribute, or returns a previous definition if one was already defined. Attributes can be compared using the reference equality operator (==).

Table 11-2 Attribute Types

Diameter Type

Type Constant

Java Type

Integer32

Type.INTEGER32

Integer

Integer64

Type.INTEGER64

Long

Float32

Type.FLOAT32

Float

OctetString

Type.BYTES

ByteBuffer (read-only)

UTF8String

Type.STRING

String

Address

Type.ADDRESS

InetAddress

Grouped

Type.GROUPED

AvpList

11.8 Creating Converged Diameter and SIP Applications

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 11-4.

SIP uses Call-id (the SIP-Call-ID header) to identify a particular call session between two users. OWLCS automatically links a Diameter session to the currently-active call state by encoding the SIP Call-id into the Diameter session ID. When a Diameter message is received, the container automatically retrieves the associated call state and locates the Diameter session. A Diameter session is serializable, so you can store the session as an attribute in a the SipApplicationSession object, or vice versa.

Converged applications can use the Diameter SessionListener interface to receive notification when a Diameter message is received by the session. The SessionListener interface defines a single method, rcvMessage(). Example 11-5 shows an example of how to implement the method.