Oracle® Communication and Mobility Server Developer Guide Release 10.1.3 Part Number B31511-01 |
|
|
View PDF |
This appendix describes the Oracle Diameter Java APIs, in the following sections:
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 users 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 users 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.
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 wraps around the Diameter C++ API.
This section defines the Java API for the Diameter Base Protocol. The Java interfaces and classes described here enable Java developers to build application based on the Diameter base protocol.This Java API was designed to provide several implementations. The next section will define and describe in detail one possible implementation: Rf Diameter Application.
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.
The Diameter Java API is composed of several interfaces:
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.
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 are exchanged.
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.
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.
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.
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.
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.
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
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).
This section describes the Java interface.
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.
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.
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)
Like any Diameter application, an Rf application can receive/send accounting events from/to the Diameter stack.
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 as follows:
DiameterTimeoutEvent(Object, DiameterSession, int): This event is generated by the Diameter implementation when one of the session timers elapses. 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. 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.
To send an accounting event to the Diameter stack, the user must call the accounting application eventRaised(DiameterEvent) method.The only accounting event triggered by the Rf application is DiameterRfOutOfSpaceEvent(Object, int). Events raised 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 the 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.
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:
FSM admits the following option settings:
AUTO_ANSWER
AUTO_DELETION
ENABLE_INVALID_COMMAND
ENABLE_SND_MISSING_AVP
FSM permits the following option settings:
AUTO_ANSWER
AUTO_DELETION
DELETE_ON_TIMEOUT
SUPERVISION_TIMER_DURATION
ENABLE_INVALID_COMMAND
ENABLE_SND_MISSING_AVP
FSM permits the following option settings:
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.
As presented in [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 beginning and end 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 message 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.
Following are the types of FSM which can be implemented in an Rf application.
This FSM responds to [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.
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.
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.
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).
This section details the 3GPP/Ro Diameter Java Interface
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.
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 principle 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.
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 an RAA, specifying only the Result-Code AVP.
Diameter Message
createReAuthAnswer(String resultCode)
The 3GPP Ro Interface dictionary is returned by getRoDictionary() and must be extended by the Diameter stack.
Like any Diameter application, an Ro application can receive/send events from/to the Diameter stack.
To receive an accounting event from the Diameter stack, user must implement the processEvent(DiameterEvent) callback in the DiameterRoListener implementation.The list of the possible received accounting events are as follows:
DiameterTimeoutEvent(Object, DiameterSession, int): This event is generated by the Diameter implementation when one of the session timers elapses. 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. Reasons to trigger an event for the Rf Interface are:
TERMINATE_SERVICE: The event is triggered by the stack when the service is terminated by the stack or by the server.
GRANT_SERVICE: The event is triggered by the stack when the service is granted by server.
BACKUP_SERVICE: The event is triggered by the stack when the Tx2 timer expires and the 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.
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.
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:
FSM permits the following option settings:
AUTO_ANSWER
AUTO_DELETION
SUPERVISION_TIMER_DURATION
DELETE_ON_TIMEOUT
ENABLE_INVALID_COMMAND
ENABLE_SND_MISSING_AVP
As presented in [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 message 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.
Following are the types of FSM which can be implemented in a Ro application.
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 and 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 its first sent message. Once a 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.
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.
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 its 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 credit control request messages 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.
This section defines a Java API for the 3GPP [TS 29.328] and [TS 29.329] Sh Interface over the Diameter protocol.
This section provides information about the 3GPP/Sh Diameter Java Interface.
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.
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.
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)
The 3GPP Sh Interface dictionary is returned by getShDictionary() and must be extended by the Diameter stack.
Like any Diameter application, an Sh application can receive and send events to and from the Diameter stack.To receive an event from the Diameter application, users must implement the processEvent(DiameterEvent) callback in the DiameterShListener implementation.
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. Following is the list of the Sh application configurable options which can be set depending on the implemented FSM:Values for the 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
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.
The following figure shows the transactions that are required on the Diameter offline interface in order to perform event based charging. Following is an example of a call flow between an Accounting Client and an Accounting Server.
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 an 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.
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)
An instance of the Diameter stack can be created as follows:
Figure A-4 Oracle Diameter Stack Creation
Get an instance of the DiameterFactory class myFactory using the following method: DiameterFactory.getInstance().
Create myStack, an instance of the DiameterStack class, using the following method: myFactory.createDiameterStack().
Once the Diameter stack is defined, the current accounting application objects may be instantiated. An Accounting Diameter application is represented by instances of the 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 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:
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 dictionary, and attaching 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.
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, extend the dictionary with application specific AVP and command codes. Use the myStack.extendGrammar(myDictionnary) dictionary.The Rf Listener is created and registered as follows:
Figure A-6 Rf Listener Creation and Registration
DiameterRfListenerImpl is an implementation of DiameterRfListener interface and may be implemented by the application programmer. myRfListener is an instance of DiameterRfListenerImpl.
Attach myRfProvider to the created listener myRfListener using the following method: setDiameterRfListener().
The Accounting Application must 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
Create a listening Point from a LocalURI, an instance of DiameterListeningPoint, using the following method: myStack.createDiameterListeningPoint()
Create a route configuration using the following method: myStack.createDiameterRoute(). This is not mandatory for server processes, if the isUnknownPeerAuthorized() callback is implemented in the listener. This callback 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.
Once the initialization and configuration phase is over, the Accounting Diameter application is able to send and receive Diameter accounting messages (ACR/ACA).
The Accounting Request is created as follows:
Get an instance of the DiameterRfMessageFactory class myDiameterRfMessageFactory using the following method: getDiameterRfMessageFactory() for the client side.
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 callback implemented by the programmer is called. For example, if an accounting Request (ACR) is received, the accountingRequestReceived() callback is called. In all the other cases, the received messages are delivered through the myRfListener.processEvent() implemented by the accounting application programmer.
Create a client diameter session, an instance of DiameterSession, by using the method: createClientDiameterAcctSession().
Send the created Accounting Request (ACR) myACR to the server side by using the method: sendMessage().
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.
The Accounting Answer is created as follows:
Figure A-10 Creating the Corresponding ACA
Get an instance of the DiameterRfMessageFactory class myDiameterRfMessageFactory by using the method: getDiameterRfMessageFactory() on the server side.
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.
Send the created Accounting Answer myACA to the client side.
Process the incoming Accounting Answer (ACA) message contained in the received event by using the method: accountingAnswerReceived(event).
In the last step, a global cleanup of all created routes, providers and listening points is done.
Figure A-12 Cleaning Up of Routes, Providers, and Listening Points
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).