/spring-boot-starter-smpp

Spring boot starter to send SMS via SMPP

Primary LanguageJavaMIT LicenseMIT

spring-boot-starter-smpp

Maven Central codecov Travis-CI Conventional Commits

Quality Gate Status Reliability Rating Maintainability Rating Security Rating

Bugs Code Smells Vulnerabilities

Duplicated Lines (%) Lines of Code Technical Debt

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
  • 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>1.0.0</version>
</dependency>

Gradle:

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

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.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.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 provide several abstractions:

SenderClient

This interface represents smpp protocol TRANSMITTER client. This is entry point to sending any messages. Spring-boot-starter-smpp comes with several implementations:

class diagram

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 type. Key purpose is listening delivery receipts. By default starter use DefaultResponseClient. This class keeping smpp connection and pushing delivery receipts to DeliveryReportConsumer.

DeliveryReportConsumer

This class 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.

SenderManager

This is high level abstraction over sender clients.

class diagram

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