DEV Community: Gauthier Cassany

Quickly bootstrap a new Spring Boot project with the Spring CLI

Gauthier Cassany — Tue, 16 Aug 2022 10:39:00 +0000

Generating a Spring Boot project can be made through various means, each having its own use case depending on your situation.

You can use the Spring Initializr web UI which is beginner-friendly and perfect to get an overview of what is available.

You can also generate your project inside your favorite IDE like Eclipse or Intellij by using plugins.

And finally, you can generate your project without leaving your shell with the Spring CLI, and that is what we are going to do.

In this article, we will use the CLI to generate a new Spring Boot Project.

Installing the CLI

Before generating anything, we need to install the Spring CLI on our machine.

For that, you can check out Spring official documentation.

It shows how to install the CLI manually or by using sdkman. Do as you want, but I strongly advise you to use sdkman!

With it, installing the CLI is as simple as typing a single command, and you are good to go.

$ sdk install springboot
$ spring --version
Spring CLI v2.7.1

Bootstrapping the project

We are now ready to bootstrap our project.

Let’s say that we are asked to build a simple REST API exposing simple CRUD operations.

For that, we will need the following dependencies :

a web layer to build the HTTP endpoints and provide the interface to be used by client applications
a data layer to access the database and persist the clients’ operations

On top of that, this REST API needs to be at the cutting edge, so it will use Java 17 and it will be a Gradle project.

Great, we know what we want to build and what is needed to build it, but how do we know what is available to us?

To know what the Spring CLI can provide, we can use the following command.

$ spring init --list
.   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
:: Service capabilities ::  https://start.spring.io

Supported dependencies
+--------------------------------------+--------------------------------------------------------------+-------------------------------+
| Id                                   | Description                                                  | Required version              |
+--------------------------------------+--------------------------------------------------------------+-------------------------------+
| activemq                             | Spring JMS support with Apache ActiveMQ 'Classic'.           | >=2.0.0.RELEASE and <3.0.0-M1 |
|...                                   |                                                              |                               |
| websocket                            | Build WebSocket applications with SockJS and STOMP.          |                               |
+--------------------------------------+--------------------------------------------------------------+-------------------------------+

Project types (* denotes the default)
+-----------------+------------------------------------------+-----------------------------+
| Id              | Description                              | Tags                        |
+-----------------+------------------------------------------+-----------------------------+
| gradle-build    | Generate a Gradle build file.            | build:gradle,format:build   |
| gradle-project  | Generate a Gradle based project archive. | build:gradle,format:project |
| maven-build     | Generate a Maven pom.xml.                | build:maven,format:build    |
| maven-project * | Generate a Maven based project archive.  | build:maven,format:project  |
+-----------------+------------------------------------------+-----------------------------+

Parameters
+-------------+------------------------------------------+------------------------------+
| Id          | Description                              | Default value                |
+-------------+------------------------------------------+------------------------------+
| artifactId  | project coordinates (infer archive name) | demo                         |
| bootVersion | spring boot version                      | 2.7.1                        |
| description | project description                      | Demo project for Spring Boot |
| groupId     | project coordinates                      | com.example                  |
| javaVersion | language level                           | 17                           |
| language    | programming language                     | java                         |
| name        | project name (infer application name)    | demo                         |
| packageName | root package                             | com.example.demo             |
| packaging   | project packaging                        | jar                          |
| type        | project type                             | maven-project                |
| version     | project version                          | 0.0.1-SNAPSHOT               |
+-------------+------------------------------------------+------------------------------+

We get a list of all available dependencies, project types, and project parameters that we can specify during the project bootstrap.

For the web layer, we are using the web dependency that contains Spring MVC and other web-related dependencies.

For the data layer, we are using the data-jpa dependency that contains Spring data with Hibernate as Implementation of the JPA.

And finally, we need to get the required JDBC driver to connect to our database.

Let’s say that we have chosen PostgreSQL as our database of choice.

We thus need to get the postgresql dependency.

The goal of this article is not to show all available dependencies, so let’s keep it at that for today.

We can now run the command to bootstrap our project.

$ spring init --dependencies=web,data-jpa,postgresql --java-version=17 --build=gradle spring-boot-cli
Using service at https://start.spring.io
Project extracted to '/home/mohzen/dev/spring-boot-cli'

Let’s check out the resulting project.

$ cd spring-boot-cli/
$ ll
total 44
drwxr-xr-x  4 mohzen mohzen 4096 Jul 13 22:16 ./
drwxr-xr-x 18 mohzen mohzen 4096 Jul 13 22:16 ../
-rw-r--r--  1 mohzen mohzen  444 Jul 13 22:16 .gitignore
-rw-r--r--  1 mohzen mohzen 1397 Jul 13 22:16 HELP.md
-rw-r--r--  1 mohzen mohzen  559 Jul 13 22:16 build.gradle
drwxr-xr-x  3 mohzen mohzen 4096 Jul 13 22:16 gradle/
-rwxr-xr-x  1 mohzen mohzen 8070 Jul 13 22:16 gradlew*
-rw-r--r--  1 mohzen mohzen 2763 Jul 13 22:16 gradlew.bat
-rw-r--r--  1 mohzen mohzen   37 Jul 13 22:16 settings.gradle
drwxr-xr-x  4 mohzen mohzen 4096 Jul 13 22:16 src/

We are now ready to start building our application!

Implement Role-based authorization in Spring Boot with Keycloak

Gauthier Cassany — Tue, 26 Jul 2022 11:04:00 +0000

Role-based access control is a must-have for any application dealing with users who can access resources depending on their organization's role.

In a previous article, we have learned how to secure our Spring Boot REST API with Keycloak by using the OpenID Connect authentication protocol.

In this article, we are going to build on this sample application and add role-based authorization.

The purpose is to authorize access of some endpoints only to users having a specific role. More precisely, we are going to restrict the DELETE endpoint to only users having the admin role.

Adding a new endpoint

Let’s first extend our Spring Controller by adding a new DELETE endpoint.

package com.mozen.springbootkeycloack.controller;

import com.mozen.springbootkeycloack.model.Plant;
import com.mozen.springbootkeycloack.service.PlantService;
import com.sun.istack.NotNull;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

@Slf4j
@RestController()
@RequestMapping("/plant")
public class PlantController {

        ...

    @DeleteMapping("/{plantId}")
    public void deletePlant(@PathVariable long plantId) {

        log.info("Delete plant request for plant " + plantId + " received");

        plantService.deletePlant(plantId);
    }
}

Extending the configuration

Going back to the application.yml file, we specify a new property for the Keycloak configuration.

...

keycloak:
    ...
  use-resource-role-mappings: false

We set the use-resource-role-mappings property to false.

It means that authorization will be based on Keycloak realm level roles, and not client roles specific to the Spring Boot application.

We do that because the default Keycloak admin role we are using is defined as a realm-level role.

This property is already set to false by default, but I find that setting it explicitly makes it clearer in this context. This is a matter of taste though, so you can skip it if you want.

We also need to make a slight edit to the WebSecurityConfiguration.

@KeycloakConfiguration
public class WebSecurityConfiguration extends KeycloakWebSecurityConfigurerAdapter {

    @Autowired
    public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
        KeycloakAuthenticationProvider keycloakAuthenticationProvider =
                keycloakAuthenticationProvider();
        keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(new SimpleAuthorityMapper());
        auth.authenticationProvider(keycloakAuthenticationProvider);
    }

    @Bean
    @Override
    protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
        return new NullAuthenticatedSessionStrategy();
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        http.csrf()
                .disable()
                .authorizeRequests()
                .antMatchers(HttpMethod.DELETE,"/plant/**")
                .hasRole("admin")
                .anyRequest()
                .authenticated()
                .and()
                .sessionManagement()
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS);
    }
}

We add a new antMatcher that restricts all routes starting with ‘/plant/’ and using the HTTP DELETE method, which fits the deletePlant endpoint we have added previously.

Note the role mapping is done using the SimpleAuthorityMapper. By default, Spring Security adds a prefix ‘ROLE_’ to any authority, but Keycloak’s roles do not.

By using this mapper, the prefix will be added to any authority sent in the Keycloak token if it is not already here.

Configuring Keycloak

We already have the ‘admin’ user from the previous article. This user already has the ‘admin’ role.

We need to create a new user that does not own the admin role.

This one will be used to demonstrate that our role-based authorization is working and that the DELETE endpoint will be forbidden for this user.

Testing the application

Let's first start our application.


mvn spring-boot:run

To test our setup, we are going to use the same method as the previous article, and use Postman to play the client role.

We improve our Postman configuration by adding the new user in the variables collection

Let’s first ensure that the ‘user’ with no admin role cannot access the delete endpoint.

We First fetch the token with the non-admin user.

And let’s try to use the delete endpoint by providing this token in the Authorization header.

As expected, we receive a 401 Unauthorized error, because the admin role is missing.

This time around, we get back a new token with the admin user.

The delete endpoint can now be used successfully.

And that’s it! We now have Role-Based Authorization.

Note that since version 5.7.0 of Spring Security, the WebSecurityConfigurerAdapter is deprecated. It is now advised to use the new configuration type following the component-based design. As of now, the Keycloak Spring Boot Adapter does not support this new configuration type. I will try to update this article to support this new configuration type as soon as possible.

You can access the demo project for this blog post here https://github.com/Mozenn/spring-boot-keycloak-roles.

Secure your Spring Boot Rest API with Keycloak

Gauthier Cassany — Mon, 27 Jun 2022 11:30:47 +0000

Security is often overlooked and is seen as a burden that goes against development velocity. But in today’s age, the more secure layers there are, the safer it is. That is what Security in Depth is, and one part is to secure our REST API.

In this blog post, we are going to learn how to add authentication to a Spring Boot REST API.

And instead of building a brittle custom implementation that might contain security issues, it is better to rely on battle-tested solutions. One of them is Keycloak, an open-source identity, and management solution developed by Red Hat.

In a previous post, we have already learned how to set up Keycloak using Docker, and we are going to use this setup as a starting point.

Of course, you can set up your Keycloak instance however you want. The only requirement is to have a running Keycloak instance.

Project setup

The first step is to generate the spring boot project using Spring Initializr. In this tutorial, We are using the spring CLI via SDKman, but it can quickly be done using the web UI https://start.spring.io/ or directly through your IDEA https://www.jetbrains.com/help/idea/spring-boot.html.

To have a walkthrough of how to set up the CLI on your own machine, follow this guide https://docs.spring.io/spring-boot/docs/current/reference/html/getting-started.html#getting-started.installing.cli.sdkman. Once you have installed the CLI , execute this command to generate the project with the necessary dependencies.

spring init --dependencies=web,data-jpa,h2,lombok,security spring-boot-keycloak

We package the following dependencies :

the web dependency for the REST API
the spring data JPA for the data access layer, which uses hibernate as the default Object Relational Mapping tool
the h2 library to provide an easy-to-use in-memory embedded database. This type of database is suited for small toy projects such as this one, but it should not be used for any serious project that will be shipped to production at some point
Lombok to generate snippets of code through annotation and avoid any boilerplate code
The security dependency to get access to Spring Security

On top of that, we also add the Keycloak Spring Boot Adapter dependency to our pom.xml.

...

<properties>
    <keycloak.version>17.0.0</keycloak.version>
</properties>

...

<dependencies>
    ...
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-spring-boot-starter</artifactId>
        <version>${keycloak.version}</version>
    </dependency>
</dependencies>

This adapter provides an implementation to integrate Keycloak with Spring Security.

The configuration for the adapter is placed in the application.yml file.

server:
  port: 9000

spring:
  datasource:
    url: jdbc:h2:mem:mydb
    username: mozen
    password: password

keycloak:
  realm: master
  auth-server-url: http://${KEYCLOAK_HOST:localhost}:${KEYCLOAK_PORT:8180}/auth
  resource: spring-app
  bearer-only: true

This resource is set up as bearer only. This means that this application is not participating in the login flow, and it expects all received requests to contain the authentication bearer token.

With this type of client, we rely on other clients to execute the authentication flow and get the bearer token. Usually, a frontend application handles the login and gets the bearer token, then sends requests to the backend application by providing the token in the HTTP headers.

We use the master realm, which is the default Keycloak realm.

There are many more properties you can configure here to fit your needs. To get an overview of all of them, you can checkout out this page.

Building the application without security

Let’s define the necessary components for our simple HTTP endpoint.

First, let’s create a simple Plant Entity that will represent the resource of our REST API.

 package com.mozen.springbootkeycloack.model;

import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;
import org.hibernate.annotations.NaturalId;

import javax.persistence.*;
import java.time.Instant;

@Entity
@Table(name = "plant")
@Getter
@Setter
@ToString
@EqualsAndHashCode
public class Plant {

    public Plant() {
        this.createdAt = Instant.now();
    }

    public Plant(String name, String scientificName, String family) {
        this.name = name;
        this.scientificName = scientificName;
        this.family = family;
        this.createdAt = Instant.now();
    }

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id")
    private Long id;

    @NaturalId()
    @Column(name = "name")
    private String name;

    @NaturalId()
    @Column(name = "scientificName")
    private String scientificName;

    @Column(name = "family")
    private String family;

    @Column(name = "createdAt")
    private Instant createdAt = Instant.now();
}

We then create a Spring JPA Repository for this entity.

package com.mozen.springbootkeycloack.repository;

import com.mozen.springbootkeycloack.model.Plant;
import org.springframework.data.repository.CrudRepository;

public interface PlantRepository extends CrudRepository<Plant, Long> {
}

By extending the CrudRepository interface, we get access to all CRUD operations on the entity.

Let’s continue with the business layer.

package com.mozen.springbootkeycloack.service;

import com.mozen.springbootkeycloack.model.Plant;
import com.mozen.springbootkeycloack.repository.PlantRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.Optional;

@Transactional
@Service
public class PlantService {

    private PlantRepository plantRepository;

    public PlantService(
            PlantRepository plantRepository) {
        this.plantRepository = plantRepository;
    }

    public Plant getPlant(long plantId) throws RuntimeException {
        Optional<Plant> plantOpt = plantRepository.findById(plantId);

        if (!plantOpt.isPresent()) {
            throw new RuntimeException("Plant could not be found with id : " + plantId);
        }

        return plantOpt.get();
    }
}

This sample application is so small that we could skip implementing this service and implement the logic directly inside the controller, but let’s do things right regardless.

Finally, We create our HTTP endpoint inside a Spring Controller.

 package com.mozen.springbootkeycloack.controller;

import com.mozen.springbootkeycloack.model.Plant;
import com.mozen.springbootkeycloack.service.PlantService;
import com.sun.istack.NotNull;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

@Slf4j
@RestController()
@RequestMapping("/plant")
public class PlantController {

    private PlantService plantService;

    public PlantController(PlantService plantService) {
        this.plantService = plantService;
    }

    @GetMapping("/{plantId}")
    public Plant getPlant(@PathVariable @NotNull Long plantId) {

        log.info("Request for plant " + plantId + " received");

        return plantService.getPlant(plantId);
    }
}

If you want more details on this implementation, I have made a similar application in a previous blog where I go into more details on the how and why of this implementation.

Keycloak configuration

We can now dive into Keycloak configuration.

Once logged into the admin console, we can go to the client page and create the client for our Spring Boot application.

We have to set the Access Type to bearer-only to match the configuration of the application.yml file.

In order to test our endpoint, we define a second client that will represent the client (in the sens of client-server relationship) for our Spring application.

This client is of type public, and is responsible for the login with Keycloak to get the access token that will be sent in each request to the Spring Boot application.

This type of client is usually used for frontend applications that handle the login process inside the browser.

Spring security Setup

Keycloak is now ready, and so is our application, but it has yet to be secured.

For that, we need to set up Spring Security.

It can be configured like any other Spring Boot project, by creating a class extending the WebSecurityConfigurerAdapter.

We make use of the previously added Keycloak adapter by extending the KeycloakWebSecurityConfigurerAdapter.

package com.mozen.springbootkeycloack.security;

import org.keycloak.adapters.springsecurity.KeycloakConfiguration;
import org.keycloak.adapters.springsecurity.authentication.KeycloakAuthenticationProvider;
import org.keycloak.adapters.springsecurity.config.KeycloakWebSecurityConfigurerAdapter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.core.authority.mapping.SimpleAuthorityMapper;
import org.springframework.security.web.authentication.session.NullAuthenticatedSessionStrategy;
import org.springframework.security.web.authentication.session.SessionAuthenticationStrategy;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.util.Arrays;

@KeycloakConfiguration
public class WebSecurityConfiguration extends KeycloakWebSecurityConfigurerAdapter {

    @Autowired
    public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
        KeycloakAuthenticationProvider keycloakAuthenticationProvider =
                keycloakAuthenticationProvider();
        keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(new SimpleAuthorityMapper());
        auth.authenticationProvider(keycloakAuthenticationProvider);
    }

    @Bean
    @Override
    protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
        return new NullAuthenticatedSessionStrategy();
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        http.csrf()
            .disable()
            .authorizeRequests()
            .anyRequest()
            .authenticated()
            .and()
            .sessionManagement()
            .sessionCreationPolicy(SessionCreationPolicy.STATELESS);
    }
}

It extends the WebSecurityConfigurerAdapter and sets up all Keycloak-related configurations such as filter configuration or authentication. Everything is done to make our life easy and work out of the box with minimal configuration on our hands. We just have to define the configuration specific to our application.

You can still check out how the adapter has been implemented by exploring the code if you are interested in how things work behind the scene.

The most important part is the override of the configure() method. It is where we enforce that every received request must be authenticated, by containing the authentication token in the HTTP headers.

Because we will consume the endpoint using Postman, we can safely disable CSRF.

Disabling CSRF means that the application is now vulnerable to CSRF attacks. This type of attack can only be performed from a request coming from a browser. If we wanted to handle it safely, we would need to manage a CSRF cookie we would provide during login and check if it is sent in each request we received.

We also provide a SessionAuthenticationStrategy bean of type `NullAuthenticatedSessionStrategy. It basically does nothing, but this is fine because authentication is not handled by the application for bearer-only clients.

At the time of writing this post, the Spring Boot Keycloak adapter contains a bug that raises a circular dependencies expectation at startup.

A workaround is to declare a Bean of type KeycloakConfigResolver inside a class annotated with @Configuration, but different from the WebSecurityConfiguration class we have already defined.

`
@Configuration
public class ApplicationConfiguration {

@Bean
public KeycloakConfigResolver KeycloakConfigResolver() {
    return new KeycloakSpringBootConfigResolver();
}

}
`

And we are done with the Spring Boot application.

Client Setup and Testing

Let's first start our application.

mvn spring-boot:run

To test what we have built, we need a client application that consumes the HTTP endpoint.

In a production environment, the request usually comes from a front-end Single Page Application or another backend service. For the sake of this tutorial, we are going to handle the login process to get the authentication token using Postman. We are going to use the public client we have created in the previous part.

Let’s first create a Postman collection.

We set the authorization configuration at the collection level so that every request of the collection will inherit from it, and send the token.

For the same purpose, we define the variables at the collection level to make them available to each request.

The first request is the GetToken request. It uses the OpenID token endpoint from Keycloak by following the password authentication workflow.

Because this request is sent to Keycloak, we must override the authorization configuration to indicate that no auth needs to be done.

We could manually copy and paste the token returned by Keycloak, but there is a simpler way by using the Test feature from Postman.

This feature allows us to write some code. It is usually used to run some tests on the response. But we can also leverage this feature to feed the token inside the keycloakToken variable we have defined at the collection level.

In this way, we can directly run sequentially the GetToken request followed by the GetPlant Request without doing any manual action.

We can now successfully access the Plant endpoint.

In the following blog post, we will learn how to improve our sample application with Role-based Access.

You can access the demo project for this blog post here https://github.com/Mozenn/spring-boot-keycloak.

Build a Spring Boot REST API with Paginated Full-Text Search using Hibernate Search

Gauthier Cassany — Thu, 26 May 2022 11:54:30 +0000

In a previous article, we learned how to add full-text-search to a Spring Boot Rest API using Hibernate Search.

In this article, we are going to build on that, and learn how to add paginated search to our existing REST API.

Project setup

You can check out the previous blog post to get a detailed walkthrough on how to set up the project using Spring Initializer.

You can also get the final result of the last article on Github.

Extending the data model

The first thing to tackle is to find a way to receive the new data needed to add pagination.

For that, we can extend the SearchRequestDTO.

package com.mozen.springbootpaginatedsearch.model;

import lombok.Data;
import lombok.EqualsAndHashCode;

import javax.validation.constraints.Min;

@Data
@EqualsAndHashCode(callSuper = true)
public class PageableSearchRequestDTO extends SearchRequestDTO{

    @Min(0)
    private int pageOffset;
}

We only need to define a single new field, the pageOffset. This field is used to control the index of the page we want to query.

We also define a new PageDTO. This data structure is used to hold the result of our paginated search.

package com.mozen.springbootpaginatedsearch.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.List;

@Data
@AllArgsConstructor
@NoArgsConstructor
public class PageDTO<T> {

    private List<T> content;
    private long total;
}

Extending the data layer

We declare a new searchPageBy function in the SearchRepository interface.

package com.mozen.springbootpaginatedsearch.repository;

import com.mozen.springbootpaginatedsearch.model.PageDTO;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.repository.NoRepositoryBean;

import java.io.Serializable;
import java.util.List;

@NoRepositoryBean
public interface SearchRepository<T, ID extends Serializable> extends JpaRepository<T, ID> {

    List<T> searchBy(String text, int limit, String... fields);

    PageDTO<T> searchPageBy(String text, int limit, int offset, String... fields);
}

The signature is quite similar to the existing searchBy function. We just add the new offset parameter that indicates the page to query.

We replicate this change to the SearchRepositoryImpl class.

package com.mozen.springbootpaginatedsearch.repository;

import com.mozen.springbootpaginatedsearch.model.PageDTO;
import org.hibernate.search.engine.search.query.SearchResult;
import org.hibernate.search.mapper.orm.Search;
import org.hibernate.search.mapper.orm.session.SearchSession;
import org.springframework.data.jpa.repository.support.JpaEntityInformation;
import org.springframework.data.jpa.repository.support.SimpleJpaRepository;
import org.springframework.transaction.annotation.Transactional;

import javax.persistence.EntityManager;
import java.io.Serializable;
import java.util.List;

@Transactional
public class SearchRepositoryImpl<T, ID extends Serializable> extends SimpleJpaRepository<T, ID>
        implements SearchRepository<T, ID> {

    private final EntityManager entityManager;

    public SearchRepositoryImpl(Class<T> domainClass, EntityManager entityManager) {
        super(domainClass, entityManager);
        this.entityManager = entityManager;
    }

    public SearchRepositoryImpl(
            JpaEntityInformation<T, ID> entityInformation, EntityManager entityManager) {
        super(entityInformation, entityManager);
        this.entityManager = entityManager;
    }

    @Override
    public List<T> searchBy(String text, int limit, String... fields) {

        SearchResult<T> result = getSearchResult(text, limit, 0, fields);

        return result.hits();
    }

    @Override
    public PageDTO<T> searchPageBy(String text, int limit, int offset, String... fields) {
        SearchResult<T> result = getSearchResult(text, limit, offset, fields);

        return new PageDTO<T>(result.hits(), result.total().hitCount());
    }

    private SearchResult<T> getSearchResult(String text, int limit, int offset, String[] fields) {
        SearchSession searchSession = Search.session(entityManager);

        SearchResult<T> result =
                searchSession
                        .search(getDomainClass())
                        .where(f -> f.match().fields(fields).matching(text).fuzzy(2))
                        .fetch(offset, limit);
        return result;
    }
}

We can reuse the existing getSearchResult method, by adding a new “offset” argument. We then use this argument in the Hibernate Search fetch() method, which already provides a signature that accepts the offset parameter for pagination purposes.

The PageDTO is built using the result from the search Query.

Extending the business layer

We can build on the existing logic by extracting the part handling the field to search on to avoid duplication, and then call the repository function with or without pagination depending on whether we use the searchPlant() method or the searchPlantPage() method.

package com.mozen.springbootpaginatedsearch.service;

import com.mozen.springbootpaginatedsearch.model.PageDTO;
import com.mozen.springbootpaginatedsearch.model.Plant;
import com.mozen.springbootpaginatedsearch.repository.PlantRepository;
import org.springframework.stereotype.Service;

import java.util.Arrays;
import java.util.List;

@Service
public class PlantService {

    private PlantRepository plantRepository;

    private static final List<String> SEARCHABLE_FIELDS = Arrays.asList("name","scientificName","family");

    public PlantService(PlantRepository plantRepository) {
        this.plantRepository = plantRepository;
    }

    public List<Plant> searchPlants(String text, List<String> fields, int limit) {

        List<String> fieldsToSearchBy = getFieldsToSearchBy(fields);

        return plantRepository.searchBy(
                text, limit, fieldsToSearchBy.toArray(new String[0]));
    }

    public PageDTO<Plant> searchPlantPage(String text, List<String> fields, int limit, int pageOffset) {
        List<String> fieldsToSearchBy = getFieldsToSearchBy(fields);

        return plantRepository.searchPageBy(
                text, limit, pageOffset, fieldsToSearchBy.toArray(new String[0]));
    }

        // We extract the common logic in a separate function
    private List<String> getFieldsToSearchBy(List<String> fields) {
        List<String> fieldsToSearchBy = fields.isEmpty() ? SEARCHABLE_FIELDS : fields;

        boolean containsInvalidField = fieldsToSearchBy.stream(). anyMatch(f -> !SEARCHABLE_FIELDS.contains(f));

        if(containsInvalidField) {
            throw new IllegalArgumentException();
        }
        return fieldsToSearchBy;
    }
}

Extending the web layer

There is not much to do in this one.

We just need a new endpoint to receive paginated search requests by using our new PageableSearchRequestDTO, and by returning a PageDTO.

package com.mozen.springbootpaginatedsearch.controller;

import com.mozen.springbootpaginatedsearch.model.PageDTO;
import com.mozen.springbootpaginatedsearch.model.PageableSearchRequestDTO;
import com.mozen.springbootpaginatedsearch.model.Plant;
import com.mozen.springbootpaginatedsearch.model.SearchRequestDTO;
import com.mozen.springbootpaginatedsearch.service.PlantService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@Slf4j
@RestController
@RequestMapping("/plant")
public class PlantController {

    private PlantService plantService;

    public PlantController(PlantService plantService) {
        this.plantService = plantService;
    }

    @GetMapping("/search")
    public List<Plant> searchPlants(SearchRequestDTO searchRequestDTO) {

        log.info("Request for plant search received with data : " + searchRequestDTO);

        return plantService.searchPlants(searchRequestDTO.getText(), searchRequestDTO.getFields(), searchRequestDTO.getLimit());
    }

    @GetMapping("/search/page")
    public PageDTO<Plant> searchPlantPage(PageableSearchRequestDTO pageableSearchRequestDTO) {

        log.info("Request for plant page search received with data : " + pageableSearchRequestDTO);

        return plantService.searchPlantPage(pageableSearchRequestDTO.getText(), pageableSearchRequestDTO.getFields(), pageableSearchRequestDTO.getLimit(), pageableSearchRequestDTO.getPageOffset());
    }
}

We log the received request data and call our new function defined in the plantService.

Putting it all together

Time to test our code!

We can start our application with the command line.

mvn spring-boot:run

Similar to the first article, we can either use Postman ...

Or we can use a simple cUrl command.

// Request page 1 with 2 items per page on all fields

curl -X GET 'http://localhost:9000/plant/search?text=cherry&limit=2&pageOffset=1'

// Request page 2 with 3 items per page on scientificName field

curl -X GET 'http://localhost:9000/plant/search?text=asian&limit=3&fields=name&fields=scientificName&pageOffset=2'

And we are done! Our full-text search implementation now supports pagination.

There is still a lot we can add to our implementation, and I will do so in following articles.

You can access the demo project for this blog post here https://github.com/Mozenn/spring-boot-paginated-search.

Build a Spring Boot REST API with Full-Text Search using Hibernate Search

Gauthier Cassany — Wed, 06 Apr 2022 15:43:56 +0000

Search is one of the pillars of the web, and full-text search is one of the mandatory features that every website needs. But implementing such a feature is complex, and lots of skilled engineers have already thought hard about this topic. So let’s not reinvent the wheel, and use the battle-tested Hibernate Search library.

In this blog post, we are going to learn how to build a simple REST API endpoint in Spring boot with full-text search using Hibernate Search. We will only go through the basics, but Hibernate Search is a feature-rich library with many features going way beyond what we will see in this post. You can check everything that it provides in the official documentation https://docs.jboss.org/hibernate/stable/search/reference/en-US/html_single/#gettingstarted-framework.

Project Bootstrap

The first step is to generate the spring boot project using spring initializr. In this tutorial, We are using the spring CLI via SDKman, but it can easily be done using the web UI https://start.spring.io/ or directly through your IDEA https://www.jetbrains.com/help/idea/spring-boot.html.

spring init --dependencies=web,data-jpa,h2,lombok,validation spring-boot-hibernate-search

We package the following dependencies :

the web dependency for the REST API.
the spring data JPA for the data access layer, which uses hibernate as the default Object Relational Mapping tool.
the h2 library to provide an easy-to-use in-memory embedded database. This type of database is suited for small toy projects such as this one, but it should not be used for any serious project that will be shipped to production at some point.
Lombok to generate snippets of code through annotation and avoid any boilerplate code
validation is the Hibernate implementation of the validation API that follows the JSR 380 specification. It allows, among other things, to validate beans using annotation.

Hibernate Search Setup

As with many libraries, Spring Boot provides an easy way to integrate Hibernate Search. We just need to add the required dependencies into the pom.xml file.

<properties>
    <hibernate.search.version>6.1.1.Final</hibernate.search.version>
</properties>

...

<dependencies>
    ...
    <dependency>
        <groupId>org.hibernate.search</groupId>
        <artifactId>hibernate-search-mapper-orm</artifactId>
        <version>${hibernate.search.version}</version>
    </dependency>
    <dependency>
        <groupId>org.hibernate.search</groupId>
        <artifactId>hibernate-search-backend-lucene</artifactId>
        <version>${hibernate.search.version}</version>
    </dependency>
</dependencies>

We are using hibernate search 6 which is the most recent version to date, with Lucene as the backend. Lucene is an open-source indexing and search engine library, and the default implementation used by Hibernate Search. We could also use different implementations such as ElasticSearch or OpenSearch.

Defining the data model

The first step is to define the model of the entity on which the search will be done.

As an example, we will use a Plant entity, containing the plant's common name, scientific name, family, and date of creation.

import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;
import org.hibernate.annotations.NaturalId;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.FullTextField;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.Indexed;

import javax.persistence.*;
import java.time.Instant;

@Indexed
@Entity
@Table(name = "plant")
@Getter
@Setter
@ToString
@EqualsAndHashCode
public class Plant {

    public Plant() {
        this.createdAt = Instant.now();
    }

    public Plant(String name, String scientificName, String family) {
        this.name = name;
        this.scientificName = scientificName;
        this.family = family;
        this.createdAt = Instant.now();
    }

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @FullTextField()
    @NaturalId()
    private String name;

    @FullTextField()
    @NaturalId()
    private String scientificName;

    @FullTextField()
    private String family;

    private Instant createdAt ;
}

Let’s ignore the JPA and Lombok annotations, and focus on the Hibernate Search-related ones.

First, the @Index annotation indicates to Hibernate Search that we want to index this entity in order to apply search operation on it.

Second, we annotate the fields we want to search on with the @FullTextField annotation. This annotation works only for string fields, but others exist for fields of different types.

And ... that’s it! It is as simple as that for a simple case such as ours!

But you can do much more with what the library provides, such as using conditional indexing or tweaking indexing coordination. Once again, check out the official documentation if you want to know more.

Defining the data layer

We now need to define our data layer handling the interactions with the database.

We use Spring Data repositories which build an abstraction around the Hibernate implementation of JPA. It is provided in the spring-boot-starter-data-jpa dependency added previously.

For a basic use case requiring only CRUD operations, we can define a simple repository for the Plant entity and extends the JpaRepository interface directly.

But this is not enough for full-text search. In our case, we would like to add the search features to all repositories we define. For that, we need to add custom methods to the JpaRepository interface, or any interface extending the base Repository interface.

This way, we declare those methods only once and make them available for every repository of every entity of our project.

Let’s see how we can do such a thing.

First, we need to create a new generic interface that extends the JpaRepository interface.

@NoRepositoryBean
public interface SearchRepository<T, ID extends Serializable> extends JpaRepository<T, ID> {

    List<T> searchBy(String text, int limit, String... fields);
}

We declare the searchBy function that will be used for full-text search operations.

The @NoRepositoryBean annotation tells spring that this repository interface should not be instantiated like any other bean with the @Repository annotation.

We use this annotation because the purpose of this interface is not to be used directly, but to be implemented by other repositories.

We also need to create the implementation for this interface.

@Transactional
public class SearchRepositoryImpl<T, ID extends Serializable> extends SimpleJpaRepository<T, ID>
        implements SearchRepository<T, ID> {

    private final EntityManager entityManager;

    public SearchRepositoryImpl(Class<T> domainClass, EntityManager entityManager) {
        super(domainClass, entityManager);
        this.entityManager = entityManager;
    }

    public SearchRepositoryImpl(
            JpaEntityInformation<T, ID> entityInformation, EntityManager entityManager) {
        super(entityInformation, entityManager);
        this.entityManager = entityManager;
    }

    @Override
    public List<T> searchBy(String text, int limit, String... fields) {

        SearchResult<T> result = getSearchResult(text, limit, fields);

        return result.hits();
    }

    private SearchResult<T> getSearchResult(String text, int limit, String[] fields) {
        SearchSession searchSession = Search.session(entityManager);

        SearchResult<T> result =
                searchSession
                        .search(getDomainClass())
                        .where(f -> f.match().fields(fields).matching(text).fuzzy(2))
                        .fetch(limit);
        return result;
    }
}

The searchBy method implementation is where Hibernate Search is used.

The following arguments are passed:

text: text to search for
limit: maximum number of elements to search for
fields: name of all the fields to search on

We make use of java varargs to pass all the fields we want to search on.

Here, we use a simple fuzzy algorithm as the full-text matching algorithm, but we can easily make more complex searches using custom analyzers.

From now on, repositories requiring full-text-search just have to implement the SearchRepository interface instead of the standard JpaRepository interface provided by Spring.

And this is exactly what we are doing for the Plant entity.

package com.mozen.springboothibernatesearch.repository;

import com.mozen.springboothibernatesearch.model.Plant;
import org.springframework.stereotype.Repository;

@Repository
public interface PlantRepository extends SearchRepository<Plant, Long> {
}

As you can see, all implementation is already done, and we just need to implement the previously created SearchRepository interface to get access to the implementation defined in the SearchRepositoryImpl class.

The final step is to indicate to Spring to detect Jpa Repositories using the SearchRepositoryImpl as the base class.

package com.mozen.springboothibernatesearch;

import com.mozen.springboothibernatesearch.repository.SearchRepositoryImpl;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;

@Configuration
@EnableJpaRepositories(repositoryBaseClass = SearchRepositoryImpl.class)
public class ApplicationConfiguration {
}

Note that because we do not specify any base package to search into, Spring will use the package where this Configuration is defined as the base package.

Defining the business layer

Let’s now create the business code using the data layer we’ve just defined, by declaring a service.

package com.mozen.springboothibernatesearch.service;

import com.mozen.springboothibernatesearch.model.Plant;
import com.mozen.springboothibernatesearch.repository.PlantRepository;
import org.springframework.stereotype.Service;

import java.util.Arrays;
import java.util.List;

@Service
public class PlantService {

    private PlantRepository plantRepository;

    private static final List<String> SEARCHABLE_FIELDS = Arrays.asList("name","scientificName","family");

    public PlantService(PlantRepository plantRepository) {
        this.plantRepository = plantRepository;
    }

    public List<Plant> searchPlants(String text, List<String> fields, int limit) {

        List<String> fieldsToSearchBy = fields.isEmpty() ? SEARCHABLE_FIELDS : fields;

        boolean containsInvalidField = fieldsToSearchBy.stream(). anyMatch(f -> !SEARCHABLE_FIELDS.contains(f));

        if(containsInvalidField) {
            throw new IllegalArgumentException();
        }

        return plantRepository.searchBy(
                text, limit, fieldsToSearchBy.toArray(new String[0]));
    }
}

We tell Spring that this bean is part of the business layer of the application.

It contains a searchPlant function that forwards the call to the searchBy function of the SearchRepository.

Before forwarding the call, it validates the provided fields.

Those fields are whitelisted to check that the search will be made only against the desired fields, which are the ones we have annotated with @FullTextField annotation earlier.

We throw an IllegalArgumentException if one of the provided fields is not part of the whitelisted ones. The exception is not handled for the sake of simplicity, but it should be handled properly using one of the many ways provided by spring to handle exceptions.

Defining the web layer

The next step is to define the REST API to receive the HTTP request coming from client applications.

package com.mozen.springboothibernatesearch.controller;

import com.mozen.springboothibernatesearch.model.Plant;
import com.mozen.springboothibernatesearch.model.SearchRequestDTO;
import com.mozen.springboothibernatesearch.service.PlantService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@Slf4j
@RestController
@RequestMapping("/plant")
public class PlantController {

    private PlantService plantService;

    public PlantController(PlantService plantService) {
        this.plantService = plantService;
    }

    @GetMapping("/search")
    public List<Plant> searchPlants(SearchRequestDTO searchRequestDTO) {

        log.info("Request for plant search received with data : " + searchRequestDTO);

        return plantService.searchPlants(searchRequestDTO.getText(), searchRequestDTO.getFields(), searchRequestDTO.getLimit());
    }
}

We use a basic Rest controller with a single GET mapping. Before forwarding the call to the business layer, we log the event to trace the reception of the request to ease the monitoring of the application. It receives the search request using a SearchRequestDTO

 package com.mozen.springboothibernatesearch.model;

import lombok.Data;

import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;
import java.util.ArrayList;
import java.util.List;

@Data
public class SearchRequestDTO {

    @NotBlank
    private String text;

    private List<String> fields = new ArrayList<>();

    @Min(1)
    private int limit;
}

It is a simple POJO containing the parameters used for the search. Once again, we use Javax Bean Validation annotations to ensure the request is valid, as well as Lombok @data annotation to generate boilerplate code (Getters, Setters, toString(), ...).

Note that by using a POJO as a single argument for the REST API endpoint, we expect the client to send those parameters as Request Parameter inside the HTTP request.

Indexing the data

Finally, for Lucene to be able to search through the data, it needs to be indexed.

At runtime, the index is automatically managed by Hibernate, by applying the change each time an operation is executed through Hibernate ORM such as creating or deleting an Entity. However, We still need to initialize the index for data already stored in the database if any.

For that purpose, we need to add some configurations inside the application.yml file:

server:
    port: 9000

spring:
    datasource:
        url: jdbc:h2:mem:mydb
        username: mozen
        password: password
    jpa:
        open-in-view: false
        properties:
            hibernate:
                search:
                    backend:
                        type: lucene
                        directory.root: ./data/index

We indicate the root directory of where the Lucene index is stored. Here, we choose to place it directly in the project folder, but this directory should be carefully chosen when running in production, depending on where your application is deployed.

We also create a component to wrap all operations related to the Lucene index.

package com.mozen.springboothibernatesearch.index;

import org.hibernate.search.mapper.orm.Search;
import org.hibernate.search.mapper.orm.massindexing.MassIndexer;
import org.hibernate.search.mapper.orm.session.SearchSession;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Transactional;

import javax.persistence.EntityManager;

@Transactional
@Component
public class Indexer {

    private EntityManager entityManager;

    private static final int THREAD_NUMBER = 4;

    public Indexer(EntityManager entityManager) {
        this.entityManager = entityManager;
    }

    public void indexPersistedData(String indexClassName) throws IndexException {

        try {
            SearchSession searchSession = Search.session(entityManager);

            Class<?> classToIndex = Class.forName(indexClassName);
            MassIndexer indexer =
                    searchSession
                            .massIndexer(classToIndex)
                            .threadsToLoadObjects(THREAD_NUMBER);

            indexer.startAndWait();
        } catch (ClassNotFoundException e) {
            throw new IndexException("Invalid class " + indexClassName, e);
        } catch (InterruptedException e) {
            throw new IndexException("Index Interrupted", e);
        }
    }
}

For our simple demo application, we only declare a function that builds the index for a given Class using the specified amount of threads in the process.

We now need to call that function passing the previously defined Plant class as an argument.

For that purpose, we could also create a new REST Controller containing an endpoint to trigger the indexing via an HTTP request, to be able to rebuild the index at will.

But for the sake of this article, we are just going to use an ApplicationRunner that will be called at each startup.

@SpringBootApplication
public class Application {

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

    @Bean
    public ApplicationRunner buildIndex(Indexer indexer) throws Exception {
        return (ApplicationArguments args) -> {
            indexer.indexPersistedData("com.mozen.springboothibernatesearch.model.Plant");
        };
    }
}

We define the Bean directly in the main Application class.

The buildIndex method takes the Indexer as an argument through dependency injection. The method is executed during the application startup, right after the context initialization, and before the startup of the spring boot application.

Putting it all together

Let’s first initialize the sample data.

package com.mozen.springboothibernatesearch;

import com.mozen.springboothibernatesearch.index.Indexer;
import com.mozen.springboothibernatesearch.model.Plant;
import com.mozen.springboothibernatesearch.repository.PlantRepository;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import java.util.Arrays;
import java.util.List;

@SpringBootApplication
public class Application {

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

    @Bean
    public ApplicationRunner initializeData(PlantRepository plantRepository) throws Exception {
        return (ApplicationArguments args) -> {
            List<Plant> plants = Arrays.asList(
                    new Plant("subalpine fir", "abies lasiocarpa", "pinaceae"),
                    new Plant("sour cherry", "prunus cerasus", "rosaceae"),
                    new Plant("asian pear", "pyrus pyrifolia", "rosaceae"),
                    new Plant("chinese witch hazel", "hamamelis mollis", "hamamelidaceae"),
                    new Plant("silver maple", "acer saccharinum", "sapindaceae"),
                    new Plant("cucumber tree", "magnolia acuminata", "magnoliaceae"),
                    new Plant("korean rhododendron", "rhododendron mucronulatum", "ericaceae"),
                    new Plant("water lettuce", "pistia", "araceae"),
                    new Plant("sessile oak", "quercus petraea", "fagaceae"),
                    new Plant("common fig", "ficus carica", "moraceae")
            );
            plantRepository.saveAll(plants);
        };
    }

    @Bean
    public ApplicationRunner buildIndex(Indexer indexer) throws Exception {
        return (ApplicationArguments args) -> {
            indexer.indexPersistedData("com.mozen.springboothibernatesearch.model.Plant");
        };
    }
}

We extend the main Application class with a second Bean declaration. It will be run in the same way as the first one, during the application startup.

Note that we did not declare the data SQL schema anywhere. Because our database is an embedded database, the property spring.jpa.hibernate.ddl-auto is set to create-drop by default, and our database schema is automatically generated, which is neat for simple applications such as this one.

Now, let’s test, by first starting our application.

mvn spring-boot:run

There are multiples ways to test the search endpoint.

We can use the API Platform Postman :

Or we can use a simple cUrl command with the required parameters :

// Search in all fields
curl -X GET 'http://localhost:9000/plant/search?text=cherry&limit=5'

// Search only in specified fields 
curl -X GET 'http://localhost:9000/plant/search?text=sian p&limit=5&fields=name&fields=scientificName'

And that’s it! We now have full-text-search implemented through an HTTP endpoint.

As I’ve said many times during this blog, Hibernate Search provides much more features, and we’ve just scratched the surface here.

I will publish more blog posts to address more advanced topics soon.

You can access the demo project for this blog post here https://github.com/Mozenn/spring-boot-hibernate-search.

Build a paginated list in React with SWR and Styled Components

Gauthier Cassany — Thu, 10 Mar 2022 13:01:54 +0000

In a previous blog post, we have learned how to build an API with pagination. In this blog post, we are focusing on how to consume such an API by building a paginated list using React, the most popular javascript frontend framework at the moment.

Project setup

To generate the project, we use the popular toolchain Create React App :

npx create-react-app build-paginated-list-in-react

Once the project is created, we install the required dependencies using npm :

npm i swr axios styled-components

Axios is a popular HTTP client we use to consume the API and get our paginated data. It is a substitute to the fetch API provided by default in most browsers. It is easy to use and provides useful features out of the box such as automatic JSON transformation or HTTP interceptors.

SWR is a data fetching library created by Vercel, the company behind Next.js. It provides a custom React hook with a whole lot of features and built-in optimization, and is very well documented on top of that https://swr.vercel.app/.

Styled Components is the most used CSS-in-JS styling library. CSS-in-JS is a styling technique where the styles are written in javascript, and then parsed to generate the CSS. If CSS-in-JS is not to your liking, there are many other ways to style components in React such as utility libraries like Tailwind, CSS modules, or even vanilla CSS.

For the purpose of this blog, we are using mockAPI as the backend layer https://mockapi.io/docs.

We keep things simple by declaring a single entity and by using the default setup :

The only modification is to define the JSON template of the response for the root endpoint :

We add the total number of elements available which will be of use when building the pagination mechanism.

Building the base

Let’s start by building the basic elements of our application.

The first step is to declare global styles used all across the application :

:root {
  --color-primary: rgb(123, 168, 119);
  --color-primary-light: rgb(214, 244, 207);
  --color-primary-dark: rgb(71, 92, 68);
  --color-primary-disabled: rgb(103, 112, 99);
  --color-secondary: rgb(148, 134, 107);
  --color-background: rgb(255, 255, 255);

  background-color: var(--color-background);
  color: var(--color-primary-dark);
}

body {
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen",
    "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue",
    sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

Aside from fonts, the purpose of this file is to declare the colors used in our application. We use CSS custom properties for that purpose so that if one color needs a slight adjustment, it will be applied everywhere, without the need to modify the color in every single place it is used.

We also edit the default App.js component :

import styled from "styled-components";
import PaginatedList from "./Components/PaginatedList";

const Container = styled.div`
  display: flex;
  flex-direction: column; 
  align-items: center,
  marginTop: 2rem,
  > * {
    margin-right: 0.8rem;
  }
`;

const Header = styled.header`
  padding: 2rem 0 2rem 2rem;
  background: var(--color-primary);
  color: white;
`;

const Title = styled.h2`
  margin: 0;
`;

const App = () => {
  return (
    <Container>
      <Header>
        <Title>Paginated List in React with SWR</Title>
      </Header>
      <main>
        <PaginatedList />
      </main>
    </Container>
  );
};

export default App;

We keep the layout simple, with only a basic header containing a title and the PaginatedList component.

As stated before, we make use of styled component to declare our style directly in the component. In this manner, we keep the styles close to where they are used, and it makes the JSX clear and concise.

Building the components

We can now build the components using a top-down approach, by implementing the components as we need them.

Let’s start by creating the main component which is the PaginatedList component :

import useSWR from "swr";
import axios from "axios";
import styled from "styled-components";
import { useState } from "react";
import Plant from "./Plant";
import Pagination from "./Pagination";
import SortButton from "./SortButton";

const fetcher = async (url) => {
  const res = await axios.get(url);
  return res.data;
};

const Container = styled.div`
  display: flex;
  flex-direction: column;
  align-items: center;
  margin-top: 2rem;
`;

const PlantContainer = styled.div`
  display: flex;
  flex-direction: column;
  align-items: center;
  margin-bottom: 2rem;
`;

const PaginatedList = () => {
  const [page, setPage] = useState(1);
  const [sortBy, setSortBy] = useState("name");
  const [order, setOrder] = useState("desc");
  const limit = 5;

  const { data, error } = useSWR(
    `${process.env.REACT_APP_API_URL}/plant?page=${page}&limit=${limit}&sortBy=${sortBy}&order=${order}`,
    fetcher
  );

  if (!data || !data.items) {
    return null;
  }

  return (
    <Container>
      <SortButton order={order} setOrder={setOrder} />
      <PlantContainer>
        {data.items.map((plant) => (
          <Plant plant={plant} key={plant.name} />
        ))}
      </PlantContainer>
      <Pagination
        page={page}
        setPage={setPage}
        limit={limit}
        total={data.total}
      />
    </Container>
  );
};

export default PaginatedList;

We keep track of the state of the pagination and sorting using useState hooks. The state and their setter functions are passed to the components that need them through props, but we could use a Context or even a global state management library if we would want our application to grow in complexity, and avoid bad practices like props drilling.

We fetch the data from MockAPI using the useSWR hook. This hook takes a key and a fetcher function that is given the key as an argument.
In our case, the key is simply the complete URL of the endpoint to fetch our data from, and the fetcher function a simple fetch to the provided URL, which is done using Axios ... and that’s it!

The useSwr also returns an error object, which is defined only if the promise from the fetch has been rejected. We don’t handle it here, but we could return a different component when the error is defined.

Using fetching library such as SWR is great because, on top of providing a very straightforward API, It also provides handy features that improve performance and user experience out of the box such as automatic revalidation, error handling, caching, and much more. You can check the official documentation to learn more about it https://swr.vercel.app/docs/getting-started.

Once the data is fetching from MockAPI, we map each fetched plant to a Plant component :

import styled from "styled-components";

const Container = styled.div`
  display: flex;
  align-items: center;
  border: 3px solid var(--color-secondary);
  border-radius: 15px;
  padding: 0.6rem;
  margin-top: 2rem;
  > * {
    margin-right: 0.8rem;
  }
`;

const Key = styled.label``;

const Value = styled.label`
  margin-left: 0.5rem;
  font-weight: 700;
`;

const Plant = ({ plant }) => {
  return (
    <Container>
      {Object.entries(plant).map(([key, value]) => {
        return (
          <div>
            <Key>{`${key} :`}</Key>
            <Value>{`${value}`}</Value>
          </div>
        );
      })}
    </Container>
  );
};

export default Plant;

We loop on each property of the plant to display each value alongside its key. We again make use of styled component and flexbox for the styling of the component.

As you may have noticed, the fetched data is sorted thanks to the sortBy and order query string parameters in the URL. In our simple demo application, the field by which to sort by is hardcoded, but we could create a component to let the user set it dynamically.

To control the order of the list, we define a SortButton component :

import styled from "styled-components";
import sortasc from "../images/sortasc.svg";
import sortdesc from "../images/sortdesc.svg";

const Button = styled.div`
  border-radius: 15px;
  padding: 0.6rem;
  cursor: pointer;
  background-color: var(--color-primary);
  transition: background-color 0.3s;
  &:hover {
    background-color: var(--color-primary-dark);
  }
  &:active {
    background-color: var(--color-primary-light);
  }
`;

const Image = styled.img`
  width: 1.5rem;
  filter: invert(100%) sepia(0%) saturate(7500%) hue-rotate(175deg)
    brightness(121%) contrast(114%);
`;

const SortButton = ({ order, setOrder }) => {
  return (
    <Button
      onClick={() =>
        setOrder((previousOrder) => (previousOrder === "desc" ? "asc" : "desc"))
      }
    >
      <Image src={order === "desc" ? sortdesc : sortasc} alt='sort icon' />
    </Button>
  );
};

export default SortButton;

The state for the order and its setter are passed as props directly to the component.

The order toggles between descending and ascending order each time the button is pressed. The component then re-renders to update the image to show the new order applied to the list.

Let’s now checkout the Pagination component, which control everything pagination related :

import styled from "styled-components";
import chevronLeft from "../images/chevron-left.svg";
import chevronsLeft from "../images/chevrons-left.svg";
import chevronRight from "../images/chevron-right.svg";
import chevronsRight from "../images/chevrons-right.svg";

const PaginationContainer = styled.div`
  display: flex;
  align-items: center;
  > * {
    margin-right: 0.8rem;
  }
`;

const PaginationButton = styled.button`
  display: flex;
  align-items: center;
  outline: none;
  border: none;
  border-radius: 50px;
  img {
    filter: invert(100%) sepia(0%) saturate(7500%) hue-rotate(175deg)
      brightness(121%) contrast(114%);
  }
  ${(props) => (props.disabled ? disabled : enabled)};
`;

const enabled = `
cursor: pointer;
background-color: var(--color-primary);
transition: background-color 0.2s;

&:hover {
  background-color: var(--color-primary-dark);
}

&:active {
  background-color: var(--color-primary-light);
}
`;

const disabled = `
  background-color: var(--color-primary-disabled);
`;

const PaginationLabel = styled.label`
  font-size: 1rem;
`;

const Pagination = ({ page, setPage, total, limit }) => {
  const goToFirstPage = () => setPage(1);

  const goToLastPage = () => setPage(getLastPage());

  const incrementPage = () => page < getLastPage() && setPage(page + 1);

  const decrementPage = () => page > 1 && setPage(page - 1);

  const atFirstPage = () => page === 1;

  const atLastPage = () => page === getLastPage();

  const getLastPage = () => Math.ceil(total / limit);

  return (
    <PaginationContainer>
      <PaginationButton
        onClick={() => goToFirstPage()}
        disabled={atFirstPage()}
      >
        <img src={chevronsLeft} alt='go to first page icon' />
      </PaginationButton>
      <PaginationButton
        onClick={() => decrementPage()}
        disabled={atFirstPage()}
      >
        <img src={chevronLeft} alt='go to previous page icon' />
      </PaginationButton>
      <PaginationLabel>{page}</PaginationLabel>
      <PaginationButton onClick={incrementPage} disabled={atLastPage()}>
        <img src={chevronRight} alt='go to next page icon' />
      </PaginationButton>
      <PaginationButton onClick={goToLastPage} disabled={atLastPage()}>
        <img src={chevronsRight} alt='go to last page icon' />
      </PaginationButton>
    </PaginationContainer>
  );
};

export default Pagination;

All required states, setup, and parameters are passed as props, in a similar way to previous components.

We create buttons to do the following actions :

go to the first page
go to the previous page
go to the next page
go to the last page

We make use of the total number of elements that we have added to the template returned by MockAPI to know when the last page is reached.

We also make use of styled component props to have a base styling for all buttons and change only the colors and the cursor depending on whether the button is disabled or not.

Putting it all together

Now that everything is setup we can start our project :

npm run start

And here is the final result !

The project for this blog is available here https://github.com/Mozenn/pagination-in-react-with-useSwr.

Build a .jar file inside a Docker container with Maven

Gauthier Cassany — Tue, 15 Feb 2022 11:35:07 +0000

Containers have become very popular during the last few years thanks to the rise of Docker. The most common use case is to run an application in isolation, be it in a development environment or a production environment. But it can also be used for more specific use cases.

In this article, we are going to build a jar file inside a docker container.

Why should we do that you might ask ?

Well, this use case is not very common, but using docker as a wrapper to build an artifact in isolation can be quite handy, the main benefit being to avoid setting a dedicated environment on the host machine to build the artifact. You also avoid filling your host machine by downloading the libraries and packages required by your application.

Now that we know the why, let’s check out the how !

Project setup

The first step is to generate a toy project for demonstration purposes.

As we are using maven as a build tool, we can use the quickstart maven archetype to generate the maven project.

mvn archetype:generate -DgroupId=com.mozen.jardocker -DartifactId=build-jar-inside-docker -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

We get a basic maven project with the following structure :

We edit the pom.xml file to generate an executable jar with dependencies :

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mozen.jardocker</groupId>
  <artifactId>build-jar-inside-docker</artifactId>
  <version>1.0-SNAPSHOT</version>
  <name>build-jar-inside-docker</name>
  <url>http://maven.apache.org</url>

  <properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
    <maven-compiler-plugin.version>3.8.1</maven-compiler-plugin.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.2.2</version>
        <executions>
          <execution>
            <id>default-jar</id>
            <phase>none</phase>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-assembly-plugin</artifactId>
        <configuration>
          <finalName>build-jar-inside-docker-${project.version}</finalName>
          <appendAssemblyId>false</appendAssemblyId>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
          <archive>
            <manifest>
              <mainClass>com.mozen.jardocker.App</mainClass>
            </manifest>
          </archive>
        </configuration>
        <executions>
          <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

We have specified the target and source version of the jdk for our project with the properties maven.compiler.source and maven.compiler.target.

The maven-assembly-plugin is used to generate the jar with all required dependencies as well as the manifest file, to indicate the main entry class. It is bound to the package phase so that it is executed during the package phase of the maven lifecycle.

We set the appendAssemblyId element to false to prevent the addition of the “jar-with-dependencies” suffix to the name of our jar, and only rely on the finalName attribute to define it.

We also specify the maven-jar-plugin, not to generate the jar file but rather to prevent a second jar to be generated. By default, this second jar won’t have any dependencies and manifest, that’s why we prefer to use the maven-assembly-plugin that packages them by default.

That’s it for the project. Let’s now set up our docker build configuration.

Dockerfile setup

We first create a dockerfile to define the image of the container on which the jar file will be built :

FROM maven:3.8.2-jdk-11

COPY . .

RUN mvn clean package

As you can see, it is surprisingly short. We base the image from the official maven image available on docker hub https://hub.docker.com/_/maven?tab=description.

We use the JDK 11 based image so that it stays consistent with the JDK version used for the previously generated project.

Then, we copy our project into the container. Here the first ‘.’ defines the source path from our host, which is where the Dockerfile is located, and the second ‘.’ defines the target path in the container, which is the WORKDIR, equal to the root path ‘/’ by default.

To sum up, it means that we take the entire project directory and we copy it inside the container.

But wait, did I say the entire project? Wouldn’t it be smart if we prevent copying useless files and folders such as IDE-related files or git-related files?

Well, yes it is ! That is why you make use of a .dockerignore file

.idea
.git
.gitignore
*/target
README.md

This file plays the same role as a .gitignore file, meaning that docker will not copy the specified files and folders when the building is done, thus improving the speed performance and decreasing the size of the container.

The final step is to create a script that makes the entire build workflow a single command process :

#! /bin/bash

if [ -d "./target/" ]
then
    rm -r target/
fi
docker build -t build-jar-inside-docker-image .
docker create -it --name build-jar-inside-docker build-jar-inside-docker-image bash
docker cp build-jar-inside-docker:/target ./target
docker rm -f build-jar-inside-docker

We first build the docker image from our Dockerfile using the docker build command. The -t is used to specify the image tag, and the ‘.’ to specify where the Dockerfile is located.

We then create a container based on the newly built image.

The third command will run only once the container has been created and the .jar has been built. It simply copies the /target folder generated during the build from the container to the host.

The final step is to delete the previously built container, so that our script is idempotent, meaning it will produce the same result each time we execute it. Without this step, we would get an error if we run the script multiple times because the container name “build-jar-inside-docker” would already exist.

For the same purpose, we clear the target folder at each execution to avoid any error caused by an already existing target folder.

Building the jar

We can finally build our jar using a single command line :

sh build.sh

mohzen@DESKTOP-BDASKRH:~/dev/build-jar-inside-docker$ ll target/
total 40
drwxr-xr-x 9 mohzen mohzen 4096 Feb  2 22:20 ./
drwxr-xr-x 6 mohzen mohzen 4096 Feb  2 22:20 ../
drwxr-xr-x 2 mohzen mohzen 4096 Feb  2 22:20 archive-tmp/
-rw-r--r-- 1 mohzen mohzen 1138 Feb  2 22:20 build-jar-inside-docker-1.0-SNAPSHOT.jar
drwxr-xr-x 3 mohzen mohzen 4096 Feb  2 22:20 classes/
drwxr-xr-x 3 mohzen mohzen 4096 Feb  2 22:20 generated-sources/
drwxr-xr-x 3 mohzen mohzen 4096 Feb  2 22:20 generated-test-sources/
drwxr-xr-x 3 mohzen mohzen 4096 Feb  2 22:20 maven-status/
drwxr-xr-x 2 mohzen mohzen 4096 Feb  2 22:20 surefire-reports/
drwxr-xr-x 3 mohzen mohzen 4096 Feb  2 22:20 test-classes/

And that’s it!

As I said at the start of this article, this pattern is not relevant in most use cases, but it is always a nice addition to our software engineer toolbox.

You can access the demo project for this blog post here https://github.com/Mozenn/build-jar-file-inside-docker-container.

Build a Spring Boot REST API with Pagination and Sorting

Gauthier Cassany — Wed, 26 Jan 2022 11:12:39 +0000

Pagination is an important feature for REST API, and is used for many use cases where we want to fetch only a small part of an entire dataset. It might be for performance reasons, and fetch only the data needed at that time. It can also be used by the frontend to display items using a paginated view type of UI such as infinite scrolling.

Spring Boot provides a pagination feature integrated into the spring data JPA library, making it easy to integrate such a mechanism in our own REST API.

Let’s check this out!

Project setup

This section is dedicated to the project setup. You can skip this part and go straight to the implementation if you are not interested.

spring init --dependencies=web,data-jpa,h2,lombok spring-boot-pagination-and-sorting

We package the following dependencies :

the web dependency for the REST API
the spring data JPA for the data access layer, which uses hibernate as the default Object Relational Mapping tool
the h2 library to provide an easy-to-use in-memory embedded database. This type of database is suited for small toy projects such as this one, but it should not be used for any serious project that will be shipped to production at some point
Lombok to generate snippets of code through annotation and avoid any boilerplate code

Once the project has been generated, we need to set some properties in the application.yml file

server:
  port: 9000

spring:
  datasource:
    url: jdbc:h2:mem:mydb
    username: mozen
    password: password

We explicitly set the port at which our application can be reached. The default port has a value of 8080, but this port is often used by many applications and systems, so overwriting this default value will lessen the probability of port collision and save us some headaches on future debugging.

Spring boot will automatically detect that we use an h2 two database by scanning the dependency, so no need to specify anything about the driver, the database platform, or the dialect.

Defining the data model

We first define the model for the entity.

As an example, we will use a Plant entity, containing the plant's common name, scientific name, family, and date of creation.

package com.mozen.springbootpaginationandsorting.model;

import lombok.Getter;
import lombok.Setter;
import org.hibernate.annotations.NaturalId;

import javax.persistence.*;
import java.time.Instant;
import java.util.Objects;

@Entity
@Table(name = "plant")
@Getter
@Setter
public class Plant {

    public Plant() {
        this.createdAt = Instant.now();
    }
    public Plant(String name, String scientificName, String family) {
        this.name = name;
        this.scientificName = scientificName;
        this.family = family;
        this.createdAt = Instant.now();
    }

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id")
    private Long id;

    @NaturalId()
    @Column(name = "name")
    private String name;

    @NaturalId()
    @Column(name = "scientificName")
    private String scientificName;

    @Column(name = "family")
    private String family;

    @Column(name = "createdAt")
    private Instant createdAt = Instant.now();

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Plant)) return false;
        Plant plant = (Plant) o;
        return Objects.equals(id, plant.id) && Objects.equals(name, plant.name) && Objects.equals(scientificName,
                plant.scientificName) && Objects.equals(family, plant.family) && Objects.equals(createdAt,
                plant.createdAt);
    }

    @Override
    public int hashCode() {
        return Objects.hash(id, name, scientificName, family, createdAt);
    }

    @Override
    public String toString() {
        return "Plant{" +
                "id=" + id +
                ", name='" + name + '\'' +
                ", scientificName='" + scientificName + '\'' +
                ", family='" + family + '\'' +
                ", createdAt=" + createdAt +
                '}';
    }
}

We define a JPA entity and skip any form of validation constraints that we could declare using hibernate validator.

We also do not consider any domain-driven design constraint given the simplicity of the project.

Defining the data layer

For the data layer, we make use of the spring JPA repository provided by the spring-boot-starter-data-jpa dependency.

package com.mozen.springbootpaginationandsorting.repository;

import com.mozen.springbootpaginationandsorting.model.Plant;
import org.springframework.data.jpa.repository.PagingAndSortingRepository;

public interface PlantRepository extends PagingAndSortingRepository<Plant, Long> {
}

By implementing the PagingAndSortingRepository interface, we automatically have access to basic CRUD operations such as find, add or delete, provided by the CrudRepository Interface. But what is more important in our case is the findAll(Pageable) method made available by the repository. This method returns a Page with T being the type of the entity, which, in this context, is the Plant entity.

The PagingAndSortingRepository is a generic interface, with the first generic representing the type of entity handled by the repository, and the second generic parameter representing the type of Id used by the entity. In our case, we have previously declared the id field of the Plant entity as a Long.

Check out the official Spring documentation to have a complete overview of what Spring JPA Repositories are capable of https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#jpa.repositories.

Defining the business layer

We then define the service that represents the business layer of the application.

package com.mozen.springbootpaginationandsorting.service;

import com.mozen.springbootpaginationandsorting.model.PageSettings;
import com.mozen.springbootpaginationandsorting.model.Plant;
import com.mozen.springbootpaginationandsorting.repository.PlantRepository;
import lombok.NonNull;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Transactional
@Service
public class PlantService {

    private PlantRepository plantRepository;

    @Autowired
    public PlantService(
            PlantRepository plantRepository) {
        this.plantRepository = plantRepository;
    }

    public Page<Plant> getPlantPage(@NonNull PageSettings pageSetting) {

        Sort plantSort = pageSetting.buildSort();
        Pageable plantPage = PageRequest.of(pageSetting.getPage(), pageSetting.getElementPerPage(), plantSort);

        return plantRepository.findAll(plantPage);
    }
}

We define our class as a @Service so that spring can auto-configure it on application startup during Beans instantiation. We could also use the @Component annotation, but using the @Service annotation for Bean part of the service layer is more semantic.

We use a PageSettings POJO to group all pagination-related parameters and avoid passing too many arguments.

package com.mozen.springbootpaginationandsorting.model;

import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import org.springframework.data.domain.Sort;

@Slf4j
@Data
public class PageSettings {

    private int page = 0;

    private int elementPerPage = 2;

    private String direction = "dsc";

    private String key;

    public Sort buildSort() {
        switch (direction) {
            case "dsc":
                return Sort.by(key).descending();
            case "asc":
                return Sort.by(key).ascending();
            default:
                log.warn("Invalid direction provided in PageSettings, using descending direction as default value");
                return Sort.by(key).descending();
        }
    }
}

The @data annotation provided by Lombok generates all setters and getters, a constructor taking all required parameters, which is none for this class, as well as basic methods like toString(), equals, and hashCode.

We build the Sort object that will be required for the pagination based on the key and the direction fields.

The key is the name of the property on which the plant will be sorted and the direction defines the direction by which the plant will be sorted.

Be aware that the property selected as key must be unique, otherwise you can receive the same element twice on two different pages.

Coming back to the PlantService, we inject the PlantRepository defined earlier, and make use of the findAll method to get a Page instance containing the list of Plants for the requested page, as well as other useful properties such as the total amount of elements, the total amount of pages, and many more.

Defining the web layer

Finally, let’s create the web layer and expose the endpoint to fetch a page of plants by creating a Spring Controller.

package com.mozen.springbootpaginationandsorting.controller;

import com.mozen.springbootpaginationandsorting.mapper.PageToPageDTOMapper;
import com.mozen.springbootpaginationandsorting.model.PageDTO;
import com.mozen.springbootpaginationandsorting.model.PageSettings;
import com.mozen.springbootpaginationandsorting.model.Plant;
import com.mozen.springbootpaginationandsorting.service.PlantService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Slf4j
@RestController()
@RequestMapping("/plant")
public class PlantController {

    private PlantService plantService;

    private PageToPageDTOMapper<Plant> pageToPageDTOMapper;

    @Autowired
    public PlantController(PlantService plantService, PageToPageDTOMapper<Plant> pageToPageDTOMapper) {
        this.plantService = plantService;
        this.pageToPageDTOMapper = pageToPageDTOMapper;
    }

    @GetMapping("/page")
    public PageDTO<Plant> getPlantPage(PageSettings pageSettings) {

        log.info(
                "Request for plant page received with data : " + pageSettings);

        return pageToPageDTOMapper.pageToPageDTO(plantService.getPlantPage(pageSettings));
    }
}

In the same way as the @Service earlier, we use the @RestController annotation to define the class as a Component in a more semantic way. This annotation also contains the @ResponseBody annotation, which will automatically serialize the response returned from the controller methods.

We also make use of a PageToPageDTOMapper :

package com.mozen.springbootpaginationandsorting.mapper;

import com.mozen.springbootpaginationandsorting.model.PageDTO;
import org.springframework.data.domain.Page;
import org.springframework.stereotype.Component;

@Component
public class PageToPageDTOMapper<T> {

    public PageDTO<T> pageToPageDTO(Page<T> page) {
        PageDTO<T> pageDTO = new PageDTO<>();
        pageDTO.setContent(page.getContent());
        pageDTO.setTotalElements(page.getTotalElements());

        return pageDTO;
    }
}

Using this mapper, we only return what is needed by the client of the API. This part is optional, and we could directly return the Page object, but I like to clearly define what is returned and have control over the contract of the API.

Putting it all together

We use the ApplicationRunner functional interface to initialize the sample data.

package com.mozen.springbootpaginationandsorting;

import com.mozen.springbootpaginationandsorting.model.Plant;
import com.mozen.springbootpaginationandsorting.repository.PlantRepository;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import java.util.Arrays;
import java.util.List;

@SpringBootApplication
public class Application {

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

    @Bean
    public ApplicationRunner run(PlantRepository plantRepository) throws Exception {
        return (ApplicationArguments args) -> {
            List<Plant> plants = Arrays.asList(
                    new Plant("subalpine fir", "abies lasiocarpa", "pinaceae"),
                    new Plant("sour cherry", "prunus cerasus", "rosaceae"),
                    new Plant("asian pear", "pyrus pyrifolia", "rosaceae")
            );
            plantRepository.saveAll(plants);
        };

    }
}

For demonstration purposes, we define the Bean directly in the main Application class.

The run method takes the PlantRepository as an argument, using Spring dependency injection. The method is executed during the application startup, right after the context initialization, and before the startup of the spring boot application.

You might have noticed that we did not declare the data SQL schema anywhere. Because our database is an embedded database, the property spring.jpa.hibernate.ddl-auto is set to create-drop by default, and our database schema is automatically generated.

We can finally run our application either through the IDE or using the command line with the following command:

mvn spring-boot:run

To fetch the pagination endpoint, we can use the popular API platform Postman

Or we can use a simple cURL command by providing the necessary parameters

curl -X GET 'http://localhost:9000/plant/page?direction=asc&key=name&page=0&elementPerPage=2'

Of course, this demo shows only the basics of pagination, but it provides a good starting point if you need such a feature for your REST API.

You can access the demo project for this blog post here https://github.com/Mozenn/spring-boot-rest-api-with-pagination-and-sorting

Set up Keycloak with Docker and PostgreSQL

Gauthier Cassany — Tue, 21 Dec 2021 11:14:35 +0000

In this blog post, we are going to learn how to run Keycloak inside docker, using a dedicated PostgreSQL database also running in a docker container.

This setup is mostly designed to be used in a development environment, but it is a good starting point for a production environment using a microservice architecture.

To use this setup on your own machine, you will need Docker and Docker compose. Check out the documentation to have a walkthrough on how to install docker on your favorite OS https://docs.docker.com/get-docker/.

Let's start right off by setting up the PostgreSQL database.

Setup PostgreSQL with docker

In our setup, we use PostgreSQL as a database for Keycloak to persist data such as users, clients or realms and replace the H2 database provided by default.

We run our PostgreSQL instance in a Docker container, using the official PostgreSQL image provided on Docker Hub.

We use Docker compose to ease our multi-container setup by defining the PostgreSQL instance in a docker-compose.yml file.

version: "3.9"
services:
  postgres:
    container_name: postgres_blog
    image: "postgres:13.2"
    volumes:
      - ./db-data:/var/lib/postgresql/data/
      - ./sql:/docker-entrypoint-initdb.d/:ro
    env_file:
      - ./database.dev.env
    networks:
      - backend
    ports:
      - "5432:5432"
  pgadmin:
    container_name: pgadmin_blog
    image: "dpage/pgadmin4:5.1"
    env_file:
      - ./database.dev.env
    ports:
      - "5050:80"
    networks:
      - backend

There are several things going on here. Let's explain them one by one.

We first define volumes to mount data into the container as well as to persist data on the host.

Here, we provide both a source and a target path, making those volumes bind mounts. This type of volume is fine for a dev environment, but using named volumes or copying files directly in the container is more advised for production environment, except if you want full control of your filesystem, and apply modifications outside docker.

The first bind mount is used to persist data even if the container is stopped. The second one mounts files to initialize the Keycloak and application databases.

The first two scripts are only necessary if you want to store application-related data in the same database as the Keycloak one.

#!/bin/bash

psql -U dev -tc "SELECT 1 FROM pg_database WHERE datname = 'app'" \
| grep -q 1 || psql -U dev -c "CREATE DATABASE app"

Unlike MySQL-like databases, PostgreSQL does not have a CREATE DATABASE IF EXIST statement.

As a workaround, we use a bash script to run a psql command that creates the database if it does not exist. Here the double pipe means that the CREATE DATABASE psql command will be run only if the grep command does not succeed.

\c app;

DROP TABLE IF EXISTS Member;

CREATE TABLE Member (
    id VARCHAR(50) NOT NULL PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(50) NOT NULL,
    createdAt TIMESTAMP DEFAULT NOW()
);

DROP TABLE IF EXISTS Post;

CREATE TABLE Post (
    id SERIAL NOT NULL PRIMARY KEY,
    title VARCHAR(50) NOT NULL,
    scientificName VARCHAR(50) NOT NULL,
    family VARCHAR(32) NOT NULL,
    rating NUMERIC(3,2) DEFAULT 0.5,
    authorId VARCHAR(50),
    createdAt TIMESTAMP DEFAULT NOW(),
    CONSTRAINT fk_member FOREIGN KEY(authorId) REFERENCES Member(id)
    ON DELETE SET NULL ON UPDATE CASCADE
);

the second script is more straightforward. It simply initializes the application database schema.

#!/bin/bash

psql -U dev -tc "SELECT 1 FROM pg_database WHERE datname = 'keycloak'" \
| grep -q 1 || psql -U dev -c "CREATE DATABASE keycloak"

psql -U dev -c "CREATE USER keycloak WITH PASSWORD 'kc'"

In the last one, we create the Keycloak database in a similar fashion as the application database.

We also create a new user that will be used by Keycloak to get access to the database. It is a good security practice to define a dedicated user for specific usage and not use the default superuser.

The .env file is used to define environment variables listed in the docker hub page to indicate the user to create by default, defined in the previous script :

POSTGRES_USER="dev"
POSTGRES_PASSWORD="pwd"

In addition, we define a pgAdmin service. It provides an easy-to-use User Interface and prevents entering the container directly to query the database using the command line.

We just need to add two new environment variables to define the default login to access the UI.

POSTGRES_USER="dev"
POSTGRES_PASSWORD="pwd"
PGADMIN_DEFAULT_EMAIL="user@domain.local"
PGADMIN_DEFAULT_PASSWORD="admin"

Setup Keycloack with docker

Keycloak is an open-source identity and management solution developed by Red Hat. It is a robust alternative to SaaS products such as auth0 or cloud services such as Firebase or AWS Cognito, and will fulfill nearly all of your authorization or authentication needs. If you still have specific needs not covered by the default implementation, Keycloak provides many Service Provider Interfaces to plug your own custom providers.

If you want to learn more about Keycloak, check out the official documentation https://www.keycloak.org/

The first step is to complete our docker-compose file by adding the keycloak service

version: "3.9"
services:
  postgres:
    container_name: postgres_blog
    image: "postgres:13.2"
    env_file:
      - ./database.dev.env
    networks:
      - backend
    volumes:
      - ./db-data:/var/lib/postgresql/data/
      - ./sql:/docker-entrypoint-initdb.d/:ro
    ports:
      - "127.0.0.1:5432:5432"
  pgadmin:
    container_name: pgadmin_blog
    image: "dpage/pgadmin4:5.1"
    env_file:
      - ./database.dev.env
    ports:
      - "127.0.0.1:5050:80"
    networks:
      - backend
  keycloak:
    container_name: keycloak_blog
    image: "jboss/keycloak:15.0.2"
    depends_on:
      - "postgres"
    env_file:
      - ./keycloak.dev.env
    ports:
      - "127.0.0.1:8180:8080"
      - "127.0.0.1:8787:8787" # debug port
    networks:
      - backend

networks:
  backend:
    name: backend
    driver: bridge

No need to define new volumes here, we only need to map the 8080 port to access Keycloak from the host, as well as the debug port, in case we want to attach a remote debugger from our IDE for example.

In a similar way to the PostgreSQL setup, we use a .env file to set necessary environment variables.

KEYCLOAK_USER=admin
KEYCLOAK_PASSWORD=password
DEBUG=true
DEBUG_PORT='*:8787'
DB_VENDOR=POSTGRES
DB_ADDR=postgres
DB_PORT=5432
DB_DATABASE=keycloak
DB_USER=keycloak
DB_PASSWORD=kc
TZ=Europe/Paris

All available environment variables are listed on the docker hub page of the Keycloak image https://hub.docker.com/r/jboss/keycloak/.

We also create a new script to create both the Keycloak user and database.

We define all services on the same network so that every container can communicate with one another.

Here, we use the bridge mode because communication only happens on the same host.

Finally, we specify that the Keycloak service depends on the PostgreSQL one, or we will get a database connection error during the boot phase of the Keycloak container.

Putting it all together

Now that we have created all the necessary declarations, it is time to run our setup.

Docker-compose make it easy by using a single command that bootstrap all services

docker-compose up -d

We can check that all containers are running once the startup is done

docker ps

We can now access the Keycloak back office through the port mapped in the docker-compose.yml file and by using the login previously defined in our .env file.

Once logged in, we can customize our realm by creating users, clients, and many other actions. I let you check the official Keycloak documentation to get a grasp of all the features that Keycloak provides.

We can also access the PostgreSQL database using pgAdmin :

We then need to set up the connection to the PostgreSQL database :

And finally, we can access our application schema :

The repository containing all configuration files is available here: https://github.com/Mozenn/setup-keycloak-with-docker-and-postgresql

Resources

Keycloak official documentation https://www.keycloak.org/documentation
Docker Keycloak image page https://hub.docker.com/r/jboss/keycloak/
Docker networking overview https://docs.docker.com/network/