JBoss.orgCommunity Documentation

JBoss Communications MAP Stack User Guide

by Amit Bhayani, Bartosz Baranowski, and Oleg Kulikov

Abstract

This User Guide introduces SS7 MAP Stack.


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 JBoss Communications MAP Stack , or contact the authors.

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

Important

For better understanding of this chapter please read GSM 09.02.

Mobile application part ( MAP ) is the protocol which is used to allow the GSM network nodes within the Network Switching Subsystem ( NSS ) to communicate with each other to provide services, such as roaming capability, text messaging ( SMS ), Unstructured Supplementary Service Data ( USSD ) and subscriber authentication. MAP provides an application layer on which to build the services that support a GSM network. This application layer provides a standardized set of services. MAP uses the services of the SS7 network, specifically the Signaling Connection Control Part ( SCCP ) and the Transaction Capabilities Application Part ( TCAP )

MAP provides a number of services, which can be classified as

  • Mobility services

  • Location management services

  • Paging and search

  • Access management

  • Handover services

  • Authentication management

  • Security management

  • International mobile equipment identities management

  • Subscriber management

  • Identity management

  • Fault recovery

  • Subscriber information

  • Operation and maintenance

  • Subscriber tracing

  • Other operation and maintenance

  • Call handling

  • Supplementary services–related services

  • Short Message Service (SMS) management

  • Network-requested Packet Data Protocol (PDP) context activation

  • Location service management

The JBoss Communications implementation of MAP is only capable of Supplementary services–related services related to USSD as of today.

Within each of these service classifications, a number of messages are used to communicate between the various network entities as defined by each of the message sets. Within each message set is a predefined set of parameters. These parameters may be optional or mandatory, as defined by the standards.

  1. Downloading the source code

    Use SVN to checkout a specific release source, the base URL is ?, then add the specific release version, lets consider 1.0.0.BETA2.

    [usr]$ svn co ?/1.0.0.BETA2 isup-1.0.0.BETA2
  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 binaries.

    				    [usr]$ cd isup-1.0.0.BETA2
    				    [usr]$ mvn install
    				    

    Once the process finishes you should have the binary jar files in the target directory of module.

JBoss Communications MAP Stack MAP builds abstraction layer over protocol definition. The MAP API is totally defined by Mobicents Media Server Team.

All interactions are handled by MAP Dialog. MAP Dialog doesn't maintain any FSM and is on top of TCAP Dialog. MAP uses the terms of ITU-T TCAP: a Begin message (with one invoke) initiates the transaction, and an End message (with a return-result or return-error) ends the transaction. It is defined by following interface:




package org.mobicents.protocols.ss7.map.api;
import org.mobicents.protocols.ss7.map.api.dialog.AddressString;
import org.mobicents.protocols.ss7.map.api.dialog.MAPUserAbortChoice;
import org.mobicents.protocols.ss7.map.api.service.supplementary.ProcessUnstructuredSSIndication;
import org.mobicents.protocols.ss7.map.api.service.supplementary.USSDString;
public interface MAPDialog {
    /**
     * Returns this Dialog's ID. Thiis ID is actually TCAP's Dialog ID.
     * {@link org.mobicents.protocols.ss7.tcap.api.tc.dialog.Dialog}
     * 
     * @return
     */
    public Long getDialogId();
    /**
     * This is equivalent of MAP User issuing the MAP_DELIMITER Service Request.
     * send() is called to explicitly request the transfer of the MAP protocol
     * data units to the peer entities.
     */
    public void send() throws MAPException;
    /**
     * This is equivalent of MAP User issuing the MAP_CLOSE Service Request.
     * This service is used for releasing a previously established MAP dialogue.
     * The service may be invoked by either MAP service-user depending on rules
     * defined within the service-user.
     * 
     * <br/>
     * 
     * If prearrangedEnd is false, all the Service Primitive added to MAPDialog
     * and not sent yet, will be sent to peer.
     * 
     * <br/>
     * 
     * If prearrangedEnd is true, all the Service Primitive added to MAPDialog
     * and not sent yet, will not be sent to peer.
     * 
     * @param prearrangedEnd
     */
    public void close(boolean prearrangedEnd) throws MAPException;
    /**
     * This is equivalent to MAP User issuing the MAP_U_ABORT Service Request.
     * 
     * @param userReason
     */
    public void abort(MAPUserAbortChoice mapUserAbortChoice)
            throws MAPException;
    /**
     * Add's a new Process Unstructured SS Request as Component.
     * 
     * @param ussdDataCodingScheme
     *            The Data Coding Scheme for this USSD String as defined in GSM
     *            03.38
     * @param ussdString
     *            Ussd String
     * @param msisdn
     *            The MSISDN in {@link AddressString} format. This is optional
     * @throws MAPException
     */
    public void addProcessUnstructuredSSRequest(byte ussdDataCodingScheme,
            USSDString ussdString, AddressString msisdn) throws MAPException;
    /**
     * Add's a new ProcessUnstructured SS Response as Component.
     * 
     * @param invokeId
     *            The original invoke ID retrieved from
     *            {@link ProcessUnstructuredSSIndication}
     * @param lastResult
     *            Specify if this Result is last - true, or there would be
     *            follow-up results - false
     * @param ussdDataCodingScheme
     *            The Data Coding Scheme for this USSD String as defined in GSM
     *            03.38
     * @param ussdString
     *            Ussd String {@link USSDString}
     * @throws MAPException
     */
    public void addProcessUnstructuredSSResponse(long invokeId,
            boolean lastResult, byte ussdDataCodingScheme, USSDString ussdString)
            throws MAPException;
    /**
     * Add's a new Unstructured SS Request
     * 
     * @param ussdDataCodingScheme
     *            The Data Coding Scheme for this USSD String as defined in GSM
     *            03.38
     * @param ussdString
     *            Ussd String {@link USSDString}
     * @throws MAPException
     */
    public void addUnstructuredSSRequest(byte ussdDataCodingScheme,
            USSDString ussdString) throws MAPException;
    /**
     * Add's a new Unstructured SS Response
     * 
     * @param invokeId
     *            The original invoke ID retrieved from
     *            {@link UnstructuredSSIndication}
     * @param lastResult
     *            Specify if this Result is last - true, or there would be
     *            follow-up results - false
     * @param ussdDataCodingScheme
     *            The Data Coding Scheme for this USSD String as defined in GSM
     *            03.38
     * @param ussdString
     *            Ussd String {@link USSDString}
     * @throws MAPException
     */
    public void addUnstructuredSSResponse(long invokeId, boolean lastResult,
            byte ussdDataCodingScheme, USSDString ussdString)
            throws MAPException;
}
            

Common MAP Services are represented by bellow interfaces

Supplementary services–related service messages for USSD are represented by following interfaces

All the MAP Service messages implements the MAPMessage Interface.




package org.mobicents.protocols.ss7.map.api;
public interface MAPMessage {
    public long getInvokeId();
    public void setInvokeId(long invokeId);
    public MAPDialog getMAPDialog();
    public void setMAPDialog(MAPDialog mapDialog);
    
}
            

All service message specific to USSD implements the USSDService Interface which it-self extends MAPMessage interface




package org.mobicents.protocols.ss7.map.api.service.supplementary;
import org.mobicents.protocols.ss7.map.api.MAPMessage;
public interface USSDService extends MAPMessage {
    /**
     * This parameter contains the information of the alphabet and the language
     * used for the unstructured information in an Unstructured Supplementary
     * Service Data operation. The coding of this parameter is according to the
     * Cell Broadcast Data Coding Scheme as specified in GSM 03.38.
     * 
     * @return
     */
    public byte getUSSDDataCodingScheme();
    /**
     * 
     * @param ussdDataCodingSch
     */
    public void setUSSDDataCodingScheme(byte ussdDataCodingSch);
    /**
     * <p>
     * This parameter contains a string of unstructured information in an
     * Unstructured Supplementary Service Data operation. The string is sent
     * either by the mobile user or the network. The contents of a string sent
     * by the MS are interpreted by the network as specified in GSM 02.90.
     * </p>
     * <br/>
     * <p>
     * USSD String is OCTET STRING (SIZE (1..160))
     * </p>
     * 
     * <br/>
     * 
     * <p>
     * The structure of the contents of the USSD-String is dependent -- on the
     * USSD-DataCodingScheme as described in TS GSM 03.38.
     * </p>
     * 
     * 
     * 
     * @return
     */
    public USSDString getUSSDString();
    /**
     * 
     * @param ussdString
     */
    public void setUSSDString(USSDString ussdString);
}
            

MAP is part of SS7 protocol stack. AS such it relies on TCAP which in-turn relies on SCCP as means of transport. To create MAP stack you require properly configured SCCP layer. Please refer to ??? for details and examples.

JBoss Communications MAP is defined by provider and stack interfaces. Interfaces are defined as follows:



package org.mobicents.protocols.ss7.map.api;
public interface MAPStack {
    
    public MAPProvider getMAPProvider();
    
}
                
            

package org.mobicents.protocols.ss7.map.api;
import org.mobicents.protocols.ss7.map.api.dialog.AddressString;
import org.mobicents.protocols.ss7.sccp.parameter.SccpAddress;
public interface MAPProvider {
    public static final int NETWORK_UNSTRUCTURED_SS_CONTEXT_V2 = 1;
    /**
     * Creates a new Dialog. This is equivalent to issuing MAP_OPEN Service
     * Request to MAP Provider.
     * 
     * @param applicationCntx
     *            This parameter identifies the type of application context
     *            being established. If the dialogue is accepted the received
     *            application context name shall be echoed. In case of refusal
     *            of dialogue this parameter shall indicate the highest version
     *            supported.
     * 
     * @param destAddress
     *            A valid SCCP address identifying the destination peer entity.
     *            As an implementation option, this parameter may also, in the
     *            indication, be implicitly associated with the service access
     *            point at which the primitive is issued.
     * 
     * @param destReference
     *            This parameter is a reference which refines the identification
     *            of the called process. It may be identical to Destination
     *            address but its value is to be carried at MAP level.
     * 
     * @param origAddress
     *            A valid SCCP address identifying the requestor of a MAP
     *            dialogue. As an implementation option, this parameter may
     *            also, in the request, be implicitly associated with the
     *            service access point at which the primitive is issued.
     * 
     * @param origReference
     *            This parameter is a reference which refines the identification
     *            of the calling process. It may be identical to the Originating
     *            address but its value is to be carried at MAP level.
     *            Processing of the Originating-reference shall be performed
     *            according to the supplementary service descriptions and other
     *            service descriptions, e.g. operator determined barring.
     * @return
     */
    public MAPDialog createNewDialog(MAPApplicationContext appCntx,
            SccpAddress origAddress, AddressString origReference,
            SccpAddress destAddress, AddressString destReference)
            throws MAPException;
    /**
     * Add MAP Dialog listener to the Stack
     * 
     * @param mapDialogListener
     */
    public void addMAPDialogListener(MAPDialogListener mapDialogListener);
    /**
     * Remove MAP DIalog Listener from the stack
     * 
     * @param mapDialogListener
     */
    public void removeMAPDialogListener(MAPDialogListener mapDialogListener);
    /**
     * Add MAP Service listener to the stack
     * 
     * @param mapServiceListener
     */
    public void addMAPServiceListener(MAPServiceListener mapServiceListener);
    /**
     * Remove MAP Service listener from the stack
     * 
     * @param mapServiceListener
     */
    public void removeMAPServiceListener(MAPServiceListener mapServiceListener);
    /**
     * Get the {@link MapServiceFactory}
     * 
     * @return
     */
    public MapServiceFactory getMapServiceFactory();
    /**
     * Get {@link MAPDialog} corresponding to passed dialogId
     * 
     * @param dialogId
     * @return
     */
    public MAPDialog getMAPDialog(Long dialogId);
}
                

Provider allows user to access stack facitlities, create dialogs, register as listener for incoming common service messages and register as listener for incoming USSD service messages. Listener's declares set of callbacks methods. They are defined as follows:

    

package org.mobicents.protocols.ss7.map.api;
import org.mobicents.protocols.ss7.map.api.dialog.MAPAcceptInfo;
import org.mobicents.protocols.ss7.map.api.dialog.MAPCloseInfo;
import org.mobicents.protocols.ss7.map.api.dialog.MAPOpenInfo;
import org.mobicents.protocols.ss7.map.api.dialog.MAPProviderAbortInfo;
import org.mobicents.protocols.ss7.map.api.dialog.MAPRefuseInfo;
import org.mobicents.protocols.ss7.map.api.dialog.MAPUserAbortInfo;
public interface MAPDialogListener {
    public void onMAPOpenInfo(MAPOpenInfo mapOpenInfo);
    
    public void onMAPAcceptInfo(MAPAcceptInfo mapAccptInfo);
    
    public void onMAPCloseInfo(MAPCloseInfo mapCloseInfo);
    
    public void onMAPRefuseInfo(MAPRefuseInfo mapRefuseInfo);
    
    public void onMAPUserAbortInfo(MAPUserAbortInfo mapUserAbortInfo);
    
    public void onMAPProviderAbortInfo(MAPProviderAbortInfo mapProviderAbortInfo);
}
                
                
    

package org.mobicents.protocols.ss7.map.api;
import org.mobicents.protocols.ss7.map.api.service.supplementary.ProcessUnstructuredSSIndication;
import org.mobicents.protocols.ss7.map.api.service.supplementary.UnstructuredSSIndication;
public interface MAPServiceListener {
    
    public void onProcessUnstructuredSSIndication(ProcessUnstructuredSSIndication procUnstrInd);
    
    public void onUnstructuredSSIndication(UnstructuredSSIndication unstrInd);
    
    
}
                
                

    


import org.mobicents.protocols.ss7.map.api.MAPApplicationContext;
import org.mobicents.protocols.ss7.map.api.MAPDialog;
import org.mobicents.protocols.ss7.map.api.MAPDialogListener;
import org.mobicents.protocols.ss7.map.api.MAPProvider;
import org.mobicents.protocols.ss7.map.api.MAPServiceListener;
import org.mobicents.protocols.ss7.map.api.MapServiceFactory;
import org.mobicents.protocols.ss7.map.api.dialog.AddressNature;
import org.mobicents.protocols.ss7.map.api.dialog.AddressString;
import org.mobicents.protocols.ss7.map.api.dialog.MAPAcceptInfo;
import org.mobicents.protocols.ss7.map.api.dialog.MAPCloseInfo;
import org.mobicents.protocols.ss7.map.api.dialog.MAPOpenInfo;
import org.mobicents.protocols.ss7.map.api.dialog.MAPProviderAbortInfo;
import org.mobicents.protocols.ss7.map.api.dialog.MAPRefuseInfo;
import org.mobicents.protocols.ss7.map.api.dialog.MAPUserAbortInfo;
import org.mobicents.protocols.ss7.map.api.dialog.NumberingPlan;
import org.mobicents.protocols.ss7.map.api.service.supplementary.ProcessUnstructuredSSIndication;
import org.mobicents.protocols.ss7.map.api.service.supplementary.USSDString;
import org.mobicents.protocols.ss7.map.api.service.supplementary.UnstructuredSSIndication;
import org.mobicents.protocols.ss7.sccp.parameter.SccpAddress;
public class MAPClient implements MAPDialogListener, MAPServiceListener {
    MAPProvider mapProvider;
    MapServiceFactory servFact = mapProvider.getMapServiceFactory();
    SccpAddress destAddress = null;
    // The address created by passing the AddressNature, NumberingPlan and
    // actual address
    AddressString destReference = servFact.createAddressString(
            AddressNature.international_number, NumberingPlan.land_mobile,
            "204208300008002");
    SccpAddress origAddress = null;
    AddressString origReference = servFact.createAddressString(
            AddressNature.international_number, NumberingPlan.ISDN,
            "31628968300");
    public void run() throws Exception {
        // First create Dialog
        MAPDialog mapDialog = mapProvider.createNewDialog(
                MAPApplicationContext.networkUnstructuredSsContextV2,
                destAddress, destReference, origAddress, origReference);
        // The dataCodingScheme is still byte, as I am not exactly getting how
        // to encode/decode this.
        byte ussdDataCodingScheme = 0x0f;
        // USSD String: *125*+31628839999#
        // The Charset is null, here we let system use default Charset (UTF-7 as
        // explained in GSM 03.38. However if MAP User wants, it can set its own
        // impl of Charset
        USSDString ussdString = servFact.createUSSDString("*125*+31628839999#");
        
        
        AddressString msisdn = this.servFact
        .createAddressString(AddressNature.international_number,
                NumberingPlan.ISDN, "31628838002");             
        mapDialog.addProcessUnstructuredSSRequest(ussdDataCodingScheme,
                ussdString, msisdn);
        // This will initiate the TC-BEGIN with INVOKE component
        mapDialog.send();
    }
    public void onMAPAcceptInfo(MAPAcceptInfo mapAccptInfo) {
        // TODO Auto-generated method stub
    }
    public void onMAPCloseInfo(MAPCloseInfo mapCloseInfo) {
        // TODO Auto-generated method stub
    }
    public void onMAPOpenInfo(MAPOpenInfo mapOpenInfo) {
        // TODO Auto-generated method stub
    }
    public void onMAPProviderAbortInfo(MAPProviderAbortInfo mapProviderAbortInfo) {
        // TODO Auto-generated method stub
    }
    public void onMAPRefuseInfo(MAPRefuseInfo mapRefuseInfo) {
        // TODO Auto-generated method stub
    }
    public void onMAPUserAbortInfo(MAPUserAbortInfo mapUserAbortInfo) {
        // TODO Auto-generated method stub
    }
    public void onProcessUnstructuredSSIndication(
            ProcessUnstructuredSSIndication procUnstrInd) {
        // TODO Auto-generated method stub
    }
    public void onUnstructuredSSIndication(UnstructuredSSIndication unstrInd) {
        // TODO Auto-generated method stub
    }
}
                
                

Revision History
Revision 1.0Wed June 2 2010Amit Bhayani
Creation of the JBoss Communications MAP Stack User Guide.