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>