Revision: 5aba069bbd27
Author: Vinu S Renish <[email protected]>
Date: Sat Jan 12 08:26:10 2013
Log: MAP chapter edited for clarity and grammar
http://code.google.com/p/jss7/source/detail?r=5aba069bbd27
Modified:
/docs/sources/src/main/resources/en-US/Chapter-MAP.xml
=======================================
--- /docs/sources/src/main/resources/en-US/Chapter-MAP.xml Sat Jan 12
02:28:43 2013
+++ /docs/sources/src/main/resources/en-US/Chapter-MAP.xml Sat Jan 12
08:26:10 2013
@@ -13,22 +13,25 @@
<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,
+ ) to communicate with each other in order 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>
+ <acronym>USSD</acronym>) and subscriber authentication.
+ </para>
+ <para>
+ <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>)
+ ) and the Transaction Capabilities Application Part
(<acronym>TCAP</acronym>).
</para>
<important>
<para>For better understanding of this chapter you must be familiar with
the specifications defined in <literal>GSM 09.02</literal>.</para>
</important>
<para>
-MAP has full implementation for USSD, SMS and Location Management Service
(LMS) Services
- and partial implementation for Mobility service (updateLocation,
sendAuthenticationInfo,
- anyTimeInterrogation, checkIMEI operations) only. You can find the
list of implemented MAP messages here: <ulink type="http"
url="http://code.google.com/p/jss7/source/browse/map/MAPMessagesImplemented.ods";>MAPMessagesImplemented.ods</ulink>.
The document uses color coding to represent the status of the
implementation:
+MAP has full implementation for USSD, SMS and LMS (Location Management
Service) services
+ and partial implementation for Mobility Services (updateLocation,
sendAuthenticationInfo,
+ anyTimeInterrogation, checkIMEI operations). You can find the list of
implemented MAP messages here: <ulink type="http"
url="http://code.google.com/p/jss7/source/browse/map/MAPMessagesImplemented.ods";>MAPMessagesImplemented.ods</ulink>.
The document uses color coding to represent the status of the
implementation:
<variablelist>
<varlistentry>
<term>Green</term>
@@ -55,60 +58,70 @@
<title>&THIS.APPLICATION; MAP
</title>
<para>
- The
<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.
- MAP user application must implement interfaces to listen MAP messages
and dialogue and component handling primitives.
- One interface is
<classname>org.mobicents.protocols.ss7.map.api.MAPDialogListener</classname>
- (listening associated with dialog events).
+ The methods required to represent the MAP Protocol Stack are defined in
the interface
<classname>org.mobicents.protocols.ss7.map.api.MAPStack</classname> which
exposes
<classname>org.mobicents.protocols.ss7.map.api.MAPProvider</classname>
+ that interacts directly with the
<classname>MAPStack</classname>.
+ This interface defines the methods that will be used by any registered
MAP-User application.
+ </para>
+ <para>
+ A MAP-User application must implement interfaces to listen for MAP
messages and also implement interfaces for dialogue and component handling
primitives. One such interface is
<classname>org.mobicents.protocols.ss7.map.api.MAPDialogListener</classname>
which must be implemented for listening associated with dialog events.
Others are one or more interfaces for listening associated with
component events based on
- <classname>org.mobicents.protocols.ss7.map.api.MAPServiceListener
interface.</classname>
- Each MAP-User interested in listening messages specific to MAP
Service implements specific MAPServiceListener.
-
+
<classname>org.mobicents.protocols.ss7.map.api.MAPServiceListener</classname>
interface.
</para>
-
<para>
- Each MAP-User interested in listening messages specific to MAP Service
implements specific <classname>MAPServiceListener</classname>.
- <itemizedlist>
- <listitem>
- <para>
- MAP-User interested only in call handling operations implements
<classname>org.mobicents.protocols.ss7.map.api.service.callhandling.MAPServiceCallHandlingListener</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- MAP-User interested only in LMS operations implements
<classname>org.mobicents.protocols.ss7.map.api.service.lsm.MAPServiceLsmListener</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- MAP-User interested only in mobility operations implements
<classname>org.mobicents.protocols.ss7.map.api.service.mobility.MAPServiceMobilityListener</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- MAP-User interested only in OAM operations implements
<classname>org.mobicents.protocols.ss7.map.api.service.oam.MAPServiceOamListener</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- MAP-User interested only in PDP context activation operations
implements
<classname>org.mobicents.protocols.ss7.map.api.service.pdpContextActivation.MAPServicePdpContextActivationListener</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- MAP-User interested only in SMS operations implements
<classname>org.mobicents.protocols.ss7.map.api.service.sms.MAPServiceSmsListener</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- MAP-User interested only in supplementary operations implements
<classname>org.mobicents.protocols.ss7.map.api.service.supplementary.MAPServiceSupplementaryListener</classname>
- </para>
- </listitem>
- </itemizedlist>
- MAP-User interested in all the services must implement all the service
listener class.
+ Below is a list of MAP Service Listener classes. A MAP-User interested
in listening for messages specific to a particular MAP Service must
implement the corresponding MAPServiceListener.
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ LMS operations
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.lsm.MAPServiceLsmListener</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Mobility operations
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.mobility.MAPServiceMobilityListener</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>OAM operations
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.oam.MAPServiceOamListener</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PDP context activation operations
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.pdpContextActivation.MAPServicePdpContextActivationListener</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SMS operations
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.sms.MAPServiceSmsListener</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Supplementary operations
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.supplementary.MAPServiceSupplementaryListener</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ A MAP-User interested in all the services must implement all the above
Service Listener classes.
</para>
<!-- <para>
The class diagram looks like
@@ -132,9 +145,9 @@
<para>
- The
<classname>org.mobicents.protocols.ss7.map.MAPStackImpl</classname>
- is concrete implementation of
<classname>MAPStack.</classname>
- The MAP User application gets reference to MAPProvider by doing JNDI
lookup as explained in <xref linkend="design_overview_ss7_service"/>
+ The <classname>org.mobicents.protocols.ss7.map.MAPStackImpl</classname>
class
+ is a concrete implementation of
<classname>MAPStack</classname>.
+ The MAP-User application gets a reference to
<classname>MAPProvider</classname> by doing a JNDI lookup as explained in
<xref linkend="design_overview_ss7_service"/>.
</para>
<programlisting
@@ -145,35 +158,71 @@
</programlisting>
<para>
- The MAP User application should register the concrete implementation of
<classname>MAPDialogListener</classname>
- with <classname>MAPProvider</classname> to listen for incoming MAP
Dialog and MAP Primitive messages.
- The MAP User application should register the concrete implementation of
<classname>MAPServiceListener</classname>
- with corresponding <classname>MAPServiceBase </classname> to listen
for incoming MAP Service messages.
- Following MAPServiceBase are exposed by
<classname>MAPProvider</classname>.
- <itemizedlist>
- <listitem>
- <para>For call handling service
<classname>org.mobicents.protocols.ss7.map.api.service.callhandling.MAPServiceCallHandling</classname></para>
- </listitem>
- <listitem>
- <para>For LSM service
<classname>org.mobicents.protocols.ss7.map.api.service.lsm.MAPServiceLsm</classname></para>
- </listitem>
- <listitem>
- <para>For mobility service
<classname>org.mobicents.protocols.ss7.map.api.service.mobility.MAPServiceMobility</classname></para>
- </listitem>
- <listitem>
- <para>For OAM service
<classname>org.mobicents.protocols.ss7.map.api.service.oam.MAPServiceOam</classname></para>
- </listitem>
- <listitem>
- <para>For PDP context activation service
<classname>org.mobicents.protocols.ss7.map.api.service.pdpContextActivation.MAPServicePdpContextActivation</classname></para>
- </listitem>
- <listitem>
- <para>For SMS service
<classname>org.mobicents.protocols.ss7.map.api.service.sms.MAPServiceSms</classname></para>
- </listitem>
- <listitem>
- <para>For supplementary service
<classname>org.mobicents.protocols.ss7.map.api.service.supplementary.MAPServiceSupplementary</classname></para>
- </listitem>
- </itemizedlist>
+ To listen for incoming MAP Dialog and MAP Primitive messages, the
MAP-User application should register the concrete implementation of
<classname>MAPDialogListener</classname> with
<classname>MAPProvider</classname>.
</para>
+ <para>
+ To listen for incoming MAP Service messages, the MAP-User
application should register the concrete implementation of
<classname>MAPServiceListener</classname> with the corresponding
<classname>MAPServiceBase </classname>. The following
<classname>MAPServiceBase</classname> services are exposed by the
<classname>MAPProvider</classname>:
+ <variablelist>
+ <varlistentry>
+ <term>Call handling service
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.callhandling.MAPServiceCallHandling</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LSM service
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.lsm.MAPServiceLsm</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Mobility service
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.mobility.MAPServiceMobility</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>OAM service
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.oam.MAPServiceOam</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PDP context activation service
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.pdpContextActivation.MAPServicePdpContextActivation</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SMS service
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.sms.MAPServiceSms</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Supplementary service
+ </term>
+ <listitem>
+
<para><classname>org.mobicents.protocols.ss7.map.api.service.supplementary.MAPServiceSupplementary</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+
+ </para>
<programlisting language="Java" role="JAVA"><![CDATA[
public class UssdClientExample implements MAPDialogListener,
MAPServiceSupplementaryListener {
@@ -184,7 +233,7 @@
}]]>
</programlisting>
- <para>Before any MAP specific service can be used, the corresponding
service should be activated.</para>
+ <para>Prior to using any MAP specific service, the corresponding service
should be activated as shown below:</para>
<programlisting language="Java" role="JAVA"><![CDATA[
....
@@ -194,7 +243,7 @@
</programlisting>
<para>
- The MAP User Application leverages:
+ The MAP-User Application leverages:
<itemizedlist>
<listitem>
<para><classname>MAPParameterFactory</classname> to create instances
of
@@ -232,7 +281,7 @@
<title>&THIS.APPLICATION; Sending a MAP request
(processUnstructuredSS-Request as an example)</title>
<para>
- For sending a MAP request we need at the client side:
+ For sending a MAP request, you must do the following at
the client side:
</para>
<para>
- Create a new MAP Dialog
@@ -264,7 +313,7 @@
// to encode/decode this.
byte ussdDataCodingScheme = 0x0f;
// 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
+// explained in GSM 03.38. However if MAP-User wants, it can set its own
// impl of Charset
USSDString ussdString = paramFact.createUSSDString(ussdMessage, null);
ISDNAddressString msisdn =
client.getMAPProvider().getMAPParameterFactory().
@@ -285,7 +334,7 @@
- Wait for a response from the server
</para>
<para>
- At the server side when receiving TC-Begin message the following
sequence of events occurs:
+ At the server side, when the TC-Begin message is received, the
following sequence of events occur:
</para>
<programlisting
language="Java"
@@ -296,11 +345,11 @@
<para>
This is the request for MAP Dialog processing.
- A MAP user can reject the Dialog by invoking
mapDialog.refuse() method.
+ A MAP-User can reject the Dialog by invoking the
<literal>mapDialog.refuse()</literal> method.
</para>
<para>
- Then the incoming primitives corresponded events (one or more) occur.
In this case it is
+ This is followed by the events (one or more) corresponding to the
incoming primitives. In this case it is:
</para>
<programlisting
language="Java"
@@ -309,7 +358,7 @@
]]></programlisting>
<para>
- When processing component-depended messages you can add response
components.
+ When processing component-dependant messages, you can add response
components.
In this case it is processUnstructuredSS-Response as an
example:
</para>
<programlisting
@@ -335,10 +384,10 @@
]]></programlisting>
<para>
- If the preparing of response takes more time we should return the
control and prepare the answer asynchronously in separate thread.
+ If preparing the response takes more time, you should return the
control and prepare the answer asynchronously in a separate thread.
</para>
<para>
- If error or reject primitives are included into a TCAP message
following events occur:
+ If error or reject primitives are included in a TCAP message, the
following events occur:
</para>
<programlisting
language="Java"
@@ -349,9 +398,8 @@
]]></programlisting>
<para>
- After all incoming components have been processing
onDialogDelimiter(MAPDialog mapDialog);
- event is invoked (or onDialogClose(MAPDialog mapDialog)
in TC-END case).
- If all response components have been prepared we can tell the stack to
send response:
+ After all incoming components have been processed, the event
<literal>onDialogDelimiter(MAPDialog mapDialog);</literal> or in the case
of TC-END, <literal>onDialogClose(MAPDialog mapDialog)</literal> is invoked.
+ If all response components have been prepared you can tell the stack to
send the response:
<itemizedlist>
<listitem>
<para><classname>mapDialog.close(false);</classname> - to send
TC-END</para>
@@ -363,18 +411,15 @@
<para><classname>mapDialog.close(true);</classname> - sends TC-END
without any components (prearrangedEnd)</para>
</listitem>
</itemizedlist>
- Instead of send() and close(boolean prearrangedEnd) methods you can
invoke
- sendDelayed() or closeDelayed(boolean prearrangedEnd)
methods.
- These methods make the same as send() and close() methods, but when
these methods are invoked from MAP Service message handlers
- (component handler methods called by stack while parsing incoming
components)
- real sending and dialog closing will occur only when all incoming
components events
- and onDialogDelimiter() or onDialogClose() is processed.
+ Instead of <literal>send()</literal> and <literal>close(boolean
prearrangedEnd</literal>) methods you can invoke
+ <literal>sendDelayed()</literal> or <literal>closeDelayed(boolean
prearrangedEnd)</literal> methods.
+ These methods are similar to <literal>send()</literal> and
<literal>close()</literal> methods, but when these methods are invoked from
MAP Service message handlers (component handler methods called by stack
while parsing incoming components), real sending and dialog closing will
occur only when all incoming component events and
<literal>onDialogDelimiter() </literal> or
<literal>onDialogClose()</literal> is processed.
- If all response components have been prepared we should return the
control and
- will send a response when all components are ready.
+ If all response components have been prepared you should return the
control and
+ send a response when all components are ready.
</para>
<para>
- In the error case you can terminate a MAP dialog in any method by
invoking
+ In case of an error, you can terminate a MAP dialog in any method by
invoking
<itemizedlist>
<listitem>
<para><classname>mapDialog.abort(mapUserAbortChoice);</classname> -
sends TC-U-ABORT primitive</para>
@@ -382,7 +427,7 @@
</itemizedlist>
</para>
<para>
- If no local actions or no response from a peer for a long time,
timeouts occur and the following methods are invoked:
+ If there are no local actions or there is no response from a peer for a
long time, a timeout occurs and the following methods are invoked:
<itemizedlist>
<listitem>
<para><classname>MAPDialogListener.onDialogTimeout(MAPDialog
mapDialog);</classname></para>
@@ -393,9 +438,9 @@
</itemizedlist>
</para>
<para>
- In <classname>onDialogTimeout()</classname> method you can invoke
<classname>mapDialog.keepAlive();</classname> to prevent closing a Dialog.
+ In the <classname>onDialogTimeout()</classname> method you can invoke
<classname>mapDialog.keepAlive();</classname> to prevent a Dialog from
closing.
For preventing an Invoke timeout you should invoke
<classname>resetInvokeTimer(Long invokeId);</classname>
- (before onInvokeTimeout() occured).
+ before <classname>onInvokeTimeout()</classname> occurs.
</para>
</section>
@@ -403,8 +448,6 @@
<section
id="map_usage_example">
<title>&THIS.APPLICATION; MAP Usage</title>
- <para>The complete example looks like</para>
-
<programlisting
language="Java"
role="JAVA"><