Revision: 16239
Author: [email protected]
Date: Fri Jan  7 05:07:54 2011
Log: MAP Chapter
http://code.google.com/p/mobicents/source/detail?r=16239

Added:
/trunk/protocols/ss7/docs/sources/src/main/resources/en-US/images/MapClassDiagram.png
Modified:
 /trunk/protocols/ss7/docs/sources/src/main/resources/en-US/Chapter-MAP.xml

=======================================
--- /dev/null   
+++ /trunk/protocols/ss7/docs/sources/src/main/resources/en-US/images/MapClassDiagram.png Fri Jan 7 05:07:54 2011
Binary file, no diff available.
=======================================
--- /trunk/protocols/ss7/docs/sources/src/main/resources/en-US/Chapter-MAP.xml Tue Jan 4 22:44:10 2011 +++ /trunk/protocols/ss7/docs/sources/src/main/resources/en-US/Chapter-MAP.xml Fri Jan 7 05:07:54 2011
@@ -8,15 +8,154 @@
 <chapter id="map">

        <title>MAP</title>
+
+ <para>Mobile application part (<acronym>MAP</acronym>) is the protocol that is used to allow the <acronym>GSM</acronym> network nodes + within the Network Switching Subsystem (<acronym>NSS</acronym>) to communicate with each other to provide services, such as roaming capability, + text messaging (<acronym>SMS</acronym>), Unstructured Supplementary Service Data (<acronym>USSD</acronym>) and subscriber authentication. + <acronym>MAP</acronym> provides an application layer on which to build the services that support a <acronym>GSM</acronym> network. + This application layer provides a standardized set of services. <acronym>MAP</acronym> uses the services of the <acronym>SS7</acronym> network, + specifically the Signaling Connection Control Part (<acronym>SCCP</acronym>) and the Transaction Capabilities Application Part (<acronym>TCAP</acronym>)
+       </para>
+ <important><para>For better understanding of this chapter please read GSM 09.02.</para> </important>
+
        <para>
- <literal>MAP</literal> stack runs on top of <literal>TCAP</literal>. It requires <literal>SS7 Service</literal> deployed to access <literal>SCCP</literal> - access point. Starting <literal>MAP</literal> stack can be done as follows: + <classname>org.mobicents.protocols.ss7.map.api.MAPStack</classname> interface defines the methods required to represent MAP Protocol Stack. + MAPStack exposes <classname>org.mobicents.protocols.ss7.map.api.MAPProvider</classname> that interacts directly with MAPStack. This interface + defines the methods that will be used by any registered MAP User application implementing the + <classname>org.mobicents.protocols.ss7.map.api.MAPDialogListener</classname> and <classname>org.mobicents.protocols.ss7.map.api.MAPServiceListener</classname> + interface to listen MAP messages and dialogue handling primitives. The class diagram looks like
        </para>
+
+               <mediaobject
+                       id="map_classdia">
+                       <imageobject>
+                               <imagedata
+                                       width="300px"
+                                       align="center"
+                                       fileref="images/MapClassDiagram.png"
+                                       format="PNG" />
+                       </imageobject>
+                       <caption>
+                               <para>&THIS.PLATFORM; &THIS.APPLICATION; MAP 
Class Diagram
+                               </para>
+                       </caption>
+               </mediaobject>
+
+ <note><para>&THIS.PLATFORM; &THIS.APPLICATION; MAP has implementation for USSD Message only. Any contribution to implement + message specific to SMS or other are welcome. We will provide you all the help that you may need initially.</para></note>
+
+       <para>
+ <classname>org.mobicents.protocols.ss7.map.MAPStackImpl</classname> is concrete implementation of <classname>MAPStack</classname>. + The MAP User application creates instance of <classname>MAPStackImpl</classname> passing the reference of <classname>SccpProvider</classname> and + new instance of <classname>SccpAddress</classname> representing address to which bind listenes. TODO : Bartek
+       </para>
+
        <programlisting
                language="Java"
                role="JAVA"><![CDATA[
-
+ SccpProvider sccpProvider = getSccpProvider(); //JNDI lookup of SCCP Stack and get Provider
+               SccpAddress localAddress createLocalAddress();
+
+ MAPStackImpl mapStack = new MAPStackImpl(sccpPprovider, localAddress);
+
+               ]]>
+       </programlisting>
+
+ <para>The reference to <classname>SccpProvider</classname> is received from <classname>SccpStack</classname>. + To get handle to <classname>SccpStack</classname> do the JNDI look-up passing the + JNDI name configured in SS7 service as explained in <xref linkend="configuring_SS7Service"/> </para>
+
+
+       <programlisting
+               language="Java"
+               role="JAVA"><![CDATA[
+    private static SccpProvider getSccpProvider() throws NamingException {
+
+        // no arg is ok, if we run in JBoss
+        InitialContext ctx = new InitialContext();
+        try {
+            String providerJndiName = "/mobicents/ss7/sccp";
+ return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
+
+        } finally {
+            ctx.close();
+        }
+    }
+               ]]>
+       </programlisting>
+
+ <para>The MAP User application should register the concrete implementation of + <classname>MAPDialogListener</classname> and <classname>MAPServiceListener</classname> + with <classname>MAPProvider</classname> to listen for incoming MAP Dialog and MAP Primitive messages.
+       </para>
+
+       <programlisting
+               language="Java"
+               role="JAVA"><![CDATA[
 public class MAPExample implements MAPDialogListener, MAPServiceListener {
+               .....
+               mapProvider = mapStack.getMAPProvider();
+        mapProvider.addMAPDialogListener(this);
+        mapProvider.addMAPServiceListener(this);
+        ....
+}
+               ]]>
+       </programlisting>
+
+ <para>The MAP User Application leverages <classname>MapServiceFactory</classname> to create instance of + <classname>USSDString</classname> and <classname>AddressString</classname> </para>
+
+       <programlisting
+               language="Java"
+               role="JAVA"><![CDATA[
+               MapServiceFactory servFact = mapProvider.getMapServiceFactory();
+ USSDString ussdString = servFact.createUSSDString("*125*+31628839999#",
+                null);
+
+        AddressString msisdn = this.servFact.createAddressString(
+                AddressNature.international_number, NumberingPlan.ISDN,
+                "31628838002");
+               ]]>
+       </programlisting>
+
+ <para>The MAP User Application leverages <classname>MAPProvider</classname> to create new
+       <classname>MAPDialog</classname> and send USSD message</para>
+
+       <programlisting
+               language="Java"
+               role="JAVA"><![CDATA[
+        // First create Dialog
+        MAPDialog mapDialog = mapProvider.createNewDialog(
+                MAPApplicationContext.networkUnstructuredSsContextV2,
+                destAddress, destReference, origAddress, origReference);
+
+        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#",
+                null);
+
+        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();
+               ]]>
+       </programlisting>
+
+       <para>The complete example looks like</para>
+
+       <programlisting
+               language="Java"
+               role="JAVA"><![CDATA[
+public class MAPExample implements MAPDialogListener, MAPServiceListener {

     private MAPStack mapStack;
     private MAPProvider mapProvider;
@@ -50,55 +189,37 @@
         mapProvider.addMAPServiceListener(this);
     }

-    private static SccpProvider getSccpProvider()
-
-    throws NamingException
-
-    {
+    private static SccpProvider getSccpProvider() throws NamingException {

         // no arg is ok, if we run in JBoss
-
         InitialContext ctx = new InitialContext();
-
         try {
-
-            String adapterName = "jmx/invoker/RMIAdaptor";
-
-            Object obj = ctx.lookup(adapterName);
-
-            if (!(obj instanceof RMIAdaptor))
-
-            {
-
-                throw new ClassCastException
-
-                ("Object not of type: RMIAdaptorImpl, but: " +
-
-                (obj == null ? "not found" : obj.getClass().getName()));
-
-            }
-
-            // SS7Service is JMX bean, lets use it to get
-
-            MBeanServerConnection con = createMBeanServerConnection();
-
-            ObjectName on = new ObjectName(
-                    "org.mobicents.ss7:service=SS7Service");
-
- String providerJndiName = con.invoke(on, "getJndiName", null, null);
-
-            InitialContext ctx = new InitialContext();
-
-            return (SccpProvider) ctx.lookup(providerJndiName);
-
-        } finally
-
-        {
-
-            ctx.close();
-
-        }
-
+            String providerJndiName = "/mobicents/ss7/sccp";
+ return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
+
+        } finally {
+            ctx.close();
+        }
+    }
+
+    private static SccpAddress createLocalAddress() {
+        GlobalTitle gt = GlobalTitle
+                .getInstance(
+                        NatureOfAddress.NATIONAL.getValue(),
+ org.mobicents.protocols.ss7.indicator.NumberingPlan.ISDN_MOBILE,
+                        NatureOfAddress.NATIONAL, "1234");
+
+        return new SccpAddress(gt, 0); // 0 is Sub-System number
+    }
+
+    private static SccpAddress createRemoteAddress() {
+        GlobalTitle gt = GlobalTitle
+                .getInstance(
+                        NatureOfAddress.NATIONAL.getValue(),
+ org.mobicents.protocols.ss7.indicator.NumberingPlan.ISDN_MOBILE,
+                        NatureOfAddress.NATIONAL, "1572582");
+
+        return new SccpAddress(gt, 0); // 0 is Sub-System number
     }

     public void run() throws Exception {
@@ -171,29 +292,20 @@

     }

-    public static void main(String[] args) {
-
-        int translationType = 0;
-
-        int subSystemNumber = 0;
-
-        GlobalTitle gt = GlobalTitle.getInstance(translationType,
- NumberingPlan.ISDN_MOBILE, NatureOfAddress.NATIONAL, "1234");
-
-        SccpAddress localAddress = new SccpAddress(gt, 0);
-
-        gt = GlobalTitle.getInstance(translationType,
- NumberingPlan.ISDN_MOBILE, NatureOfAddress.NATIONAL, "1572582");
-
-        SccpAddress remoteAddress = new SccpAddress(gt, 0);
-
- MAPExample c = new MAPExample(getSccpProvider(), localAddress, remoteAddress);
+    public static void main(String[] args) throws Exception {
+ SccpProvider sccpProvider = getSccpProvider(); // JNDI lookup of SCCP
+
+        SccpAddress localAddress = createLocalAddress();
+        SccpAddress remoteAddress = createRemoteAddress();
+
+        MAPExample example = new MAPExample(sccpProvider, localAddress,
+                remoteAddress);
+
+        example.run();

     }

-}
-
-
+}
                ]]>
-               </programlisting>
+       </programlisting>
 </chapter>

Reply via email to