JBoss.orgCommunity Documentation

Mobicents JAIN SLEE Diameter CCA Resource Adaptor User Guide


This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in the the Issue Tracker, against the product Mobicents JAIN SLEE Diameter CCA Resource Adaptor, or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier: JAIN_SLEE_DIAMETER_CCA_RA_User_Guide

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

This resource adaptor provides DIAMETER API for JSLEE applications. CCA is a RFC specification of DIAMETER extension to allow real time credit control of end user services, ie. SIP services, equipment access, network access, ... etc.

Events represent DIAMETER CCA messages received by stack, that is requests and answers with command code equal to 272. Events are fired either on client or server activity.

The activities are custom defined by RA Type to ease use of RA. Activities represent DIAMETER session between two peers. SLEE applications use activities to create,send and receive messages.

Diameter CCA Resource Adaptor Type is defined by Mobicents team as part of effort to standarize RA Types.

Diameter CCA Type 2.7.0.FINAL defines two types of activities:

net.java.slee.resource.diameter.cca.CreditControlClientSession

This type of activity represents client side of credit control session. It is a source of answers to credit control requests issued with this activity. It is also source of re-authentication requests.

This activity type can be created with call to one of methods of CreditControlProvider. It ends once underlying credit control session ends. State machine for client credit control can be found here and here .

net.java.slee.resource.diameter.cca.CreditControlServerSession

This type of activity represents server side of credit control session. It is source of credit control requests issued from client side and answers to re-auth requests.

This activity type is created explicitly for incoming requests by Resource Adaptor. It ends once underlying credit control session ends. State machine for server credit control can be found here and here

Both activities define methods required to properly function and expose necessary information to JSLEE services. Common part for each is defined as follows:




        public CreditControlSessionState getState();
        public String getSessionId();
        public CreditControlAVPFactory getCCAAvpFactory();
        public CreditControlMessageFactory getCCAMessageFactory();
    
    
CreditControlSessionState getState();

returns current state of credit control session. State directly follows definition from credit control rfc .

String getSessionId();

returns session Id of underlying diameter session.

CreditControlAVPFactory getCCAAvpFactory()

returns AVP factory capable of creating specifc AVPs for credit control. It also exposes means of accessing base AVP factory.

CreditControlMessageFactory getCCAMessageFactory();

returns message factory capable of creating credit control messages. It also exposes means of accessing base factory.

Client type activity interface is defined as follows:




       CreditControlRequest createCreditControlRequest();
       void sendCreditControlRequest(CreditControlRequest ccr) throws IOException;
       void sendInitialCreditControlRequest(CreditControlRequest ccr) throws IOException;
       void sendReAuthAnswer(ReAuthAnswer rar) throws IOException;
       void sendUpdateCreditControlRequest(CreditControlRequest ccr) throws IOException;
       void sendTerminationCreditControlRequest(CreditControlRequest ccr) throws IOException;
    
CreditControlRequest createCreditControlRequest();

Creates credit control request for this activity. Fills AVPs appropriate for this session..

void sendCreditControlRequest(CreditControlRequest ccr) throws IOException;

sends credit control request, does not perform any other operations.

void sendInitialCreditControlRequest(CreditControlRequest ccr) throws IOException;

sends credit control request. Ensures that its initial request by setting proper AVP .

void sendUpdateCreditControlRequest(CreditControlRequest ccr) throws IOException;

sends credit control request. Ensures that its update request by setting proper AVP .

void sendTerminationCreditControlRequest(CreditControlRequest ccr) throws IOException;

sends credit control request. Ensures that its termination request by setting proper AVP .

void sendReAuthAnswer(ReAuthAnswer rar) throws IOException;

sends re-authentication answer on this session.

Server type activity interface is defined as follows:



    
      CreditControlAnswer createCreditControlAnswer();
      void sendCreditControlAnswer(CreditControlAnswer cca) throws IOException;
      void sendReAuthRequest(ReAuthRequest rar) throws IOException;
    
    
    
CreditControlAnswer createCreditControlAnswer();

creates credit control answer for last received request.

void sendCreditControlAnswer(CreditControlAnswer cca) throws IOException;

sends credit control answer through this session.

void sendReAuthRequest(ReAuthRequest rar) throws IOException;

sends re-authentication request through this session.

Note

It is safe to type cast activities to interface defined in Base RA Type: net.java.slee.resource.diameter.base.DiameterActivity

Credit Control declares only two additional events, to those defined in Base RA Type, namely CreditControlAnswer and CreditControlRequest. However, it also reuses Base events.




Important

Spaces where introduced in Name and Class column values, to correctly render the table. Please remove them when using copy/paste.

Resource Adaptor SBB Interface provides SBBs with means of accessing RA objects required for interaction in DIAMETER world. It is defined as follows:



    
    package net.java.slee.resource.diameter.cca;
    import net.java.slee.resource.diameter.base.CreateActivityException;
    import net.java.slee.resource.diameter.base.events.avp.DiameterIdentity;
    public interface CreditControlProvider {
      CreditControlClientSession createClientSession() throws CreateActivityException;
      CreditControlClientSession createClientSession(DiameterIdentity destinationHost, 
        DiameterIdentity destinationRealm) throws CreateActivityException;
      CreditControlMessageFactory getCreditControlMessageFactory();
      CreditControlAVPFactory getCreditControlAVPFactory();
      int getPeerCount();
      DiameterIdentity[] getConnectedPeers();
    }
    

Simple client side requesting credits, with EVENT_TYPE credit control request:




private void doSendEventCCR(int currencyCode,int value) {
    try {
        //Create session.
        CreditControlClientSession session = this.provider.createClientSession();
        ActivityContextInterface localACI = this.acif.getActivityContextInterface(session);
        localACI.attach(this.getSbbContext().getSbbLocalObject());
        CreditControlRequest request = session.createCreditControlRequest();
    
        List<DiameterAvp> avps = new ArrayList<DiameterAvp>();
 
        avps.add(avpFactory.getBaseFactory().createAvp(Avp.ORIGIN_HOST, 
            ("aaa://" + originIP + ":" + originPort).getBytes()));
        avps.add(avpFactory.getBaseFactory().createAvp(Avp.ORIGIN_REALM, 
            originRealm.getBytes()));
        //or dedicated:
        //request.setDestinationHost(destinationHost);
        //request.setDestinationRealm(destinationRealm);
        avps.add(avpFactory.getBaseFactory().createAvp(Avp.DESTINATION_HOST, 
            ("aaa://" + destinationIP + ":" + destinationPort).getBytes()));
        avps.add(avpFactory.getBaseFactory().createAvp(Avp.DESTINATION_REALM, 
            destinationRealm.getBytes()));
        //Event Type request has request type set to '4'
        avps.add(avpFactory.getBaseFactory().createAvp(
            CreditControlAVPCodes.CC_Request_Type, 4l));
        avps.add(avpFactory.getBaseFactory().createAvp(
            CreditControlAVPCodes.CC_Request_Number, 0l));
            RequestedServiceUnitAvp rsu = this.avpFactory.createRequestedServiceUnit();
            CcMoneyAvp ccMoney = this.avpFactory.createCcMoney();
        ccMoney.setCurrencyCode(currencyCode);
        UnitValueAvp unitValue = this.avpFactory.createUnitValue();
        unitValue.setValueDigits(value);
        ccMoney.setUnitValue(unitValue);
        
        rsu.setCreditControlMoneyAvp(ccMoney);
            avps.add(rsu);
            avps.add(avpFactory.getBaseFactory().createAvp(
            CreditControlAVPCodes.Requested_Action, 0));
        //use extension avps to fill message or dedicated setters/getters
        request.setExtensionAvps(avps.toArray(new DiameterAvp[avps.size()]));
        // Now create and send
        
        if (logger.isInfoEnabled())
            logger.info("About to send:\n" + request);
            session.sendCreditControlRequest(request);
    } catch (Exception e) {
        logger.error("Failed to create/send Credit-Control-Request.", e);
    }
}
    
    
    ....
    
    public void onCreditControlAnswer(CreditControlAnswer answer, ActivityContextInterface aci) {
        logger.info("Received CCA with Result-Code[" + answer.getResultCode() + "].");
        switch (answer.getCcRequestType().getValue()) {
        case 1:
        case 2:
        case 3:
            logger.error("Received 'session' credit control answer. Expecting EVENT_TYPE answer");
            break;
        case 4:
            //result code 2xxx is success
            if(answer.getResultCode()/1000 == 2 )
            {
                //assume msg is correct
                GrantedServiceUnitAvp gsu = answer.getGrantedServiceUnit();
                CcMoneyAvp money = gsu.getCreditControlMoneyAvp();
                doSpendMoney(money);
            }else
            {
                //error, this will pring formated msg dump.
                logger.warn("Result of CC operation is a failure:\n"+answer);
            }
            break;      
        }
    } 
    

Server application to handle simple direct debiting:



public void onCreditControlRequest(CreditControlRequest request, 
    ActivityContextInterface aci) {
    if (logger.isInfoEnabled())
        logger.info("Received Credit-Control-Request (Application-Id[" + request.getHeader().getApplicationId() + "].");
    // INITIAL_REQUEST(1), UPDATE_REQUEST(2), TERMINATION_REQUEST(3),
    // EVENT_REQUEST(4)
    CreditControlServerSession session = (CreditControlServerSession) aci.getActivity();
    CreditControlAnswer answer = null;
    if(request.getRequestedAction() == RequestedActionType.DIRECT_DEBITING)
    {
    
        switch (request.getCcRequestType().getValue()) {
        case 1:
            try {
                if (logger.isInfoEnabled())
                    logger.info("Got INITIAL_REQUEST(1).");
                if (getSentInitialAnswer()) {
                    logger.error("Error. Initial answer already sent! Aborting.");
                    return;
                }
                
                answer = session.createCreditControlAnswer();
                if(userHasCredit(request.getUserName(),request.getRequestedServiceUnit()))
                {
                    GrantedServiceUnitAvp gsu = chargeUser(request.getRequestedServiceUnit());
                    answer.setGrantedServiceUnit(gsu);
                    answer.setResultCode(2001);
                }else
                {
                    //4012 == CREDIT_LIMIT_REACHED
                    answer.setResultCode(4012);
                }
                if (logger.isInfoEnabled()) {
                    logger.info("Processed Credit-Control-Request:\n" + request);
                    logger.info("Sending Credit-Control-Answer:\n" + answer);
                }
                session.sendCreditControlAnswer(answer);
                this.setSentInitialAnswer(true);
            } catch (Exception e) {
                logger.error("Failed to create/send Credit-Control-Answer to reply INITIAL_REQUEST(1).", e);
            }
            break;
        case 2:
            try {
                if (logger.isInfoEnabled())
                    logger.info("Got UPDATE_REQUEST(2).");
                if (getSentUpdateAnswer()) {
                    logger.error("Error. Update answer already sent! Aborting.");
                    return;
                }
                answer = session.createCreditControlAnswer();
                if(userHasCredit(request.getUserName(),request.getRequestedServiceUnit()))
                {
                    GrantedServiceUnitAvp gsu = chargeUser(request.getRequestedServiceUnit());
                    answer.setGrantedServiceUnit(gsu);
                    answer.setResultCode(2001);
                }else
                {
                    //4012 == CREDIT_LIMIT_REACHED
                    answer.setResultCode(4012);
                }
                if (logger.isInfoEnabled()) {
                    logger.info("Processed Credit-Control-Request:\n" + request);
                    logger.info("Sending Credit-Control-Answer:\n" + answer);
                }
                session.sendCreditControlAnswer(answer);
                setSentUpdateAnswer(true);
            } catch (Exception e) {
                logger.error("Failed to create/send Credit-Control-Answer to reply UPDATE_REQUEST(2).", e);
            }
            break;
        case 3:
            try {
                if (logger.isInfoEnabled())
                    logger.info("Got TERMINATION_REQUEST(3).");
                if (getSentTerminationAnswer()) {
                    logger.error("Error. Termination answer already sent! Aborting.");
                    return;
                }
                answer = session.createCreditControlAnswer();
                if(userHasCredit(request.getUserName(),request.getRequestedServiceUnit()))
                {
                    GrantedServiceUnitAvp gsu = chargeUser(request.getRequestedServiceUnit());
                    answer.setGrantedServiceUnit(gsu);
                    answer.setResultCode(2001);
                }else
                {
                    //4012 == CREDIT_LIMIT_REACHED
                    answer.setResultCode(4012);
                }
                if (logger.isInfoEnabled()) {
                    logger.info("Processed Credit-Control-Request:\n" + request);
                    logger.info("Sending Credit-Control-Answer:\n" + answer);
                }
                session.sendCreditControlAnswer(answer);
                setSentTerminationAnswer(true);
            } catch (Exception e) {
                logger.error("Failed to create/send Credit-Control-Answer to reply TERMINATION_REQUEST(3).", e);
            }
            break;
        case 4:
            try {
                if (logger.isInfoEnabled())
                    logger.info("Got EVENT_REQUEST(4).");
                answer = session.createCreditControlAnswer();
                if(userHasCredit(request.getUserName(),request.getRequestedServiceUnit()))
                {
                    GrantedServiceUnitAvp gsu = chargeUser(request.getRequestedServiceUnit());
                    answer.setGrantedServiceUnit(gsu);
                    answer.setResultCode(2001);
                }else
                {
                    //4012 == CREDIT_LIMIT_REACHED
                    answer.setResultCode(4012);
                }
                if (logger.isInfoEnabled())
                    logger.info("Sending Credit-Control-Answer:\n" + answer);
                session.sendCreditControlAnswer(answer);
            } catch (Exception e) {
                logger.error("Failed to create/send Credit-Control-Answer to reply EVENT_REQUEST(4).", e);
            }
            break;
        default:
            logger.error("Unexpected CC-Request-Type in message: " + request.getCcRequestType() + ". Aborting...");
        }
        }else
        {
            answer = session.createCreditControlAnswer();
            //4011 == DIAMETER_CREDIT_CONTROL_NOT_APPLICABLE
            answer.setResultCode(4011);
            session.sendCreditControlAnswer(answer);
        }
    }
    

This RA uses the Mobicents diameter stack to provide service. The stack is the result of the work done by Mobicents JAIN SLEE and Diameter development teams.

There is a single Resource Adaptor Entity created when deploying the Resource Adaptor, named DiameterCCA. The DiameterCCA entity uses the default Resource Adaptor configuration, specified in Section 3.1, “Configuration”.

The DiameterCCA entity is also bound to Resource Adaptor Link Name DiameterCCA, to use it in an Sbb add the following XML to its descriptor:



    
    <resource-adaptor-type-binding>
            <resource-adaptor-type-ref>
                <resource-adaptor-type-name>DiameterCCA</resource-adaptor-type-name>
                <resource-adaptor-type-vendor>java.net</resource-adaptor-type-vendor>
                <resource-adaptor-type-version>0.8.1</resource-adaptor-type-version>
            </resource-adaptor-type-ref>
            <activity-context-interface-factory-name>
                slee/resources/CCAResourceAdaptor/java.net/0.8.1/acif
            </activity-context-interface-factory-name>

            <resource-adaptor-entity-binding>
                <resource-adaptor-object-name>
                    slee/resources/diameter-cca-ra-interface
                </resource-adaptor-object-name>
                <resource-adaptor-entity-link>DiameterCCA
                </resource-adaptor-entity-link>
            </resource-adaptor-entity-binding>
    </resource-adaptor-type-binding>
    
    
    

  1. Downloading the source code

    Use SVN to checkout a specific release source, the base URL is http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/resources/diameter-cca, then add the specific release version, lets consider 2.7.0.FINAL.

    [usr]$ svn co http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/resources/diameter-cca/2.7.0.FINAL diameter-cca-2.7.0.FINAL
  2. Building the source code

    Important

    Maven 2.0.9 (or higher) is used to build the release. Instructions for using Maven2, including install, can be found at http://maven.apache.org

    Use Maven to build the deployable unit binary.

    				    [usr]$ cd diameter-cca-2.7.0.FINAL
    				    [usr]$ mvn install
    				    

    Once the process finishes you should have the deployable-unit jar file in the target directory, if Mobicents JAIN SLEE is installed and environment variable JBOSS_HOME is pointing to its underlying JBoss Application Server directory, then the deployable unit jar will also be deployed in the container.

Note

Diameter CCA depends on Base RA and MUX, please refer to separate documentation for proper setup.

Similar process as for Section 4.2.1, “Release Source Code Building”, the only change is the SVN source code URL, which is http://mobicents.googlecode.com/svn/trunk/servers/jain-slee/resources/diameter-cca.

Revision History
Revision 1.0Tue Feb 3 2010Bartosz Baranowski
Creation of the Mobicents JAIN SLEE Diameter CCA RA User Guide.