org.jainslee.resources.diameter.ro (Diameter Resource Adaptor Types)

The Diameter Ro Resource Adaptor type is based on RFC 4006 and 3GPP specifications of Ro interface defined in:

The RoProviderFactory provider factory interface provides methods to obtain a appropriate version of provider interface.

SBBs can obtain a RoProviderFactory instance via JNDI after specifying an appropriate <resource-adaptor-entity-binding> entry in the SBB deployment descriptor.

Following provider interfaces provide methods to obtain a factory class to create Diameter Credit Control AVPs and Diameter messages.

For Ro version 7.9.0. org.jainslee.resources.diameter.ro.v790.RoProvider

For Ro version 8.2.0. org.jainslee.resources.diameter.ro.v820.RoProvider

For Ro version 8.13.0. org.jainslee.resources.diameter.ro.v8d0.RoProvider

For Ro version 9.6.0. org.jainslee.resources.diameter.ro.v960.RoProvider

For Ro version 10.0.0. org.jainslee.resources.diameter.ro.va00.RoProvider

For Ro version 11.8.0. org.jainslee.resources.diameter.ro.vb80.RoProvider

For Ro version 12.11.0. org.jainslee.resources.diameter.ro.vcb0.RoProvider

SBBs can obtain instance of one of provider interfaces calling one of methods: getRoPoviderV790() getRoPoviderV820() getRoPoviderV8d0() getRoPoviderV960() getRoPoviderVa00() getRoPoviderVb80() getRoPoviderVcb0() These methods return either instance of RoProvider if resource adaptor entity is configured to support corresponding 3GPP version or null if resource adaptor entity is not configured to support such 3GPP version.

Client Functionality -- Sending Diameter Credit Control requests

Asynchronous Requests

Examples below are applicable to RoProvider for all supported 3GPP versions. The SBB developer has to use only packages corresponding to required 3GPP version as listed below:

For 3GPP 7.9.0 : org.jainslee.resources.diameter.ro.v790 and org.jainslee.resources.diameter.ro.types.v790

For 3GPP 8.2.0 : org.jainslee.resources.diameter.ro.v820 and org.jainslee.resources.diameter.ro.types.v820

For 3GPP 8.13.0 : org.jainslee.resources.diameter.ro.v8d0 and org.jainslee.resources.diameter.ro.types.v8d0

For 3GPP 9.6.0 : org.jainslee.resources.diameter.ro.v960 and org.jainslee.resources.diameter.ro.types.v960

For 3GPP 10.0.0 : org.jainslee.resources.diameter.ro.va00 and org.jainslee.resources.diameter.ro.types.va00

For 3GPP 11.8.0 : org.jainslee.resources.diameter.ro.vb80 and org.jainslee.resources.diameter.ro.types.vb80

For 3GPP 12.11.0 : org.jainslee.resources.diameter.ro.vcb0 and org.jainslee.resources.diameter.ro.types.vcb0

The RoProvider interface provides a method to create a RoClientSessionActivity on which asynchronous Diameter requests can then be sent.

Diameter credit control activities are created using the createClientSessionActivity() method or the createRoClientSessionActivity(DiameterIdentity, DiameterIdentity) method. The RoClientSessionActivity returned can be used to send asynchronous requests. When answers are received by the Diameter stack, CreditControlAnswer events are fired on the activity.

Synchronous Requests

Note: The synchronous API should only be used for simple test services that are not expected to run at high loads. The resource adaptor does not currently implement timeouts for synchronous requests, so SBBs may block indefinitely. Services that use the synchronous model also do not scale well.

The RoProvider interface also has methods which will send a Diameter request then block until the answer is received. A CreditControlAnswer instance will be the return value of the method call. See the RoProvider class for details.

Example

The following code fragment demonstrates an initial Credit Control Request being created and sent. The diameterRoProvider variable contains the RA SBB provider interface retrieved from JNDI. (Note: the utility methods used to create grouped AVPs are not shown.)

            RoMessageFactory messageFactory = diameterRoProvider.getRoMessageFactory();

            CreditControlRequest ccr = messageFactory.createRoCreditControlRequest();

            ccr.setDestinationRealm(new DiameterIdentity("opencloud"));
            ccr.setSubscriptionId(createSubscriptionId(messageFactory, subscriptionAddress));
            ccr.setMultipleServicesCreditControl(createMsccRequested(messageFactory,1));

            ServiceInformation serviceInformation = messageFactory.createServiceInformation();
            serviceInformation.setMmsInformation(createMmsInformation(messageFactory));
            ccr.setServiceInformation(serviceInformation);
                
            RoClientSessionActivity roActivity = diameterRoProvider.createRoClientSessionActivity();
            ActivityContextInterface diameterACI = diameterRoACIFactory.getActivityContextInterface(roActivity);
            diameterACI.attach(getSbbLocalObject());
        
            roActivity.sendInitialCreditControlRequest(ccr);

Client Functionality -- Receiving Diameter Credit Control Answers

The following code fragment demonstrates a Credit Control Answer being received by an SBB.

        public void onCreditControlAnswer(CreditControlAnswer cca, ActivityContextInterface aci) {

            switch ((int) cca.getResultCode()) {

                case DiameterCcaResultCode.DIAMETER_CREDIT_CONTROL_NOT_APPLICABLE:

                    // ... do behaviour required for billing not applicable ...

                    break;

                case DiameterResultCode.DIAMETER_AUTHORIZATION_REJECTED:  // insufficient credit

                    // ... do behaviour required for insufficient credit ...

                    break;

                case DiameterResultCode.DIAMETER_SUCCESS:
                    MultipleServicesCreditControl[] mscc = cca.getMultipleServicesCreditControls();

                    GrantedServiceUnit gsu = mscc[0].getGrantedServiceUnit();
            
                    final long ccTime = gsu.getCcTime();

                    // invalid response
                    if (ccTime == 0) {
                        // ... handle error: illegal Diameter CCA Answer (GSU CC Time = 0)
                    }

                    break;
                default:
                    // ... handle error: illegal Diameter CCA Answer, unknown result code
            }
        }

Server Functionality -- Receiving Diameter Ro Credit Control Requests

The following code fragment demonstrates a Credit Control Request being received by an SBB, and an answer being sent using the same activity.

        public void onCreditControlRequestInitial(CreditControlRequest event, ActivityContextInterface aci) {
            // do logic for CCR-Initial

            RoServerSessionActivity activity = (RoServerSessionActivity) aci.getActivity();
            CreditControlAnswer cca = activity.createCreditControlAnswer();
            cca.setResultCode(DiameterResultCode.DIAMETER_SUCCESS);
            cca.setCcRequestType(CcRequestType.INITIAL_REQUEST);
            try {
                activity.sendCreditControlAnswer(cca);
            }
            catch (SendException e) {
                // ... handle error: SendException sending answer
            }
        }

        public void onCreditControlRequestUpdate(CreditControlRequest event, ActivityContextInterface aci) {
            // do logic for CCR-Update

            RoServerSessionActivity activity = (RoServerSessionActivity) aci.getActivity();
            CreditControlAnswer cca = activity.createCreditControlAnswer();
            cca.setResultCode(DiameterResultCode.DIAMETER_SUCCESS);
            cca.setCcRequestType(CcRequestType.UPDATE_REQUEST);
            try {
                activity.sendCreditControlAnswer(cca);
            }
            catch (SendException e) {
                // ... handle error: SendException sending answer
            }
        }

        public void onCreditControlRequestTermination(CreditControlRequest event, ActivityContextInterface aci) {
            // do logic for CCR-Termination

            RoServerSessionActivity activity = (RoServerSessionActivity) aci.getActivity();
            CreditControlAnswer cca = activity.createCreditControlAnswer();
            cca.setResultCode(DiameterResultCode.DIAMETER_SUCCESS);
            cca.setCcRequestType(CcRequestType.TERMINATION_REQUEST);
            try {
                activity.sendCreditControlAnswer(cca);
            }
            catch (SendException e) {
                // ... handle error: SendException sending answer
            }
        }