spring-boot-starter-smpp

This Spring Boot starter can be used by any Spring Boot application that wants to send SMS messages using SMPP. SMPP v3.4 spec

Features

• Sending message with delivery receipt
• Sending datagram message (without delivery receipt)
• Sending silent message
• Sending flash message
• Cancel message
• Multiply SMPP connection
• SMPP connection load balancing

Usage

Add the following dependency to your project:

Maven:

<dependency>
  <groupId>com.github.mikesafonov</groupId>
  <artifactId>spring-boot-starter-smpp</artifactId>
  <version>latest</version>
</dependency>

Gradle:

dependencies {
    implementation 'com.github.mikesafonov:spring-boot-starter-smpp:latest'
}

Configure spring-boot application via properties (see Configuration section).

Use SenderManager to send SMS:

public class RoundRobinApplicationService {
    private final SenderManager senderManager;

    public void sendMessage(String from, String to, String text) {
        Message message = Message.simple(text)
                .from(from)
                .to(to)
                .build();
        senderManager.getClient().send(message);
    }
}

Configuration

The following tables show the available configuration:

Configuration	Description	Default
smpp.defaults	Default smpp connection properties
smpp.defaults.ucs2Only	Using ucs2 encoding only or not	false
smpp.defaults.maxTry	Number of attempts to reconnect if smpp session is closed	5
smpp.defaults.connectionMode	Client connection mode (STANDARD, TEST, MOCK)	STANDARD
smpp.defaults.windowSize	Smpp connection window size	90
smpp.defaults.loggingPdu	Is logging smpp pdu	false
smpp.defaults.loggingBytes	Is logging smpp bytes	false
smpp.defaults.rebindPeriod	Connection rebind period (Duration)	90s
smpp.defaults.requestTimeout	Request timeout (Duration)	5s
smpp.defaults.allowedPhones	Array of phones to send. Using only if connectionMode is TEST	[]
smpp.defaults.connectionType	Type of smpp connections(TRANSCEIVER or TRANSMITTER_RECEIVER)	TRANSMITTER_RECEIVER
smpp.connections	Map of SMSC connections
smpp.connections.<name>.credentials	SMSC connection credentials
smpp.connections.<name>.credentials.host	SMSC host
smpp.connections.<name>.credentials.port	SMSC port
smpp.connections.<name>.credentials.username	SMSC username
smpp.connections.<name>.credentials.password	SMSC password
smpp.connections.<name>.ucs2Only	Using ucs2 encoding only or not	false
smpp.connections.<name>.maxTry	Number of attempts to reconnect if smpp session is closed	5
smpp.connections.<name>.connectionMode	Client`s connection mode	STANDARD see com.github.mikesafonov.smpp.config.ConnectionMode
smpp.connections.<name>.windowSize	Smpp connection window size	90
smpp.connections.<name>.loggingPdu	Is logging smpp pdu	false
smpp.connections.<name>.loggingBytes	Is logging smpp bytes	false
smpp.connections.<name>.rebindPeriod	Connection rebind period (Duration)	90s
smpp.connections.<name>.requestTimeout	Request timeout (Duration)	5s
smpp.connections.<name>.allowedPhones	Array of phones to send. Using only if connectionMode is TEST	[]
smpp.connections.<name>.connectionType	Type of smpp connections(TRANSCEIVER or TRANSMITTER_RECEIVER)
smpp.connections.<name>.systemType	The systemType parameter is used to categorize the type of ESME that is binding to the SMSC.
smpp.setupRightAway	Should setup smpp clients after creation and fail fast if connection cant be established	true

Configuration example for .properties file:

smpp.connections.one.credentials.host=localhost
smpp.connections.one.credentials.username=user
smpp.connections.one.credentials.password=pass
smpp.connections.one.credentials.port=1111
smpp.connections.two.credentials.host=localhost
smpp.connections.two.credentials.username=user2
smpp.connections.two.credentials.password=pass2
smpp.connections.two.credentials.port=2222

Configuration example for .yaml file:

smpp:
    default:
        maxTry: 10
        ucs2Only: true
    connections:
        one:
           credentials:
                host: localhost
                username: user
                password: pass
                port: 1111
        two:
           credentials:
                host: localhost
                username: user2
                password: pass2
                port: 2222

Build

Build from source

You can build application using following command:

./gradlew clean build -x signArchives

Requirements:

JDK >= 1.8

Unit tests

You can run unit tests using following command:

./gradlew test

Mutation tests

You can run mutation tests using following command:

./grdlew pitest

You will be able to find pitest report in build/reports/pitest/ folder.

Integration tests

You can run integration tests using following command:

./grdlew testIntegration

Key abstractions

This starter provides several abstractions:

SenderClient

This interface represents smpp protocol TRANSMITTER or TRANSCEIVER (see connectionType property) client. This is entry point to sending any messages. Spring-boot-starter-smpp comes with several implementations:

DefaultSenderClient

This is default implementation. DefaultSenderClient creates real smpp connection and performing all requests.

TestSenderClient

TestSenderClient should be used for testing purpose. TestSenderClient client may provide real smpp connection via proxy implementation of SenderClient. Every incoming request will be redirected to real SenderClient only if destination phone contains in list of allowed phone (smpp.connections.<name>.allowedPhones property). Otherwise response will be generated by SmppResultGenerator.

MockSenderClient

MockSenderClient does not perform any connection via smpp and only generate response using SmppResultGenerator.

SmppResultGenerator

Implementations of this interface is used by MockSenderClient and TestSenderClient clients to generate request response.

Starter by default use AlwaysSuccessSmppResultGenerator which always generate success response with random smsc message id.

You can implement own SmppResultGenerator to add custom logic.

TypeOfAddressParser

DefaultSenderClient use implementation of TypeOfAddressParser to detect TON and NPI parameters for source and destination address of message. Starter provide DefaultTypeOfAddressParser and UnknownTypeOfAddressParser implementations.

By default starter use DefaultTypeOfAddressParser. DefaultTypeOfAddressParser supports international and alphanumeric ton parameters, otherwise return UNKNOWN ton/npi.

UnknownTypeOfAddressParser always return UNKNOWN ton/npi. This means what your SMS center must detect this parameters by himself.

ResponseClient

This abstraction represent connection via SMPP with RECEIVER or TRANSCEIVER (see connectionType property) type. Key purpose is listening delivery receipts. By default starter use DefaultResponseClient. This class keeping smpp connection and pushing all incoming PDU to SmppSessionListener.

SmppSessionListener

This class dedicated to listening all incoming PDU traffic. By default starter use ResponseSmppSessionHandler. This class find delivery receipts and push to DeliveryReportConsumer.

DeliveryReportConsumer dedicated to handle DeliveryReport on client side. Client may build custom logic on receiving delivery receipts by implementing this interface. Starter use by default NullDeliveryReportConsumer if client doesnt provide any implementation of DeliveryReportConsumer. NullDeliveryReportConsumer ignore any delivery receipts.

You can use custom SmppSessionListener by creating appropriate bean.

SenderManager

This is high level abstraction over sender clients.

This starter comes with one default implementation - StrategySenderManager. StrategySenderManager holds list of smsc connections and return sender client based on some rules which implemented by IndexDetectionStrategy

There are two default implementation of IndexDetectionStrategy - RandomIndexDetectionStrategy(return random sender client) and RoundRobinIndexDetectionStrategy (return sender client based on round and robbin algorithm). RoundRobinIndexDetectionStrategy strategy used by default.

Contributing

Feel free to contribute. New feature proposals and bug fixes should be submitted as GitHub pull requests. Fork the repository on GitHub, prepare your change on your forked copy, and submit a pull request.

IMPORTANT!

Before contributing please read about Conventional Commits / Conventional Commits RU