Skip Headers

Oracle® Communication and Mobility Server Developer's Guide Release 10.1.3 Part Number E10293-02 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# A Oracle Diameter Java APIs

This appendix describes the Oracle Diameter Java APIs in the following sections:

- "Diameter Java Base Protocol API"

- "3GPP/Rf Diameter Java API"

- "3GPP/Ro DIAMETER JAVA API"

- "3GPP/Sh Diameter Java API"

- "Diameter Application Example"

Figure A-1 Oracle Diameter Architecture

Description of "Figure A-1 Oracle Diameter Architecture"

The Base Protocol library is the main element in the picture. It contains the base protocol implementation, and is available as a standalone C++ shared library. On its upper side, the Diameter Base Protocol library, provides an application registration mechanism. The specific application subclass AcctApplication can be derived by user depending on the state machine required to be used by the application to be implemented. Each Application object can implement its own session subclass. Specific session subclass (AuthSession and AcctSession) can be derived by user depending on the state machine (Authentication, Authorization or Accounting) implemented by the application.On its lower side, the Diameter Base Protocol library also provides an API to interact with its transport modules. This API enables the user application to instantiate any subclass of the Transport class. These subclasses can be system dependant, and can provide any kind of transport protocols for Diameter. Diameter comes with a socket based transport module for TCP and SCTP kernel implementations in Unix-like environments.The Diameter Base Protocol library also provides a direct Core interface. This API supports all the configuration needs, including dynamic realm-based routing table configuration, generic tracing and logging callbacks, external memory manager support, and dynamic dictionary extensibility.

## Diameter Java Base Protocol API

The Diameter Java API is an API compliant with JAIN. The JAIN initiative represents a community of communications experts defining the necessary Java interfaces as an extension of the core Java platform to migrate proprietary communications networks to open standardized based networks. The Diameter Java API is a wrapping of Diameter C++ API.

This section defines the Java API for the Diameter Base Protocol. The Java interfaces and classes described in this part enable Java developers to build application based on the Diameter base protocol.This Java API was designed in such a way that it is possible to provide several implementations of it. The next section will define and describe in details one of possible implementation: Rf Diameter Application.

Figure A-2 Oracle Diameter Java API Architecture

Description of "Figure A-2 Oracle Diameter Java API Architecture"

Through Diameter interfaces, a Diameter protocol stack provider is obtained from the factory, and Diameter listeners are then attached to the providers created by the Diameter stack.

### Base Protocol Diameter Java Interface

The Diameter Java API is composed of several interfaces:

#### Diameter Factory

The DiameterFactory interface is used by the Diameter applications to obtain specific instances of different implementations of all interfaces defined in Diameter Java API. The only instance of the DiameterFactory can be obtained using the getInstance() method.

#### Diameter Stack

The DiameterStack interface represents a Diameter Protocol Stack as defined in [RFC 3588]. This interface is used also to create providers, routes and listening points. A Diameter stack must be initialized and configured before any messages exchange (see section [6.2]).

#### Diameter Application

The DiameterProvider interface represents a Diameter Application (with one Authorization/Authentication Application ID or one Accounting Application ID) running on top of the Diameter base protocol.The DiameterListener interface processes events that are triggered by an object implementing the DiameterProvider interface. There can be only one listener per provider. This interface must be implemented by the application programmer.

#### Diameter Transport

The DiameterRoute interface represents a route entry in the realm-based routing table. A Diameter client application calls the createDiameterRoute method to declare remote peers. The DiameterListeningPoint interface represents a local transport address for a Diameter stack and enables it to accept incoming connection from declared remote peers.

#### Diameter AVPs

The DiameterMessageFactory interface provides factory methods that enable a Diameter application to create AVPs and messages for a particular implementation of this specification. AVPs are defined by the following class types:

- DiameterFloat32AVP: represents a 32-bit float AVP

- DiameterFloat64AVP: represents a 64-bit float AVP

- DiameterInteger32AVP: represents a 32-bit integer AVP

- DiameterInteger64AVP: represents a 64-bit integer AVP

- DiameterGroupedAVP: represents a grouped AVP

- DiameterOctetStringAVP: represents an AVP which value is a raw byte array

- DiameterGenericAVP: represents an AVP which has not been declared in the protocol dictionary

The DiameterMessage interface represents a Diameter Message as defined in [RFC 3588]. The Diameter messages are composed from AVPs added by calling add() method.

#### Diameter Session

The DiameterSession interface represents a Diameter session as per [RFC 3588]. A Diameter application calls the createClientDiameterSession method from the DiameterProvider interface if it needs to send a request for a new Diameter session. Then it can send the request by calling sendMessage method. Also, an incoming request can be handled by calling createServerDiameterSession to create a new server session, then using sendMessage to send the response.

#### Diameter Event

The DiameterEvent interface is the base class for all Diameter events. These events specialize this interface:

- DiameterMessageEvent: This event is generated when an incoming message is available

- DiameterRealmStateChangeEvent: This event notifies the application of the reachability or unreachability of a remote realm, as a result of peers coming up or down

- DiameterSessionEvent: represents all the events which are related to a Diameter session such as received messages, session timeouts, and session errors.

The Diameter stack delivers information to the user application by creating instances of the Diameter Event class and passing these instances to the DiameterListener.processEvent method.

#### Diameter Exception

The DiameterException interface represents the base class for all the Diameter exceptions. These exceptions specialize this interface:

- DiameterInvalidArgumentException: This exception is thrown or when a method receives an invalid parameter value

- DiameterInvalidMessageException: This exception is thrown when a Diameter Message can't be encoded

- DiameterMessageException: This exception is thrown when a failure occurs during a sending message

- DiameterTransportFailureException: This exception is thrown when a synchronous transport failure occurs during an API action

- DiameterUnsupportedFeatureException: This exception is thrown by an implementation when an operation is invoked that is not supported by this implementation

## 3GPP/Rf Diameter Java API

This section defines a Java API for the 3GPP [TS 32.299] Rf Interface over the Diameter protocol ([TS 32.225], [TS 32.200] and [TS 32.240] in order to specify).

### 3GPP/Rf Diameter Java Interface

This section describes the Java interface.

#### Rf Provider

The DiameterRfProvider interface represents a Rf Diameter Application as defined in 3GPP Interfaces. An instance of a class implementing this interface can be obtained by calling the DiameterStack.createDiameterRfProvider(Properties, refFSM). The different values of refFSM are:

- RFC_SRV_LESS for Rfc 3588 stateless server state machine

- RFC_SRV_FULL for Rfc 3588 stateful server state machine

- RFC_CL for Rfc 3588 client state machine

The Properties parameter specifies the features that will be handled by this Rf provider. This is a list of properties which may contain a number of options. See section [3.2.6] for know more about Rf Application options.

#### Rf Listener

The DiameterRfListener interface processes accounting messages that are received by the DiameterRfProviderImpl class implementing the DiameterRfProvider interface. A DiameterRfListener instance is registered to a provider by the following method DiameterRfProvider. setDiameterRfListener (). This interface provides two principles methods: accountingRequestReceived() and accountingAnswerReceived(). The first one must be implemented and called when the option AUTO_ANSWER is set to false. In this case, the server must be able to create an accounting answer corresponding to the received accounting request. The second one processes the received accounting answer.

#### Rf Message Factory

The DiameterRfMessageFactory interface provides factory methods that enable an application to create Diameter Rf messages as defined in 3GPP: createAccountingRequest() and createAccountingAnswer(). An instance of a class implementing this interface can be obtained by calling the DiameterStack.getRfDiameterMessageFactory() method.Messages created by this factory are as following:

- Accounting-Request (ACR)--The first following method creates a basic ACR (with only mandatory AVPs) and the second one creates a more sophisticated ACR with the most used AVPs as defined in 3GPP:

  - DiameterMessage

        createAccountingRequest (String Destination-Realm,
                                 int Accounting-Record-Type,
                                 int Accounting-Record-Number)

  - DiameterMessage

        createAccountingRequest(String Destination-Realm,
                                 int Accounting-Record-Type,
                                 int Accounting-Record-Number,
                                 String roleOfNode,
                                 String userSessionId,
                                 String callingPartyAddress,
                                 String calledPartyAddress)

- Accounting-Answer (ACA)--The first following method creates a basic ACA (with only mandatory AVPs) and the second one creates a more sophisticated ACA with the most used AVPs as defined in 3GPP:

  - Diameter Message

    -     createAccountingAnswer (String Result-Code,
                                   int Accounting-Record-Type,
                                   int Accounting-Record-Number)

  - Diameter Message

    -     createAccountingAnswer (String Result-Code,
                                   int Accounting-Record-Type,
                                   int Accounting-Record-Number,
                                   String roleOfNode,
                                   String userSessionId,
                                   String callingPartyAddress,
                                   String calledPartyAddress)

##### 3GPP/Rf Dictionary

The 3GPP Rf Interface dictionary is returned by getRfDictionary() and must be extended by the Diameter stack.

#### Rf Events

Like any Diameter application, an Rf application can receive/send accounting events from/to the Diameter stack.

##### Process Event

To receive an accounting event from the Diameter stack, user has to implement the processEvent(DiameterEvent) callback in the DiameterRfListener implementation.The list of the possible received accounting events are the following ones:

- DiameterTimeoutEvent(Object, DiameterSession, int): This event is generated by the Diameter implementation when one of the session timers elapses. The different reasons to trigger an event for the Rf Interface are:

  - SESSION_TIMEOUT_EXPIRED: The event is triggered by the stack on session supervision timer expiration

  - TX_TIMEOUT_EXPIRED: The event is triggered by the stack on session supervision timer expiration.

  - INTERIM_TIMEOUT_EXPIRED: The event is triggered when the time specified by the interim interval duration has expired.

- DiameterServiceEvent(Object, DiameterSession, int): This event is generated by the Diameter implementation when one service is finished. The different reasons to trigger an event for the Rf Interface are:

  - TERMINATE_SERVICE: The event is triggered by the stack when service is terminated by the stack or by server.

- DiameterInvalidMessageReceivedEvent(Object, DiameterSession, Message): This event is triggered by the stack when an invalid message has been received. This event object contains the invalid received message.

##### Raise Events

To send an accounting event to the Diameter stack, user has to call the accounting application eventRaised(DiameterEvent) method.The only accounting event triggered by the Rf application is DiameterRfOutOfSpaceEvent(Object, int). The different types of event for an DiameterRfOutOfSpaceEvent are:

- EVT_OUT_OF_SPACE: The event can be triggered by the application to inform the stack that there is no more space to store the received/sent accounting message. This event is created by instantiating DiameterRfOutOfSpaceEvent class with the type parameter set to EVT_OUT_OF_SPACE. When the Rf server AUTO_ANSWER mode is activated and once the EVT_OUT_OF_SPACE event has been triggered, the stack automatically responds with an answer message including the Result-Code AVP set to DIAMETER_OUT_OF_SPACE and this until the EVT_NOT_OF_OUT_SPACE event triggering.

- EVT_END_OUT_OF_SPACE: The event can be triggered by the application to inform the stack that there is space again to store the received/sent accounting request message. This event is created by instantiating DiameterRfOutOfSpaceEvent class with the type EVT_END_OUT_OF_SPACE. Triggering such an event is relevant only after having triggered an EVT_OUT_OF_SPACE event.

  The DiameterRfOutOfSpaceEvent is relevant only when AUTO_ANSWER mode is activated.

#### Rf Application Options

These options specify the features handled by the accounting Application. This is a list of Properties (see java.util.properties) which may contain a number of options. An option can be specific to an FSM. Here is the list of the Rf application configurable options which can be set depending on the implemented FSM:

##### Rf Server Stateless

FSM admits following options setting:

- AUTO_ANSWER

- AUTO_DELETION

- ENABLE_INVALID_COMMAND

- ENABLE_SND_MISSING_AVP

##### Rf Server StateFul

FSM admits following options setting:

- AUTO_ANSWER

- AUTO_DELETION

- DELETE_ON_TIMEOUT

- SUPERVISION_TIMER_DURATION

- ENABLE_INVALID_COMMAND

- ENABLE_SND_MISSING_AVP

##### Rf Client

FSM admits following options setting:

- AUTO_DELETION

- ENABLE_INVALID_COMMAND

- ENABLE_SND_MISSING_AVP

- DELETE_ON_TIMEOUT

- SUPERVISION_TIMER_DURATION

- INTERIM_INTERVAL

- REALTIME_REQUIRED

The default value of the INTERIM_INTERVAL and REALTIME_REQUIRED options can be overwritten dynamically by the application for a specific session by using the setSessionParameter() method.

#### Rf Application FSM

As presented in the [RFC 3588], different types of accounting records are sent depending on the actual type of accounted service. If the accounted service is a one-time event, meaning that the start and stop of the event are simultaneous, then the Accounting-Record-Type AVP must be set to the value EVENT_RECORD.If the accounted service is of a measurable length, then the AVP must use the values START_RECORD, STOP_RECORD, and possibly, INTERIM_RECORD.Here are the two different messages flows which can be handled by the Rf Diameter application.One-time event accounting service:

- Client > ACR (EVENT_RECORD) > Server

- Client < ACA (EVENT_RECORD) < Server

Measurable length duration accounting service:

- Client > ACR (START_RECORD) > Server

- Client < ACA (START_RECORD) < Server

- Client > ACR (INTERIM_RECORD) > Server

- Client < ACA (INTERIM_RECORD) < Server

- Client > ACR (INTERIM_RECORD) > Server

- Client < ACA (INTERIM_RECORD) < Server

- Client > ACR (STOP_RECORD) > Server

- Client < ACA (STOP_RECORD) < Server

ACR(EVENT_RECORD) stands for Accounting-Request message with Accounting-Record-Type AVP set to EVENT_RECORD and request flag set to true.ACA(EVENT_RECORD) stands for Accounting-Answer message with Accounting-Record-Type AVP set to EVENT_RECORD and request flag set to false.

Below are the different types of FSM which can be implemented in Rf application.

##### Rf Client FSM

This FSM responds to the [RFC 3588] requirements which define the client side state machine. A session instantiated by an application implementing this FSM expects to receive an accounting request message including an Accounting-Record-Type AVP value set to EVENT_RECORD or START_RECORD as first received message. Once an accounting request message with the Accounting-Record-Type AVP value set to START_RECORD is received, the FSM expects to receive other(s) accounting request message(s) with the Accounting-Record-Type AVP value set to INTERIM_RECORD or STOP_RECORD. The reception of an accounting request message including an Accounting-Record-Type AVP value set to STOP_RECORD corresponds to the end of the session.

##### RF Stateful Server FSM

This FSM responds to the [RFC 3588] requirements which define the server side state machine that may be followed by applications that require keeping track of the session state at the accounting server. An application implementing this FSM waits for a request accounting message and sends a response with the same Accounting-Record-Type AVP value as received in the request message. A session instantiated by an application implementing this FSM expects to receive an accounting request message including an Accounting-Record-Type AVP value set to EVENT_RECORD or START_RECORD as first received message. Once an accounting request message with the Accounting-Record-Type AVP value set to START_RECORD is received, the FSM expects to receive other(s) accounting request message(s) with the Accounting-Record-Type AVP value set to INTERIM_RECORD or STOP_RECORD. The reception of an accounting request message including an Accounting-Record-Type AVP value set to STOP_RECORD represents the end of the session.

##### Rf Stateless Server FSM

This FSM responds to the [RFC 3588] requirements which define the default server side state machine requiring the reception of the accounting records in any order and at any time, and doesn't place any standard requirement on the processing of the records. An application implementing this FSM waits for a request accounting message and sends a response with the same Accounting-Record-Type AVP value as received in the request message.

## 3GPP/Ro DIAMETER JAVA API

This section defines a Java API for the 3GPP [TS 32.299] Ro Interface over the Diameter protocol ([TS 32.225], [TS 32.200] and [TS 32.240] in order to specify).

### 3GPP/Ro DIAMETER JAVA INTERFACE

This section details the 3GPP/Ro Diameter Java Interface

#### Ro Provider

The DiameterRoProvider interface represents a Ro Diameter Application as defined in 3GPP Interfaces. An instance of a class implementing this interface can be obtained by calling the DiameterStack.createDiameterRoProvider(Properties, refFSM). The different value of refFSM are:

- RFC_CL_LESS for Rfc 4006 event base client state machine

- RFC_CL_FULL for Rfc 4006 session based client state machine

- RFC_SRV for Rfc 4006 server state machine

The Properties parameter specifies the features that will be handled by this Ro provider. This is a list of properties which may contain a number of options. See section [4.2.6] for know more about Ro Application options.

#### Ro Listener

The DiameterRoListener interface processes accounting messages that are received by the DiameterRoProviderImpl class implementing the DiameterRoProvider interface. A DiameterRoListener instance is registered to a provider by the following method DiameterRoProvider. setDiameterRoListener (). This interface provides four principles methods: creditControlRequestReceived(), creditControlAnswerReceived(), reAuthRequestReceived() and reAuthAnswerReceived().The first and third one must be implemented and called when the option AUTO_ANSWER is set to false. In this case, the server must be able to create an accounting answer corresponding to the received accounting request. The second and last methods process the received accounting answers.

#### Ro Message Factory

The DiameterRoMessageFactory interface provides factory methods that enable an application to create Diameter Ro messages as defined in 3GPP: createCreditControlRequest(), createCreditConrolAnswer(), createReAuthRequest() and createReAuthAnswer(). An instance of a class implementing this interface can be obtained by calling the DiameterStack.getRoDiameterMessageFactory() method.Messages created by this factory are:

- Credit-Control-Request (CCR)

  These methods create a basic CCR (with only mandatory AVPs). The first one creates the CCR without the Requested-Action AVP (mandatory only in event sessions). In the others, the method's name specifies the Requested-Action value:

  - DiameterMessage

        createCreditControlRequest (String destinationRealm,
           int authApplicationId,
           StringserviceContextId,
           String CCRequestType
           int CCRequestNumber)

  - DiameterMessage

        createCreditControlRequestDirectDebiting(String destinationRealm,
           int authApplicationId,
           String serviceContextId,
           int CCRequestNumber)

  - DiameterMessage

        createCreditControlRequestRefundAccount(String destinationRealm,
           int authApplicationId,
           String serviceContextId,
           int CCRequestNumber)

  - DiameterMessage

        createCreditControlRequestCheckBalance(String destinationRealm,
           int authApplicationId,
           String serviceContextId,
           int CCRequestNumber)

  - DiameterMessage

        createCreditControlRequestPriceEnquiry(String destinationRealm,
           int authApplicationId,
           String serviceContextId,
           int CCRequestNumber)

- Credit-Control-Answer (CCA)

  The first following method creates a basic CCA (with only mandatory AVPs) and the second one creates an CCA from an CCR:

  - DiameterMessage

        createCreditControlAnswer(String resultCode,
           int authApplicationId,
           String CCRequestType,
           int CCRequestNumber)

  - Diameter Message

        createCreditControlAnswer(String resultCode,
           DiameterMessage messageCCR)

- Re-Auth-Request (RAR)

  This method creates a basic RAR (with only mandatory AVPs)

  - Diameter Message

        createReAuthRequest(String destinationRealm,
           String destinationHost,
           int authApplicationId,
           String reAuthRequestType)

- Re-Auth-Answer (RAA)

  This method creates a RAA, specifying only the Result-Code AVP.

  - Diameter Message

        createReAuthAnswer(String resultCode)

#### 3GPP/Ro Dictionary

The 3GPP Ro Interface dictionary is returned by getRoDictionary() and must be extended by the Diameter stack.

#### Ro Events

Like any Diameter application, an Ro application can receive/send events from/to the Diameter stack.

##### Process Events

To receive an accounting event from the Diameter stack, user has to implement the processEvent(DiameterEvent) callback in the DiameterRoListener implementation.The list of the possible received accounting events are the following ones:

- DiameterTimeoutEvent(Object, DiameterSession, int): This event is generated by the Diameter implementation when one of the session timers elapses. The different reasons to trigger an event for the Ro Interface are:

  - SESSION_TIMEOUT_EXPIRED: The event is triggered by the stack on session supervision timer expiration

  - TX_TIMEOUT_EXPIRED: The event is triggered by the stack on session supervision timer expiration.

  - TRA_TIMEOUT_EXPIRED: The event is triggered by the stack when the RAA is not sent on time by the application.

- DiameterServiceEvent(Object, DiameterSession, int): This event is generated by the Diameter implementation when one service is finished. The different reasons to trigger an event for the Rf Interface are:

  - TERMINATE_SERVICE: The event is triggered by the stack when service is terminated by the stack or by server.

  - GRANT_SERVICE: The event is triggered by the stack when service is granted by server.

  - BACKUP_SERVICE: The event is triggered by the stack when Tx2 timer expired and backup server needs to be contacted by the application.

  - ERROR_SERVICE: The event is triggered by the stack when a service error is detected by the stack.

- DiameterInvalidMessageReceivedEvent(Object, DiameterSession, Message): This event is triggered by the stack when an invalid message has been received. This event object contains the invalid received message.

##### Raise Events

To send an accounting event to the Diameter stack, user has to call the accounting application eventRaised(DiameterEvent) method. The only accounting event triggered by the Rf application is DiameterBackupEvent(Object, int) The different types of event for an DiameterBackupEvent are:

- EVT_NOBACKUP_ACCEPTED: The event can be triggered by the application to inform the stack that it doesn't have any backup server address.

- EVT_BACKUP_SUCCESS: The event can be triggered by the application to inform the stack that it received a successful credit control answer from the backup server.

- EVT_BACKUP_FAILED: The event can be triggered by the application to inform the stack that it received a failed credit control answer from the backup server.

These events are relevant only when the stack has sent a BackupService event to the application.

#### Ro Application Options

These options specify the features handled by the accounting Application. This is a list of properties (see java.util.properties) which may contain a number of options. An option can be specific to an FSM. Here is the list of the Ro application configurable options which can be set depending on the implemented FSM:

##### Ro Server

FSM admits following options setting

- AUTO_ANSWER

- AUTO_DELETION

- SUPERVISION_TIMER_DURATION

- DELETE_ON_TIMEOUT

- ENABLE_INVALID_COMMAND

- ENABLE_SND_MISSING_AVP

##### Ro StateFul Client

FSM admits following options setting

- AUTO_DELETION

- DELETE_ON_TIMEOUT

- TX_TIMER_DURATION

- TRA_TIMER_DURATION

- CCFH

- ENABLE_INVALID_COMMAND

- ENABLE_SND_MISSING_AVP

##### Ro StateLess Client

FSM admits following options setting

- AUTO_DELETION

- DDFH

- TX1_TIMER_DURATION

- TX2_TIMER_DURATION

- BACKUP_TIMER_DURATION

- RETRANSMISSION_INTERVAL

- RETRANSMISSION_ATTEMPS

- ENABLE_INVALID_COMMAND

- ENABLE_SND_MISSING_AVP

#### Ro Application FSM

As presented in the [RFC 4006], different types of credit control requests are sent depending on the actual type of credit control service. If the credit control service is a one-time event, meaning that the start and stop of the event are simultaneous, then the CC-Request-Type AVP must be set to the value EVENT_REQUEST.If the credit control service is of a measurable length, then the AVP must use the values INITIAL_REQUEST, TERMINATION_REQUEST, and possibly, UPDATE_REQUEST.Here are the two different messages flows which can be handled by the Ro Diameter application.One-time event credit control service:

- Client > CCR (EVENT_REQUEST) > Server

- Client < CCA (EVENT_REQUEST) < Server

Measurable length duration accounting service:

- Client > CCR (INITIAL_REQUEST) > Server

- Client < CCA (INITIAL_REQUEST) < Server

- Client > CCR (UPDATE_REQUEST) > Server

- Client < CCA (UPDATE_REQUEST) < Server

- Client > CCR (UPDATE_REQUEST) > Server

- Client < CCA (UPDATE_REQUEST) < Server

- Client > CCR (TERMINATION_REQUEST) > Server

- Client < CCA (TERMINATION_REQUEST) < Server

CCR(EVENT_REQUEST) stands for Credit-Control-Request message with CC-Request-Type AVP set to EVENT_REQUEST.CCA(EVENT_REQUEST) stands for Credit-Control-Answer message with CC-Request-Type AVP set to EVENT_REQUEST.

Below are the different types of FSM which can be implemented in Ro application.

##### Ro Stateful Client FSM

This FSM responds to the [RFC 4006] requirements which define the session-based credit control client state machine when the first interrogation is executed after the authorization/authentication process.A session instantiated by an application implementing this FSM expects to send a credit control request message including a CC-Request-Type AVP value set to INITIAL_REQUEST as first sent message. Once an credit control answer message with the CC-Request-Type AVP value set to INITIAL_REQUEST is received, the FSM expects to send either other(s)) credit control request message(s) with the CC-Request-Type AVP value set to UPDATE_REQUEST or UPDATE_REQUEST or a Re-Authentication request message. The reception of a credit control answer message including a CC-Request-Type AVP value set to TERMINATION_REQUEST represents the end of the session.

##### Ro StateLess Client FSM

This FSM responds to the [RFC 4006] requirements which define the event-based credit control client state machine.An application implementing this FSM sends a credit control request message with the CC-Request-Type AVP set to EVENT_REQUEST and waits for the credit control answer with the CC-Request-Type AVP set to EVENT_REQUEST. The reception of a credit control answer message including a CC-Request-Type AVP value set to EVENT_REQUEST represents the end of the session.

##### Ro Server FSM

This FSM responds to the [RFC 4006] requirements which define the credit control server state machine. An application implementing this FSM waits for a credit control request message and expects to send a response with the same CC-Request-Type AVP value as received in the request message.A session instantiated by an application implementing this FSM expects to receive an accounting request message including an CC-Request-Type AVP value set to EVENT_REQUEST or INITIAL_REQUEST as first received message. Once a credit control request message with the CC-Request-Type AVP value set to INITIAL_REQUEST is received, the FSM expects to receive other(s) credit control request message(s) with the CC-Request-Type AVP value set to UPDATE_REQUESTor TERMINATION_REQUEST. The emission of a credit control answer message including a CC-Request-Type AVP value set to TERMINATION_REQUEST represents the end of the session.

## 3GPP/Sh Diameter Java API

This section defines a Java API for the 3GPP [TS 29.328] and [TS 29.329] Sh Interface over the Diameter protocol.

### 3GPP/Sh Diameter Java Interface

This section provides information about the 3GPP/Sh Diameter Java Interface.

#### Sh Provider

The DiameterShProvider interface represents a Sh Diameter Application as defined in 3GPP Interfaces. An instance of a class implementing this interface can be obtained by calling the DiameterStack.createDiameterShProvider(Properties)The Properties parameter specifies the features that will be handled by this Sh provider. This is a list of properties which may contain a number of options. See section [5.2.6] for know more about Sh Application options.

#### Sh Listener

The DiameterShListener interface processes Diameter messages that are received by the DiameterShProviderImpl class implementing the DiameterShProvider interface. A DiameterShListener instance is registered to a provider by the following method DiameterShProvider. setDiameterShListener (). This interface provides the following methods:

- profileUpdateRequestReceived()

- profileUpdateAnswerReceived()

- pushNotificationRequestReceived()

- pushNotificationAnswerReceived()

- subscribeNotificationRequestReceived()

- subscribeNotificationAnswerReceived()

- userDataRequestReceived()

- userDataAnswerReceived()

These methods process the received Diameter messages.

#### Sh Message Factory

The DiameterShMessageFactory interface provides factory methods which enable an application to create Diameter messages as defined by the 3GPP [TS 29.328] specification (Sh interface): createProfileUpdateRequest(), createProfileUpdateAnswer(), createPushNotificationRequest(), createPushNotificationAnswer(), createSubscribeNotificationRequest(), createSubscribeNotification Answer(), createUserDataRequest() and createUserDataAnswer(). An instance of a class implementing this interface can be obtained by calling the DiameterStack.getShDiameterMessageFactory() method.Messages created by this factory are:

- Profile-Update-Request (PUR)

      DiameterMessage
      createProfileUpdateRequest(String destinationRealm,
        String userIdentity,
        String userData)

- Profile-Update-Answer (PUA)

      DiameterMessage
      createProfileUpdateAnswer(String resultCode)

- Push-Notification-Request (PNR)

      DiameterMessage
      createPushNotificationRequest(String destinationRealm,
        String destinationHost,
        String userIdentity,
        String userData)

- Push-Notification-Answer (PNA)

      DiameterMessage
        createPushNotificationAnswer(String resultCode)

- Subscribe-Notification-Request (SNR)

      DiameterMessage
        createSubscribeNotificationRequest(String destinationRealm,
        String userIdentity,
        String dataReference,
        String subsReqType)

      DiameterMessage
        createSubscribeNotificationRequest(String destinationRealm,
        String userIdentity,
        String dataReference,
        String subsReqType,
        String serviceIndication,
        String serverName)

- Subscribe-Notification-Answer (SNA)

      DiameterMessage
        createSubscribeNotificationAnswer(String resultCode)

- User-Data-Request (UDR)

      DiameterMessage
        createUserDataRequest(String destinationRealm,
        String userIdentity,
        String userIdentityType,
        String dataReference)

      DiameterMessage
        createUserDataRequest(String destinationRealm,
        String userIdentity,
        String userIdentityType,
        String dataReference,
        String requestedDomain,
        String currentLocation,
        String serviceIndication,
        String serverName,
        String destinationHost)

- User-Data-Answer (UDA)

      DiameterMessage
        createUserDataAnswer(String resultCode, String userData)

### 3GPP/Sh Dictionary

The 3GPP Sh Interface dictionary is returned by getShDictionary() and must be extended by the Diameter stack.

### Sh Events

Like any Diameter application, an Sh application can receive/send events from/to the Diameter stack.To receive an event from the Diameter application, user has to implement the processEvent(DiameterEvent) callback in the DiameterShListener implementation.

### Sh Application Options

These options specify the features handled by the accounting Application. This is a list of Properties (see java.util.properties) which may contain a number of options. Here is the list of the Sh application configurable options which can be set depending on the implemented FSM:The different value of options are:

- AUTO_SESSION_DELETION

- SESSION_DELETED_EVENT

- AUTO_SESSION_TERMINATION_REQUEST

- AUTO_SESSION_ABORT_ANSWERAUTO_SESSION_TERMINATION_ANSWER

- SESSION_TIMEOUT_EVENT

- AUTH_AUTHORIZATION_LIFETIME_EXPIRED_EVENT

- AUTH_GRACE_PERIOD_EXPIRED_EVENT

- LISTENER_SEND_HOOK

## Diameter Application Example

This section presents an example of an accounting call flow and describes in detail the steps that are performed by a typical Accounting Diameter application to represent it. The aim is to show how to use the Rf Java API to exchange accounting information between the Accounting Client and the Accounting Server.

### Accounting Call Flow

The following figure shows the transactions that are required on the Diameter offline interface in order to perform event based charging. It's an example of a call flow between an Accounting Client and an Accounting Server.

Figure A-3 Accounting Call Flow Example

Description of "Figure A-3 Accounting Call Flow Example"

The network element (acting as client) sends an Accounting-Request (ACR) with Accounting-Record-Type AVP set to EVENT_RECORD to indicate service specific information to the CDF (acting as server).The server processes the received Accounting-Request and returns an Accounting-Answer (ACA) message with Accounting-Record-Type AVP set to EVENT_RECORD to the client.The following section describes all the steps that must be performed to create a Rf client/server Diameter Application. The steps where the side (client or server) is not specified are common to both sides.

Several steps are required to initialize the Diameter stack before messages can be exchanged. These steps are the following ones:

- Create a DiameterStack instance

- Register the Rf Diameter application to the created Diameter stack

- Create listening points to bind to local transport addresses (optional / server side)

- Configure routes and connect to Diameter peers (optional / client side)

#### Application initialization

An instance of the Diameter stack can be created as follows:

Figure A-4 Oracle Diameter Stack Creation

Description of "Figure A-4 Oracle Diameter Stack Creation"

1. Get an instance of the DiameterFactory class myFactory using the following method: DiameterFactory.getInstance().

2. Create myStack, an instance of the DiameterStack class, using the following method: myFactory.createDiameterStack().

##### Rf Diameter Application

Once the Diameter stack is defined, the current accounting application objects may be instantiated. An Accounting Diameter application is represented by instances of the two following interfaces: DiameterRfProvider and DiameterRfListener. The former represents the Accounting Diameter application for use by the higher-level user code; the latter represents the Accounting Diameter application for use by the Diameter stack. The DiameterRfProvider interface is used by the higher-level user code to send accounting messages (Accounting Request(ACR) and accounting Answer(ACA)) and control the application behavior. All the call back methods defined in the DiameterRfListener interface are used by the Diameter stack to deliver these accounting messages and some events to the user code.

The Rf provider is created as follows:

Figure A-5 Rf Provider Creation

Description of "Figure A-5 Rf Provider Creation"

3. Create my Rf Provider, an instance of DiameterRfProvider, using the following method: myStack.createDiameterRfProvider(). The instantiation is done with the application name matching the one configured in the xml dictionary, and attach it to a listener so that it receives all incoming messages. Among the parameters passed during the provider creation, properties is a set of accounting options previously defined at the section [3.2.6] and refFSM is the reference to the FSM to execute.

   The 3GPP Rf Interface dictionary is returned by getRfDictionary() and must be extended by the Diameter stack.

   For increased flexibility in a real accounting application, we can extend the dictionary with application specific AVP and command codes. The using method is myStack.extendGrammar(myDictionnary).The Rf Listener is created and registered as follows:

   Figure A-6 Rf Listener Creation and Registration

   Description of "Figure A-6 Rf Listener Creation and Registration"

4. DiameterRfListenerImpl is an implementation of DiameterRfListener interface and may be implemented by the application programmer. myRfListener is an instance of DiameterRfListenerImpl.

5. Attach myRfProvider to the created listener myRfListener using the following method: setDiameterRfListener().

##### Transport configuration

The Accounting Application has to create one or several instances of the DiameterListeningPoint interface to listen for incoming connections on one or several transport addresses. As soon as the listening point has been created, the Diameter stack is ready to accept incoming connection from remote peers which can be declared by using the createDiameterRoute() method.

Figure A-7 Routes and Listening Points Creation

Description of "Figure A-7 Routes and Listening Points Creation"

6. Create a listening Point from a LocalURI, an instance of DiameterListeningPoint, using the following method: myStack.createDiameterListeningPoint()

7. Create a route configuration using the following method: myStack.createDiameterRoute() but it's not mandatory for server process, if the isUnknownPeerAuthorized() callback is implemented in the listener. This call back is called if the Diameter stack receives a connection request from a peer that has not been declared in the routing table. The connection is accepted only if this method returns true.

#### Accounting Diameter message exchange

Once the initialization and configuration phase is over, the Accounting Diameter application is able to send and receive Diameter accounting messages (ACR/ACA).

##### Accounting-Request (ACR)

The Accounting Request is created as follows:

Figure A-8 ACR Creation

Description of "Figure A-8 ACR Creation"

8. Get an instance of the DiameterRfMessageFactory class myDiameterRfMessageFactory using the following method: getDiameterRfMessageFactory() for the client side.

9. Create an Accounting Request for the client side, an instance of the DiameterMessage class, using the following method: createAccountingRequest().

   All incoming messages are delivered to the user accounting application through the DiameterRfListener interface. When accounting messages (ACR/ACA) are received by the client or server side, the corresponding call-back implemented by the programmer is called. For example, if an accounting Request (ACR) is received, the accountingRequestReceived() call-back is called. In all the other cases, the received messages are delivered through the myRfListener.processEvent() implemented by the accounting application programmer.

   Figure A-9 ACR Reception

   Description of "Figure A-9 ACR Reception"

10. Create a client diameter session, an instance of DiameterSession, by using the method: createClientDiameterAcctSession().

11. Send the created Accounting-Request (ACR) myACR to the server side by using the method: sendMessage().

12. Process an incoming Accounting-Request (ACR) message contained in the received event by using the following method: accountingRequestReceived(event). Create a server session from the received request. This session, on server side, can be deleted just after sending the answer.

##### Accounting-Answer (ACA)

The Accounting Answer is created as follows:

Figure A-10 Creating the Corresponding ACA

Description of "Figure A-10 Creating the Corresponding ACA"

13. Get an instance of the DiameterRfMessageFactory class myDiameterRfMessageFactory by using the method: getDiameterRfMessageFactory() on the server side.

14. Create an Accounting Answer for the server side, an instance of the DiameterMessage class, by using the method: createAccountingAnswer().

    All incoming messages are delivered to the user accounting application through the DiameterRfListener interface.

    Figure A-11 ACA Reception

    Description of "Figure A-11 ACA Reception"

15. Send the created Accounting-Answer myACA to the client side.

16. Process the incoming Accounting-Answer (ACA) message contained in the received event by using the method: accountingAnswerReceived(event).

#### Cleaning

In the last step, a global cleaning of all created routes, providers and listening points is done.

Figure A-12 Cleaning Up of Routes, Providers, and Listening Points

Description of "Figure A-12 Cleaning Up of Routes, Providers, and Listening Points"

17. Cleaning:

    - Delete all the created listening points by using the method: myStack.deleteDiameterListeningPoint(listeningPoint)

    - Delete the created provider by using myStack.deleteDiameterRfProvider(myRfProvider).

    - Delete all the created routes by using myStack.deleteDiameterRoute(route).