JBoss.orgCommunity Documentation

Chapter 4. Protocol

4.1. API
4.1.1. MAP Dialog overview
4.1.2. Common MAP Services
4.1.3. Supplementary services–related services
4.2. Stack
4.3. Configuration
4.3.1. Dependencies
4.4. Example

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();
    
    public void stop();
    
    public void start() throws IllegalStateException, StartFailedException;
}
                
            

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);
    
    
}
                
                

MAP layer does not require any config. However it requires properly set TCAP and its sublayers. Please refer to TCAP User Guide for supported configuration options.

    


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
    }
}