PageRenderTime 38ms CodeModel.GetById 29ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/protocols/smpp/docs/UserGuide.html

http://mobicents.googlecode.com/
HTML | 280 lines | 233 code | 47 blank | 0 comment | 0 complexity | b5b5e303c61d5f497f7aede7096f6c92 MD5 | raw file
  1<html>
  2  <head>
  3    <link rel="stylesheet" href="UserGuide.css" type="text/css" />
  4    <title>Java SMPP API User's Guide</title>
  5    </head>
  6
  7    <body>
  8      <div class="smppapiDoc">
  9        <h1>Java SMPP API User's Guide</h1>
 10
 11        <h2>Document status</h2>
 12        <p>
 13        This document is brief and extremely rough-and-ready.  Feedback and criticism should be posted to the relevant discussion forums on <a href="http://www.sf.net/projects/smppapi/">Sourceforge</a>.
 14        </p>
 15        <p>
 16        The latest version of this document is always available at <a href="http://smppapi.sourceforge.net/user-guide/">http://smppapi.sourceforge.net/user-guide/</a>.
 17        </p>
 18
 19        <h2>Introduction</h2>
 20        <p>
 21        This guide describes the use of the <b>Java SMPP API (<i>smppapi</i>)</b> in an application. The project resides on the web at <a href="http://www.sf.net/projects/smppapi">http://www.sf.net/projects/smppapi</a>.
 22        </p>
 23
 24        <p>
 25        This guide is meant only as an introduction to the functionality provided by the API. Developer's should refer to the <a href="apiDocs/index.html">API documentation</a> for a comprehensive description of the interfaces available.
 26        </p>
 27
 28        <h3>License</h3>
 29        <p>The smppapi is released under the GNU Lesser GPL (LGPL). The text of the LGPL should be in the LICENSE file in the top-level of the smppapi distribution and can also be <a href="http://www.opensource.org/">the Open Source Initiative</a>.
 30        </p>
 31
 32        <h2>Interface version</h2>
 33        <p>
 34        The API supports versions 3.3 and 3.4 of the SMPP specification.
 35        </p>
 36
 37        <h2>Packages</h2>
 38        <p>
 39        The smppapi classes are packaged in (and under) the <code>ie.omk.smpp namespace.</code> Top-level classes (such as <b><code><a href="apiDocs/ie/omk/smpp/Connection.html">Connection</a></b>) are in the <code>ie.omk.smpp</code> package. SMPP message primitives (requests and responses) are in the <code>ie.omk.smpp.message</code> package. Classes which handle network connectivity (eg <b><code><a href="apiDocs/ie/omk/smpp/net/TcpLink.html">TcpLink</a></code></b>) reside in the <code>ie.omk.smpp.net</code> package. There are also some utility classes in <code>ie.omk.smpp.util</code> package.
 40
 41          <h2>Establishing the network link</h2>
 42          <p>
 43          The physical connection between an SMPP application (<i>ESME</i>) and the <i>SMSC</i> is defined by the <code>SmscLink</code> abstract class. Specific network implementations extend this class to allow the API to communicate with the SMSC over any Java-supported network protocol. The smppapi currently provides two concrete SmscLink implementations:
 44          <ul>
 45            <li><code>TcpLink</code>. This allows an ESME to communicate with the SMSC
 46            over the Internet-standard TCP/IP protocol.
 47
 48            <li><code>StreamLink</code>. This class is mainly provided for debugging purposes.
 49            It allows the ESME to provide any Java input stream and output stream for the
 50            smppapi to use for i/o.
 51          </ul>
 52          </p>
 53
 54          <h3>Using <code>TcpLink</code></h3>
 55          <p>
 56          A TCP/IP link can be established to the SMSC in two ways. In the first case, the developer relies on the API to open the underlying socket to the remote system. In the second, the socket connection is already established.
 57          </p>
 58
 59          <p>
 60          <u>Case 1</u>:
 61          <div class="codeblock">
 62try {
 63    // First get the java.net.InetAddress for the SMSC:
 64    InetAddress smscAddr = InetAddress.getByName("smsc.domain.com");
 65
 66    // Use port 5432
 67    TcpLink smscLink = new TcpLink(smscAddr, 5432);
 68
 69    // Open the connection (not required)..
 70    smscLink.open();
 71} catch(java.net.UnknownHostException ux) {
 72    System.err.println("SMPPAPI: " + ux.getMessage());
 73}
 74          </div>
 75          </p>
 76
 77          <p>
 78          <u>Case 2</u>:
 79          <div class="codeblock">
 80try {
 81    // Open the socket..
 82    Socket s = new Socket("smsc.domain.com", 5432);
 83
 84    // Create the TCP link..
 85    TcpLink smscLink = new TcpLink(s);
 86} catch (java.net.UnknownHostException x) {
 87    ...
 88} catch (java.io.IOException x) {
 89    ...
 90}
 91          </div>
 92          </p>
 93
 94          <h3>Using <code>StreamLink</code></h3>
 95          <p>
 96          The <code>StreamLink</code> class is provided mainly for debugging purposes.  It's primary purpose is to read SMPP packets from a binary file. However, it is possible to pass any Java <code>InputStream</code> and <code>OutputStream</code> to the <code>StreamLink</code> constructor. For instance, if a file 'responses.bin' exists that contains a set of response messages that a developer wishes to test against, she may do so like this:
 97          <div class="codeblock">
 98FileInputStream fin = new FileInputStream("responses.bin");
 99FileOutputStream fout = new FileOutputStream("/dev/null");
100
101StreamLink link = new StreamLink(fin, fout);
102
103Connection tran = new Connection(link);
104link.bind(Connection.TRANSMITTER, ...);
105
106// run tests...
107          </div>
108          Obviously, the responses should match whatever requests are sent.
109          </p>
110
111          <h2>Connections, Transmitters, Receivers and Transceivers.</h2>
112          <p>
113          SMPP defines three modes of operation for an ESME; transmitter, receiver and transceiver. An ESME must select one of these modes of operation when it <i>binds</i> to the SMSC. In transmitter mode, an ESME is capable of submitting messages to the SMSC, querying the status of messages and system parameters but it is not able to receive short messages from the SMSC.  To be capable of receiving delivery of short messages, an ESME must also bind as a receiver. In receiver mode, the SMSC will send <code>deliver_sm</code> packets to the ESME. In receiver mode, however, all the operations available in transmitter mode are disabled. A receiver and transmitter type connection require two separate network links. That is, a receiver and transmitter connection cannot share the same TCP network link.
114
115          <p>SMPP version 3.4 introduced the transceiver type of connection. When an ESME binds to the SMSC in transceiver mode, it is similar to having a transmitter and receiver connection over the same network link. However, SMPP 3.4 also altered other aspects of the protocol, so the transceiver connection cannot be considered identical to a transmitter and receiver rolled into one.</p>
116
117          <p>To bind to the SMSC as a particular type, the calling application should pass the appropriate enumeration value into the
118          <code>Connection.bind</code> method. Valid enumeration values are:
119          <ul>
120            <li><code>Connection.TRANSMITTER</code>
121            <li><code>Connection.RECEIVER</code>
122            <li><code>Connection.TRANSCEIVER</code>
123          </ul>
124
125          Note that the Connection object must have it's internal version set appropriately to support a transceiver connection. See the <code>Connection.setVersion</code> method.
126
127          <h2>Synchronous versus Asynchronous communication.</h2>
128          <p>
129          The smppapi supports both synchronous and asynchronous communication. <b>Synchronous</b> communication is the default. This means that when a request is sent to the SMSC, the API <i>blocks</i> until the response is received from the SMSC. In asynchronous communication, the API returns immediately after sending a request and notifies your application once the response is received from the SMSC. More than one <i>observer</i> can be notified of an incoming SMPP packet from the SMSC.
130          </p>
131
132          <p>
133          As synchronous communication is the default, no special action needs to be taken when using the <code>Connection</code> class. Its use is simply:
134          <div class="codeblock">
135try {
136    Connection trans = new Connection(smscLink);
137    .
138        .
139        SMPPResponse resp = trans.sendRequest(req);
140    if (resp.getCommandStatus() != 0) {
141        ...
142    }
143} catch (SMPPException x) {
144    ...
145}
146          </div>
147          </p>
148
149          <p>
150          To create a <code>Connection</code> that uses asynchronous communication, an implementation of the <code>ie.omk.smpp.event.ConnectionObserver</code> interface is needed. The connection observer will receive updates from the API for various internal API events, including packet reception.
151          <div class="codeblock">
152public class MyListener implements ie.omk.smpp.event.ConnectionObserver {
153
154    public void packetReceived(Connection source, SMPPPacket packet) {
155        // Process received packet
156        ...
157    }
158
159    // Method called for API events other than packet reception.
160    public void update(Connection source, SMPPEvent event) {
161        // process event..
162        ...
163    }
164}
165          </div>
166          </p>
167
168          <p>
169          This observer object must now be registered with the <code>Connection</code> object so that it can receive updates.
170          <div class="codeblock">
171// Create a listener object
172MyListener myListener = new MyListener();
173
174// Create an asynchronous transmitter..
175Connection trans = new Connection(smscLink, true);
176
177// Register the listener..
178trans.addObserver(myListener);
179          </div>
180          </p>
181
182          <h2>Synchronous communication as a receiver</h2>
183          <p>
184          While it is possible to use synchronous communication with a receiver connection, it is generally more useful to use asynchronous communication when binding as a receiver.  This is because the only thing a receiver application does once it binds is wait for the SMSC to deliver messages to it. Therefore, it makes sense for a receiver application to bind and then let the smppapi wait for incoming messages. Once received, the application will be passed an <code>SMPPEvent</code> as described above.
185          </p>
186
187          <p>
188          To use synchronous communication while bound as a receiver, have a look at the <code><a href="apiDocs/ie/omk/smpp/Connection.html#readNextPacket(long)">Connection.readNextPacket</a></code> method.
189
190          <h2>Binding to the SMSC</h2>
191          <p>
192          To bind to the SMSC, call the <code>Connection.bind</code> method with appropriate arguments. For example:
193          </p>
194
195          <p>
196          <u>Binding to the SMSC as a transmitter</u>:
197          <div class="codeblock">
198Connection c = new Connection(smscLink);
199
200/*
201 * Bind to the SMSC...use the default routing information
202 * configured at the SMSC..
203 */
204BindResp r = c.bind(Connection.TRANSMITTER, "sysID", "secret", "sysType", null);
205if (r.getCommandStatus() != 0) {
206    ...
207}
208
209...
210          </div>
211          </p>
212
213          <h2>Handling an SMPPEvent</h2>
214          <p>
215          As already discussed, when using asynchronous communication, the smppapi will notify an observer of an incoming SMPP packet from the SMSC with a call to it's <code>packetReceived</code> method.  <u>It is very important to keep thread-safety in mind when writing your event handler methods</u> as the smppapi makes no guarantees that it will dispatch only one event at a time.  An example SMPP event handler follows:
216          <div class="codeblock">
217public class MyListener implements ie.omk.smpp.event.ConnectionObserver {
218    public void packetReceived(Connection source, SMPPPacket pak) {
219        try {
220            switch (pak.getCommandID()) {
221                case SMPPPacket.ESME_BNDTRN_RESP:
222                    if (pak.getCommandStatus() == 0) {
223                        // successfully bound...
224                        this.submitMessages();
225                    } else {
226                        // handle error...
227                    }
228                    break;
229
230                case SMPPPacket.ESME_SUB_SM_RESP:
231                    ...
232                        break;
233
234                case SMPPPacket.GENERIC_NAK:
235                    ..
236                        break;
237            } catch (SMPPException x) {
238                // handle exception...
239            }
240        }
241
242        public void update(Connection source, SMPPEvent event) {
243            // called for control events..
244            switch (event.getType()) {
245                case SMPPEvent.RECEIVER_EXCEPTION:
246                    // an exception occurred in the receiver thread..
247                    break;
248
249                case SMPPEvent.RECEIVER_EXIT:
250                    // the receiver thread has just died.
251                    break;
252
253                    // see the event framework for further events.
254            }
255        }
256    }
257}
258          </div>
259          </p>
260
261          <h2>Automatic responses.</h2>
262          <p>
263          In certain cases the SMSC may send request packets to an ESME. The only two cases in SMPP version 3.3 are when the SMSC is delivering short messages to an ESME (only relevant to a receiver) and when the SMSC sends an <code>EnquireLink</code> request (both receiver and transmitter). The <code>Connection</code> can be set up to automatically respond to these messages. Thus, so long as the ESME is 'alive', if the SMSC sends an <code>EnquireLink</code> request, the smppapi will respond immediately with <code>EnquireLinkResp</code>. The request packet will still be passed to the application by the smppapi in the normal manner.
264          </p>
265
266          <p>
267          By default, automatically acknowledging links is <b>enabled</b> while automatically acknowledging messages is <b>disabled</b>. To change these settings, use the <code>Connection.autoAckLink</code> and <code>Connection.autoAckMessages</code> methods.
268          </p>
269
270          <h2>Appendix A: Glossary.</h2>
271          <table cols="2">
272            <tr><td>SMPP</td><td>Short Message Peer to Peer</td></tr>
273            <tr><td>SMSC or SC</td><td>Short Message Service Centre</td></tr>
274            <tr><td>ESME or SME</td><td>(External) Short Message Entity</td></tr>
275          </table>
276
277          <div class="copyright">&copy; Copyright 1998 - 2007 by Oran Kelly. <a href="http://smppapi.sourceforge.net/">smppapi</a></div>
278    </div>
279  </body>
280</html>