About the SMPP Resource Adaptor

The Short Message Peer-to-Peer Protocol (SMPP) resource adaptor provides support for writing SMPP services that can act in either a External Short Message Entity (ESME) or Message Center (MC) role.

It supports persistent "bound" connections to a Message Centre, in which the resource adaptor is responsible for all session-related logic (connecting, binding, etc.), as well as generic SMPP services, in which the service is responsible for managing the session.

When using service-managed sessions, services can function as ESME or MC nodes, or both (an RE or Routing Entity). The type of node is determined automatically when the service sends or receives its first PDUs in a session. For example, if a service 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. For example, an MC cannot send SUBMIT_SM requests because this is not allowed by the SMPP protocol.

When using bound connections, services may only function as ESME nodes. They cannot open or close SMPP sessions, or send or receive session-related requests.

Topics

Resource Adaptor Configuration

How to configure general settings for a resource adaptor entity

Profile Configuration

How to use profiles to configure bound sessions

Events

Events fired by the resource adaptor when messages are received

MBeans

The management beans which can be used to view the state of bound sessions

Other documentation for the SMPP Resource Adaptor can be found on the SMPP Resource Adaptor product page.

Resource Adaptor Configuration

Resource adaptor configuration properties apply to when the resource adaptor is acting as a server and for service-managed client sessions. The only configuration properties used in bound mode are the two properties that reference the profiles (BoundSessionConfigurationProfileTable and BoundSessionConfigurationProfileNames), as well as SmppResponseReceivedTimeout and SmppStateCheckingEnabled. See Profile Configuration for information about configuration of bound sessions.

Warning

We do not recommend using service-managed client or server sessions and bound sessions in a single entity. So do not set both SmppBindAddresses and BoundSessionConfigurationProfile…​, or open a session from the provider of an entity that has either of these set.

The resource adaptor will handle these cases but they are not supported for live production environments.

Table 1. Resource Adaptor Configuration Properties
Property Name Type Default Comment

SmppBindAddresses

String

Allows a different bind address (network address and port combination) to be specified for each node in a cluster. See note below.

SmppListenAddress

String

Local IP address to listen on (empty = listen on all addresses). SmppBindAddresses should be used in preference to this.

SmppListenPort

Integer

2775

Local TCP port to listen on. SmppBindAddresses should be used in preference to this.

SmppSessionInitTimeout

Long

30000

Timeout (in ms) for session init, an SMPP_TIMEOUT_SESSION_INIT event will be fired if session was not bound this amount of time after TCP connection opened

SmppEnquireLinkTimeout

Long

60000

Timeout (in ms) for link enquiry, an SMPP_TIMEOUT_ENQUIRE_LINK event will be fired periodically using this interval

SmppInactivityTimeout

Long

120000

Timeout (in ms) for session inactivity, an SMPP_TIMEOUT_INACTIVITY event will be fired if session is inactive for this amount of time

SmppResponseReceivedTimeout

Long

11000

Timeout (in ms) for receiving a response from the a peer, an SMPP_TIMEOUT_RESPONSE_RECEIVED will be fired if this amount of time passes

SmppResponseSentTimeout

Long

10000

Timeout (in ms) for a service to send a response to an incoming request, resource adaptor will send a GENERIC_NACK it this amount of time passes

SmppStateCheckingEnabled

Boolean

true

Determines whether stack checks for correct session state when sending/receiving messages.

BoundSessionConfigurationProfileTable

String

The profile table containing bound session configuration profiles.

BoundSessionConfigurationProfileNames

String

The names of the bound session configuration profiles.

Notes

SmppSessionInitTimeout, SmppEnquireLinkTimeout and SmppInactivityTimeout

These properties control timers in the resource adaptor and fire a SLEE event when the timeout elapses.

Important

The resource adaptor does not send any messages or perform any other action as a result of these timeouts elapsing, other than to fire an event so the service managing the session can take some action.

The exception to this is that if the inactivity timeout fires for a second time, the resource adaptor assumes the service has not closed the connection as it supposed to, and closes it itself.

SmppBindAddresses, SmppListenAddress and SmppListenPort

These properties are used to specify an address and port for a TCP listen socket.

Tip We recommend always using SmppBindAddresses. SmppListenAddress and SmppListenPort exist for compatibility with deployment scripts that used a previous version of the resource adaptor.

The SmppBindAddresses property allows a different bind address (network address and port combination) to be specified for each node in a cluster.

It is a string property with the format

{node}address:port,{node}address:port,...

This allows entities running on two nodes on the same host to use different ports, for example:

{101}0.0.0.0:2775,{102}0.0.0.0:2776

It also allows entities running on different hosts to specify an interface to listen on that is specific to each host, for example:

{101}192.168.1.100:2775,{102}192.168.1.101:2775
Important If SmppBindAddresses is empty, then SmppListenAddress and SmppListenPort will be used, and the same bind address will be used on all nodes. This configuration is not recommended.

Active Reconfiguration

The resource adaptor supports active reconfiguration. You can update most configuration properties without having to deactivate the resource adaptor entity. The only properties that cannot be updated while the entity is active are SmppListenAddress, SmppListenPort and SmppBindAddresses.

Tip When BoundSessionConfigurationProfileNames is updated, the resource adaptor will compare the new value with the previous one to determine which sessions need to be stopped, started or reconfigured.

Profile Configuration

Bound sessions are configured using SLEE profiles. You must create one profile per bound session peer.

Information about more general resource adaptor configuration properties is in resource adaptor configuration.

Table 2. SmppBoundSessionConfigurationProfile Attributes
Profile Attribute Type Default Comment

Host

String

localhost

IP address or hostname of SMSC to connect to

Port

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

null

Value for system_id in bind request. Must be 15 characters or less.

Password

String

null

Value for password in bind request. Must be 8 characters or less.

BindInterfaceVersion

String

50

Value for interface_version in bind request. Must be 2-digit hex value, "34" for SMPPv3.4 or "50" for SMPPv5.0

SystemType

String

null

Optional value for system_type in bind request.

Address

String

null

Optional ESME address/range for bind request in the form: ton:npi:address, eg. 1:1:123456

RebindInterval

Integer

5000

Interval (in ms) between re-bind attempts. Must be greater than 100.

EnquireLinkInterval

Integer

5000

Interval (in ms) between ENQUIRE_LINK requests. The resource adaptor periodically sends these to check the session is still active. Set to 0 to disable (not recommended). If set, must be greater than 100.

InactivityTimeout

Integer

15000

If no transactions have completed (including ENQUIRE_LINKs) after this time, the session will be closed. Set to 0 to disable (not recommended). If set, must be greater than 100.

MaxOutgoingRequests

Integer

0

A maximum number of outgoing requests that may be outstanding on this session. 0 means no limit.

PermanentBindFailureCodes

String

ESME_RINVSRCADR, ESME_RBINDFAIL, ESME_RINVPASWD, ESME_RINVSYSID, ESME_RINVSRCTON, ESME_RINVSRCNPI, ESME_RINVSYSTYP

Bind failure codes that are considered permanent - the RA will not attempt to rebind. May be empty.

EnquireLinkInterval/InactivityTimeout

Certain considerations must be taken into account when specifying these values.

ENQUIRE_LINK request messages are sent if no message has been received in the time specified by EnquireLinkInterval.

The ultimate determination of when to disconnect and reconnect is made according to the value of InactivityTimeout. If no messages have been received (including ENQUIRE_LINK or ENQUIRE_LINK_RESP) within this time, then the session is closed.

So it is important that the value of InactivityTimeout be sufficiently larger than EnquireLinkInterval for the desired number of ENQUIRE_LINK attempts to have occurred before the connection is closed.

For example, for the resource adaptor to close the connection after 6 seconds, and have a single ENQUIRE_LINK attempt before that, you might set:

EnquireLinkInterval=5000
InactivityTimeout=6000

To close the connection after 8 seconds, and have two ENQUIRE_LINK attempts before that, you might use:

EnquireLinkInterval=3500
InactivityTimeout=8000

PermanentBindFailureCodes

This configuration property is specified as a comma-delimited list, and may contain status codes or their symbolic names as defined in the SMPP specification.

The default value is: ESME_RINVSRCADR, ESME_RBINDFAIL, ESME_RINVPASWD, ESME_RINVSYSID, ESME_RINVSRCTON, ESME_RINVSRCNPI, ESME_RINVSYSTYP.

Updating Configuration Profiles

Warning Changes to profiles are not automatically picked up by the resource adaptor. The administrator must trigger a configuration reload for the profiles to be reloaded. This applies even when resource adaptor entities are deactivated and reactivated — the configuration profiles will not be reloaded unless triggered by the administrator.

A configuration reload can be triggered in the Rhino command line console:

updateraentityconfigproperties <entity-name>

When using the Rhino Element Manager, you can edit and save an unchanged resource adaptor entity configuration to achieve the same result.

MBeans

The resource adaptor entity will register two types of MBean: SmppMXBean and SmppBoundSessionMXBean.

SmppMXBean

There is one of these per entity. It is registered when the entity is created.

It has attributes for the number of bound sessions, the internal state and links to the bound session MBeans.

The internal state refers to whether the entity regards itself as active and functioning (which is independent of the SLEE container’s view of that state). The possible states are INACTIVE, INITIALISING, INITIALISATION_FAILED, ACTIVE and STOPPING.

SmppBoundSessionMXBean

There is one of these per bound session. It is registered when a bound session name is read from the BoundSessionConfigurationProfileNames configuration property, and deregistered if the bound session is removed from that list.

It has attributes for the bound session name, state, and a link to the entity.

It also has an operation to force an immediate reconnect.

The bound session states are: NEW, DISCONNECTED, CONNECTED, BOUND, RECONNECTING and UNBOUND.

Events

Each type of SMPP Protocol Data Unit (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 below.

The SMPP RA does not emit a SMPP_TIMEOUT_RESPONSE_SENT event, even though this event type is defined by com.opencloud.slee.resources.smpp.SmppErrorEvent. This event is handled internally by the RA, as it means that the application (SBB) has not sent a response to an incoming request within the stack’s ResponseSentTimeout. This may indicate that there was some error in the SLEE during event processing. The RA sends a GENERIC_NACK PDU with status ESME_RSYSERR in this case. The RA also sends a GENERIC_NACK if the event was processed successfully but not handled by any SBBs, or if the event processing failed for some other reason.

Bound sessions

The resource adaptor will not emit any bind request or response events since the session is already bound. The events SMPP_TIMEOUT_SESSION_INIT, SMPP_TIMEOUT_INACTIVITY, SMPP_TIMEOUT_ENQUIRE_LINK, SMPP_NEW_SESSION and SMPP_END_SESSION are not emitted by this resource adaptor since these timeouts are not relevant to SBBs in this mode.

The SMPP_TIMEOUT_RESPONSE_RECEIVED event will be emitted if a response to a request is not received in time (see SmppResponseReceivedTimeout in the configuration properties table below).

SMPP Session Events

Class: com.opencloud.slee.resources.smpp.SmppSessionEvent

  • com.opencloud.slee.resources.smpp.SMPP_NEW_SESSION

  • com.opencloud.slee.resources.smpp.SMPP_END_SESSION

SMPP Request Events

Class: com.opencloud.slee.resources.smpp.SmppRequestEvent

  • com.opencloud.slee.resources.smpp.pdu.ALERT_NOTIFICATION

  • com.opencloud.slee.resources.smpp.pdu.BIND_TRANSMITTER

  • com.opencloud.slee.resources.smpp.pdu.BIND_RECEIVER

  • com.opencloud.slee.resources.smpp.pdu.BIND_TRANSCEIVER

  • com.opencloud.slee.resources.smpp.pdu.DELIVER_SM

  • com.opencloud.slee.resources.smpp.pdu.SUBMIT_SM

  • com.opencloud.slee.resources.smpp.pdu.DATA_SM

  • com.opencloud.slee.resources.smpp.pdu.CANCEL_SM

  • com.opencloud.slee.resources.smpp.pdu.QUERY_SM

  • com.opencloud.slee.resources.smpp.pdu.REPLACE_SM

  • com.opencloud.slee.resources.smpp.pdu.ENQUIRE_LINK

  • com.opencloud.slee.resources.smpp.pdu.OUTBIND

  • com.opencloud.slee.resources.smpp.pdu.UNBIND

SMPP Response Events

Class: com.opencloud.slee.resources.smpp.SmppResponseEvent

  • com.opencloud.slee.resources.smpp.pdu.GENERIC_NACK

  • com.opencloud.slee.resources.smpp.pdu.BIND_TRANSMITTER_RESP

  • com.opencloud.slee.resources.smpp.pdu.BIND_RECEIVER_RESP

  • com.opencloud.slee.resources.smpp.pdu.BIND_TRANSCEIVER_RESP

  • com.opencloud.slee.resources.smpp.pdu.DELIVER_SM_RESP

  • com.opencloud.slee.resources.smpp.pdu.SUBMIT_SM_RESP

  • com.opencloud.slee.resources.smpp.pdu.DATA_SM_RESP

  • com.opencloud.slee.resources.smpp.pdu.CANCEL_SM_RESP

  • com.opencloud.slee.resources.smpp.pdu.QUERY_SM_RESP

  • com.opencloud.slee.resources.smpp.pdu.REPLACE_SM_RESP

  • com.opencloud.slee.resources.smpp.pdu.ENQUIRE_LINK_RESP

  • com.opencloud.slee.resources.smpp.pdu.UNBIND_RESP

SMPP Error Events

Class: com.opencloud.slee.resources.smpp.SmppErrorEvent

  • com.opencloud.slee.resources.smpp.SMPP_ERROR

  • com.opencloud.slee.resources.smpp.SMPP_TIMEOUT_SESSION_INIT

  • com.opencloud.slee.resources.smpp.SMPP_TIMEOUT_ENQUIRE_LINK

  • com.opencloud.slee.resources.smpp.SMPP_TIMEOUT_INACTIVITY

  • com.opencloud.slee.resources.smpp.SMPP_TIMEOUT_RESPONSE_RECEIVED

  • com.opencloud.slee.resources.smpp.SMPP_TIMEOUT_RESPONSE_SENT

Session State Diagram

The state diagram shows the states and transitions that an SMPP Session can go through.

Note that for brevity each type of bind request has not been shown, instead BIND_xxx is used to denote BIND_TRANSMITTER, BIND_RECEIVER and BIND_TRANSCEIVER.

Note that, in any of the above states, either node closing the session will cause a transition to the INVALID state.

session state diagram

Example Transmitter Session

Session Example