Chapter 6. Developing reactive applications using Spring Boot with Vert.X

Note

Eclipse Vert.x reactive components for Spring Boot are provided as a Technology Preview.

This section provides an introduction to developing applications in a reactive way using RHOAR Spring Boot starters based on Spring Boot and Eclipse Vert.x. The following examples demonstrate how you can use the starters to create reactive applications.

6.1. Introduction to Spring Boot with Vert.X

The Spring reactive stack is build on Project Reactor, a reactive library that implements backpressure and is compliant with the Reactive Streams specification. It provides the Flux and Mono functional API types that enable asynchronous event stream processing.

On top of Project Reactor, Spring provides WebFlux, an asynchronous event-driven web application framework. While WebFlux is designed to work primarily with Reactor Netty, it can also operate with other reactive HTTP servers, such as Eclipse Vert.x.

Spring WebFlux and Reactor enable you to create applications that are:

  • Non-blocking: The application continues to handle further requests when waiting for a response from a remote component or service that is required to complete the current request.
  • Asynchronous: the application responds to events from an event stream by generating response events and publishing them back to the event stream where they can be picked up by other clients in the application.
  • Event-driven: The application responds to events generated by the user or by another service, such as mouse clicks, HTTP requests, or new files being added to a storage.
  • Scalable: Increasing the number of Publishers or Subscribers to match the required event processing capacity of an application only results in a slight increase in the complexity of routing requests between individual clients in the application. Reactive applications can handle large numbers of events using fewer computing and networking resources as compared to other application programming models.
  • Resilient: The application can handle failure of services it depend on without a negative impact on its overall quality of service.

Additional advantages of using Spring WebFlux include:

Similarity with SpringMVC
The SpringMVC API types and WebFlux API types are similar, and it is easy for developers to apply knowledge of SpringMVC to programming applications with WebFlux.

The Spring Reactive offering by Red Hat brings the benefits of Reactor and WebFlux to OpenShift and stand-alone RHEL, and introduces a set of Eclipse Vert.x extensions for the WebFLux framework. This allows you to retain the level of abstraction and rapid prototyping capabilities of Spring Boot, and provides an asynchronous IO API that handles the network communications between the services in your application in a fully reactive manner.

Annotated controllers support
WebFlux retains the endpoint controller annotations introduced by SpringMVC (Both SpringMVC and WebFlux support reactive RxJava2 and Reactor return types).
Functional programming support
Reactor interacts with the Java 8 Functional API, as well as CompletablebFuture, and Stream APIs. In addition to annotation-based endpoints, WebFlux also supports functional endpoints.

Additional resources

See the following resources for additional in-depth information on the implementation details of technologies that are part of the Spring Reactive stack:

6.2. Reactive Spring Web

The spring-web module provides the foundational elements of the reactive capabilities of Spring WebFlux, including:

  • HTTP abstractions provided by the HttpHandler API
  • Reactive Streams adapters for supported servers (Vert.x, Undertow and others)
  • Codecs for encoding and decoding event stream data. This includes:

    • DataBuffer, an abstraction for different types of byte buffer representations (Netty ByteBuf, java.nio.ByteBuffer, as well as others)
    • Low-level contracts to encode and decode content independent of HTTP
    • HttpMessageReader and HTTPMessageWriter contracts to encode and decode HTTP message content
  • The WebHandler API (a counterpart to the Servlet 3.1 I/O API that uses non-blocking contracts).

When designing your web application, you can choose between 2 programming models that Spring WebFlux provides:

Annotated Controllers
Annotated controllers in Spring WebFlux are consistent with Spring MVC, and are based on the same annotations from the spring-web module. In addition to the spring-web module from SpringMVC, its WebFlux counterpart also supports reactive @RequestBody arguments.
Functional Endpoints
Functional endpoints provided by spring WebFlux on Java 8 Lambda expressions and functional APIs, this programming model relies on a dedicated library (Reactor, in this case) that routes and handles requests. As opposed to annotation-based endpoint controllers that rely on declaring Intent and using callbacks to complete an activity, the reactive model based on functional endpoints allows request handling to be fully controlled by the application.

6.3. Creating a reactive Spring Boot HTTP service with WebFlux

Create a basic reactive Hello World HTTP web service using Spring Boot and WebFlux.

Prerequisites

Procedure

  1. Add vertx-spring-boot-starter-http as a dependency in the pom.xml file of your project.

    pom.xml

    <project>
    ...
      <dependencies>
      ...
        <dependency>
          <groupId>dev.snowdrop</groupId>
          <artifactId>vertx-spring-boot-starter-http</artifactId>
        </dependency>
      ...
      <dependencies>
    ...
    </project>

  2. Create a main class for your application and define the router and handler methods.

    HttpSampleApplication.java

    package dev.snowdrop.vertx.sample.http;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.context.annotation.Bean;
    import org.springframework.web.reactive.function.server.RouterFunction;
    import org.springframework.web.reactive.function.server.ServerRequest;
    import org.springframework.web.reactive.function.server.ServerResponse;
    import reactor.core.publisher.Mono;
    
    import static org.springframework.web.reactive.function.BodyInserters.fromObject;
    import static org.springframework.web.reactive.function.server.RouterFunctions.route;
    import static org.springframework.web.reactive.function.server.ServerResponse.ok;
    
    @SpringBootApplication
    public class HttpSampleApplication {
    
        public static void main(String[] args) {
            SpringApplication.run(HttpSampleApplication.class, args);
        }
    
        @Bean
        public RouterFunction<ServerResponse> helloRouter() {
            return route()
                .GET("/hello", this::helloHandler)
                .build();
        }
    
        private Mono<ServerResponse> helloHandler(ServerRequest request) {
            String name = request
                .queryParam("name")
                .orElse("World");
            String message = String.format("Hello, %s!", name);
    
            return ok()
                .body(fromObject(message));
        }
    }

  3. OPTIONAL: Run and test your application locally:

    1. Navigate to the root directory of your Maven project:

      $ cd myApp
    2. Package your application:

      $ mvn clean package
    3. Start your application from the command line:

      $ java -jar target/vertx-spring-boot-sample-http.jar
    4. In a new terminal window, issue an HTTP request on the /hello endpoint:

      $ curl localhost:8080/hello
      Hello, World!
    5. Provide a custom name with your request to get a personalized response:

      $ curl http://localhost:8080/hello?name=John
      Hello, John!

Additional resources

6.4. Using basic authentication in a reactive Spring Boot WebFlux application.

Create a reactive Hello World HTTP web service with basic form-based authentication using Spring Security and WebFlux starters.

Prerequisites

Procedure

  1. Add vertx-spring-boot-starter-http and spring-boot-starter-security as dependencies in the pom.xml file of your project.

    pom.xml

    <project>
    ...
      <dependencies>
      ...
        <dependency>
          <groupId>dev.snowdrop</groupId>
          <artifactId>vertx-spring-boot-starter-http</artifactId>
        </dependency>
        <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
      ...
      <dependencies>
    ...
    </project>

  2. Create an endpoint controller class for your application:

    HelloController.java

    package dev.snowdrop.vertx.sample.http.security;
    
    import java.security.Principal;
    
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
    import reactor.core.publisher.Mono;
    
    @RestController
    public class HelloController {
    
        @GetMapping("/")
        public Mono<String> hello(Mono<Principal> principal) {
            return principal
                .map(Principal::getName)
                .map(this::helloMessage);
        }
    
        private String helloMessage(String username) {
            return "Hello, " + username + "!";
        }
    }

  3. Create the main class of your application:

    HttpSecuritySampleApplication.java

    package dev.snowdrop.vertx.sample.http.security;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @SpringBootApplication
    public class HttpSecuritySampleApplication {
    
        public static void main(String[] args) {
            SpringApplication.run(HttpSecuritySampleApplication.class, args);
        }
    }

  4. Create a SecurityConfiguration class that stores the user credentials for accessing the /hello endpoint.

    SecurityConfiguration.java

    package dev.snowdrop.vertx.sample.http.security;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.security.config.annotation.web.reactive.EnableWebFluxSecurity;
    import org.springframework.security.core.userdetails.MapReactiveUserDetailsService;
    import org.springframework.security.core.userdetails.User;
    import org.springframework.security.core.userdetails.UserDetails;
    
    @EnableWebFluxSecurity
    public class SecurityConfiguration {
    
        @Bean
        public MapReactiveUserDetailsService userDetailsService() {
            UserDetails user = User.withDefaultPasswordEncoder()
                .username("user")
                .password("user")
                .roles("USER")
                .build();
    
            return new MapReactiveUserDetailsService(user);
        }
    }

  5. OPTIONAL: Run and test your application locally:

    1. Navigate to the root directory of your Maven project:

      $ cd myApp
    2. Package your application:

      $ mvn clean package
    3. Start your application from the command line:

      $ java -jar target/vertx-spring-boot-sample-http-security.jar
    4. Navigate to http://localhost:8080 using a browser to access the login screen.
    5. Log in using the credentials below:

      • username: user
      • password: user

      You receive a customized greeting when you are logged in:

      Hello, user!
    6. Navigate to http://localhost:8080/logout using a web browser and use the Log out button to log out of your application.
    7. Alternatively, use a terminal to make an unauthenticated HTTP request on localhost:8080. You receive HTTP 401 Unauthorized response from your application.

      $ curl -I http://localhost:8080
      HTTP/1.1 401 Unauthorized
      WWW-Authenticate: Basic realm="Realm"
      Cache-Control: no-cache, no-store, max-age=0, must-revalidate
      Pragma: no-cache
      Expires: 0
      X-Content-Type-Options: nosniff
      X-Frame-Options: DENY
      X-XSS-Protection: 1 ; mode=block
      Referrer-Policy: no-referrer
    8. Issue an authenticated request using the example user credentials. You receive a personalized response.

      $ curl -u user:user http://localhost:8080
      Hello, user!

Additional resources

6.5. Using OAuth2 authentication in a reactive Spring Boot application.

Set up OAuth2 authentication for your reactive Spring Boot application and authenticate using your client ID and client secret.

Prerequisites

Procedure

  1. Register a new OAuth 2 application on your Github account. Ensure that you provide the following values in the registration form:

  2. Add the following dependencies in the pom.xml file of your project:

    • vertx-spring-boot-starter-http
    • spring-boot-starter-security
    • spring-boot-starter-oauth2-client
    • reactor-netty

      Note that the reactor-netty client is required to ensure that spring-boot-starter-oauth2-client works properly.

      pom.xml

      <project>
      ...
        <dependencies>
        ...
          <dependency>
            <groupId>dev.snowdrop</groupId>
            <artifactId>vertx-spring-boot-starter-http</artifactId>
          </dependency>
          <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
          </dependency>
          <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-oauth2-client</artifactId>
          </dependency>
          <!-- Spring OAuth2 client only works with Reactor Netty client -->
          <dependency>
            <groupId>io.projectreactor.netty</groupId>
            <artifactId>reactor-netty</artifactId>
          </dependency>
        ...
        <dependencies>
      ...
      </project>

  3. Create an endpoint controller class for your application:

    HelloController.java

    package dev.snowdrop.vertx.sample.http.oauth;
    
    import org.springframework.security.core.annotation.AuthenticationPrincipal;
    import org.springframework.security.oauth2.core.user.OAuth2User;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
    import reactor.core.publisher.Mono;
    
    @RestController
    public class HelloController {
    
        @GetMapping
        public Mono<String> hello(@AuthenticationPrincipal OAuth2User oauth2User) {
            return Mono.just("Hello, " + oauth2User.getAttributes().get("name") + "!");
        }
    }

  4. Create the main class of your application:

    OAuthSampleApplication.java

    package dev.snowdrop.vertx.sample.http.oauth;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @SpringBootApplication
    public class OAuthSampleApplication {
    
        public static void main(String[] args) {
            SpringApplication.run(OAuthSampleApplication.class, args);
        }
    }

  5. Create a YAML configuration file to store the OAuth2 client ID and client secret you received from GitHub upon registering your application.

    src/main/resources/application.yml

    spring:
      security:
        oauth2:
          client:
            registration:
              github:
                client-id: YOUR_GITHUB_CLIENT_ID
                client-secret: YOUR_GITHUB_CLIENT_SECRET

  6. OPTIONAL: Run and test your application locally:

    1. Navigate to the root directory of your Maven project:

      $ cd myApp
    2. Package your application:

      $ mvn clean package
    3. Start your application from the command line:

      $ java -jar target/vertx-spring-boot-sample-http-oauth.jar
    4. Navigate to http://localhost:8080 using a web browser. You are redirected to an OAuth2 application authorization screen on GitHub. If prompted, log in using your GitHub account credentials.
    5. Click Authorize to confirm. You are redirected to a screen showing a personalized greeting message.

Additional resources

6.6. Creating a reactive Spring Boot SMTP mail application

Create a reactive SMTP email service with Spring Boot with Vert.X.

Prerequisites

  • JDK 8 or JDK 11 installed
  • Maven installed
  • A Maven-based application project configured to use Spring Boot
  • A SMTP mail server configured on your machine

Procedure

  1. Add vertx-spring-boot-starter-http and vertx-spring-boot-starter-mail as dependencies in the pom.xml file of your project.

    pom.xml

    <project>
    ...
      <dependencies>
      ...
        <dependency>
          <groupId>dev.snowdrop</groupId>
          <artifactId>vertx-spring-boot-starter-http</artifactId>
        </dependency>
        <dependency>
          <groupId>dev.snowdrop</groupId>
          <artifactId>vertx-spring-boot-starter-mail</artifactId>
        </dependency>
      ...
      <dependencies>
    ...
    </project>

  2. Create a mail handler class for your application:

    MailHandler.java

    package dev.snowdrop.vertx.sample.mail;
    
    import dev.snowdrop.vertx.mail.MailClient;
    import dev.snowdrop.vertx.mail.MailMessage;
    import dev.snowdrop.vertx.mail.SimpleMailMessage;
    import org.springframework.stereotype.Component;
    import org.springframework.util.MultiValueMap;
    import org.springframework.web.reactive.function.server.ServerRequest;
    import org.springframework.web.reactive.function.server.ServerResponse;
    import reactor.core.publisher.Mono;
    
    import static org.springframework.web.reactive.function.server.ServerResponse.noContent;
    
    @Component
    public class MailHandler {
    
        private final MailClient mailClient;
    
        public MailHandler(MailClient mailClient) {
            this.mailClient = mailClient;
        }
    
        public Mono<ServerResponse> send(ServerRequest request) {
            return request.formData()
                .log()
                .map(this::formToMessage)
                .flatMap(mailClient::send)
                .flatMap(result -> noContent().build());
        }
    
        private MailMessage formToMessage(MultiValueMap<String, String> form) {
            return new SimpleMailMessage()
                .setFrom(form.getFirst("from"))
                .setTo(form.get("to"))
                .setSubject(form.getFirst("subject"))
                .setText(form.getFirst("text"));
        }
    
    }

  3. Create the main class of your application:

    MailSampleApplication.java

    package dev.snowdrop.vertx.sample.mail;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.context.annotation.Bean;
    import org.springframework.core.io.ClassPathResource;
    import org.springframework.web.reactive.function.server.RouterFunction;
    import org.springframework.web.reactive.function.server.ServerResponse;
    
    import static org.springframework.http.MediaType.APPLICATION_FORM_URLENCODED;
    import static org.springframework.web.reactive.function.server.RequestPredicates.accept;
    import static org.springframework.web.reactive.function.server.RouterFunctions.resources;
    import static org.springframework.web.reactive.function.server.RouterFunctions.route;
    
    @SpringBootApplication
    public class MailSampleApplication {
    
        public static void main(String[] args) {
            SpringApplication.run(MailSampleApplication.class, args);
        }
    
        @Bean
        public RouterFunction<ServerResponse> mailRouter(MailHandler mailHandler) {
            return route()
                    .POST("/mail", accept(APPLICATION_FORM_URLENCODED), mailHandler::send)
                    .build();
        }
    
        @Bean
        public RouterFunction<ServerResponse> staticResourceRouter() {
            return resources("/**", new ClassPathResource("static/"));
        }
    
    }

  4. Create an application.properties file to store your SMTP server credentials:

    application.properties

    vertx.mail.host=YOUR_SMTP_SERVER_HOSTNAME
    vertx.mail.username=YOUR_SMTP_SERVER_USERNAME
    vertx.mail.password=YOUR_SMTP_SERVER_PASSWORD

  5. Create a src/main/resources/static/index.html file that serves as the frontend of your application. Alternatively, use the example HTML email form available for this procedure.
  6. OPTIONAL: Run and test your application locally:

    1. Navigate to the root directory of your Maven project:

      $ cd myApp
    2. Package your application:

      $ mvn clean package
    3. Start your application from the command line.

      $ java -jar target/vertx-spring-boot-sample-mail.jar
    4. Navigate to http://localhost:8080/index.html using a web browser to access the email form.

Additional resources

6.7. Server-sent events

Server-sent events (SSE) is a push technology allowing HTTP sever to send unidirectional updates to the client. SSE works by establishing a connection between the event source and the client. The event source uses this connection to push events to the client-side. After the server pushes the events, the connection remains open and can be used to push subsequent events. When the client terminates the request on the server, the connection is closed. SSE represents a more resource-efficient alternative to polling, where a new connection must be established each time the client polls the event source for updates. As opposed to WebSockets, SSE pushes events in one direction only (that is, from the source to the client). It does not handle bidirectional communication between the event source and the client.

The specification for SSE is incorporated into HTML5, and is widely supported by web browsers, including their legacy versions. SSE can be used from the command line, and is relatively simple to set up compared to other protocols.

SSE is suitable for use cases that require frequent updates from the server to the client, while updates from the client side to the server are expected to be less frequent. Updates form the client side to the server can then be handled over a different protocol, such as REST. Examples of such use cases include social media feed updates or notifications sent to a client when new files are uploaded to a file server.

6.8. Using Server-sent events in a reactive Spring Boot application

Create a simple service that accepts HTTP requests and returns a stream of server-sent events (SSE). When the client establishes a connection to the server and the streaming starts, the connection remains open. The server re-uses the connection to continuously push new events to the client. Canceling the request closes the connection and stops the stream, causing the client to stop receiving updates form the server.

Prerequisites

Procedure

  1. Add vertx-spring-boot-starter-http as a dependency in the pom.xml file of your project.

    pom.xml

    <project>
    ...
      <dependencies>
      ...
        <dependency>
          <groupId>dev.snowdrop</groupId>
          <artifactId>vertx-spring-boot-starter-http</artifactId>
        </dependency>
      ...
      <dependencies>
    ...
    </project>

  2. Create the main class of your application:

    SseExampleApplication.java

    package dev.snowdrop.vertx.sample.sse;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @SpringBootApplication
    public class SseSampleApplication {
    
        public static void main(String[] args) {
            SpringApplication.run(SseSampleApplication.class, args);
        }
    }

  3. Create a Server-sent Event controller class for your application. In this example, the class generates a stream of random integers and prints them to a terminal application.

    SseController.java

    package dev.snowdrop.vertx.sample.sse;
    
    import java.time.Duration;
    import java.util.Random;
    
    import org.springframework.http.MediaType;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
    import reactor.core.publisher.Flux;
    
    @RestController
    public class SseController {
    
        @GetMapping(produces = MediaType.TEXT_EVENT_STREAM_VALUE)
        public Flux<Integer> getRandomNumberStream() {
            Random random = new Random();
    
            return Flux.interval(Duration.ofSeconds(1))
                .map(i -> random.nextInt())
                .log();
        }
    }

  4. OPTIONAL: Run and test your application locally:

    1. Navigate to the root directory of your Maven project:

      $ cd myApp
    2. Package your application:

      $ mvn clean package
    3. Start your application from the command line:

      $ java -jar target/vertx-spring-boot-sample-sse.jar
    4. In a new terminal window, issue a HTTP request to localhost. You start receiving a continuous stream of random integers from the server-sent event controller:

      $ curl localhost:8080
      data:-2126721954
      
      data:-573499422
      
      data:1404187823
      
      data:1338766210
      
      data:-666543077
      ...

      Press Ctrl+C to cancel your HTTP request and terminate the stream of responses.

Additional resources

In addition to using an example, you can also use Spring Boot with Vert.X starters to create new Spring Boot applications from scratch and deploy them to OpenShift.