Open Cloud Rhino SMPP Resource Adaptors Users Guide

Transcription

1 Open Cloud Rhino SMPP Resource Adaptors Users Guide Introduction This document is a short guide to using a Java SMPP API and resource adaptors with the Open Cloud Rhino SLEE SDK. It is intended for SDK users familiar with Rhino SLEE concepts, SBB development and deployment. The SMPP API, resource adaptors, example SBBs and Javadocs are bundled in the smpp-examples.zip file. This file should be extracted in the $RHINO_HOME directory. This will create an examples/smpp subdirectory containing all the relevant code and scripts, similar to the SIP and JCC examples included with the Rhino SDK. The Javadoc for the SMPP API, resource adaptors and examples can be found under examples/smpp/docs. There is a lot of additional detail in the Javadoc so it should be used in conjunction with this document. Open Cloud SMPP API There is currently no standard Java SMPP API. Logica has produced an open source Java SMPP API that is in common use ( but this was not suitable for use as a SLEE RA because it uses synchronous interfaces and blocking I/O. A simple asynchronous and non-blocking Java SMPP API has been developed by Open Cloud for use in a SLEE RA, and this can also be used by standalone Java applications. The main interfaces of the API are outlined below, for details refer to the javadoc. The Open Cloud SMPP API (com.opencloud.slee.resources.smpp package) has two primary interfaces: SmppProvider and SmppListener. Applications use SmppProvider for opening and closing SMPP sessions, and sending SMPP request and response PDUs. Applications receive SMPP request and response PDUs by implementing the SmppListener interface and registering this with the SmppProvider. Because the SMPP protocol is inherently asynchronous, the API is as well. Applications should expect to send and receive PDUs in separate threads. SBB developers however do not need to worry about threading, since the SLEE and the RA hide this complexity from the programmer. The API is based on version 5.0 of the SMPP specification ( Applications can function as ESME or MC nodes, or both. The type of node is determined automatically when the application sends or receives its first PDUs in a session. For example, if an application creates a session and then sends an OUTBIND request, then this is MC behaviour so the node is treated as an MC from that point on, until the end of the session. Similarly if a node creates a session, and then sends a BIND_TRANSMITTER request then this is ESME behaviour. The node type determines what PDUs are allowed to be sent or received in a session. A MC node may not send SUBMIT_SM requests for example, this is not allowed by the SMPP Open Cloud Rhino SMPP RA Users Guide Page 1 of 9

2 protocol. Each SMPP PDU type is represented by its own Java class. The classes are all in the package com.opencloud.slee.resources.smpp.pdu, and are named following the SMPP PDU name, but using Java class naming conventions. PDU fields are represented by instance variables, with set/get methods for each. To send a SUBMIT_SM request, the application creates an instance of the SubmitSM class, sets fields such as the source and destination addresses, and then sends the request using the appropriate SmppProvider method: import com.opencloud.slee.resources.smpp.smppprovider; import com.opencloud.slee.resources.smpp.pdu.submitsm; import com.opencloud.slee.resources.smpp.pdu.address; import com.opencloud.slee.resources.smpp.pdu.shortmessage; SubmitSM request = new SubmitSM(); request.setsourceaddress(new Address("1234")); request.setdestaddress(new Address(" ")); request.setshortmessage(new ShortMessage("Your entry was received. Thankyou")); provider.sendrequest(sessionid, request); SMPP Generic Resource Adaptor Overview This resource adaptor was developed to support generic SMPP applications, where SBBs may be responsible for opening and closing SMPP sessions, and performing ESME and/or MC roles. Activities The activity object for the generic RA is the SMPP Session, which is simply a TCP connection between 2 SMPP peers, and some associated session state. This is represented in the API by the SmppSession interface. Events Each type of SMPP PDU is a separate SLEE event type. In addition, there are several more event types that represent session opening/closing and communication error events (timeouts, I/O errors). For the complete list of event names see the javadoc for com.opencloud.slee.resources.smpp.ra.smppresourceadaptor. SBB Interface The SBB interface object that is bound into the SBB's JNDI namespace is an instance of SmppProvider. SBBs use the SmppProvider in the same way as standalone applications would, except for the add/remove listener methods which do not apply to SBBs. These methods will throw a SecurityException if called from a SBB. Open Cloud Rhino SMPP RA Users Guide Page 2 of 9

3 Resource Adaptor Configuration Properties The generic RA has the following configuration properties, which can be set when creating a RA entity. Property Name Type Default Comment SmppListenAddress String null (listen on all addresses) Local IP address to listen on SmppListenPort Integer 2775 Local TCP port to listen on SmppInactivityTimeout Long Time (in ms) before session inactivity timer fires - session has been idle SmppSessionInitTimeout Long Time (in ms) before session init timer fires - session was not bound in time after TCP connection opened SmppEnquireLinkTimeout Long Time (in ms) before enquire link timer fires - app should send an ENQUIRE_LINK PDU SmppResponseReceivedTimeout Long Time (in ms) that stack waits for a response to be received SmppResponseSentTimeout Long Time (in ms) that stack waits for a response to be sent (to an incoming request) SmppStateCheckingEnabled Boolean true Determines whether stack checks for correct session state when sending/receiving messages. Example SBB An example SBB that uses the generic SMPP RA is test.rhino.testapps.smpp.mc.smppmcsbb. The source code is under examples/smpp/src. This SBB class is a very simple MC/SMSC that does nothing other than respond to bind, unbind and submit_sm SMPP commands. The RA and SBB can be deployed using the Ant build script in examples/smpp: $ ant deploysmppra $ ant deploymcsbb To test the SBB, SMPP requests can be sent using the supplied smpp_test_client.sh utility. This is a simple program that allows the user to connect to a host and send test SMPP commands. Open Cloud Rhino SMPP RA Users Guide Page 3 of 9

4 SMPP Bound Resource Adaptor Overview This resource adaptor is a specialized version of the SMPP RA that is designed to support a single, persistent connection to a MC (aka SMSC). The SBBs using this RA may only function as ESME nodes, and cannot open or close SMPP sessions. Applications can support connections to multiple MCs by creating multiple RA entities, each one "bound" to a specific MC. This RA is used to support the requirement of a routing table (profile) that can be used to select from many MCs to effect failover and load balancing. Each SMPP Bound RA entity represents a single SMPP session with a MC. The MC host/port to connect to is specified by passing configuration property arguments when creating the RA entity. When the RA entity is activated it automatically attempts to connect to the MC and bind. If the session dies for some reason, such as the MC going down, the RA entity will attempt to reconnect at regular intervals until successful, or the until the entity is deactivated. Activities The Bound RA uses the SmppTransaction object to represent an activity in the SLEE. The SmppTransaction activity is (typically) a short-lived activity, as it represents just a single SMPP request/response "transaction". New activities are created when the RA receives a request, or the SBB sends a request using SmppBoundSession.sendRequest(). Activities are ended when the SBB sends a response, or a response is received by the RA. The primary reason for using a different activity type for the Bound RA is performance. The SLEE must serially process all events that are fired on the same activity, in accordance with the JAIN SLEE specification. This may limit throughput if there were a small number of long-lived activities (SMPP sessions as used in the generic RA) with serial event processing on each. By using the SmppTransaction activity object, only each request/response pair on the activity need be processed serially, while many activities can be processed concurrently by the SLEE, which means better throughput. Events The bound RA emits the same events as the generic RA, except for the session timers that are not applicable as the SBB does not care about the session when using the bound RA. SBB Interface The SBB interface object that is bound into the SBB's JNDI namespace is an instance of SmppBoundSession. The SmppBoundSession interface only permits the SBB to send requests and responses on the single session. All session setup and tear down is handled by the bound RA entity. SBBs that want to be able to select between multiple SMPP sessions must ensure that they have JNDI bindings for the RA entities that they want to use. It is entirely up to Open Cloud Rhino SMPP RA Users Guide Page 4 of 9

5 the SBB developer and deployer how multiple bound RA entities are used. An example of an SBB using a "routing table" profile to select from a number of RA entities is described below. Resource Adaptor Configuration Properties Property Name Type Default Comment SMSCHost String localhost IP address or hostname of SMSC that this entity will connect to SMSCPort Integer 2775 TCP port to connect to. BindMode String TRX Type of bind request to use, must be one of TX, RX or TRX (transmitter, receiver or transceiver). SystemID String rhino SystemID in bind request for authenticating to SMSC. Password String rhino Password in bind request for authenticating to SMSC. RebindInterval Long 5000 Interval (in ms) between re-bind attempts after connection dies. EnquireLinkInterval Long 5000 Interval (in ms) between ENQUIRE_LINK requests. The RA periodically sends these to check the session is still active. EnquireLinkThreshold Integer 5 Number of consecutive failed ENQUIRE_LINK requests, after which the RA will drop the connection and attempt to reconnect to the SMSC. SmppResponseReceivedTimeout Long Time (in ms) that stack waits for a response to be received SmppResponseSentTimeout Long Time (in ms) that stack waits for a response to be sent (to an incoming request). The RA will automatically send a GENERIC_NACK if the SBB has not sent a response. Open Cloud Rhino SMPP RA Users Guide Page 5 of 9

6 SMPP Router Example This example application demonstrates the use of multiple bound RA entities and a routing table profile to implement load balancing and failover for outbound messages. Scenario The application (SBB) needs to send a short message to a mobile subscriber. This is done by sending an SMPP SUBMIT_SM PDU to one of a number of SMSCs on the mobile network. In this example assume we have two SMSCs, with hostnames smsc1 and smsc2. To implement load balancing and failover, a simple routing mechanism is used based on the SUBMIT_SM PDU source address (the application short code or phone number), and the last 2 digits of the destination address (mobile subscriber phone number). An example routing table is shown below. Source Dest Last 2 Digits Route preference smsc1, smsc smsc2, smsc smsc1, smsc smsc2, smsc1 The first row should be read as: if the source address is 4444 and the last 2 digits of the destination address are in the range 00-49, then use smsc1 first, and fall back to smsc2 if smsc1 is not available. Similarly the second row specifies that smsc2 should be used first if the destination last 2 digits are in the range In this way, the load can be divided between 2 or more SMSCs, and if a SMSC fails, requests will automatically go to the next SMSC in the list. Implementation This table can easily be implemented as a SLEE profile table, with String attributes for source address and destination last digits, and the route preference attribute can be implemented using an array of Strings since SLEE profile attributes can also be arrays. Because SBBs cannot open SMPP connections themselves, they must be able to select from a number of RA entities to find the correct outgoing route for a message. This can be done using the JNDI names for the RA entities. Each RA entity is bound to a unique JNDI name in the SBBs name space, using the <resource-adaptorentity-binding> element in the SBB deployment descriptor. The names in the route preference field of the profile can refer to JNDI names. After finding the list of JNDI names in the routing profile, the SBB can lookup the names and obtain a reference to the SmppBoundSession interface exposed by each RA entity. This allows the SBB to send the message. If a send fails, or the RA entity is not available, then the next RA entity in the list can be tried, and so on. Open Cloud Rhino SMPP RA Users Guide Page 6 of 9

7 Example Code Included in the package test.rhino.testapps.smpp.router is an example SBB and profile that implements the system described above. The source code is under examples/smpp/src. The relevant Java classes are: test.rhino.testapps.smpp.router.smpprouterbasesbb: this is a base class containing the logic for searching the routing table and selecting a SMSC (RA entity). test.rhino.testapps.smpp.router.client.smpprouterclientsbb: this is the main SBB that receives SMPP events and sends messages using methods from the router base class above. test.rhino.testapps.smpp.router.profile.smpproutingprofilecmp: this is the profile specification for the routing table. The example SBB, SmppRouterClientSbb, is configured to bind to two RA entities using the JNDI names slee/resources/smpp/smsc1 and slee/resources/smpp/smsc2, specified in the sbb-jar.xml deployment descriptor. The RA entities must be created before deploying the SBB. Each RA entity is bound to a RA link name, which is used in the sbb-jar.xml deployment descriptor to link the JNDI name to the RA entity. The logic for searching the profile and selecting a RA entity is in the superclass SmppRouterBaseSbb. The routing logic obtains the SMSC list from the profile, and attempts to lookup the RA entities in JNDI by prepending "slee/resources/smpp/" to the SMSC name from the profile. The supplied Ant build script contains targets for deploying the example application. By default, the build script creates 2 RA entities, that connect to localhost:2775 and localhost:2776. If these are not appropriate then they must be changed in the build script or the entities can be created manually using the Rhino management interfaces. A simple test program is supplied that mimics a SMSC. The test program, invoked using the script "smsc_deliver_sm.sh" in the examples/smpp directory, listens on a TCP port for SMPP connections. When a bound SMPP session is established, the user can send DELIVER_SM requests to the other node, simulating a SMSC sending short messages to an application. A number of instances of smsc_deliver_sm.sh can be run to simulate multiple SMSCs. When the SmppRouterClientSbb receives a DELIVER_SM event, it sends the DELIVER_SM_RESP message as per the SMPP protocol, and then sends a SUBMIT_SM request to one of the configured SMSCs, using the routing table. This mimics the operation of a messaging application where an acknowledgment short message is sent back to the mobile subscriber. The SMPP bound RA and SmppRouterClientSbb can be deployed using the supplied Ant build script in examples/smpp, as shown below. $ ant deploysmppboundra Buildfile: build.xml deploysmppboundra: [sleemgmt] installed: DeployableUnit[url=file:///tmp/sdk/examples/smpp/ prebuilt-jars/smpp-bound-ra.jar] Open Cloud Rhino SMPP RA Users Guide Page 7 of 9

8 Creating RA Entity with properties: SMSCHost=localhost, SMSCPort=2775,SystemID=rhino,Password=rhino [sleemgmt] Created ResourceAdaptorEntity[resource adaptor=smpp-bound 1.0, Open Cloud,entity id=0] [sleemgmt] Bound ResourceAdaptorEntity[resource adaptor=smpp-bound 1.0, Open Cloud,entity id=0] to link name smsc1 [sleemgmt] Activated ResourceAdaptorEntity[resource adaptor=smpp-bound 1.0, Open Cloud,entity id=0] Creating RA Entity with properties: SMSCHost=localhost, SMSCPort=2776,SystemID=rhino,Password=rhino [sleemgmt] Created ResourceAdaptorEntity[resource adaptor=smpp-bound 1.0, Open Cloud,entity id=1] [sleemgmt] Bound ResourceAdaptorEntity[resource adaptor=smpp-bound 1.0, Open Cloud,entity id=1] to link name smsc2 [sleemgmt] Activated ResourceAdaptorEntity[resource adaptor=smpp-bound 1.0, Open Cloud,entity id=1] BUILD SUCCESSFUL $ ant deployroutingprofile Buildfile: build.xml init: [mkdir] Created dir: /tmp/sdk/examples/smpp/jars [mkdir] Created dir: /tmp/sdk/examples/smpp/classes compile-smpptests: [mkdir] Created dir: /tmp/sdk/examples/smpp/classes/smpptests [javac] Compiling 6 source files to /tmp/sdk/examples/smpp/classes/smpptests buildroutingprofile: [jar] Building jar: /tmp/sdk/examples/smpp/jars/profile.jar [jar] Building jar: /tmp/sdk/examples/smpp/jars/ smpp-routing-profile.jar [delete] Deleting: /tmp/sdk/examples/smpp/jars/profile.jar deployroutingprofile: [sleemgmt] installed: DeployableUnit[url=file:///tmp/sdk/examples/smpp/ jars/smpp-routing-profile.jar] [sleemgmt] Created profile table SmppRoutingTable Creating default routing entry in profile SmppRoutingTable/defaultroute: SourceAddress = * DestLastDigits = SMSCList = [smsc1, smsc2] [sleemgmt] Created profile SmppRoutingTable/defaultroute [sleemgmt] Set attributes in profile SmppRoutingTable/defaultroute BUILD SUCCESSFUL $ ant deployrouterclient Buildfile: build.xml init: compile-smpptests: buildrouterclient: [jar] Building jar: /tmp/sdk/examples/smpp/jars/smpp-router-sbb.jar [jar] Building jar: /tmp/sdk/examples/smpp/jars/ smpp-router-service.jar [delete] Deleting: /export/home/ben/rhino_tck/examples/smpp/jars/ smpp-router-sbb.jar deployrouterclient: [sleemgmt] installed: DeployableUnit[url=file:///tmp/sdk/examples/smpp/ jars/smpp-router-service.jar] [sleemgmt] Activated Service[SMPP Router Client Service 1.0, Open Cloud] Open Cloud Rhino SMPP RA Users Guide Page 8 of 9

9 BUILD SUCCESSFUL The source code for the test programs called by the smpp_test_client.sh and smsc_deliver_sm.sh test scripts can be found under examples/smpp/src/com/opencloud/slee/resources/smpp/test. These are simple standalone SMPP applications that use the Open Cloud SMPP API. Open Cloud Rhino SMPP RA Users Guide Page 9 of 9