Leveraging Spring Reactive, Functional Endpoints, Docker, and MongoDB

Elattar Saad

Thu, 29th February 2024

4 min read

#spring #java #spring reactive #functional endpoints #docker #mongoDB

Leveraging Spring Reactive, Functional Endpoints, Docker, and MongoDB

Blocking is a feature of classic servlet-based web frameworks like Spring MVC. Introduced in Spring 5, Spring WebFlux is a reactive framework that operates on servers like Netty and is completely non-blocking.

Two programming paradigms are supported by Spring WebFlux. Annotations (Aspect Oriented Programming) and WebFlux.fn (Functional Programming).

"Spring WebFlux includes WebFlux.fn, a lightweight functional programming model in which functions are used to route and handle requests and contracts are designed for immutability. It is an alternative to the annotation-based programming model but otherwise runs on the same Reactive Core foundation." Spring | Functional Endpoints

Project Description

As the title describe, this is a simple Songs API build using Spring, Docker and MongoDB, the endpoints are Functional Endpoints and will have the traditional ControllerAdvice as Exception handler.

Project Dependencies

Java Version 21
Spring Boot version 3.3.0-SNAPSHOT with Spring Reactive Starter.
Spring Docker Support.
Lombok (Optional).

Talking XML these are the project dependencies:

Coding time!

First, let's setup the docker compose file /compose.yaml of the project (it should generated by spring via the docker support starter).

With that set, let's create the Song class:

The SongRepository interface will be referring to the Song class in its DB ops:

Song Functional Endpoint and Handler

Now, it's time for the Song Router, it will be responsible for router the incoming requests for the /songs ressource:

As you noticed the request are redirected to the SongHandler for a certain logic to be performed.

The SongsHandler will act as Service as well, will perform a business logic and communicate with the SongRepository for operations with the database.

Exception Handling

As previously states, will be using the same old ControllerAdvice as Exception handler with two custom Exceptions as the following:

Custom Exceptions

Custom Exception Handler

With all that been set, let's make use of our endpoint using Postman:

Creating a new Song

Spring Webflux Functional Endpoints

Getting songs by artist:

Spring Webflux Functional Endpoints

Getting all songs:

Spring Webflux Functional Endpoints

Deleting a song:

Sorry not a big fan of Madonna tbh :|

Spring Webflux Functional Endpoints

Checking the result of the delete op:

Spring Webflux Functional Endpoints

Finally,

With that said, our functional songs endpoint will be good to go for further improvements and new features. This is simple, in real industrial projects, I can assure you it can get complicated with more layers, for "getting started" purposes I avoided the use of advanced concepts such as validation, DTO, etc.

You can find the full source code here

Leveraging Spring Reactive, Functional Endpoints, Docker, and MongoDB

Elattar Saad

Thu, 29th February 2024

4 min read

Read on Medium Read on Dev.to

#spring #java #spring reactive #functional endpoints #docker #mongoDB

Two programming paradigms are supported by Spring WebFlux. Annotations (Aspect Oriented Programming) and WebFlux.fn (Functional Programming).

"Spring WebFlux includes WebFlux.fn, a lightweight functional programming model in which functions are used to route and handle requests and contracts are designed for immutability. It is an alternative to the annotation-based programming model but otherwise runs on the same Reactive Core foundation." Spring | Functional Endpoints

Project Description

As the title describe, this is a simple Songs API build using Spring, Docker and MongoDB, the endpoints are Functional Endpoints and will have the traditional ControllerAdvice as Exception handler.

Project Dependencies

Java Version 21
Spring Boot version 3.3.0-SNAPSHOT with Spring Reactive Starter.
Spring Docker Support.
Lombok (Optional).

Talking XML these are the project dependencies:

Coding time!

First, let's setup the docker compose file /compose.yaml of the project (it should generated by spring via the docker support starter).

With that set, let's create the Song class:

The SongRepository interface will be referring to the Song class in its DB ops:

Song Functional Endpoint and Handler

Now, it's time for the Song Router, it will be responsible for router the incoming requests for the /songs ressource:

As you noticed the request are redirected to the SongHandler for a certain logic to be performed.

The SongsHandler will act as Service as well, will perform a business logic and communicate with the SongRepository for operations with the database.

Exception Handling

As previously states, will be using the same old ControllerAdvice as Exception handler with two custom Exceptions as the following:

Custom Exceptions

Custom Exception Handler

With all that been set, let's make use of our endpoint using Postman:

Creating a new Song

Spring Webflux Functional Endpoints

Getting songs by artist:

Spring Webflux Functional Endpoints

Getting all songs:

Spring Webflux Functional Endpoints

Deleting a song:

Sorry not a big fan of Madonna tbh :|

Spring Webflux Functional Endpoints

Checking the result of the delete op:

Spring Webflux Functional Endpoints

Finally,

You can find the full source code here


import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Getter;
import lombok.Setter;
import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.mapping.Document;

import java.util.UUID;

@Document
@Getter
@Setter
@AllArgsConstructor
@Builder
public class Song {
    @Id
    private UUID id;
    private String title;
    private String artist;
}

SongRepository.java

import org.springframework.data.repository.reactive.ReactiveCrudRepository;
import org.springframework.stereotype.Repository;
import reactor.core.publisher.Flux;

import java.util.UUID;

@Repository
public interface SongRepository extends ReactiveCrudRepository<Song, UUID> {

    Flux<Song> findAllByArtist(final String artist);

}

SongRouterConfig.java

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerResponse;

import static org.springframework.web.reactive.function.server.RouterFunctions.route;

@Configuration
public class SongRouterConfig {

    private final SongHandler handler;

    public SongRouterConfig(SongHandler handler) {
        this.handler = handler;
    }

    @Bean
    public RouterFunction<ServerResponse> router() {
        return route().path("/songs", builder -> builder
                .GET("/artist", handler::findAllByArtist)
                .GET(handler::findAll) // Get endpoints' order is important
                .POST("/new", handler::create)
                .DELETE("/{id}", handler::delete)
        ).build();
    }
}

SongHandler.java

import io.daasrattale.webfluxmongofunctionalendpoints.song.exceptions.InvalidParamException;
import io.daasrattale.webfluxmongofunctionalendpoints.song.exceptions.InvalidUUIDException;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Mono;

import java.util.Optional;
import java.util.UUID;

@Service
public class SongHandler {

    private final SongRepository repository;

    public SongHandler(SongRepository repository) {
        this.repository = repository;
    }

    public Mono<ServerResponse> findAll(final ServerRequest request) {
        return ServerResponse
                .ok()
                .body(repository.findAll(), Song.class);
    }

    public Mono<ServerResponse> findAllByArtist(final ServerRequest request) {
        return Mono.just(request.queryParam("artist"))
                .switchIfEmpty(Mono.error(new InvalidParamException("artist")))
                .map(Optional::get)
                .map(repository::findAllByArtist)
                .flatMap(songFlux -> ServerResponse
                        .ok()
                        .body(songFlux, Song.class));
    }

    public Mono<ServerResponse> create(final ServerRequest request) {
        return request.bodyToMono(Song.class)
                .switchIfEmpty(Mono.error(new RuntimeException("Song body not found"))) // you can use that or create a custom exception (recommended)
                .doOnNext(song -> song.setId(UUID.randomUUID()))
                .flatMap(song -> ServerResponse
                        .status(HttpStatus.CREATED)
                        .body(repository.save(song), Song.class)
                );
    }

    public Mono<ServerResponse> delete(final ServerRequest request) {
        return Mono.just(request.pathVariable("id"))
                .map(UUID::fromString)
                .doOnError(throwable -> {
                    throw new InvalidUUIDException(throwable);
                })
                .flatMap(songId -> ServerResponse
                        .ok()
                        .body(repository.deleteById(songId), Void.class)
                );
    }
}

InvalidParamException.java

import lombok.Getter;

@Getter
public class InvalidParamException extends RuntimeException {

    private final String paramName;

    public InvalidParamException(final String paramName) {
        this.paramName = paramName;
    }
}

InvalidUUIDException.java

import lombok.Getter;

@Getter
public class InvalidUUIDException extends RuntimeException {

    private final Throwable cause;

    public InvalidUUIDException(final Throwable cause) {
        this.cause = cause;
    }
}

SongExceptionHandler.java

import io.daasrattale.webfluxmongofunctionalendpoints.song.exceptions.InvalidUUIDException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

import java.util.Map;

@ControllerAdvice
@Slf4j
public class SongExceptionHandler {


    @ExceptionHandler(InvalidUUIDException.class)
    public ResponseEntity<Map<String, ?>> handle(final InvalidUUIDException exception) {
        return ResponseEntity
                .badRequest()
                .body(
                        Map.of(
                                "status", 400,
                                "message", "Invalid UUID",
                                "details", exception.getCause().getMessage()
                        )
                );
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, ?>> handle(final Exception exception) {
        log.error("Unhandled Error, message: {}", exception.getMessage());
        return ResponseEntity
                .internalServerError()
                .body(
                        Map.of(
                                "status", 500,
                                "message", "Unknown Error",
                                "details", exception.getMessage()
                        )
                );
    }
}

pom.xml

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-mongodb-reactive</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-docker-compose</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.projectreactor</groupId>
            <artifactId>reactor-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

Leveraging Spring Reactive, Functional Endpoints, Docker, and MongoDB

Elattar Saad

Thu, 29th February 2024

Project Description

Project Dependencies

Coding time!

Song Functional Endpoint and Handler

Exception Handling

Custom Exceptions

Custom Exception Handler

Finally,

Read next

Leveraging Spring Reactive, Functional Endpoints, Docker, and MongoDB

Elattar Saad

Thu, 29th February 2024

Project Description

Project Dependencies

Coding time!

Song Functional Endpoint and Handler

Exception Handling

Custom Exceptions

Custom Exception Handler

Finally,

Read next