Laravel is a modern web application framework for artisans.

Introduction

Building a dockerfile for a Laravel application does not need to be tedious. The good folks at The Coding Machine have created several base images that we can leverage.

Prerequisites

You need to have the following setup on your development machine to proceed with this tutorial

1. PHP >= 7.3
2. Composer
3. Laravel
4. Docker

Let’s get started

Create a new laravel project

> laravel new laravel-app

and navigate into the laravel-app directory and execute the following command:

> php artisan serve

Try it out in your browser localhost:8000

Before we create our Dockerfile lets first create a .dockerignore file:

file: laravel-app\.dockerignore

node_modules/
public/hot/
public/storage/
storage/*.key
vendor/
.env.backup
.phpunit.result.cache
Homestead.json
Homestead.yaml
npm-debug.log
yarn-error.log
Dockerfile
docker-compose.yml
docker-compose.yaml
**.git
.idea
**.gitignore
**.gitattributes
**.sass-cache

We can now create our Dockerfile:

file: laravel-app\Dockerfile

ARG PHP_EXTENSIONS="intl pdo_mysql pdo_pgsql bcmath"

FROM thecodingmachine/php:7.4-v3-slim-apache as php_base
LABEL maintainer "Julius Krah <juliuskrah@gmail.com>"

ENV TEMPLATE_PHP_INI=production
COPY --chown=docker:docker . /var/www/html
RUN composer install --quiet --optimize-autoloader --no-dev

FROM node:10 as node_dependencies
WORKDIR /var/www/html

ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=false
COPY --from=php_base /var/www/html /var/www/html

RUN npm set progress=false && \
  npm config set depth 0 && \
  npm install && \
  npm run prod && \
  rm -rf node_modules

FROM php_base
ENV APACHE_DOCUMENT_ROOT=/var/www/html/public
COPY --from=node_dependencies --chown=docker:docker /var/www/html /var/www/html

Build and tag the image:

> docker build -t laravel-app .

Time to test our image with a container

> docker run --rm --name laravel -e DB_CONNECTION=pgsql -p 8000:80 laravel-app

NOTE: You can replace all options in the .env file with environment variables on the command line e.g. -e DB_CONNECTION=pgsql

Conclusion

An optional step is to tag and upload your image to docker hub:

> docker tag laravel-app <username>/laravel-app
> docker login
> docker push <username>/laravel-app

In this post we discussed creating a laravel project and making an OCI image out of it. Until the next post, keep doing cool things :+1:.

Short Message Peer-to-Peer (SMPP) is a protocol used by the telecommunications industry for exchanging messages between Short Message Service Centers (SMSC) and/or External Short Messaging Entities (ESME).

Introduction

In this post I will build a simple app that will send SMS using the SMPP protocol, bootstraped with Spring Boot and Camel. To use CloudHopper to send SMS refer to the CloudHopper Post.

SMPP is a level-7 TCP/IP protocol, which allows fast delivery of SMS messages. The most conmmonly used versions of SMPP are v3.3, the most widely supported standard, and v3.4, which adds transceiver support (single connections that can send and receive messages).

Prerequisites

• Java Development Kit
• Maven
• SMPP account that supports v3.4

.
|__src/
|  |__main/
|  |  |__java/
|  |  |  |__com/
|  |  |  |  |__juliuskrah/
|  |  |  |  |  |__smpp/
|  |  |  |  |  |  |__Application.java
|  |  |  |  |  |  |__MessageReceiver.java
|  |  |  |  |  |  |__MessageRoute.java
|  |  |__resources/
|  |  |  |__application.yaml
|__pom.xml

Project Setup

Create a simple Spring Boot Application by heading over to start.spring.io. Add the following to your pom.xml (assuming you picked maven) after creating your Spring-Boot application:

<!-- Sections omitted -->
<properties>
  <java.version>11</java.version>
  <camel-spring.version>3.1.0</camel-spring.version>
</properties>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.apache.camel.springboot</groupId>
      <artifactId>camel-spring-boot-dependencies</artifactId>
      <version>${camel-spring.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.apache.camel.springboot</groupId>
    <artifactId>camel-spring-boot-starter</artifactId>
  </dependency>
  <dependency>
    <groupId>org.apache.camel.springboot</groupId>
    <artifactId>camel-smpp-starter</artifactId>
  </dependency>
  <dependency>
    <groupId>org.apache.camel.springboot</groupId>
    <artifactId>camel-bean-starter</artifactId>
  </dependency>
</dependencies>

Configuring Came SMPP

SMPP using camel is very covenient, as it provides some auto-configuration for Spring. We need the following configuration to get started:

file: src/main/resources/application.yaml

camel:
  component:
    enabled: true
    smpp:
      configuration:
        host: :smpp.host:
        password: :password:
        system-id: :user:
        source-addr-ton: 0x05
        source-addr-npi: 0x01
        dest-addr-npi: 0x01
        dest-addr-ton: 0x01
        registered-delivery: 1
    bean:
      scope: singleton
  springboot:
    name: smpp-app
    main-run-controller: false

NOTE: Be sure to replace the values for host, system-id and password. You can get these values from your SMPP service provider.

That’s all we need. Now let’s add code to send an SMS

Send an SMS

We will add a simple method that sends an SMS on application bootstrap:

private Exchange sendTextMessage(ProducerTemplate template, String sourceAddress,
      String destinationAddress, String message) {
    var exchange = ExchangeBuilder.anExchange(context)
        .withHeader("CamelSmppDestAddr", List.of(destinationAddress))
        .withHeader("CamelSmppSourceAddr", sourceAddress)
        .withPattern(ExchangePattern.InOnly)
        .withBody(message).build();
    
    // exceptions are not thrown from this method
    // exceptions are stored in Exchange#setException()
    return template.send("smpp://{{camel.component.smpp.configuration.host}}", exchange);
    
}

With this method created, we can call it on application startup with a CommandlineRunner

@Bean
CommandLineRunner init(ProducerTemplate template) {
    return args -> {
        var exchange = sendTextMessage(template, "5432", "<replace with phone number>", "Hello World!");
        if (exchange.getException() == null)
            log.info("Message Id - {}", exchange.getMessage().getHeader("CamelSmppId"));
        else
            log.error("Could not send message", exchange.getException());
    };
}

Putting it all together:

file: src/main/java/com/juliuskrah/smpp/Application.java

@SpringBootApplication
public class Application {
    private static final Logger log = LoggerFactory.getLogger(Application.class);
    @Autowired private CamelContext context;

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    private Exchange sendTextMessage(ProducerTemplate template, String sourceAddress,
        String destinationAddress, String message) {
        var exchange = ExchangeBuilder.anExchange(context)
            .withHeader("CamelSmppDestAddr", List.of(destinationAddress))
            .withHeader("CamelSmppSourceAddr", sourceAddress)
            .withPattern(ExchangePattern.InOnly)
            .withBody(message).build();
        
        // exceptions are not thrown from this method
        // exceptions are stored in Exchange#setException()
        return template.send("smpp://{{camel.component.smpp.configuration.host}}", exchange);
        
    }

    @Bean
    CommandLineRunner init(ProducerTemplate template) {
        return args -> {
            var exchange = sendTextMessage(template, "5432", "<replace with phone number>", "Hello World!");
            if (exchange.getException() == null)
                log.info("Message Id - {}", exchange.getMessage().getHeader("CamelSmppId"));
            else
                log.error("Could not send message", exchange.getException());
        };
    }

}

Receive delivery receipts

After sending an SMS you may want to receive delivery receipts. To do this, we will create a bean to process the delivery receipts.

file: src/main/java/com/juliuskrah/smpp/MessageReceiver.java

@Component
public class MessageReceiver {
    private final static Logger log = LoggerFactory.getLogger(MessageReceiver.class);

    public void receive(Exchange exchange) {
        if (exchange.getException() == null) {
            var message = exchange.getIn();
            log.info("Received id {}", message.getHeader("CamelSmppId"));
            log.info("Text :- {}", message.getBody());
            log.info("Total delivered {}", message.getHeader("CamelSmppDelivered"));
            log.info("Message status {}", message.getHeader("CamelSmppStatus"));
            log.info("Submitted date {}", message.getHeader("CamelSmppSubmitDate", Date.class));
            log.info("Done date {}", message.getHeader("CamelSmppDoneDate", Date.class));
        } else
            log.error("Error receiving message", exchange.getException());
    }
}

Next we will create a router to route messages from the SMSC to our bean:

file: src/main/java/com/juliuskrah/smpp/MessageRoute.java

@Component
public class MessageRoute extends RouteBuilder {

    @Override
    public void configure() throws Exception {
        
        from("smpp://{{camel.component.smpp.configuration.host}}")
                .to("bean:messageReceiver?method=receive");
        
    }   
}

Conclusion

In this post we looked briefly at the SMPP protocol and its usage within the JVM. We also covered how to use Spring Boot and Camel to make developing an SMPP client easier.

As usual you can find the full example to this guide in the github repository. Until the next post, keep doing cool things :+1:.

JasperReports is a Java library, and it is meant for Java developers who need to add reporting to their applications.

Introduction

In this post, we will create an excel report that is exposed over RESTful endpoint using Spring Boot. In a previous post we looked at how to expose Jasper PDF over REST.

Prerequisites

• Java Development Kit 11+
• Maven

Project Structure

At the end of this guide our folder structure will look similar to the following:

.
|__src/
|  |__main/
|  |  |__java/
|  |  |  |__com/
|  |  |  |  |__juliuskrah/
|  |  |  |  |  |__jasper/
|  |  |  |  |  |  |__Application.java
|  |  |  |  |  |  |__ApplicationProperties.java
|  |  |  |  |  |  |__report/
|  |  |  |  |  |  |  |__JasperReportsService.java
|  |  |  |  |  |  |  |__ReportService.java
|  |  |  |  |  |  |__storage/
|  |  |  |  |  |  |  |__FileSystemStorageService.java
|  |  |  |  |  |  |  |__StorageException.java
|  |  |  |  |  |  |  |__StorageFileNotFoundException.java
|  |  |  |  |  |  |  |__StorageService.java
|  |  |  |  |  |  |__web/
|  |  |  |  |  |  |  |__rest/
|  |  |  |  |  |  |  |  |__ApplicationResource.java
|  |  |__resources/
|  |  |  |__reports/
|  |  |  |  |__pdf_rest_resource.jrxml
|  |  |  |  |__pdf_rest.jrxml
|  |  |  |__application.yaml
|  |  |  |__cherry.png
|  |  |  |__logo.png
|__pom.xml

How to complete this guide

To complete this guide, download (zip| tar.gz) and unzip the source repository for this guide.

Create Excel Report

Let us start by implementing a solution to generate excel in JasperReports:

file: src/main/java/com/juliuskrah/jasper/report/JasperReportsService.java

@Component
public class JasperReportsService implements ReportService {
  // ...
  @Override
  public byte[] generatePDFReport(String inputFileName, Map<String, Object> params,
    JRDataSource dataSource) {
    byte[] bytes = null;
    JasperReport jasperReport = null;
    try {
      if (storageService.jasperFileExists(inputFileName)) {
        jasperReport = (JasperReport) JRLoader.loadObject(storageService.loadJasperFile(inputFileName));
      } else {
        var jrxml = storageService.loadJrxmlFile(inputFileName);
        jasperReport = JasperCompileManager.compileReport(jrxml);
        // Save the compiled report for use on next invocation
        JRSaver.saveObject(jasperReport, storageService.loadJasperFile(inputFileName));
      }
      JasperPrint jasperPrint = JasperFillManager.fillReport(jasperReport, params, dataSource);
      var input = new SimpleExporterInput(jasperPrint);
      try (var byteArray = new ByteArrayOutputStream()) {
        var output = new SimpleOutputStreamExporterOutput(byteArray);
        var exporter = new JRXlsxExporter();
        exporter.setExporterInput(input);
        exporter.setExporterOutput(output);
        exporter.exportReport();
        bytes = byteArray.toByteArray();
        output.close();
      } catch (IOException e) {
        // handle IO error
      }
      return bytes;
    } catch (JRException e) {
      // handle error
    }
    return bytes;
  }
}

Render the Excel REST Endpoint

We will create the REST endpoint:

file: src/main/java/com/juliuskrah/jasper/web/rest/ApplicationResource.java

@RestController
public class ApplicationResource {
  // ...
  @GetMapping("/{username}")
  public ResponseEntity<byte[]> report(@PathVariable String username) {
    Map<String, Object> params = new HashMap<>();
    params.put("username", username);
    byte[] bytes = reportService.generatePDFReport("pdf_rest_resource", params);
    var contentDisposition = ContentDisposition.builder("attachment")
      .filename(username + ".xlsx").build();
    HttpHeaders headers = new HttpHeaders();
    headers.setContentDisposition(contentDisposition);
    return ResponseEntity
      .ok()
      // Specify content type as excel
      .header("Content-Type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet; charset=UTF-8")
      // Tell browser to download Excel if it can
      .headers(headers) //
      .body(bytes);
  }
}

Now navigate to http://localhost:8080/:username to view your report.

Conclusion

In this post we learned how to generate Excel with JasperReports and serve it over HTTP with Spring Boot. As usual you can find the full example to this guide in the github repository. Until the next post, keep doing cool things :+1:.

Change data capture records insert, update, and delete activity that is applied to a relational database table.

Introduction

In a microservices architecture, keeping consistent state between services becomes tedious. Several techniques have been employed over the years to tackle these challenges. One such approach is Eventual Consistency. When you want to update an ElasticSearch index with data from PostgreSQL, you have to rely on one of these techniques to keep data up-to-date.

In this blog post I will discuss an alternate technique using Change Data Capture (CDC). CDC¹ is a set of software design patterns used to determine the data that has changed so that action can be taken using the changed data. I have put together a little demo application to showcase this. In the demo I am streaming users created in Keycloak and saving them in a Java application.

Solution Architecture

Fig 1 Solution showing all the components functioning together

There are several open source CDC tools out there in the wild. I have chosen to go with Debezium and PostgreSQL; you can choose any combination of your choice. To start debzium, for CDC the following ritual must be performed.

First you have to configure your database of choice to enable CDC streaming. At the time of this writing debezium² supports the following databases:

• MongoDB
• MySQL
• PostgreSQL
• SQL Server
• Oracle
• Cassandra

PostgreSQL

We are using PostgreSQL for this demo. PostgreSQL uses a logical decoder that writes change events to a Write Ahead Log (WAL)³ after they are committed. PostgreSQL’s logical decoding feature was first introduced in version 9.4 and is a mechanism which allows the extraction of the changes which were committed to the transaction log. The changes are processed in a user-friendly manner via the help of an output plugin. The logical decoding output plugin must be installed prior to running the PostgreSQL server and enabled together with a replication slot. The output plugins supported by debezium are:

• decoderbufs
• wal2json
• pgoutput⁴ - standard logical decoding plug-in in PostgreSQL 10+

I will be using pgoutput because it requires no additional libraries to be installed. Next enable a replication slot, and configure a user with sufficient privileges to perform the replication.

According to the postgres documentation, a user with REPLICATION role is enough for CDC, however in my case I’ve never managed to get it to work with the debezium postgres connector. Let me know in the comments if you are successful. I create a user with SUPERUSER role for this purpose;

psql> CREATE ROLE postgres SUPERUSER LOGIN;
psql> ALTER ROLE postgres WITH PASSWORD 'postgrespwd';

then configure the PostgreSQL server to allow replication;

file: pg_hba.conf

local   replication     postgres                          trust   
host    replication     postgres  127.0.0.1/32            trust   
host    replication     postgres  ::1/128                 trust   

and finally configure the replication slot:

file: postgresql.conf

wal_level = logical             
max_wal_senders = 1             
max_replication_slots = 5      

With PostgreSQL up and running, create the database and user for Keycloak:

pasql> CREATE USER sample WITH PASSWORD 'sample';
pasql> CREATE DATABASE sample;
pasql> GRANT ALL PRIVILEGES ON DATABASE sample TO sample;
pasql> \c sample;
pasql> CREATE SCHEMA IF NOT EXISTS AUTHORIZATION sample;

Kafka and Zookeeper

You now need to configure Kafka and Zookeeper. I will not demonstrate how to setup Kafka and Zookeeper; everything required to run this demo is setup in a docker file.

Keycloak

Once keycloak is installed, import the sample realm. You can also run the compose file to get everything up and running.

Kafka Connect

Debezium is a Kafka Connect connector; It can be easily setup using the compose file.

Once the connector is ready to recieve connections, we make a post request to create our CDC Connector:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
> curl -s \
     -X "POST" "http://localhost:8083/connectors/" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "keycloak-connector",
  "config": {
    "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
    "database.hostname": "postgres",
    "database.port": "5432",
    "slot.name": "keycloak_debezium",
    "plugin.name": "pgoutput",
    "database.user": "postgres",
    "database.password": "postgrespwd",
    "database.dbname": "sample",
    "database.server.name": "keycloak",
    "schema.whitelist": "sample",
    "table.whitelist": "sample.user_role_mapping,sample.user_group_membership,sample.keycloak_role,sample.user_entity"
  }
}'

A brief description of the payload above;

• line 5 is the name for this CDC connector. It can be whatever you choose
• line 8 is the database hostname, it can also take an IP address
• line 10 indicates the replication slot you want to create in PostgreSQL server
• on line 11 I am using the pgoutput plugin. Other alternatives are decoderbufs and wal2json, to use these alternatives, you have to install the plugins
• on line 15 I specify a server name (Can be any name you choose). This name is used by the connector when creating the kafka topics. More on this in the next section.
• lines 16 and 17 I indicate which tables I want to capture changes on.

You can read more on the debezium documentation.

The debezium connector will now recieve changes from the PostgreSQL WAL and publish them to Kafka.

I created a sink application to process the changes from Kafka.

CDC Application

I created a representation of the CDC payload from Kafka:

file: app-service/src/main/java/com/juliuskrah/cdc/dto/KeycloakCdcDto.java

public class KeycloakCdcDto<T> {
    private Map<String, Object> schema;
    private Payload<T> payload;

    // Getters and Setters omitted for brevity

    public static class Payload<T> {
        private T before;
        private T after;
        private Map<String, Object> source;
        private char op;
        @JsonProperty("ts_ms")
        private Instant tsMs;
        
        // Getters and Setters omitted for brevity
    }
}

As already hinted in the previous section debezium creates topics in kafka for each table it captures events on in the following format <database.server.name>.<schema_name>.<table_name>. In our example above, the changes on the user_entity table will be stored in the keycloak.sample.user_entity topic.

And the consumer for the event:

file: app-service/src/main/java/com/juliuskrah/cdc/sink/KafkaConsumer.java

@KafkaListener(groupId = "${app.group.id:group-id}", offsetReset = OffsetReset.EARLIEST)
public class KafkaConsumer {

    @Topic("keycloak.sample.user_entity")
    void onReceiveUser(@KafkaKey String key, @Nullable String event) {
        // process here
    }
}

The full source code is in the github repository.

Conclusion

Integration between microservices in any deployment is crucial, and in this post I have discussed using CDC to tackle it. We also tackled setting up PostgreSQL for replication, glanced over setting up Keycloak, Zookeeper and Kafka. We looked at setting up the debezium Kafka Connector and a sample application to consume the CDC event stream. Until the next post, keep doing cool things :+1:.

References

Short Message Peer-to-Peer (SMPP) is a protocol used by the telecommunications industry for exchanging messages between Short Message Service Centers (SMSC) and/or External Short Messaging Entities (ESME).

Introduction

In this post I will build a simple app that will send SMS using the SMPP protocol, bootstraped with Spring Boot. I will use the Cloudhopper SMPP library for sending SMS. For the Camel Component example, refer to this Camel Post.

SMPP is a level-7 TCP/IP protocol, which allows fast delivery of SMS messages. The most conmmonly used versions of SMPP are v3.3, the most widely supported standard, and v3.4, which adds transceiver support (single connections that can send and receive messages).

Prerequisites

• Java Development Kit
• Maven
• SMPP account that supports v3.4

Project Structure

At the end of this guide our folder structure will look similar to the following:

.
|__src/
|  |__main/
|  |  |__java/
|  |  |  |__com/
|  |  |  |  |__juliuskrah/
|  |  |  |  |  |__smpp/
|  |  |  |  |  |  |__Application.java
|  |  |  |  |  |  |__ApplicationProperties.java
|  |  |  |  |  |  |__ClientSmppSessionHandler.java
|  |  |  |  |  |  |__DeliveryReceipt.java
|  |  |__resources/
|  |  |  |__application.yaml
|__pom.xml

Project Setup

Create a simple Spring Boot Application using any of the bootstrap options.

Add the following to your pom.xml after creating your Spring-Boot application:

<dependency>
  <groupId>com.fizzed</groupId>
  <artifactId>ch-smpp</artifactId>
  <version>5.0.9</version>
</dependency>

Configuring the SMPP Session

In order to start using SMPP to send messages, you need to establish a session. The session is usually short-lived; we will implement long-lived sessions later in this post by extending the session periodically.

To bind a session, we need a SmppSessionConfiguration and SmppClient. The SmppSessionConfiguration class contains the configurable aspects of the SmppSession. In this class you can configure the:

• Host: [smpp.serviceprovider.com]
• Port: default 2775
• System Id: [username]
• Password: [password]
• BindType: TRANSCEIVER, TRANSMITTER or RECEIVER
• Version: 3.3, 3.4, 5.0

Configuring this class will look something like the following:

public SmppSessionConfiguration sessionConfiguration() {
  SmppSessionConfiguration sessionConfig = new SmppSessionConfiguration();
  sessionConfig.setName("smpp.session");
  sessionConfig.setInterfaceVersion(SmppConstants.VERSION_3_4);
  sessionConfig.setType(SmppBindType.TRANSCEIVER);
  sessionConfig.setHost("<replace>");
  sessionConfig.setPort(2775);
  sessionConfig.setSystemId("<replace>");
  sessionConfig.setPassword("<replace>");
  sessionConfig.setSystemType(null);
  sessionConfig.getLoggingOptions().setLogBytes(false);
  sessionConfig.getLoggingOptions().setLogPdu(true);

  return sessionConfig;
}

NOTE: Be sure to replace the values for Host, SystemId and Password.

I have set the bind-type as TRANSCEIVER because I want to be able to send SMS and receive delivery receipts.

What I have to do next is create the SmppClient:

public SmppClient clientBootstrap() {
  return new DefaultSmppClient(Executors.newCachedThreadPool(), 2);
}

The DefaultSmppClient constructor takes an ExecutorService and expected number of sessions. In the example above I am creating a CachedThreadPoolExecutor and assigning 2 concurrent sessions.

With these two in place I can now establish my SmppSession:

@Bean(destroyMethod = "destroy")
public SmppSession session() throws SmppBindException, SmppTimeoutException, SmppChannelException,
    UnrecoverablePduException, InterruptedException {
  SmppSessionConfiguration config = sessionConfiguration();
  // Will use the DefaultSmppSessionHandler for now
  SmppSession session = clientBootstrap().bind(config, new DefaultSmppSessionHandler());

  return session;
}

In the above snippet, we are using a DefaultSmppSessionHandler. Later in this post I will create a custom SmppSessionListener that can handle delivery receipts.

At this point all necessary configuration is done. Everything wired up together until this point should look like this:

file: src/main/java/com/juliuskrah/smpp/Application.java

@SpringBootApplication
public class Application {
  private static final Logger log = LoggerFactory.getLogger(Application.class);

  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }

  public SmppSessionConfiguration sessionConfiguration() {
    SmppSessionConfiguration sessionConfig = new SmppSessionConfiguration();
    sessionConfig.setName("smpp.session");
    sessionConfig.setInterfaceVersion(SmppConstants.VERSION_3_4);
    sessionConfig.setType(SmppBindType.TRANSCEIVER);
    sessionConfig.setHost("<replace>");
    sessionConfig.setPort(2775);
    sessionConfig.setSystemId("<replace>");
    sessionConfig.setPassword("<replace>");
    sessionConfig.setSystemType(null);
    sessionConfig.getLoggingOptions().setLogBytes(false);
    sessionConfig.getLoggingOptions().setLogPdu(true);

    return sessionConfig;
  }

  @Bean(destroyMethod = "destroy")
  public SmppSession session() throws SmppBindException, SmppTimeoutException, SmppChannelException,
      UnrecoverablePduException, InterruptedException {
    SmppSessionConfiguration config = sessionConfiguration();
    SmppSession session = clientBootstrap().bind(config, new DefaultSmppSessionHandler());

    return session;
  }

  public SmppClient clientBootstrap() {
    return new DefaultSmppClient(Executors.newCachedThreadPool(), 2);
  }
}

If you have setup your SMPP correctly with your service provider, run the code as a Spring-Boot app:

PS C:\> mvn spring-boot:run

Send an SMS

Stop the aplication if it is still running. I will add a simple method that sends an SMS on application startup:

file: src/main/java/com/juliuskrah/smpp/Application.java

// ...

private void sendTextMessage(SmppSession session, String sourceAddress, String message, String destinationAddress) {
  // Check if session is still active
  if (session.isBound()) {
    try {
      // request delivery
      boolean requestDlr = true;
      SubmitSm submit = new SubmitSm();
      byte[] textBytes;
      textBytes = CharsetUtil.encode(message, CharsetUtil.CHARSET_ISO_8859_1);
      // set encoding for sending SMS
      submit.setDataCoding(SmppConstants.DATA_CODING_LATIN1);
      if (requestDlr) {
        submit.setRegisteredDelivery(SmppConstants.REGISTERED_DELIVERY_SMSC_RECEIPT_REQUESTED);
      }

      if (textBytes != null && textBytes.length > 255) {
        submit.addOptionalParameter(
            new Tlv(SmppConstants.TAG_MESSAGE_PAYLOAD, textBytes, "message_payload"));
      } else {
        submit.setShortMessage(textBytes);
      }

      submit.setSourceAddress(new Address((byte) 0x05, (byte) 0x01, sourceAddress));
      submit.setDestAddress(new Address((byte) 0x01, (byte) 0x01, destinationAddress));
      // submit message to SMSC for delivery with a timeout of 10000ms
      SubmitSmResp submitResponse = session.submit(submit, 10000);
      if (submitResponse.getCommandStatus() == SmppConstants.STATUS_OK) {
        log.info("SMS submitted, message id {}", submitResponse.getMessageId());
      } else {
        throw new IllegalStateException(submitResponse.getResultMessage());
      }
    } catch (RecoverablePduException | UnrecoverablePduException | SmppTimeoutException | 
        SmppChannelException | InterruptedException e) {
        throw new IllegalStateException(e);
    }
    return;
  }
  throw new IllegalStateException("SMPP session is not connected");
}

Finally, let us call the method to send SMS:

file: src/main/java/com/juliuskrah/smpp/Application.java

// ...

public static void main(String[] args) {
  ConfigurableApplicationContext ctx = SpringApplication.run(Application.class, args);
  SmppSession session = ctx.getBean(SmppSession.class);
  new Application().sendTextMessage(session, "3299", "Hello World", "<replace with phone number>");
}

Add your phone number to destinationAddress and run the application. Remember to use the international phone number format.

At this point you are done and can choose not to follow the rest of this post.

Making it Better

You may have noticed that, we hardcoded certain things like username, password and host in the source code. This does not make the app very portable. Let’s make use of externalized configuration, which has extensive support in Spring-Boot.

I will create a class ApplicationProperties which contains all the external properties we need:

file: src/main/java/com/juliuskrah/smpp/ApplicationProperties.java

@ConfigurationProperties("sms")
public class ApplicationProperties {
  @NestedConfigurationProperty
  private final Async async = new Async();
  @NestedConfigurationProperty
  private final SMPP smpp = new SMPP();

  public Async getAsync() {
    return async;
  }

  public SMPP getSmpp() {
    return smpp;
  }

  public static class Async {
    /**
     * This number should be lower than the value assigned to the core-pool-size
     */
    private int smppSessionSize = 2;
    private int corePoolSize = 5;
    private int maxPoolSize = 50;
    private int queueCapacity = 10000;
    private int initialDelay = 1000;
    private int timeout = 10000;

    // omitted getters and setters
  }

  public static class SMPP {
    private String host;
    private String userId;
    private String password;
    private int port = 2775;
    private boolean requestDelivery = false;
    private boolean detectDlrByOpts = false;

    // omitted getters and setters
  }
}

I have added default values for most of the setings in the above class. I will override some of the defaults in a yaml file:

file: src/main/resources/application.yaml

sms:
  smpp:
    host: <replace>
    user-id: <replace>
    password: <replace>
    requestDelivery: true

In the above, I am overriding the default value of requestDelivery to true.

In order to use this in our simple application, I need to register the ApplicationProperties configuration class:

file: src/main/java/com/juliuskrah/smpp/Application.java

@SpringBootApplication
@EnableConfigurationProperties(ApplicationProperties.class)
public class Application {
  // ...
}

I will rewrite sessionConfiguration method to use the externalized configuration:

file: src/main/java/com/juliuskrah/smpp/Application.java

// ...

public SmppSessionConfiguration sessionConfiguration(ApplicationProperties properties) {
SmppSessionConfiguration sessionConfig = new SmppSessionConfiguration();
  sessionConfig.setName("smpp.session");
  sessionConfig.setInterfaceVersion(SmppConstants.VERSION_3_4);
  sessionConfig.setType(SmppBindType.TRANSCEIVER);
  sessionConfig.setHost(properties.getSmpp().getHost());
  sessionConfig.setPort(properties.getSmpp().getPort());
  sessionConfig.setSystemId(properties.getSmpp().getUserId());
  sessionConfig.setPassword(properties.getSmpp().getPassword());
  sessionConfig.setSystemType(null);
  sessionConfig.getLoggingOptions().setLogBytes(false);
  sessionConfig.getLoggingOptions().setLogPdu(true);

  return sessionConfig;
}

At the beginning of this post I talked about receiving delivery receipts. The default implementation of SmppSessionListener is to discard received PDUs. So I will extend the default implementation class and handle delivery receipts in there:

file: src/main/java/com/juliuskrah/smpp/ClientSmppSessionHandler.java

public class ClientSmppSessionHandler extends DefaultSmppSessionHandler {
  private static final Logger log = LoggerFactory.getLogger(ClientSmppSessionHandler.class);
  private final ApplicationProperties properties;

  public ClientSmppSessionHandler(ApplicationProperties properties) {
    this.properties = properties;
  }

  private String mapDataCodingToCharset(byte dataCoding) {
    // implementaion in the github repository
  }

  @Override
  @SuppressWarnings("rawtypes")
  public PduResponse firePduRequestReceived(PduRequest request) {
    PduResponse response = null;
    try {
      if (request instanceof DeliverSm) {
        String sourceAddress = ((DeliverSm) request).getSourceAddress().getAddress();
        String message = CharsetUtil.decode(((DeliverSm) request).getShortMessage(),
            mapDataCodingToCharset(((DeliverSm) request).getDataCoding()));
        log.debug("SMS Message Received: {}, Source Address: {}", message.trim(), sourceAddress);

        boolean isDeliveryReceipt = false;
        if (properties.getSmpp().isDetectDlrByOpts()) {
          isDeliveryReceipt = request.getOptionalParameters() != null;
        } else {
          isDeliveryReceipt = SmppUtil.isMessageTypeAnyDeliveryReceipt(
            ((DeliverSm) request).getEsmClass());
        }

        if (isDeliveryReceipt) {
          DeliveryReceipt dlr = DeliveryReceipt.parseShortMessage(message, ZoneOffset.UTC);
          // logging delivery here, but you can do something more useful over here
          log.info("Received delivery from {} at {} with message-id {} and status {}", sourceAddress,
              dlr.getDoneDate(), dlr.getMessageId(), DeliveryReceipt.toStateText(dlr.getState()));
        }
      }
      response = request.createResponse();
    } catch (Throwable error) {
      log.warn("Error while handling delivery", error);
      response = request.createResponse();
      response.setResultMessage(error.getMessage());
      response.setCommandStatus(SmppConstants.STATUS_UNKNOWNERR);
    }
    return response;
  }
}

The DeliveryReceipt class is a utility class I created to extract delivery details from PduRequest. I will not paste the contents of the class here (it is quite lengthy), you can view its contents in the Github repository.

We just need to register this handler to take advantage of the delivery receipt handling:

file: src/main/java/com/juliuskrah/smpp/Application.java

@Bean(destroyMethod = "destroy")
public SmppSession session(ApplicationProperties properties) throws SmppBindException, 
    SmppTimeoutException, SmppChannelException,
    UnrecoverablePduException, InterruptedException {
  SmppSessionConfiguration config = sessionConfiguration(properties);
  SmppSession session = clientBootstrap().bind(config, new ClientSmppSessionHandler(properties));

  return session;
}

If you run the application now, you will see delivery receipts printed in the console. This solution however is far from ideal. As I said earlier, the Sessions are short-lived; given a scenario where a mobile device is switched off, the SMS will be delivered only when the device is switched back on. In this same scenario, the SMPP Session may be closed when the delivery is received, leading to lost delivery receipts. To overcome this limitation I have to design the application to periodically refresh the session before it un-binds.

I will use EnquireLinkResp to periodically extend the session:

file: src/main/java/com/juliuskrah/smpp/Application.java

@EnableScheduling
@SpringBootApplication
@EnableConfigurationProperties(ApplicationProperties.class)
public class Application {
  // ...

  @Scheduled(
      initialDelayString = "${sms.async.initial-delay}", 
      fixedDelayString = "${sms.async.initial-delay}")
  void enquireLinkJob() {
    if (session.isBound()) {
      try {
        log.info("sending enquire_link");
        EnquireLinkResp enquireLinkResp = session.enquireLink(new EnquireLink(),
            properties.getAsync().getTimeout());
        log.info("enquire_link_resp: {}", enquireLinkResp);
      } catch (SmppTimeoutException e) {
        log.info("Enquire link failed, executing reconnect; " + e);
        log.error("", e);
      } catch (SmppChannelException e) {
        log.info("Enquire link failed, executing reconnect; " + e);
        log.warn("", e);
      } catch (InterruptedException e) {
        log.info("Enquire link interrupted, probably killed by reconnecting");
      } catch (Exception e) {
        log.error("Enquire link failed, executing reconnect", e);
      }
    } else {
      log.error("enquire link running while session is not connected");
    }
  }
}

I have added annotation on top of the class to @EnableScheduling which allows spring to process the @Scheduled annotation. The fixedDelayString value ${sms.async.initial-delay} is set in the application.yaml file:

file: src/main/resources/application.yaml

sms:
  async:
    initial-delay: 30000

This will cause the application to enquire link every 30 seconds. This solution is far from perfect. When internet connectivity is lost on the server running the application, this will not work. Also when the Session unexpectedly unbinds this solution will not work. I have implemented a more robust solution on the persistent branch of the Github repository accompanying this post.

Before we wrap up, it is not very good practice to store sentive information in plain text on files. There are several best practices and solutions out there e.g. using Vault from Hashicorp. I am going to implement the simplest solution by using environment variables:

PS C:\> set SMS_SMPP_HOST=<host>
PS C:\> set SMS_SMPP_USER_ID=<user>
PS C:\> set SMS_SMPP_PASSWORD=<password>

Conclusion

In this post we looked briefly at the SMPP protocol and its usage within the JVM. We also covered how to use Spring Boot to make developing an SMPP client easier.

As usual you can find the full example to this guide in the github repository. Until the next post, keep doing cool things :+1:.

Microservices enable different teams to work on smaller pieces, using independent technologies, producing safer, more frequent deployments

Introduction

If you are not already using Microservices, you are safely out of the early adopter phase of the adoption curve, and it is probably time to get started. In this article, we will demonstrate the essential components for creating RESTful microservices, using Consul service registry, Spring Boot for all the scaffolding, dependency injection, and dependencies, Maven for the build, and Spring REST.

Over the last two decades, enterprise has become very agile in our SDLC process, but our applications tend to still be rather monolith, with huge jars supporting all of the varied APIs and versions in play. But nowadays there is a push towards more Lean, DevOps-ey processes, and functionality is becoming “serverless”. Refactoring to Microservices can decouple code and resources, make builds smaller, releases safer, and APIs more stable.

Prerequisites

• Java Development Kit
• Maven
• Docker (Optional)

Purpose

In this post, we will build a simple geospatial application that clients can call with two spatial points. The points microservice will send the points the client submitted to a distance microservice to calculate the distance between the given points, and then return the result to the points service, exposing all that via a rest call.

Microservice Architecture

Project Structure

At the end of this guide our folder structure will look similar to the following:

.
|__distance/
|  |__src/
|  |  |__main/
|  |  |  |__java/
|  |  |  |  |__com/
|  |  |  |  |  |__juliuskrah/
|  |  |  |  |  |  |__distance
|  |  |  |  |  |  |  |__DistanceApplication.java
|  |  |  |__resources/
|  |  |  |  |__application.yaml
|  |  |  |  |__bootstrap.yaml
|  |__pom.xml
|__points/
|  |__src/
|  |  |__main/
|  |  |  |__java/
|  |  |  |  |__com/
|  |  |  |  |  |__juliuskrah/
|  |  |  |  |  |  |__point/
|  |  |  |  |  |  |  |__PointsApplication.java
|  |  |  |__resources/
|  |  |  |  |__application.yaml
|  |  |  |  |__bootstrap.yaml
|  |__pom.xml

Before we get to work on creating our microservices, let’s prepare our environment by setting up Consul.

Download Consul Service Registry

We will be using Hashicorp Consul for service discovery, so head over to https://www.consul.io/downloads.html and download Consul, for Windows, Linux, Mac, etc. That will provide an executable that you will want to add to your path.

From a shell prompt, launch Consul in dev mode:

PS C:\> consul agent -dev

If you prefer to use docker, here’s the command to start consul in dev mode:

PS C:\> docker run -d --name=dev-consul -e CONSUL_BIND_INTERFACE=eth0 consul

To verify that it is running, head over to a browser and access the consul UI http://localhost:8500. If all is well, consul should report that it is alive and well.

Consul running on port 8500

If there are any issues at this point, be sure ports 8500 and 8600 are available.

Create the SpringBoot application

We will use Spring Intitializr to create the scaffolding for our SpringBoot applications. Head over to the Spring Initializr webapp and create the distance microservice. Select Web and Consul Discovery then click Generate Project to download a zip file. Extract this zip file and load the project into your favorite IDE or text editor.

Generate Distance Microservice

We can use the generated application.properties, but Spring-Boot also recognizes YAML format, and that’s a little easier to visualize, so let’s rename it application.yaml. Also create a bootstrap.yaml file.

We will name the microservice distance. We can specify a port or use port 0 to have the application use an available port. In our case we will use 57116. If you deploy this service as a Docker container you will be able to map that to any port of your choosing. Let’s name the application in bootstrap.yaml and specify our port by adding the following to our application.yaml:

file: distance/src/main/resources/application.yaml

server:
  port: 57116
spring:
  cloud:
    consul:
      discovery:
        register-health-check: false

file: distance/src/main/resources/bootstrap.yaml

spring:
  application:
    name: distance

Now build the project, and run it:

PS C:\> .\mvnw spring-boot:run

We should now see this service in Consul, so let’s head back over to our browser, load up http://localhost:8500/ui/dc1/services (or refresh if you’re already there).

Distance Service registered in Consul

As you can see from the above diagram, the distance service has been registered with consul.

We need to add the JTS library to the application classpath to aid us with the distance measurement:

file: distance/pom.xml

...
<dependency>
  <groupId>org.locationtech.jts</groupId>
  <artifactId>jts-core</artifactId>
  <version>1.15.1</version>
</dependency>
...

The distance microservice will serve one request /distance/start/@{start}/dest/@{dest} which returns the distance computed.

file: distance/src/main/java/com/juliuskrah/distance/DistanceApplication.java

@RestController
@SpringBootApplication
public class DistanceApplication {
  static GeometryFactory fact = new GeometryFactory();
  static WKTReader wktRdr = new WKTReader(fact);

  public static void main(String[] args) {
    SpringApplication.run(DistanceApplication.class, args);
  }
	
  @GetMapping(path = "/distance/start/@{start}/dest/@{dest}", produces = "application/json")
  public double points(@PathVariable String start, @PathVariable String dest) {
    double distance = 0.0;
    String[] pointA = start.split(",");
    String[] pointB = dest.split(",");
    String wktA = "POINT (" + pointA[0] + " " + pointA[1] +")";
    String wktB = "POINT (" + pointB[0] + " " + pointB[1] +")";
		
    try {
      Geometry A = wktRdr.read(wktA);
      Geometry B = wktRdr.read(wktB);

      System.out.println("Geometry A: " + A);
      System.out.println("Geometry B: " + B);
      DistanceOp distOp = new DistanceOp(A, B);
      distance = distOp.distance();
			
    } catch (ParseException e) {
      // ignore
    }	
    return distance;
  }	
}

Restart the distance service and test the endpoint http://localhost:57116/distance/start/@50.8307467,-1.2099742/dest/@5.5790564,-0.7073872, and you should see 45.25448120020473.

Our first microservice is open for business!

Points Microservice

Head over to Spring Intitializr to create the points microservice. Select Web and Consul Discovery, change “Artifact” to points then click Generate Project to download a zip file. Extract the contents of the zip file and load the project into your favorite IDE or text editor.

We will name the microservice points in bootstrap.yaml. We will use port 57216 for the points microservice:

file: points/src/main/resources/application.yaml

server:
  port: 57216
spring:
  cloud:
    consul:
      discovery:
        register-health-check: false

file: points/src/main/resources/bootstrap.yaml

spring:
  application:
    name: points

Give it a spin .\mvnw spring-boot:run to ensure everything is working.

If it’s all good we can implement the points microservice:

file: points/src/main/java/com/juliuskrah/point/PointsApplication.java

@RestController
@SpringBootApplication
public class PointsApplication {
  @Autowired
  private RestTemplate restTemplate;

  public static void main(String[] args) {
    SpringApplication.run(PointsApplication.class, args);
  }

  @GetMapping(path = "/points/start/@{start}/dest/@{dest}", produces = "application/json")
  public double points(@PathVariable String start, @PathVariable String dest) {
    return restTemplate.getForObject("http://distance/distance/start/@{start}/dest/@{dest}",
      double.class, start, dest);
  }

  @Bean
  @LoadBalanced
  public RestTemplate loadBalancedRestTemplate(RestTemplateBuilder builder) {
    return builder.build();
  }
}

A few things to note about the snippet above – @LoadBalanced, annotation to mark a RestTemplate bean to be configured to use a round-robin LoadBalancerClient for client-side load-balancing. This same annotation allows RestTemplate to determine the URI of the downstream microservice by name. This is how the http://DISTANCE/distance/start/@{start}/dest/@{dest} seemingly works despite missing a host and port in the URI passed to RestTemplate#getForObject.

This approach is efficient as we leave the job of discovery the services’ host and port to the discovery server (consul); we don’t have to worry about knowing the IPs of all microservices. In a large project consisting of thousands of microservices, you will soon come to agree that knowing all IPs of services starts to become a jarring task; this is where service discovery starts to shine.

Let’s put the points microservice to the test http://localhost:57216/points/start/@5.8307467,-1.2099742/dest/@5.5790564,-0.7073872.

This completes out points service using Spring-Boot.

Conclusion

In this tutorial we learned the fundamentals of Microservices. We learned what is a Discovery client, we also built two microservices to demonstrate how service discovery allows microservices to find each other.
As usual you can find the full example to this guide in the github repository. Until the next post, keep doing cool things :+1:.

The Interceptors specification defines three kinds of interception points:

• business method interception,
• lifecycle callback interception, and
• timeout method interception (EJB only).

We will explore the basics of using interceptors in CDI. A simple interceptor will be created that initializes a cutomer’s account with 10 USD.

In the above snippet we create the @InterceptorBinding which can be applied to a TYPE or a METHOD.

Next is to create the actual Interceptor class with a binding to the AccountOpeningInterceptor.

Then we apply the Interceptor to the method call that requires interception.

On that note and until the next post; keep doing cool things :smile:.

Apache DeltaSpike is a collection of portable CDI extensions.

Introduction

DeltaSpike Data Module provides capabilities for implementing repository patterns and thereby simplifying the repository layer not unlike Spring Data. In this post we will take a JPA project and rewrite the repository layer to use DeltaSpike Data. Basically, we will strip off the boilerplate EntityManager queries and enable centralization of query logic and consequently reducing code duplication and improve testability.

Prerequisites

• Java Development Kit
• Maven

Project Structure

At the end of this guide our folder structure will look similar to the following:

.
|__src/
|  |__main/
|  |  |__java/
|  |  |  |__com/
|  |  |  |  |__juliuskrah/
|  |  |  |  |  |__cdi/
|  |  |  |  |  |  |__ApplicationResources.java
|  |  |  |  |  |  |__business/
|  |  |  |  |  |  |  |__CustomerService.java
|  |  |  |  |  |  |  |__dto/
|  |  |  |  |  |  |  |  |__CustomerBean.java
|  |  |  |  |  |  |  |__mapper/
|  |  |  |  |  |  |  |  |__CustomerMapper.java
|  |  |  |  |  |  |__entity/
|  |  |  |  |  |  |  |__Customer.java
|  |  |  |  |  |  |__repository/
|  |  |  |  |  |  |  |__CustomerRepository.java
|  |  |  |  |  |  |__web/
|  |  |  |  |  |  |  |__IndexController.java
|  |  |__resources/
|  |  |  |__db/
|  |  |  |  |__migration/
|  |  |  |  |  |__`V1__Create_customer_table.sql`
|  |  |  |__META-INF/
|  |  |  |  |__persistence.xml
|  |  |  |__modules/
|  |  |  |  |__com/
|  |  |  |  |  |__h2database/
|  |  |  |  |  |  |__h2/
|  |  |  |  |  |  |  |__main/
|  |  |  |  |  |  |  |  |__module.xml
|  |  |  |__project-defaults.yaml
|  |  |__webapp/
|  |  |  |__WEB-INF/
|  |  |  |  |__templates/
|  |  |  |  |  |__default.xhtml
|  |  |  |  |__beans.xml
|  |  |  |  |__web.xml
|  |  |  |__index.html
|  |  |  |__index.xhtml
|__pom.xml

Setting Up

Download the initial project (zip| tar.gz) and extract. From the extracted directory run the following command:

C:\> mvn clean wildfly-swarm:run

Wait for all the dependencies to download and swarm to start.

DeltaSpike

Add the DeltaSpike Data dependencies:

file: pom.xml

...
<dependency>
  <groupId>org.apache.deltaspike.modules</groupId>
  <artifactId>deltaspike-data-module-api</artifactId>
  <version>1.8.1</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>org.apache.deltaspike.modules</groupId>
  <artifactId>deltaspike-data-module-impl</artifactId>
  <version>1.8.1</version>
  <scope>runtime</scope>
</dependency>
...

Replace the code in CustomerRepository:

file: src/main/java/com/juliuskrah/cdi/repository/CustomerRepository.java

@Repository
public interface CustomerRepository extends EntityRepository<Customer, UUID> {

  @Query("SELECT c FROM Customer c WHERE c.id = :id")
  Optional<Customer> findOne(@QueryParam("id") UUID id);
}

There are a few things to note here. The @Repository annotation tells the extension that this is a repository for the Customer entity. Any method defined on the repository will be processed by the framework.

The EntityRepository Interface is mainly intended to hold complex query logic, working with both a repository and an EntityManager in the service layer might unnecessarily clutter code. The top base type is the EntityRepository interface, providing common methods used with an EntityManager.

DeltaSpike Data module supports also annotating methods for more control on the generated query using @Query. If the JPQL query requires named parameters to be used, this can be done by annotating the arguments with the @QueryParam annotation.

For all these to work, DeltaSpike Data requires an EntityManager exposed via a CDI producer - which is common practice in Java EE applications:

@Produces
@PersistenceContext
EntityManager em;

Transactions

DeltaSpike Data module uses a ResourceLocalTransactionStrategy as default TransactionStrategy when demarcating transactions. Our example is configured to use jta-data-source, and the ResourceLocalTransactionStrategy does not quite fit our needs here.

Let’s talk a little about JPA transactions to understand our decision not to use ResourceLocalTransactionStrategy. A transaction is a set of operations that either fail or succeed as a unit. Transactions are a fundamental part of persistence. A database transaction consists of a set of SQL DML (Data Manipulation Language) operations that are committed or rolled back as a single unit. An object level transaction is one in which a set of changes made to a set of objects are committed to the database as a single unit.

JPA provides two mechanisms for transactions. When used in Java EE JPA provides integration with JTA (Java Transaction API). JPA also provides its own EntityTransaction implementation for Java SE and for use in a non-managed mode in Java EE. Transactions in JPA are always at the object level, this means that all changes made to all persistent objects in the persistence context are part of the transaction.

Resource local transactions are used in Java SE, or in application managed (non-managed) mode in Java EE. To use resource local transactions the transaction-type attribute in the persistence.xml is set to RESOURCE_LOCAL. Local JPA transactions are defined through the EntityTransaction class. It contains basic transaction API including begin, commit and rollback.

JTA transactions are used in Java EE, in managed mode (CMT). To use JTA transactions the transaction-type attribute in the persistence.xml is set to JTA. JTA transactions are defined through the JTA UserTransaction class.

JTA transactions can be used in two modes in Java EE. In Java EE managed mode such as an EntityManager injected through @PersistenceContext, this mode is also known as Container Managed Transaction (CMT).

The second mode allows the EntityManager to be application managed, (normally obtained from an injected EntityManagerFactory, or directly from JPA Persistence) also known as Bean Managed Transaction (BMT). This allows the persistence context to survive transaction boundaries, and follow the normal EntityManager life-cycle similar to resource local.

DeltaSpike has three implementations of TransactionStrategy:

• ResourceLocalTransactionStrategy which uses EntityTransaction
• BeanManagedUserTransactionStrategy which uses UserTransaction
• ContainerManagedTransactionStrategy

We have to tell DeltaSpike to use ContainerManagedTransactionStrategy:

file: src/main/resources/META-INF/apache-deltaspike.properties

globalAlternatives.org.apache.deltaspike.jpa.spi.transaction.TransactionStrategy = org.apache.deltaspike.jpa.impl.transaction.ContainerManagedTransactionStrategy

Conclusion

We have been introduced to DeltaSpike Data Module, and we saw how easy it is to use for contructing queries. We also did a quick introduction to Transactions in JPA.

As usual you can find the full example to this guide in the github repository. Until the next post, keep doing cool things :+1:.

Contexts and Dependency Injection for the Java EE Platform is a JCP standard for dependency injection and contextual lifecycle management and one of the most important and popular parts of Java EE.

Introduction

Contexts and Dependency Injection for Java EE (CDI) was introduced as part of the Java EE platform, and has quickly become one of the most important and popular components of the platform.

The CDI specification defines a set of complementary services that help improve the structure of application code. CDI layers an enhanced lifecycle and interaction model over existing Java component types, including managed beans and Enterprise Java Beans.

You can run CDI in a Java EE or SE environment. However to leverage the full capabilities of CDI, it is recommended to use a Java EE container. In this tutorial, we will cover just the EE approach and we will be using Wildfly-Swarm, a lighweight alternative to the Wildfly Java EE container which is also a very good fit for deploying microservices.

What We will Cover

CDI is quite broad; as it provides integration and contracts with the wider Java EE ecosystem. This being an introductory post, we limit the scope of what is covered to:

• Bean Scope
• Producer
• Inject
• Event

Prerequisites

• Java Development Kit
• Maven
• Eclipse 4.6.0+

Project Structure

At the end of this guide our folder structure will look similar to the following:

.
|__src/
|  |__main/
|  |  |__java/
|  |  |  |__com/
|  |  |  |  |__juliuskrah/
|  |  |  |  |  |__cdi/
|  |  |  |  |  |  |__ApplicationContext.java
|  |  |  |  |  |  |__ApplicationResources.java
|  |  |  |  |  |  |__business/
|  |  |  |  |  |  |  |__CustomerService.java
|  |  |  |  |  |  |  |__dto/
|  |  |  |  |  |  |  |  |__CustomerBean.java
|  |  |  |  |  |  |  |__mapper/
|  |  |  |  |  |  |  |  |__CustomerMapper.java
|  |  |  |  |  |  |__entity/
|  |  |  |  |  |  |  |__Customer.java
|  |  |  |  |  |  |__repository/
|  |  |  |  |  |  |  |__CustomerRepository.java
|  |  |  |  |  |  |__web/
|  |  |  |  |  |  |  |__IndexController.java
|  |  |__resources/
|  |  |  |__db/
|  |  |  |  |__migration/
|  |  |  |  |  |__`V1__Create_customer_table.sql`
|  |  |  |__META-INF/
|  |  |  |  |__persistence.xml
|  |  |  |__modules/
|  |  |  |  |__com/
|  |  |  |  |  |__h2database/
|  |  |  |  |  |  |__h2/
|  |  |  |  |  |  |  |__main/
|  |  |  |  |  |  |  |  |__module.xml
|  |  |  |__project-defaults.yaml
|  |  |__webapp/
|  |  |  |__WEB-INF/
|  |  |  |  |__views/
|  |  |  |  |  |__index.xhtml
|  |  |  |  |  |__templates/
|  |  |  |  |  |  |__default.xhtml
|__pom.xml

Setting Up

Download the initial project (zip| tar.gz) and extract. Import the extracted project into Eclipse and follow the Mapstruct instructions to generate mappers in Eclipse.

Run the application as a Java application; use org.wildfly.swarm.Swarm as the main class. ince it is up, access the application in your browser http://localhost:8080. Let’s start by understanding what a bean scope is.

Bean Scopes

A bean is exactly what you think it is. Only now, it has a true identity in the container environment.

Managed Beans are defined as container-managed objects with minimal programming restrictions, otherwise known by the acronym POJO (Plain Old Java Object). They support a small set of basic services, such as resource injection, lifecycle callbacks and interceptors. Companion specifications, such as EJB and CDI, build on this basic model.

A bean is usually an application class that contains business logic. It may be called directly from Java code, or it may be invoked via the Unified EL. A bean may access transactional resources. Dependencies between beans are managed automatically by the container. Most beans are stateful and contextual. The lifecycle of a bean is managed by the container.

The scope of a bean determines:

• the lifecycle of each instance of the bean and
• which clients share a reference to a particular instance of the bean.

For a given thread in a CDI application, there may be an active context associated with the scope of the bean. This context may be unique to the thread (for example, if the bean is request scoped), or it may be shared with certain other threads (for example, if the bean is session scoped) or even all other threads (if it is application scoped).

The scope of a bean defines the lifecycle and visibility of its instances. The CDI context model is extensible, accommodating arbitrary scopes. However, certain important scopes are built into the specification, and provided by the container. Each scope is represented by an annotation type.

According to the CDI specification, a scope determines:

• When a new instance of any bean with that scope is created
• When an existing instance of any bean with that scope is destroyed
• Which injected references refer to any instance of a bean with that scope

For example, if we have a session-scoped bean, CustomerRepository , all beans that are called in the context of the same HttpSession will see the same instance of CustomerRepository. This instance will be automatically created the first time a CustomerRepository is needed in that session, and automatically destroyed when the session ends.

Built-in Scopes

CDI defines four built-in scopes:

• @RequestScoped: A bean instance is created for each request.
• @SessionScoped: Creates a bean bound to the HTTP Session.
• @ApplicationScoped: A single bean instance is shared by the application.

• @ConversationScoped: The conversation scope is a bit like the traditional session scope in that it holds state associated with a user of the system, and spans multiple requests to the server.

  A conversation represents a task—a unit of work from the point of view of the user. The conversation context holds state associated with what the user is currently working on. If the user is doing multiple things at the same time, there are multiple conversations.

  The conversation context is active during any servlet request (since CDI 1.1). Most conversations are destroyed at the end of the request. If a conversation should hold state across multiple requests, it must be explicitly promoted to a long-running conversation.

Let’s start by creating some Application-Scoped beans:

file: src/main/java/com/juliuskrah/cdi/repository/CustomerRepository.java

@ApplicationScoped
public class CustomerRepository {
  // ...
}

file: src/main/java/com/juliuskrah/cdi/business/CustomerService.java

@ApplicationScoped
public class CustomerService {
  // ...
}

We can Inject these beans into other beans. We will cover this later in this post.

Producers

CDI distinguishes between two types of producers:

• Producer methods let us overcome certain limitations that arise when a container, instead of the application, is responsible for instantiating objects. They’re also the easiest way to integrate objects which are not beans into the CDI environment.
• A producer field is a simpler alternative to a producer method. A producer field is declared by annotating a field of a bean class with the @Produces annotation — the same annotation used for producer methods. A producer field is really just a shortcut that lets us avoid writing a useless getter method.

Let’s demonstrate that with an example:

file: src/main/java/com/juliuskrah/cdi/ApplicationResources.java

@RequestScoped
public class ApplicationResources {

  @Produces
  @PersistenceContext
  EntityManager em;

  @Produces
  public Logger produceLog(InjectionPoint injectionPoint) {
    return Logger.getLogger(injectionPoint.getMember().getDeclaringClass());
  }
}

We created a producer field EntityManager, which will enable us inject an EntityManager into CDI beans. We also created a producer method Logger to easily inject a logger into bean classes.

Inject

The @Inject annotation lets us define an injection point that is injected during bean instantiation. Injection can occur via three different mechanisms.

• Bean constructor parameter injection: A bean can only have one injectable constructor.
• Initializer method parameter injection: A bean can have multiple initializer methods.
• And direct field injection: Getter and setter methods are not required for field injection to work.

Dependency injection always occurs when the bean instance is first instantiated by the container. Simplifying just a little, things happen in this order:

• First, the container calls the bean constructor (the default constructor or the one annotated @Inject), to obtain an instance of the bean.
• Next, the container initializes the values of all injected fields of the bean.
• Next, the container calls all initializer methods of bean (the call order is not portable, don’t rely on it).
• Finally, the @PostConstruct method, if any, is called.

file: src/main/java/com/juliuskrah/cdi/repository/CustomerRepository.java

@ApplicationScoped
public class CustomerRepository {
  private EntityManager em;

  public CustomerRepository() {}

  @Inject
  public CustomerRepository(EntityManager em) {
    this.em = em;
  }

  // ...
}

file: src/main/java/com/juliuskrah/cdi/web/IndexController.java

@Path("/")
@Controller
public class IndexController {
  @Inject
  private CustomerService customerService;
  @Inject
  private Logger log;

  // ...
}

Events

Dependency injection enables loose-coupling by allowing the implementation of the injected bean type to vary, either at deployment time or runtime. Events go one step further, allowing beans to interact with no compile time dependency at all. Event producers raise events that are delivered to event observers by the container.

This basic schema might sound like the familiar observer/observable pattern, but there are a couple of twists:

• not only are event producers decoupled from observers; observers are completely decoupled from producers,
• observers can specify a combination of “selectors” to narrow the set of event notifications they will receive, and
• observers can be notified immediately, or can specify that delivery of the event should be delayed until the end of the current transaction.

CDI events are made up of:

• Event Payload: The event object carries state from producer to consumer. The event object is nothing more than an instance of a concrete Java class. (The only restriction is that an event type may not contain type variables).
• Event Observers: An observer method is a method of a bean with a parameter annotated @Observes or @ObservesAsync. The annotated parameter is called the event parameter. The type of the event parameter is the observed event type.
• Event Producers: Event producers fire events either synchronously or asynchronously using an instance of the parameterized Event interface. An instance of this interface is obtained by injection.

file: src/main/java/com/juliuskrah/cdi/business/CustomerService.java

@ApplicationScoped
public class CustomerService {
  @Inject // Inject event
  private Event<CustomerBean> customerEventSrc;

  public CustomerBean createCustomer(CustomerBean customer) {
    Customer c = // ...
    // Produce customer event
    customerEventSrc.fire(customer);
    return customer;
  }

  /**
   * The producer and observer do not necessarily have to be in the same class
   */
  public void onCustomerListChanged(
    // Observe customer event 
    @Observes(notifyObserver = Reception.IF_EXISTS, 
    during = TransactionPhase.AFTER_COMPLETION) 
    final CustomerBean customer) {
    // Add your logic here
  }
  // ...
}

Conclusion

This is an introductory post to CDI. We covered the basics of CDI with @Inject, @Produces and bean scopes. As usual you can find the full example to this guide in the github repository. Until the next post, keep doing cool things :+1:.

JasperReports is a Java class library, and it is meant for those Java developers who need to add reporting capabilities to their applications.

Introduction

In this post, we will create a PDF report that is exposed over a RESTful endpoint using Spring Boot. This is also a good place to start for those of you trying to figure out how to integrate JasperReports with Spring Framework 5. To serve excel over REST, refer to this Excel Post.

Prerequisites

• Java Development Kit
• Maven

Project Structure

At the end of this guide our folder structure will look similar to the following:

.
|__src/
|  |__main/
|  |  |__java/
|  |  |  |__com/
|  |  |  |  |__juliuskrah/
|  |  |  |  |  |__jasper/
|  |  |  |  |  |  |__Application.java
|  |  |  |  |  |  |__ApplicationProperties.java
|  |  |  |  |  |  |__report/
|  |  |  |  |  |  |  |__JasperReportsService.java
|  |  |  |  |  |  |  |__ReportService.java
|  |  |  |  |  |  |__storage/
|  |  |  |  |  |  |  |__FileSystemStorageService.java
|  |  |  |  |  |  |  |__StorageException.java
|  |  |  |  |  |  |  |__StorageFileNotFoundException.java
|  |  |  |  |  |  |  |__StorageService.java
|  |  |  |  |  |  |__web/
|  |  |  |  |  |  |  |__rest/
|  |  |  |  |  |  |  |  |__ApplicationResource.java
|  |  |__resources/
|  |  |  |__reports/
|  |  |  |  |__pdf_rest_resource.jrxml
|  |  |  |  |__pdf_rest.jrxml
|  |  |  |__application.yaml
|  |  |  |__cherry.png
|  |  |  |__logo.png
|__pom.xml

How to complete this guide

To complete this guide, download (zip| tar.gz) and unzip the source repository for this guide.

Create PDF Report

Let us start by implementing a solution to generate PDFs in JasperReports:

file: src/main/java/com/juliuskrah/jasper/report/JasperReportsService.java

@Component
public class JasperReportsService implements ReportService {
  // ...
  @Override
  public byte[] generatePDFReport(String inputFileName, Map<String, Object> params,
    JRDataSource dataSource) {
    byte[] bytes = null;
    JasperReport jasperReport = null;
    try (ByteArrayOutputStream byteArray = new ByteArrayOutputStream()) {
      // Check if a compiled report exists
      if (storageService.jasperFileExists(inputFileName)) {
        jasperReport = (JasperReport) JRLoader.loadObject(storageService.loadJasperFile(inputFileName));
      }
      // Compile report from source and save
      else {
        String jrxml = storageService.loadJrxmlFile(inputFileName);
        jasperReport = JasperCompileManager.compileReport(jrxml);
        // Save compiled report. Compiled report is loaded next time
        JRSaver.saveObject(jasperReport, storageService.loadJasperFile(inputFileName));
      }
      JasperPrint jasperPrint = JasperFillManager.fillReport(jasperReport, params, dataSource);
      // return the PDF in bytes
      bytes = JasperExportManager.exportReportToPdf(jasperPrint);
    }
    catch (JRException | IOException e) {
      e.printStackTrace();
    }
    return bytes;
  }
}

Render the PDF REST Endpoint

We will create the REST endpoint:

file: src/main/java/com/juliuskrah/jasper/web/rest/ApplicationResource.java

@RestController
public class ApplicationResource {
  // ...
  @GetMapping("/{username}")
  public ResponseEntity<byte[]> report(@PathVariable(required = false) String username) {
    Map<String, Object> params = new HashMap<>();
    params.put("username", username);
    byte[] bytes = reportService.generatePDFReport("pdf_rest_resource", params);
    return ResponseEntity
      .ok()
      // Specify content type as PDF
      .header("Content-Type", "application/pdf; charset=UTF-8")
      // Tell browser to display PDF if it can
      .header("Content-Disposition", "inline; filename=\"" + username + ".pdf\"")
      .body(bytes);
  }
}

Now navigate to http://localhost:8080/:username to view your report.

Conclusion

In this post we learned how to generate PDF with JasperReports and serve it over HTTP with Spring Boot.
As usual you can find the full example to this guide in the github repository. Until the next post, keep doing cool things :+1:.