JBoss.orgCommunity Documentation

Mobicents JAIN SLEE USSD Gateway Application 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 USSD Gateway Application, or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier: USSDGateway_Application_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.

USSD stands for Unstructured Supplementary Service Data what is a capability of GSM mobile phone much like the Short Message Service (SMS). But there is a difference between USSD and SMS handling.

SMS uses store and forward method of message delivery. Short Message is delivered first to Sender's Short Message Service Center (SMSc) which will try to deliver the message to recipient. So SMS does not guarantee that message will be delivered instantly.

USSD information is sent from mobile handset directly to application platform handling service. So USSD suppose to establish a real time session between mobile handset and application handling the service. The concept of real time session is very useful for constructing an interactive menu driven application.

A user who is dialing USSD service number initiates dialog with USSD handling application deployed on the Mobicents Platform as depicted on the figure below. The "Network Node" depicted could be MSC, HLR or VLR. The Mobicents Platform integrates with "Network Node" using MAP protocol.

General interworking diagram

The detailed description of the allowed MMIs or phone number which user can dial is presented in 3GPP TS 22.090. In the user's home network the following number range is defined for USSD services: 1, 2 or 3 digits from the set (*, #) followed by 1X(Y), where X=any number 0-4, Y=any number 0-9, then, optionally "*" followed by any number of any characters, and concluding with # SEND

For example user can dial *#122# to reach a specific USSD service which is deployed in the home network. The application in its order can reply with menu.

One of the biggest benefits is that this service is always available even when user is currently in roaming.

Below diagram depicts typical MAP message flow for implementing data transfer between "Network Node" and Mobicents platform to implement menu driven application. For more information on mobile- (and network-) initiated USSD operations and the use of MAP USSD services, refer to [3GPPTS 24.090] in the References section.

Message flow

Mobile initiated USSD service starts when user dials USSD string *#122#.

  • The Network sends TCAP Begin message with Component MAP_PROCESS_UNSTRUCTURED_SS_REQUEST to the Mobicents platform. The Mobicents platform invokes USSD application logic .

  • Application request additional information from user (action one or action two) via MAP_UNSTRUCTURED_SS_REQUEST encapsulated in TCAP Continue message. At this time TCAP Dialogue starts.

  • Application receives user's selection of the action.

  • Application performs its logic and sends a response back to the user. At this time application do not want to get additional information from the user and it sends response using MAP_PROCESS_UNSTRUCTURED_SS_REQUEST and terminates TCAP dialogue.

  1. Downloading the source code

    Use SVN to checkout a specific release source, the base URL is http://mobicents.googlecode.com/svn/tags/applications/ussdgateway, then add the specific release version, lets consider 1.0.0.BETA1.

    [usr]$ svn co http://mobicents.googlecode.com/svn/tags/applications/ussdgateway/1.0.0.BETA1 slee-application-ussdgateway-1.0.0.BETA1
  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 binary.

    				    [usr]$ cd slee-application-ussdgateway-1.0.0.BETA1
    				    [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.

Similar process as for Section 2.2.1, “Release Source Code Building”, the only change is the SVN source code URL, which is https://mobicents.googlecode.com/svn/trunk/applications/ussdgateway.

Rule engine (Drools) is configured with USSDGatewayChangeSet.xml file. Its content alters how rule set is loaded and maintained within engine. There are two ways of maintaining rules:

Guvnor is deployed along with USSD Gateway Application. To access it simply go to http://<your server>/drools-guvnor/ . This will bring initial info screen or login screen - depends on configuration.

If you have not configured the security you can directly login without providing any user id or password.

In case Guvnor has not been used(it is a new repository) you will get a message asking if you would you like to install a sample repository? Its upto you to install the sample repository. If you say yes, you would get sample repository which you can refer to have better understanding of Guvnor

Once you log-in follow the bellow steps:

This concludes configuration of Guvnor . Note that this has to be done only once.

Important

To obtain the application's complete source code please refer to Section 2.2, “Mobicents JAIN SLEE USSD Gateway Application Source Code”.

This chapter explains how components perform their tasks. For more detailed explanation of JSLEE related source code and xml descriptors, please refer to simple examples, like sip-wakeup. Also for detailed description of rules source code please refer to Drools documentation

USSD Gateway Application makes use of Drools as rules engine.

Engine is configured with DRL files. DRL file contains set of rules which perform operations on facts passed into engine. USSD Gateway Application DRL file defines rules to match initial USSD string to set of values identifying protocol and address of peer to which messages should be forwarded. Rule file name is USSDGateway.drl. File content looks as follows:



package org.mobicents.ussdgateway.rules
1
import org.mobicents.ussdgateway.rules.Call;
2
rule "USSDGateway1"
    
3
    when
        $c : Call( ussdString == "*123#" )
    then
4
        $c.setSip( true );
        $c.setSipProxy( "192.168.0.101" );
        $c.setSipTo("123");
        $c.setSipPort(5060);
5
end
    
    

1

import of fact POJO

2

definition of rule

3

condition to enter rule clause. It accesses fact property ussdString and matches it against #123* value, if it matches engine jumps to then part

4

rule part which sets defined SIP peer as destination for messages

5

end of USSDGateway1 rule

Rules are fed with facts on which engine performs matching operations(in general). Facts are simple POJO classes. This applications fact looks as follows:



package org.mobicents.ussdgateway.rules;
import java.io.Serializable;
/**
 * Acts as Fact for Rules
 * @author amit bhayani
 *
 */
public class Call implements Serializable {
    //Initial string, its like #123*
    private String ussdString;
    
    private boolean isSip;
    private boolean isHttp;
    private boolean isSmpp;
    
    private String sipProxy;
    private String sipTo;
    private int sipPort;
    
    //to be used with other protocols
    private String genericUrl;
    
    public Call(String ussdString){
        this.ussdString = ussdString;
    }
    public String getUssdString() {
        return ussdString;
    }
    public boolean isSip() {
        return isSip;
    }
    public void setSip(boolean isSip) {
        this.isSip = isSip;
    }
    public boolean isHttp() {
        return isHttp;
    }
    public void setHttp(boolean isHttp) {
        this.isHttp = isHttp;
    }
    public boolean isSmpp() {
        return isSmpp;
    }
    public void setSmpp(boolean isSmpp) {
        this.isSmpp = isSmpp;
    }
    public String getSipProxy() {
        return sipProxy;
    }
    public void setSipProxy(String sipProxy) {
        this.sipProxy = sipProxy;
    }
    public String getSipTo() {
        return sipTo;
    }
    public void setSipTo(String sipTo) {
        this.sipTo = sipTo;
    }
    public int getSipPort() {
        return sipPort;
    }
    public void setSipPort(int sipPort) {
        this.sipPort = sipPort;
    }
    /**
     * @return the genericUrl
     */
    public String getGenericUrl() {
        return genericUrl;
    }
    /**
     * @param genericUrl the genericUrl to set
     */
    public void setGenericUrl(String genericUrl) {
        this.genericUrl = genericUrl;
    }
    
}
    
                

JMX part of USSD Gateway Application is responsible for initiating rules engine and exposing management methods. Single JMX bean is defined with XML descriptor file jboss-beans.xml. Descriptor content looks as follows:



<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:jboss:bean-deployer:2.0 bean-deployer_2_0.xsd"
    xmlns="urn:jboss:bean-deployer:2.0">

    <bean name="RulesService" class="org.mobicents.ussdgateway.rules.RulesService">
        <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(
            name="org.mobicents.ussdgateway:service=RulesService"
            ,exposedInterface=org.mobicents.ussdgateway.rules.RulesServiceMBean.class
            ,registerDirectly=true)
        </annotation>
    </bean>
</deployment>
    
    

JMX interface is defined as follows:



package org.mobicents.ussdgateway.rules;
import javax.naming.NamingException;
/**
 * 
 * @author amit bhayani
 *
 */
public interface RulesServiceMBean  extends org.jboss.system.ServiceMBean {
    
1
    String getJndiName();
    void setJndiName(String jndiName) throws NamingException;
    
    
2
    void startService() throws Exception;
    void stopService() throws Exception;
}
    
    

It defines following:

1

management method. This method controls JNDI name under which rule engine is made available to SLEE Service

2

regular lifecycle methods

Implementation of above interface fulfills defined contracts in following way:

void startService() throws Exception



public void startService() throws Exception {
1
        setupRule();
2
        rebind();
        
        this.logger.info("Started Rules Service");
}
private void setupRule() {
3
        Resource resource = ResourceFactory.newUrlResource(CHANGESET_FILE_PATH);
4
        kagent = KnowledgeAgentFactory.newKnowledgeAgent("UssdGatewayAgent");
        kagent.applyChangeSet(resource);
        ResourceFactory.getResourceChangeNotifierService().start();
        ResourceFactory.getResourceChangeScannerService().start();
}
private void rebind() throws NamingException {
        InitialContext rootCtx = new InitialContext();
        // Get the parent context into which we are to bind
        Name fullName = rootCtx.getNameParser("").parse(jndiName);
        System.out.println("fullName=" + fullName);
        Name parentName = fullName;
        if (fullName.size() > 1)
            parentName = fullName.getPrefix(fullName.size() - 1);
        else
            parentName = new CompositeName();
        Context parentCtx = createContext(rootCtx, parentName);
        Name atomName = fullName.getSuffix(fullName.size() - 1);
        String atom = atomName.get(0);
        NonSerializableFactory.rebind(parentCtx, atom, kagent);
}
private static Context createContext(Context rootContext, Name name)
            throws NamingException {
        Context subctx = rootContext;
        for (int n = 0; n < name.size(); n++) {
            String atom = name.get(n);
            try {
                Object obj = subctx.lookup(atom);
                subctx = (Context) obj;
            } catch (NamingException e) { // No binding exists, create a
                // subcontext
                subctx = subctx.createSubcontext(atom);
            }
        }
        return subctx;
}
            
            

1

load rules into engine

2

bind rule engine to specified JNDI name

3

load ChangeSet as rule resource

4

create rule engine and initiate it

void stopService() throws Exception



    public void stopService() throws Exception {
    
1
        unbind(jndiName);
    }
            
            

1

unbind rule engine from JNDI

void setJndiName(String jndiName) throws NamingException



public void setJndiName(String jndiName) throws NamingException {
    
1
        String oldName = this.jndiName;
        this.jndiName = jndiName;
        
2
        if (getState() == STARTED) {
            unbind(oldName);
            try {
                rebind();
            } catch (Exception e) {
                NamingException ne = new NamingException(
                        "Failed to update jndiName");
                ne.setRootCause(e);
                throw ne;
            }
        }
    }
            
            

1

set property and retain old value

1

rebind rule engine in JNDI in case bean is running

JMX bean loads change set file USSDGatewayChangeSet.xml. This file controls how rules set is loaded and maintained by rule engine. Please refer to Section 2.4, “Rule engine configuration” for details.

Since there is no standard defined for communication between USSD gateway and service providing peers, Mobicents USSD Gateway Application defines its own standard for encoding.

This SLEE library contains all classes required to properly encode and decode messages exchanged between Mobicents USSD Gateway and service providing peers. Library itself is built on top of JAXB framework.

Standard is defined with single XSD file ussd.xsd. This file defines three types of encoded data:

Library classes are plain JAXB POJOs. They are marshalled to XML form in standard way:



import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBElement;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Unmarshaller;
import org.mobicents.ussdgateway.ObjectFactory;
import org.mobicents.ussdgateway.USSDAbort;
import org.mobicents.ussdgateway.USSDRequest;
import org.mobicents.ussdgateway.USSDResponse;
JAXBContext jAXBContext = JAXBContext.newInstance("org.mobicents.ussdgateway");
ObjectFactory objectFactory = new ObjectFactory();
USSDRequest req = this.objectFactory.createUSSDRequest();
req.setInvokeId(1);
req.setUssdCoding(0xFF);
req.setUssdString("#112*");
ByteArrayOutputStream bos = new ByteArrayOutputStream();
JAXBElement<USSDRequest> jxb = this.objectFactory.createRequest(req);
jAXBContext.createMarshaller().marshal(jxb, bos);
String xmlRequest = new String(bos.toByteArray());
Unmarshaller um = this.jAXBContext.createUnmarshaller();
JAXBElement o = (JAXBElement) um
        .unmarshal(new ByteArrayInputStream(xmlRequest));
if (o.getDeclaredType().equals(USSDRequest.class)) {
    //do something
} else if (o.getDeclaredType().equals(USSDResponse.class)) {
    //do something
} else if (o.getDeclaredType().equals(USSDAbort.class)) {
    //do something
}
        

In SLEE components library is referenced as follows:



<library-ref>
    <library-name>library-ussdgateway</library-name>
    <library-vendor>org.mobicents</library-vendor>
    <library-version>2.0</library-version>
</library-ref>
        

Revision History
Revision 1.0Wed June 2 2010Bartosz Baranowski
Creation of the Mobicents JAIN SLEE USSD Gateway Application User Guide.