You’ll learn how they differ in their approaches, use cases, and design. You’ll then have the necessary information to make a proper choice.

Table of Contents

• Introduction to OpenFeign

• Introduction to WebClient

• Main Differences

• Performance Considerations

• Use Cases

• Conclusion

Introduction to OpenFeign

OpenFeign is an HTTP client tool developed originally by Netflix and now maintained as an open-source community project. In the Spring Cloud ecosystem, OpenFeign allows you to define REST clients using annotated Java interfaces, reducing boilerplate code.

A basic OpenFeign client looks like this:

@FeignClient(name = "book-service")
public interface BookClient {
    @GetMapping("/books/{id}")
    User getBookById(@PathVariable("id") Long id);
}

You can then inject BookClient like any Spring Bean:

@Service
public class BookService {
    @Autowired
    private BookClient bookClient;

    public User getBook(Long id) {
        return bookClient.getBookById(id);
    }
}

OpenFeign is well integrated with Spring Cloud Discovery Service (Eureka), Spring Cloud Config, and Spring Cloud LoadBalancer. This makes it perfect for service-to-service calls in a microservice architecture based on Spring Cloud. It has several important features.

• Declarative syntax: It uses interfaces and annotations to define HTTP clients, avoiding manual request implementation.

• Spring Cloud integration: It integrates well with the components of Spring Cloud, like Service Discovery (Eureka), Spring Config, and Load Balancer.

• Retry and fallback mechanisms: It can be easily integrated with Spring Cloud Circuit Breaker or Resilience4j.

• Custom configurations: You can customize many aspects, like headers, interceptors, logging, timeouts, and encoders/decoders.

Introduction to WebClient

WebClient is a reactive HTTP client, and it’s part of the Spring WebFlux module. It is mainly based on non-blocking asynchronous HTTP communication, but it can also deal with synchronous calls.

While OpenFeign follows a declarative design, WebClient offers an imperative, fluent API.

Here’s a basic example of using WebClient synchronously:

WebClient client = WebClient.create("http://book-service");

User user = client.get()
        .uri("/books/{id}", 1L)
        .retrieve()
        .bodyToMono(Book.class)
        .block(); // synchronous

Or asynchronously:

Mono<User> bookMono = client.get()
        .uri("/books/{id}", 1L)
        .retrieve()
        .bodyToMono(Book.class);

Being designed to be non-blocking and reactive, WebClient gives its best with high-throughput, I/O intensive operations. This is particularly true if the entire stack is reactive.

Main Differences

Programming Model

• OpenFeign: Declarative. You just have to define interfaces. The framework will provide implementations of those interfaces.

• WebClient: Programmatic. You use an imperative, fluent API to implement HTTP calls.

Synchronous/Asynchronous Calls

• OpenFeign: Based on synchronous calls. You require customization or third-party extensions to implement asynchronous behavior.

• WebClient: Asynchronous and non-blocking. It fits well with systems based on a reactive stack.

Integration with Spring Cloud

• OpenFeign: It integrates well with the Spring Cloud stack, such as service discovery (Eureka), client-side load balancing, and circuit breakers.

• WebClient: It integrates with Spring Cloud, but additional configuration is required for some features, like load balancing.

Boilerplate Code

• OpenFeign: You have to define only the endpoint with Interfaces, and the rest is implemented automatically by the framework.

• WebClient: You have a little more code to write and more explicit configuration.

Error Handling

• OpenFeign: You require custom error handling or fallbacks by Hystrix or Resilience4j.

• WebClient: Error handling is more flexible with operators like onStatus() and exception mapping.

Performance Considerations

When high throughput is not the main concern, OpenFeign is a better choice, since it is well-suited for traditional, blocking applications where simplicity and developer productivity are more important than maximum throughput.

When you have a large number of concurrent requests, such as hundreds or thousands per second, with OpenFeign, you can encounter thread exhaustion problems unless you significantly increase the thread pool sizes. This results in higher memory consumption and increased CPU overhead. For a monolithic application with blocking operations, OpenFeign is better, because mixing blocking and non-blocking models is discouraged.

WebClient is more suitable if your application is I/O bound and has to handle heavy loads. Its non-blocking, reactive nature is excellent for those scenarios, because it can handle more concurrent requests with fewer threads. WebClient does not block a thread while waiting for a response, it releases it immediately to be reused for other work. It also provides a reactive feature called backpressure, used to control the data flow rate. This is useful when dealing with large data streams or when the speed at which clients consume data is too low. It's suited for applications that need to manage thousands of concurrent requests. It is more complex, though, and has a steeper learning curve.

Use Cases

Use OpenFeign When:

• You need to call other services in a Spring Cloud microservice architecture, with tight integration with Service Discovery and Spring Cloud LoadBalancer.

• You prefer productivity and simplicity.

• You’re bound to a synchronous, blocking model.

Use WebClient When:

• You're using Spring WebFlux to develop the application.

• You need full control over request/response handling.

• You require high-performance, non-blocking communication.

• You want more control over error handling and retry logic.

Conclusion

The architecture and performance requirements of your system guide the choice between OpenFeign and WebClient.

OpenFeign is ideal for synchronous REST calls in a Spring Cloud stack and helps in reducing boilerplate code. WebClient, on the other hand, gives its best for reactive and high-performance applications and is more flexible.

If you're building a traditional microservices system using Spring Boot and Spring Cloud, OpenFeign is most likely to be the obvious choice. If you're in the context of reactive programming or you have to handle thousands of concurrent connections, then WebClient would be a better choice.

Understanding both tools, their pros and cons, is important to make the proper choice.

We'll also deploy the application on Azure App Service and make it production-ready by setting up features like autoscaling and multiple environments.

You'll learn how Neon Postgres can make your development and deployment processes easier along the way.

Here's what we'll cover:

• Setting up a Neon Postgres database and exploring its features
• Building a CRUD application using Spring Boot and deploying the application on Azure App Service
• Why Neon is a good fit for infrastructure that auto-scales
• Database branching in Neon Postgres and how it can ease the development workflow

Prerequisites

• Working knowledge of Java, Maven, and Spring Boot
• Basics of SQL databases
• Understanding of serverless and cloud services
• Familiarity with testing and deployment processes

Table of Contents

• What is Neon Postgres?
• How to Set Up the Database
  • Create the Database
• How to Build the Spring Boot CRUD App
  • Create an Entity Class
  • Create a Repository
  • Create a REST Controller
  • Configure the Database
• How to Deploy on Azure App Service
  • Create a New Web App
  • Deploy the Application
  • Access the Application
• How to Set Up Autoscaling
  • Autoscaling in Azure
  • Autoscaling in Neon
• How to Configure Database Branches in Neon
• Summary

What is Neon Postgres?

Neon is a fully managed serverless Postgres database platform. It offers features such as high availability, automatic backups, and scaling options to handle varying traffic levels.

Neon is designed to be cost-efficient and developer-friendly, and it focuses on providing a seamless experience for developers.

In addition to the standard Postgres features, it provides capabilities like database branching, allowing you to create Git-like branches of the database for different purposes.

How to Set Up the Database

To begin with, let's explore how you can set up a Neon database for your application.

Firstly, you'll need to create an account on the Neon website. It doesn't require a credit card to sign up, and you're automatically set up with the free tier to get started.

Here's a pricing and features comparison of Neon plans:

Neon pricing plans

In the free tier, we get 0.5 GB of storage with basic computing which is enough for playing around with the database and building small applications.

Create the Database

Once you've signed up, you can access the dashboard and create a new project.

Star by filling in the project name, region, and Postgres version options. In addition to this, we can choose two additional options:

• compute size – You can choose a min and max compute size for the database. This is useful for autoscaling the database based on the load.
• suspend time – You can set a time after which the database will be suspended if not being used. This is useful for saving costs when the database is not being used.

Creating a database project in Neon

Once you submit the form, Neon will create the database and provide the connection details.

Neon Dashboard

As you can see, the database was set up in 3.3 seconds (compared to hours of installing and setting up your own infrastructure). You can choose multiple ways to connect to the database. For this tutorial, select Java as your programming language and get the JDBC connection string.

How to Build the Spring Boot CRUD App

Next, let's set up our CRUD application. We'll use Spring Boot, as it provides easy bootstrapping and configuration for building web applications.

We can use the Spring Initializr to generate a new Spring Boot project with the necessary dependencies:

• Spring Web – for building web applications
• Spring Data JPA – for working with databases using JPA
• PostGres Driver – for connecting to the Postgres database

Creating a Spring Boot project using Spring Initializer

You can generate, download, and import the project into your favorite IDE.

Create an Entity Class

Let's create an entity class to represent the data in the application. First, create a User class:

@Entity(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;

    // Constructors, Getters and Setters
}

The entity name users is the name of the table you want to use in your database.

Create a Repository

Next, create a repository interface to interact with the database. You'll extend the JpaRepository interface provided by Spring Data JPA:

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
}

You need to annotate the interface with @Repository to mark it as a Spring bean. The JpaRepository interface provides methods for CRUD operations like save, findAll, findById, delete, and so on, so you don't need to write the queries manually.

You'll provide your entity class User and the type of the primary key Long as type arguments to the JpaRepository interface.

Create a REST Controller

Finally, create a REST controller to handle the CRUD operations. You'll inject the UserRepository into the controller and implement the necessary endpoints:

@RestController
@RequestMapping("/users")
public class UserController {
    private final UserRepository userRepository;

    public UserController(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @GetMapping
    public List<User> getUsers() {
        return userRepository.findAll();
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userRepository.save(user);
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) {
        user.setId(id);
        return userRepository.save(user);
    }

    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        userRepository.deleteById(id);
    }
}

Here are a few things to note:

• You're using the @RestController annotation to mark the class as a controller that handles REST requests.
• The @RequestMapping annotation specifies the base URL for the endpoints.
• You're injecting the UserRepository into the controller using constructor injection.
• Finally, you're implementing your API endpoints for CRUD operations using the @GetMapping, @PostMapping, @PutMapping, and @DeleteMapping annotations.

Configure the Database

To connect your Spring Boot application to the Neon Postgres database, you need to configure the database URL, username, and password in the application.properties file:

spring.datasource.url=jdbc:postgresql://<db-url>/<db-name>?sslmode=require
spring.datasource.username=<username>
spring.datasource.password=<password>
spring.jpa.hibernate.ddl-auto=update

Here, you configured the database URL, username, and password provided by Neon when you created the database. The spring.jpa.hibernate.ddl-auto=update property tells Spring Boot to automatically create the necessary tables or columns based on the entity classes when the application starts.

How to Deploy on Azure App Service

Now that your Spring Boot application is ready, it's time to deploy it on Azure App Service.

Create a New Web App

To deploy your Spring Boot application on Azure App Service, you'll first create a new Web App. You can do this through the Azure portal by following these steps:

• Log in to the Azure portal.
• Click on the Create a resource button.
• Search for Web App and select the Create option.
• Fill in the necessary details like resource group, app name, runtime stack, and region.
• Click the Review + create button.

Creating a Web App in Azure

Deploy the Application

The Web App takes a couple of minutes to create. Once done, you can deploy your Spring Boot application to Azure App Service.

One of the easiest ways to deploy is to package your Spring Boot application as a JAR file and deploy it to Azure App Service using the Azure CLI.

To do this, run the below commands:

mvn package
az webapp deploy --src-path neon-demo-0.0.1-SNAPSHOT.jar --resource-group learn-ba1a439c-71ca-4cab-9bb1-f5b1331bab04 --name neon-app

Here, you're packaging your Spring Boot application using Maven and deploying the JAR file to Azure App Service using the Azure CLI. You've provided the path to the JAR file, the resource group, and the app name you previously configured.

Access the Application

Once the deployment is complete, you can access your Spring Boot application on Azure App Service by navigating to the URL of the Web App. Your app is available at neon-app.azurewebsites.net

Let's use _curl _to test the endpoints.

Create a User

curl -X POST -d '{"name":"John Doe","email":"john@gmail.com"}' https://neon-app.azurewebsites.net/users

Here you provide user data in JSON format to create a new user.

Get Users

You can also can test that the user was created by fetching all users:

curl -X GET https://neon-app.azurewebsites.net/users

How to Set Up Autoscaling

A production application may experience varying levels of traffic, and it's important to scale the application dynamically based on the load.

Let's explore how you can autoscale your application when needed.

Autoscaling in Azure

Azure App Service provides autoscaling options that let you automatically adjust the number of instances as needed.

You can configure autoscaling rules in the Azure portal by following these steps:

• Navigate to the Web App in the Azure portal.
• Click the Scale out (App Service Plan) option from the left menu.
• Configure the autoscaling rules – you can choose predefined rules like traffic or create custom rules based on metrics like CPU usage, memory usage, or custom metrics.
• Save.

Azure will automatically scale the application based on the configured rules.

Autoscaling in Neon

Since your application is automatically scaled based on the load, you'll want to ensure that the database can handle the increased traffic.

Neon provides autoscaling options to scale the database dynamically based on the load. You can configure autoscaling rules in the Neon dashboard to ensure the database can handle the increased load.

Follow the below steps to configure autoscaling in Neon:

1. Navigate to the Neon dashboard and select the database. Then select the branch to configure autoscaling.

Selecting a branch from Neon project dashboard

2. Click on the Edit button next to the Compute section. Configure the autoscaling rules based on metrics like CPU usage, memory usage, or custom metrics.

Branch details view in Neon

3. Configure the min-max compute size and Save. Neon will automatically scale the database based on the configured rules when needed.

Setting up autoscaling for compute

Ensuring that both the application and the database can scale dynamically based on the load will help you handle varying levels of traffic efficiently.

How to Configure Database Branches in Neon

In a typical development workflow, multiple databases may be used for different purposes like development, testing, and production.

Neon Postgres provides database branching to create multiple branches for different purposes. Each branch is an instance of the database that you can use independently.

This Git-like feature helps set up a copy of the database for different environments like development, staging, and production. It also helps preserve data for different versions of the application.

Let's explore how you can create and manage branches in Neon Postgres:

• Navigate to the Neon dashboard and select the database.
• In the Branches section, click on the View All button.
• You can create a new branch from an existing one by clicking on the Create Branch button. You'll need to provide the branch name and what data to copy from the parent branch.

Create branch option

• You can either copy all the data or copy until a point in time or a specific record. This is useful for multiple purposes like restoring data, creating a new environment, or testing new features.

Creating a new branch

• Neon will create a new branch of the database that can be used independently. You can find the URL, username, and password for the new branch in the dashboard. And this happens in real time without any downtime and delays.

Branch-specific connection details

Now you can use your dev branch for local development and testing, and the main branch for production. This helps in keeping the data separate and ensures that changes in one branch do not affect the other branches.

Summary

In this article, we built a CRUD application using Spring Boot, Neon Postgres, and Azure App Service.

We explored how to set up the Neon Postgres database, build a basic CRUD application using Spring Boot, deploy the application on Azure App Service, and configure autoscaling for the application and the database.

We also learned about how the database branching feature in Neon Postgres helps you create branches of the database for different environments and purposes.

For this purpose, you can use a software tool based on Scala called Gatling. This article will teach you how to integrate it into a Spring Boot application and perform a load test.

Main Concepts

Gatling is a tool you can use to execute load and performance tests. It can be used as a standalone application or integrated into a Maven or Gradle-based project.

Gatling is based on Scala, the Netty framework, and the Akka toolkit. It has an asynchronous, non-blocking architecture, which allows for high performance with minimum wasting of resources.

You can define tests by Gatling's flexible domain-specific language. You can also use its recorder function with a Graphical User Interface to capture user interactions in the browser and generate Scala scripts that can be modified and launched to perform a simulation.

In this article, you will learn how to integrate Gatling in a Spring Boot web application based on Maven. You will define a load test by its DSL, and then run it using the Gatling Maven plugin.

With Gatling, you can perform performance tests in a variety of ways. For instance, you can implement:

• Load Testing: to see how a system performs under a specific load
• Stress Testing: to find the breaking point of a system, raising the load progressively
• Soak Testing: running the system with a steady load for a long time to find its pitfalls
• Spike Testing: to see how the system performs when swiftly raising the load to a peak and then going down

The basic components by which Gatling implements the features described above are:

• Scenarios: a series of steps performed by a virtual user
• Feeders: how data is provided to feed the scenarios
• Injection: a sort of a blueprint that states how the test is performed, in terms of number of virtual users, how they change in time, and so on

Spring Boot Gatling Integration

In this article, you will start with a simple Spring Boot web application and implement and run a load test over it. You can find the source code of this sample application on GitHub.

Imagine you have a library and want to insert new books by their title. You can implement this minimal requirement using JPA by defining a Book entity, a repository class, a service class, and a controller with a REST service mapping.

The REST service is defined as a POST call to a /book endpoint that saves a new book object. You can see the implementation in the code below:

@RestController
@RequestMapping("/library")
public class BookController {

    Logger logger = LoggerFactory.getLogger(BookController.class);

    @Autowired
    BookService bookService;

    @PostMapping(value = "/book", consumes = "application/json", produces = "application/json")
    public Book createPerson(@RequestBody Book book) {
        return bookService.save(book);
    }

}

To perform a load test on the above REST endpoint, you need to integrate Gatling. You can do this by setting some Maven dependencies first:

<dependency>
    <groupId>io.gatling</groupId>
    <artifactId>gatling-app</artifactId>
    <version>3.7.2</version>
</dependency>


<dependency>
    <groupId>io.gatling.highcharts</groupId>
    <artifactId>gatling-charts-highcharts</artifactId>
    <version>3.7.2</version>
</dependency>    

<dependency>
    <groupId>com.github.javafaker</groupId>
    <artifactId>javafaker</artifactId>
    <version>0.15</version>
</dependency>

Then you also need a Maven plugin to execute the test:

<plugin>
    <groupId>io.gatling</groupId>
    <artifactId>gatling-maven-plugin</artifactId>
    <version>4.2.9</version>
    <configuration>
<simulationClass>com.codingstrain.springcloud.sample.libraryapp.books.BookSaveSimulation</simulationClass>
    </configuration>
</plugin>

Load Test Implementation

To implement a test, you need to extend the io.gatling.javaapi.core.Simulation class, as in the BookSaveSimulation class below:

import static io.gatling.javaapi.core.CoreDsl.StringBody;
import static io.gatling.javaapi.core.CoreDsl.global;
import static io.gatling.javaapi.core.CoreDsl.rampUsersPerSec;
import static io.gatling.javaapi.http.HttpDsl.http;

import java.time.Duration;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import java.util.stream.Stream;

import com.github.javafaker.Faker;

import io.gatling.javaapi.core.CoreDsl;
import io.gatling.javaapi.core.OpenInjectionStep.RampRate.RampRateOpenInjectionStep;
import io.gatling.javaapi.core.ScenarioBuilder;
import io.gatling.javaapi.core.Simulation;
import io.gatling.javaapi.http.HttpDsl;
import io.gatling.javaapi.http.HttpProtocolBuilder;


public class BookSaveSimulation extends Simulation {


    public BookSaveSimulation() {

        setUp(buildPostScenario()
            .injectOpen(injection())
            .protocols(setupProtocol())).assertions(global().responseTime()
          .max()
          .lte(10000), global().successfulRequests()
          .percent()
          .gt(90d));
    }

    private static ScenarioBuilder buildPostScenario() {
        return CoreDsl.scenario("Load POST Test")
            .feed(feedData())
            .exec(http("create-book").post("/library/book")
            .header("Content-Type", "application/json")
                .body(StringBody("{ \"title\": \"${title}\" }")));
    }

    private static Iterator <Map<String, Object>> feedData() {
        Faker faker = new Faker();
        Iterator<Map<String, Object>> iterator;
        iterator = Stream.generate(() -> {
              Map&lt;String, Objectglt; stringObjectMap = new HashMap<>();
            stringObjectMap.put("title", faker.book()
                .title());
              return stringObjectMap;
          })
          .iterator();
        return iterator;
    }

    private static HttpProtocolBuilder setupProtocol() {
        return HttpDsl.http.baseUrl("http://localhost:8080")
          .acceptHeader("application/json")
          .maxConnectionsPerHost(10)
            .userAgentHeader("Performance Test");
    }

    private RampRateOpenInjectionStep injection() {
        int totalUsers = 100;
        double userRampUpPerInterval = 10;
        double rampUpIntervalInSeconds = 30;

        int rampUptimeSeconds = 300;
        int duration = 300;
        return rampUsersPerSec(userRampUpPerInterval / (rampUpIntervalInSeconds)).to(totalUsers)
            .during(Duration.ofSeconds(rampUptimeSeconds + duration));
    }
}

The BoookSaveSimulation class uses its constructor to do all the settings using the parent class setUp method. It first implements a scenario. Since the test's purpose is to simulate a real situation in production, the scenario represents the steps performed by a configured number of virtual users interacting with the system.

The scenario in the example executes a POST call to the /library/book endpoint, sending a single title parameter in the payload. The invoked service will save a new book by the passed title value. A class named com.github.javafaker.Faker produces title values automatically and implements the feeder component described earlier in the Main Concepts section.

Then the injectOpen method defines how the virtual users are added to the simulation. The injectOpen method implements the injection part using the so-called open mode. There are two different models of injection, open and closed.

The open model simulates a scenario in which new users can be added constantly and independently from the execution state of the others. This is the model used in this article's example. On the other hand, in the closed model, new users can be added only when all the others have terminated their tasks. This helps simulate a steady load on the system.

The open injection configuration in the example sets a total number of 100 users that are added progressively 10 at a time, every 30 seconds. Once all users have been added, the execution continues for 300 seconds.

The protocols method sets up the base URL, the data type expected in the response, the maximum number of connections per host, and the User-Agent header.

The last part of this set-up phase defines a couple of assertions to consider the test passed: a maximum response time lower than 10 seconds and a percentage of successful requests greater than 90%.

How to Run the Test

To run the test, you first have to start the Spring Boot web application. You can do this, for instance, by going to the project base directory and execute the following command: mvn spring-boot:run.

Once the application is started, you can run the Gatling simulation by executing mvn gatling:test.

How to See the Results

Once the test is terminated, you will find an index.html in the /target/gatling directory with all the measurements and several graphs.

The figure below displays all the results. It shows a list of the assertions and their outcome. Then, you can see the total number of requests, and how many requests have a positive or negative result. You have useful information about the response time: minimum, maximum, average, and standard deviation, and you also have the 50th, 75th, 95th, and 99th percentiles.

Summary of the test results

A chart shows the number of requests, with positive and negative outcomes, in a particular response time range, as in the following figure.

Number of requests in particular response time ranges

Another graph shows the number of requests per second and how it changes depending on the number of active users.

Number of request per second and active users over time

You can also see in the next figure how the percentiles change over time, and with the number of active users at each point in time.

Conclusion

Evaluating the performance of a system is a complex task. Gatling makes things easy enough to integrate this kind of task with continuous integration. It gives you a comprehensive view and allows you to tweak the tests to find weaknesses and suggest solutions.

Once you have planned out your APIs, there's one crucial step you need to take care of: securing your APIs. You don't want your APIs exposed to anyone on the internet (unless you are building for open source).

Authentication ensures that your APIs can only be accessed by authenticated users of your application. A user can be authenticated with username and password, or via access token.

In this post, we are going to see how to secure your APIs using OAuth2 and access tokens. I am assuming you have a basic knowledge of Java and Spring Boot. If not, then you can check out this course on freeCodeCamp's YouTube channel.

Table of Contents

1. What is OAuth2?

2. How to Set Up the Spring Boot Application

3. Web Security Configuration

4. Public and Private APIs

5. Testing APIs with and without Access Token

6. How to Get the User's Details From the Access Token

What is OAuth2?

OAuth2 is a framework that lets third-party applications access your service on behalf of an end user. It is widely used for authentication and authorization in modern applications.

There are four components in the OAuth2 framework:

• Resource Owner: The end-user of your application.

• Authorization Server: The third-party application that authenticates the user and issues an access token after successful authentication.

• Client: The user interface through which the user wants to access your resources. The client could be a mobile app, web app, or a desktop app. The client requires an access token to access your APIs.

• Resource Server: The server hosting the protected resources. It validates the access token and grants access to the resources if authentication is successful.

The user, through the client, requests an access token from the authorization server. If authentication is successful, the client uses this token to access the protected APIs exposed by the resource server.

In this post, we are only going to focus on implementing the resource server.

How to Set Up the Spring Boot Application

To set up your application, navigate to Spring Initializr.

Spring Initializr

Choose Gradle or Maven for the project, the Spring Boot version, and the name of the project. Add the following dependencies: spring-boot-starter-web and oauth2-resource-server.

Click on Generate to download the Spring Boot application and once downloaded, extract the zip file. You should now have a running Spring Boot application with the dependencies fully loaded. Open IntelliJ (or any IDE of your choice) and select this project to start working.

You can find the complete code for this tutorial on GitHub.

Web Security Configuration

First, open application.properties and add the following property:

spring.security.oauth2.resourceserver.jwt.issuer-uri: ${JWT_ISSUER_URI}

You can find the issuer-uri in the open-id configuration of the OAuth2 service that you are using. For instance, check out the Google OAuth2 config.

Next, let's configure Spring Security.

To implement the resource server, you need to have Spring Security as one of your dependencies. Here, we don't need to add it separately since the oauth2-resource-server uses Spring Security.

When you add Spring Security in your dependencies, Spring Boot enables authentication for each API you expose. The default one is username and password-based authentication.

This happens because Spring Security has its own SecurityAutoConfiguration class that contains the default security configuration. But, we haven't added Spring Security in our dependencies.

Since we do not want username and password-based authentication, we need to disable the auto configuration. Go to the main class and add the following exclusion:

@SpringBootApplication(exclude = { SecurityAutoConfiguration.class})
public class Oauth2ResourceServerTutorialApplication {
    public static void main(String[] args) {
        SpringApplication.run(Oauth2ResourceServerTutorialApplication.class, args);
    }
}

If you run the application now, it throws an error.

Error without configuration

Let's add our own configuration now. Create a new Java class SecurityConfig with the following annotations:

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    // Beans here
}

@Configuration indicates that this is a configuration class that contains several Bean methods, that are responsible for creating beans. Beans are simply objects that form the building blocks of a Spring Boot application. @EnableWebSecurity tells Spring Boot to enable Web Security with your configurations.

Create a method that returns a bean of type SecurityFilterChain. The security filter chain bean intercepts incoming requests and applies custom filters to them. This is where you can apply different kinds of authorization to different requests.

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
                .authorizeHttpRequests((authz) -> authz
                        .requestMatchers("/public/**").permitAll()
                        .anyRequest().authenticated()
                )
                .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
        return http.build();
    }

Let's understand the key parts of this code:

• The filterChain() method takes an HttpSecurity object as an argument. This class from Spring Security allows you to configure requests.

• The method authorizeHttpRequests() takes an object that we have represented as a lambda expression.

• We have used the requestMatchers() method to match a route that will be accessible without authentication. In our case, any route starting from /public will be accessible to anyone. Requests to any other route will need authentication.

• The oauth2ResourceServer() method sets up our application as an OAuth2 resource server. Here, we specify that JWT authentication will be used with default customizers.

• Lastly, http.build() builds the HttpSecurity object and returns it.

In this project, we have configured web security in the above manner. But if you have any other requirements you may need a different configuration. For example, if you have privileged roles like admin in your application, you can specify which routes each role can access, and so on.

Visit the JWT resource server docs to understand different ways you can customize web security.

Write APIs in the Controller Class

Let's write two simple APIs. Create a class MainController that will expose these APIs:

@RestController
public class MainController {

    @GetMapping("/public")
    public String homePage() {
        return "Hello from Spring boot app";
    }

    @GetMapping("/private")
    public String privateRoute() {
        return "Private Route";
    }
}

The @RestController indicates that this class will handle HTTP requests and return the data to the client, typically in JSON format. We have written a public and a private API.

Save the file and run the application.

Testing the APIs

Let's test the above APIs using Postman, without an authorization header.

/public route

/private route

In the above two API calls, the /public route returned a response, while the /private route threw an error with a status of 401 Unauthorized.

This is because, in our configuration, we have made all routes starting with /public accessible without authentication. All the other routes would need some form of authentication. In our case, we need a Bearer Token to access the private route.

Let's include an authorization header in the request to the /private endpoint.

/private route request with access token

When we include an authorization header with the access token, the private route returns a response. For this, and any other routes not starting with /public, we need to pass an access token in the header.

We are not going to see how to obtain an access token, since we are only focussing on the resource server. The OAuth2 Client is responsible for obtaining an access token. I'll cover that in a future post.

How to Get the User's Details From the Access Token

When you make a request to a private route, the security filter intercepts this request and looks for a Bearer Token. If a token exists, it decodes the token and extracts the authentication information from the token. You can understand this whole process in detail from the OAuth2 Resource Server docs.

If the token is valid and authentication is successful, the authentication data is set on the SecurityContextHolder class. The SecurityContextHolder contains the details of the authenticated user. We use this class to extract the user's information such as name, email, and so on.

Let's see how we can get these user details. First, we get an Authentication object from the SecurityContextHolder:

Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

Then, we use the getPrincipal() that returns an object:

Object principal = authentication.getPrincipal();

Since we are using JWT Authentication, the above object can be type-casted into an object of type Jwt. The object contains the following fields:

{
    "tokenValue": token_value,
    "issuedAt": "",
    "expiresAt": "",
    "headers": {...},
    "claims": {        
        "name": full_name,
        "email": user_email,
        "given_name": first_name,
        "family_name": last_name,
        "picture": picture_link,
        ...other fields
    },
    "subject": "",
    "id": null,
    "issuer": issuer_link,
    "audience": [...],
    "notBefore": null
}

Here, we can get the user data from the claims field:

Map<String, Object> claims = ((Jwt) principal).getClaims();

Using the above map, we can get the user's information using the corresponding key value. Let's write this logic in a separate class CurrentAuthContext:

public class CurrentAuthContext {
    private static Map<String, Object> extractClaim() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        Object principal = authentication.getPrincipal();
        Map<String, Object> claims = ((Jwt) principal).getClaims();
        return claims;
    }

    public static String getUserEmail() {
        return (String) extractClaim().get("email");
    }
}

You can add more methods to get the details you need. To get the user email anywhere in the application, just call CurrentAuthContext.getUserEmail() or any other method returning the value you need.

I haven't implemented custom error handling here. You can reach out to me with different ways to implement custom error handling.

Conclusion

OAuth2 provides a robust framework for securing your APIs while providing access to authorized users. In this post, we started with understanding OAuth2 and its components.

Spring Security is a fundamental part of the Spring OAuth2 Resource Server. We learned how to implement security configurations as per our requirements. Then, we defined public and private APIs and tested them with and without an access token.

A private API can only be accessed with an access token passed through the authorization header. We also implemented some logic to extract the user's information from the access token with the SecurityContextHolder class.

I attached reference links to docs at various places for further understanding of these concepts. That's all for today. I hope this helps in your future projects.

If you are unable to understand the content or find the explanation unsatisfactory, reach out to me. New ideas are always appreciated! Feel free to connect with me on Twitter. Till then, Goodbye!!

We just posted a course on the freeCodeCamp.org YouTube channel that will teach you how to develop apps with Spring Boot and Java. Dan Vega developed this course. Dan is a spring developer advocate, course creator, and speaker.

The course is designed to guide beginners through the nuances of web application development using Spring Boot 3, the cornerstone framework for Java applications. It's a blend of theory and practical application, where you start from the grassroots and ascend to creating sophisticated web applications.

Module Breakdown

Here is a description of each module in this course.

Module 1: Course Introduction

Dive into the world of Spring Boot 3, starting with an overview of the course structure and objectives. Understand the prerequisites, including Java fundamentals and the necessary development tools like JDK 17+ and your preferred IDE or text editor. This module sets the stage, ensuring you're well-equipped to embark on this learning journey.

Module 2: Create Your Project

Kickstart your project with a detailed exploration of how to use start.spring.io for project initialization. This module covers the essentials of Java Build Tools, Maven and Gradle, and best practices for organizing your code, including where to place your code files and the importance of avoiding the default package. Learn the nuances of running your application through an IDE or Maven, and get acquainted with Spring Boot DevTools.

Module 3: REST API

Delve into creating a REST API, where you'll learn to construct a web application that communicates effectively with clients. Explore the various components of Spring, like @Component, Controller, RestController, Service, and Repository, and understand their roles in your application. This module also covers the basics of CRUD operations in an in-memory setting and introduces you to the principles of dependency injection and data validation.

Module 4: Working with Databases

This module introduces you to integrating and manipulating databases within your Spring Boot application. You'll start with the H2 Database, progressing to more complex interactions using the JDBC Client. Additionally, you'll learn how to elevate your application with Docker Compose and PostgreSQL, ensuring your app can scale and interact with more sophisticated data storage solutions.

Module 5: Rest Clients

Explore the construction and utilization of REST clients, crucial for enabling your application to communicate with other web services. This module will guide you through setting up and configuring rest clients to interact with external APIs, enhancing the capability and reach of your application.

Module 6: Testing

Ensure your application's reliability and stability by mastering testing with the Spring Boot Testing Toolkit. This module emphasizes the importance of testing in the development lifecycle, teaching you how to create and implement a comprehensive testing suite to validate your application's functionality and performance.

Embark on Your Development Journey

This course is more than just a learning experience; it's a gateway to the vast world of web application development, offering you the tools and knowledge to build your own web applications with confidence. Whether you're starting from scratch or looking to refine your skills, this course is designed to provide a structured, engaging, and informative path to mastering Spring Boot 3.

Watch the full course on the freeCodeCamp.org YouTube channel (3.5 hour watch).

We just published a comprehensive video course on the freeCodeCamp.org YouTube channel that teaches Spring Boot and Spring Data JPA, two pivotal technologies in the Java ecosystem. Bouali Ali created this course. Bouali is an experienced developer and teacher.

Spring Boot is an open-source, micro-framework from the larger Spring Framework, designed to simplify the bootstrapping and development of new Spring applications. Its primary goal is to ease the development process by offering a range of out-of-the-box features for configuration, along with embedded servers to facilitate a straightforward setup of web applications. Spring Boot's convention over configuration approach significantly reduces the amount of manual configuration required, making it a preferred choice for developers aiming to deploy applications quickly.

Spring Data JPA, on the other hand, is a part of the larger Spring Data family, aiming to simplify data access within SQL databases. It abstracts boilerplate CRUD operations, providing a more straightforward way to interact with databases through the Java Persistence API (JPA). Spring Data JPA integrates seamlessly with Spring Boot, offering an intuitive approach to handling database operations, reducing the complexity and the amount of code developers need to write.

This course is designed for both beginners and experienced developers who wish to deepen their understanding of Spring Boot and Spring Data JPA. Here's an overview of the key topics covered in the course:

Introduction to Spring Framework and Spring Boot

• Overview of Spring Framework
• Introduction to Spring Boot
• Setting up a Spring Boot project
• Understanding Spring Boot auto-configuration

Spring Boot Basics

• Building RESTful web services with Spring Boot
• Spring Boot application properties
• Logging with Spring Boot
• Building a CRUD API

Database Access with Spring Data JPA

• Configuring a data source in Spring Boot
• Introduction to Spring Data JPA
• Implementing repositories
• Entity relationships and cascading
• Transactions and locking

Advanced Spring Boot Features

• Securing Spring Boot applications with Spring Security
• Token-based authentication
• Spring Boot with OAuth2
• Microservices with Spring Boot
• Deploying Spring Boot applications

Testing

• Writing unit tests for Spring Boot applications
• Integration testing with Spring Boot

Spring Boot Best Practices

• Effective logging practices
• Exception handling
• Application monitoring with Actuator
• Tips for production-ready applications

With a blend of theoretical concepts and practical demonstrations, the course aims to equip you with the knowledge and skills required to build robust, efficient applications. Watch the full course on the freeCodeCamp.org YouTube channel (13-hour watch).

SpringBoot has a number of in-built actuators, and it also allows us to create our own Actuator Endpoint.

For frameworks written in Python like Flask or FastAPI, we can incorporate actuators by integrating a library called Pyctuator.

In this article I am going to explain how to monitor applications written in FastAPI using the Pyctuator library. I'll also show you how to manage the actuator endpoints using the SpringBootAdmin server.

What are Actuators?

We use actuators for monitoring and managing application usage in production. This usage information gets exposed to us via REST endpoints.

For example, we can access the application logs in production, environment details, and HTTP traces. And if something has gone wrong within the application, we can even access the applications “threaddump” for debugging purposes.

Here are some examples of few important actuator endpoints:

Actuators

What is Pyctuator?

Actuators become popular because of SpringBoot, but you can implement them in frameworks like FastAPI or Flask by integrating a module called Pyctuator.

Pyctuator is a Python Module, which is a partial implementation of SpringBoot Actuators. Pyctuator is managed by SolarEdge.

Some of the actuators supported by Pyctuators are:

• /health: This endpoint in Pyctuator has built-in monitoring for Redis and MySQL

• /env

• /metrics

• /logfile

• /threaddump

• /httptrace

• /loggers

What is SpringBootAdmin?

Imagine a service having all these actuators for checking metrics, httptrace, threaddump and so on. It would be pretty tedious to invoke each one of them individually to check what’s going on within the service. And if we have many services and each one of them has its own actuator endpoints, this makes monitoring even more difficult.

That’s where you can use SpringBootAdmin to manage and monitor applications.

In a nutshell, SpringBootAdmin provides a nice dashboard for all the actuator endpoints in one place.

Admin Dashboard

Use-Case for Pyctuator

The use-case is straightforward: we are going to develop a RESTful service using FastAPI framework and configure the actuators in the service using the Pyctuator module.

The service has 3 endpoints as shown in the API-Docs (Swagger) below

API-Docs

• GET /users: Return all the users that exists in the system.

• POST /users: Create user

• GET /users/{id}: Return a user with a given id

You can find the code here.

In the User-Service we are going to enable the actuators using Pyctuator and monitor them using SpringBootAdmin dashboard. We are also going to explore how we can enhance the /health actuator for monitoring Redis.

For configuring the Actuators, first we need to install “pyctuator”. You can do that using the command “pip install pyctuator”.

After installation, simply instantiating the Pyctuator object is the entry point for seeing in-built actuators within a web-framework.

Pyctuator Constructor

Before instantiating Pyctuator, if you access the /pyctuator endpoint you will get the “Not Found” message:

Without Pyctuator Configuration

After instantiation, on accessing the /pyctuator endpoint you will see all the actuators enabled by default. This is because we have defined "pyactuator_endpoint_url" within Pyctuator.

After Pyctuator Configuration

I strongly recommend going through the Pyctuator object as it explains what the mandatory and optional arguments are that we need to provide.

Understanding Constructor parameters

The mandatory parameters are:

• app – instance of FastAPI or Flask

• the application name – displayed in the info section in SpringBootAdmin

• “pyctuator_endpoint_url” – what we have seen which returns all the actuator endpoints

• “registration_url” – you will understand this one shortly.

How to Enhance the /health Endpoint

You can enhance the /health endpoint in Pyctuator to monitor Redis or MySQL databases. Say you are using Redis in your application – then we need to use RedisHealthProvider and pass the redis instance to it.

Redis Health

How to Start the SpringBootAdmin Server

To run the SpringBootAdmin server on local, we have two options: first, we can do it by creating SpringBootAdmin manually by going to start.spring.io and adding libraries.

Spring Web & Spring Boot Admin (Server):

Creating SpringBootAdmin

The second option is to run a Docker image:

docker run --rm --name spring-boot-admin -p 8080:8080 michayaak/spring-boot-admin:2.2.3-1

Once the admin server is up, we need to provide the “registration_url” to the Pyctuator Constructor as discussed earlier.

URL registration in SpringBootAdmin

The Admin Server is running on localhost:8080 and this should register our application to SpringBootAdmin. We can access all the actuator endpoints in one place:

Dashboard

All Configured Actuator Endpoints

I executed the /users endpoint few times and now HTTP Traces on the Admin side showcases all the Request-Response exchange details.

HTTP Traces

Wrapping Up

Actuators are extremely helpful in monitoring and debugging applications in production. By accessing endpoints we can get details on thread dumps, heap dumps, HTTP Traces and so on.

Pyctuator simplifies having actuators in Python APIs to a great extent. By simply importing the library and defining an object, all the actuators are ready for us within our application.

These Docker containers are lightweight, and once the tests are finished the containers get destroyed.

In the article we are going to understand what the TestContainers is and how it helps you write more reliable Tests.

We are also going to understand the important components (Annotations and Methods) of the library which help you write the Tests.

Finally, we will also learn to write a proper Integration Test in SpringBoot using the TestContainers library and its components.

Limitations of Testing with an H2 In-Memory Database

The most common approach to Integration Testing today is to use an H2 in-memory database. But there are certain limitations to this method.

First of all, say we are using version 8.0 of MySQL in production, but our integration tests are using H2. We can never execute our tests for the database version running on Production.

SpringBoot app with MySQL DB and H2

‌Secondly, the test cases are less reliable because in production we are using an altogether different database and the tests are pointing to H2. The application may run into issues in production, but the integration tests may succeed.

I was trying to access my RESTful service on local and faced this error:

“Caused by: org.postgresql.util.PSQLException: FATAL: database "example_db" does not exist”.

It happened because of a permission issue, but the tests on local worked fine.

And finally, as documented here, H2 is compatible with other databases only up to a certain point. There are few areas where H2 is incompatible. If you need to use “nativeQueries” in a SpringBoot application, for example, then using H2 may cause problems.

Enter the TestContainers Library

By using TestContainers we can overcome the limitations of H2.

• Integration tests will point to the same version of the database as it’s in production. So we can tie our TestContainer Database Image to the same version running on production.

• Integration tests are lot more reliable because both application and tests are using the same database type and version and there won't be any compatibility issues in Testcases.

What is TestContainers?

The TestContainers library is a wrapper API over Docker. When we write code to create a container behind the scenes it may be translated to some Docker command, for example‌:

MySQLContainer Creation

This code may be translated to something like the following:

docker run -d --env MYSQL_DATABASE=example_db --env MYSQL_USER=test --env MYSQL_PASSWORD=test ‘mysql:latest’

TestContainers has a method name “withCommand”. You use it to set the command that should be run inside the Docker container which confirms that TestContainers is a wrapper API over Docker.

TestContainers downloads the MySQL, Postgres, Kafka, Redis images and runs in a container. The MySQLContainer will run a MySQL Database in a container and the Testcases can connect to it on the local machine. Once the execution is over the Database will be gone – it just deletes it from the machine. In the Testcases we can start as many container images as we want.

TestContainers supports JUnit 4, JUnit 5 and Spock. If you go to the TestContainers.org website, just visit the QuickStart section that explains how to use it:

TestContainers.org how to start with Test Framework

TestContainers supports almost every Database from MySQL and Postgres to CockroachDB. You can find more info about this on the TestContainers.org website under the Modules section:‌

TestContainers support for Database Modules

‌TestContainers also supports Cloud Modules like GCloud Module and Azure Module as well. If your application is running on Google Cloud, then TestContainers has support for Cloud Spanner, Firestore, Datastore and so on.‌

TestContainers support for GCloud Module

In the article so far, we have discussed only about Databases, but TestContainers supports various other components like Kafka, SOLR, Redis, and more.

How to Use the TestContainers Library

In this article we are going to explore TestContainers with JUnit 5. To implement TestContainers we need to understand a few important TestContainers annotations, methods, and the libraries that we need to implement in our project.

TestContainers libraries

Annotations in TestContainers

Two important annotations are required in our Tests for TestContainers to work: @TestContainers and @Container.

@TestContainer is JUnit-Jupiter extension which automatically starts and stops the containers that are used in the tests. This annotation finds the fields that are marked with @Container and calls the specific Container life-cycle methods. Here, MySQLContainer life-cycle methods will be invoked.‌

MySQLContainer

The MySQLContainer is declared as static because if we declare Container as static then a single container is started and it will be shared across all the test methods.

If it’s an instance variable, then a new container is created for each test method.

TestContainers Library Methods

There are few important methods in TestContainers library that you'll use in the tests. They're good to know before using the library.

• withInitScript: Using ‘withInitScript’ we can execute the .SQL to define the schema, tables, and plus add the data into the database. In short, this method is used to run the .SQL to populate the database.

• withReuse (true): Using “withReuse” method we can enable the reuse of containers. This method works well in conjunction with enabling the “testcontainers.reuse.enable:true” property in the “.testcontainers.properties” file.

• start: we use this to start the container.

• withClasspathResourceMapping: This maps a resource (file or directory) on the classpath to a path inside the container. This will only work if you are running your tests outside a Docker container.

• withCommand: Set the command that should be run inside the Docker container.

• withExposedPorts: Used to set the port that the container listens on.

• withFileSystemBind: Used to map a file / directory from the local filesystem into the container.

TestContainers Use Case

In the example we'll look at now, the application will communicate only with the database and write the integration tests for it using TestContainers. Then we'll extend the use-case by implementing Redis in between.

If the data exists in the Redis cache it will be returned, otherwise it'll dip into the database for saving and retrieval based on the Key.

Use-Case

The service is simple. It has 2 endpoints – the first one is to create a user and the second one is to find a user by email. If the user is found it is returned, otherwise we get a 404. The service class code looks something like this:‌

Service Component

We are going to write tests for this class. You can find the entire codebase here:‌

Test Class

The test class is marked with @TestContainers annotation which starts/stops the container. We use the @Container annotation to call the specific container's life-cycle methods.

Also, the “MySQLContainer” is declared as static because then a single container is started. Then it gets shared across all the test methods (we have already discussed the importance of these annotations).

BeforeAll

Next we need to write a setup method marked with @BeforeAll, where we have enabled the “withReuse” method. This helps us reuse the existing containers. We are using the “withInitScript” method to execute the “.sql” file and then starting the container.‌

Overwriting Properties

‌@DynamicPropertySource helps us override the properties declared in the properties file. We write this method to allow TestContainers to create the URL, username, and password on its own – otherwise we may face errors.

For example on removing username and password we may face an ‘Access denied’ error which may confuse us. So it’s better to allow TestContainer to assign these properties dynamically on its own.

That’s it – we are ready to run the Testcases:

Test Cases

Execute @AfterAll to stop the container, otherwise it may keep running on your local machine if you don't explicitly stop it. ‌

How to Use GenericContainer

‌‌GenericContainer is the most flexible container. It makes it easy to run any container images within GenericContainer.

Now we have Redis in place, all we need to do in our Testcase is to spin up a GenericContainer with the Redis image.

GenericContainer for Redis

Then we start the Generic Redis container in @BeforeAll and stop it with the @AfterAll tear down method.

Starting Containers

Stopping Containers

Wrapping Up

It's extremely easy to use TestContainers in our application to write better tests. The learning curve is not too steep and it has support for various different modules from a variety of databases like Kafka, Redis and others.

Writing tests using TestContainers makes our tests lot more reliable. The only flip side is that the tests are slow compared to H2. This is because H2 is in memory and TestContainers takes time to download the image, run the container, and execute the entire setup we have discussed in this article.

In this article I am going to walk you through building a prototype with Spring Boot. Think of it like building a project for a hackathon or a prototype for your startup in limited time.

In other words, we are not trying to build something perfect – but rather something that works.

If you get stuck in any part of this tutorial or if I have forgotten to mention something, you can check out the GitHub repository I have included in the Conclusion.

Prerequisites

• Foundations of Java and OOP
• Basic knowledge of relational databases (one-to-many, many-to-many, and so on)
• Fundamentals of Spring would be helpful
• Basic level HTML

Also make sure you have the following:

• JDK (Java Development Kit) latest
• IntelliJ IDEA or some other Java IDE

What are we building?

We will build an amenity reservation system where users will log in and reserve a time to use a service such as fitness center, pool, or sauna.

Each amenity will have a certain capacity (number of people that can use the service at the same time) so that people can make use of the amenities safely during the Covid-19 pandemic.

List of Features for the App

We can think of our app as the reservation system for an apartment complex.

• Users should be able to log in.
• We will assume that the accounts of residents are pre-created and there will be no sign-up feature.
• Users should be able to view their reservations.
• Users should be able to create new reservations by selecting the amenity type, date, and time.
• Only logged-in users should be able to see the reservations page and create reservations.
• We should check the capacity and only create new reservations if the current number of reservations does not exceed the capacity.

Technologies We'll Use

We will learn about a lot of useful technologies that will make you more efficient as a Spring Boot developer. I will briefly mention what they are and what they are good for and then we will see them in action.

• Bootify
• Hibernate
• Spring Boot
• Maven
• JPA
• Swagger
• H2 In-Memory Database
• Thymeleaf
• Bootstrap
• Spring Security

Why Spring Boot?

The Spring framework is generally used for enterprise level/large scale jobs. It is not usually the first option that comes to mind for smaller projects – but I will argue that it can be quite fast for prototyping.

It has the following advantages:

• Annotation-based development generates a lot of code for you behind the scenes. And especially with the availability of libraries like Lombok, it has became a lot easier to focus on the business logic.
• It has nice in-memory database support, so that we don't need to create a real database and connect to it. (H2)
• It has a mature ecosystem so you can readily find answers to most questions.
• Almost "no configuration" is required. With the help of Spring Boot, we get rid of ugly XML configurations on the Spring side of things and configuring your application is really easy.
• There's a lot happening behind the scenes. Spring provides so much magic and does so many things to get things going. So you don't usually need to care about that stuff and can just let the framework handle things.
• We have Spring Security. Having one of the most comprehensive, battle-tested security frameworks on your side gives you more confidence in the security of your application. It also takes care of a good share of the hard work for you.

How to Create the Project with Bootify

To create the project, you will use Bootify. It's a freemium service that makes Spring Boot development faster by generating a lot of boilerplate code for you and letting you focus on business logic instead.

Bootify allows us to specify our preferences and automatically imports the dependencies similar to Spring Initializr.

But there is more than that. You can also specify your entities and it will generate the corresponding model and DTO classes. It can even generate the service and controller level code for common CRUD operations.

I believe it is a more convenient tool for API development than it is for MVC apps since it generates REST API code by default. But it will still make our lives easier even with a Spring Boot MVC application that contains views. We will just need to make some adjustments to the generated code.

Let's open the Bootify website and click the "Start Project" button at the top right corner.

You should select:

• Maven as the build type
• Java version: 14
• Tick enable Lombok
• DBMS: H2 database
• Tick add dateCreated/lastUpdated to entities
• Packages: Technical
• Enable OpenAPI/Swagger UI
• Add org.springframework.boot:spring-boot-devtools to further dependencies

After you are done, you should see this:

Now let's specify our entities. Start by clicking the Entities tab on the left menu.

We will have the following entities and relations:

1. Reservation that contains the data related to each reservation such as reservation date, reservation starting time, ending time, and the user who owns this reservation.
2. The User entity that contains our user model and will have relations with Reservation.
3. The Amenity entity to hold the type of Amenity and its capacity (maximum number of reservations for a certain time, for example 2 people can use and reserve the Sauna for the same time).

Let's define our Reservation entity as follows and keep "Add REST endpoints" checked (even though we will modify the output). Then click the Save button.

We will specify the relations later, so the only field that our user entity has is the id field.

We could create an entity for Amenities to store the data of the amenity name and its capacity and then we could reference it from the Reservation. But the relationship between Amenity and Reservation would be one-to-one.

So instead, for the sake of simplicity, we will create an enum called AmenityType and store the AmenityType inside Reservation.

Now let's create a relationship between the User and Reservation entities by clicking the + button next to the Relations menu.

Menu to create relations

It will be a Many-to-one relationship since a user can have many reservations but a reservation must have one and only one user. We will make sure this is the case by checking the required box.

User-Reservation Relation

We click "Save Changes" and we are done. Your final model should look like this:

Now click the download button on the left menu to download the generated project code so we can start working on it. You can see the first commit on the project repository to compare with yours if you have any problems.

After you download the project, open it in an IDE – I'll use IntelliJ IDEA. Your file structure should look like this:

├── amenity-reservation-system.iml
├── mvnw
├── mvnw.cmd
├── pom.xml
├── src
│   └── main
│       ├── java
│       │   └── com
│       │       └── amenity_reservation_system
│       │           ├── AmenityReservationSystemApplication.java
│       │           ├── HomeController.java
│       │           ├── config
│       │           │   ├── DomainConfig.java
│       │           │   ├── JacksonConfig.java
│       │           │   └── RestExceptionHandler.java
│       │           ├── domain
│       │           │   ├── Reservation.java
│       │           │   └── User.java
│       │           ├── model
│       │           │   ├── ErrorResponse.java
│       │           │   ├── FieldError.java
│       │           │   ├── ReservationDTO.java
│       │           │   └── UserDTO.java
│       │           ├── repos
│       │           │   ├── ReservationRepository.java
│       │           │   └── UserRepository.java
│       │           ├── rest
│       │           │   ├── ReservationController.java
│       │           │   └── UserController.java
│       │           └── service
│       │               ├── ReservationService.java
│       │               └── UserService.java
│       └── resources
│           └── application.yml
└── target
    ├── classes
    │   ├── application.yml
    │   └── com
    │       └── amenity_reservation_system
    │           ├── AmenityReservationSystemApplication.class
    │           ├── HomeController.class
    │           ├── config
    │           │   ├── DomainConfig.class
    │           │   ├── JacksonConfig.class
    │           │   └── RestExceptionHandler.class
    │           ├── domain
    │           │   ├── Reservation.class
    │           │   └── User.class
    │           ├── model
    │           │   ├── ErrorResponse.class
    │           │   ├── FieldError.class
    │           │   ├── ReservationDTO.class
    │           │   └── UserDTO.class
    │           ├── repos
    │           │   ├── ReservationRepository.class
    │           │   └── UserRepository.class
    │           ├── rest
    │           │   ├── ReservationController.class
    │           │   └── UserController.class
    │           └── service
    │               ├── ReservationService.class
    │               └── UserService.class
    └── generated-sources
        └── annotations

How to Test and Explore the Generated Code

Let's take our time to experiment with the generated code and understand it layer by layer.

The Repos folder contains the code for the data access layer, namely our repositories. We will use JPA methods to retrieve our data, which are pre-made query methods you can use by defining them inside the repository interface.

Notice that our repository classes extend the JpaRepository interface. This is the interface that allows us to use the mentioned methods.

JPA queries follow a certain convention, and when we create the method that obeys the conventions, it will automatically know what data you want to retrieve, behind the scenes. If you don't yet get it, do not worry, we will see examples.

Example keywords, sample phrases and their corresponding JPQL snippets (queries)

The Model classes present our data model, and which classes will have which fields.

Each model class corresponds to a database table with the same name and the fields in the model class will be columns in the corresponding table.

Notice the annotation @Entity on top of our model classes. This annotation is handled by Hibernate and whenever Hibernate sees @Entity, it will create a table using the name of our class as table name.

If you are wondering, "What is Hibernate anyways?", it is an object-relational-mapping (ORM) tool for Java that allows us to map the POJOs (Plain Old Java Object) to database tables. It can also provide features such as data validation constraints, but we will not go deep into Hibernate in this post since it is a vast topic on its own.

An awesome feature of Hibernate is that it handles all table creation and deletion operations so you don't have to use additional SQL scripts.

We also represent the relationships between objects in model classes. To see an example, take a look at our User class:

    @OneToMany(mappedBy = "user")
    private Set<Reservation> userReservations;

It has a userReservations object that holds a set of references that resembles the reservations of this particular user. In the Reservation class we have the reverse-relation as:

@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "user_id", nullable = false)
private User user;

Having references on both sides makes it possible to access the other side of the relationship (user object to reservation and vice versa).

Controllers will handle the requests that are passed to this controller by the request handler and return the corresponding views, in this case.

The controllers that were generated by Bootify are configured to return JSON responses, and we will modify them in the next section to return our views.

Services will hold the logic of our application. The best practice is to keep controllers thin by keeping the business logic in a separate place, the service classes.

Controllers should not interact with the repositories directly, but instead call the service which will interact with the repository, perform any additional operation, and return the result to the controller.

Let's Try Out the API

Now, let's get to the fun part and try our API to see it on action. Run the Spring application on your favorite IDE. Open your browser and go to this address:

http://localhost:8080/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/

Swagger automatically documents our code and allows you to send requests easily. You should be seeing this:

Let's first create a user by sending a POST request to UserController. We will do that by clicking the last box (the green one) under user-controller list.

Swagger shows us the parameters that this endpoint expects – only the id for now – and also the responses that the API returns.

Click the "Try it out" button at the top right corner. It asks you to enter an id. I know it is nonsense and the code will not even use this id you enter, but we will fix that in the next section (it is just a problem with the generated code).

For the sake of experimenting, enter any number, like 1 for the id, and click the execute button.

The response body contains the id of the created object. We can confirm that it is created on the database by checking the H2 console.

But before doing that, we need to make a minor adjustment to the application.yml file which contains the application settings and configuration. Open your application.yml file and paste in the following code:

spring:
  datasource:
    url: ${JDBC_DATABASE_URL:jdbc:h2:mem:amenity-reservation-system}
    username: ${JDBC_DATABASE_USERNAME:sa}
    password: ${JDBC_DATABASE_PASSWORD:}
  dbcp2:
    max-wait-millis: 30000
    validation-query: "SELECT 1"
    validation-query-timeout: 30
  jpa:
    hibernate:
      ddl-auto: update
    open-in-view: false
    properties:
      hibernate:
        jdbc:
          lob:
            non_contextual_creation: true
        id:
          new_generator_mappings: true
springdoc:
  pathsToMatch: /api/**

Then we should be able to access the H2 console by going to this address:

http://localhost:8080/h2-console/

Here you need to check that the username is "sa" and click the Connect button.

Click the USER table on the left menu and the console will write the select all query for you.

H2 Admin Panel

Let's click the Run button that is above the query.

We can see that the User object is indeed created – great!

We already have a working API at this point and we have not written a single line of code.

How to Adjust the Code for our Use Case

As I mentioned earlier, the generated code does not fully suit our use case and we need to make some adjustments to it.

Let's remove the model folder which contains DTOs and stuff that we will not use. We will show the data inside views instead.

cd src/main/java/com/amenity_reservation_system/ 
rm -rf model

We will have a lot of errors now since the code uses the DTO classes, but we will get rid of most of it after removing the controller classes.

We will delete the controllers because we do not want to expose the functionality of modifying our data anymore. Our users should be able to do that by interacting with our UI, and we will create new controllers to return the view components in the next section.

rm -rf rest

Finally, we need to do some refactoring to our service classes since the DTO classes are not present anymore:

package com.amenity_reservation_system.service;

import com.amenity_reservation_system.domain.User;
import com.amenity_reservation_system.repos.UserRepository;
import java.util.List;
import java.util.stream.Collectors;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
import org.springframework.web.server.ResponseStatusException;


@Service
public class UserService {

    private final UserRepository userRepository;

    public UserService(final UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public List<User> findAll() {
        return userRepository.findAll();
    }

    public User get(final Long id) {
        return userRepository.findById(id)
                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
    }

    public Long create(final User user) {
        return userRepository.save(user).getId();
    }

    public void update(final Long id, final User user) {
        final User existingUser = userRepository.findById(id)
                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));

        userRepository.save(user);
    }

    public void delete(final Long id) {
        userRepository.deleteById(id);
    }
}

We basically removed the DTO-related code from the UserService class and replaced the return types with User. Let's do the same for ReservationService.

package com.amenity_reservation_system.service;

import com.amenity_reservation_system.domain.Reservation;
import com.amenity_reservation_system.domain.User;
import com.amenity_reservation_system.repos.ReservationRepository;
import com.amenity_reservation_system.repos.UserRepository;
import java.util.List;
import java.util.stream.Collectors;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
import org.springframework.web.server.ResponseStatusException;


@Service
public class ReservationService {

    private final ReservationRepository reservationRepository;
    private final UserRepository userRepository;

    public ReservationService(final ReservationRepository reservationRepository,
            final UserRepository userRepository) {
        this.reservationRepository = reservationRepository;
        this.userRepository = userRepository;
    }

    public List<Reservation> findAll() {
        return reservationRepository.findAll();
    }

    public Reservation get(final Long id) {
        return reservationRepository.findById(id)
                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
    }

    public Long create(final Reservation reservation) {
        return reservationRepository.save(reservation).getId();
    }

    public void update(final Long id, final Reservation reservation) {
        final Reservation existingReservation = reservationRepository.findById(id)
                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
        reservationRepository.save(reservation);
    }

    public void delete(final Long id) {
        reservationRepository.deleteById(id);
    }

}

Let's also remove the config classes:

rm -rf config

And rename the domain folder to model. If you are using an IDE, I strongly advise that you use your IDE's rename functionality to rename this folder since it will automatically rename the imports to match the new package name.

mv domain model

Also, make sure that your model classes (User and Reservation) have the right package name after this operation. The first line of these two files should be:

package com.amenity_reservation_system.model;

If it stays as domain package, you may have errors.

At this point, you should be able to compile and run the project without any problems.

How to Create the Controllers and View Files to Show Data

Thymeleaf is a template engine for Spring that allows us to create UIs and display our model data to the users.

We can access the Java objects inside the Thymeleaf template, and we can also use plain old HTML, CSS and JavaScript. If you know about JSPs, this is JSP on steroids.

Let's create some Thymeleaf templates that will not do anything but show the data for now. We will style them in the next section. We will also create the controllers that will return these views.

Before getting started with the Thymeleaf templates, we need to add a Maven dependency for Spring Boot Thymeleaf. Your dependencies should look like this in your pom.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.4</version>
        <relativePath /><!-- lookup parent from repository -->
    </parent>
    <groupId>com</groupId>
    <artifactId>amenity-reservation-system</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>amenity-reservation-system</name>

    <properties>
        <java.version>14</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.5.2</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.20</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

You can just copy and paste the inner content of the dependencies tag. Now let's tell Maven to install the dependencies:

mvn clean install

We are now ready to create our views. Let's create a directory under resources to hold our view template files like this:

cd ../../../resources
mkdir templates

And create a view file:

cd templates
touch index.html

Copy and paste the following snippet into it. This file will be our home page in the future.

<!DOCTYPE HTML>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8"/>
    <title>Amenities Reservation App</title>

    <link th:rel="stylesheet" th:href="@{/webjars/bootstrap/4.0.0-2/css/bootstrap.min.css} "/>
</head>
<body>

<div>
hello world!
</div>

<script th:src="@{/webjars/jquery/3.0.0/jquery.min.js}"></script>
<script th:src="@{/webjars/popper.js/1.12.9-1/umd/popper.min.js}"></script>
<script th:src="@{/webjars/bootstrap/4.0.0-2/js/bootstrap.min.js}"></script>

</body>
</html>

We also need to create a controller that will return us this view so we can see it in the browser.

cd ../java/com/amenity_reservation_system
mkdir controller && cd controller
touch HomeController

Paste this code into the HomeController:

package com.amenity_reservation_system.controller;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;


@Controller
public class HomeController {

    @GetMapping("/")
    public String index(Model model) {

        return "index";
    }
}

Notice how we annotate our method with @Controller instead of @RestController this time. The @RestController annotation implies that the controller will return a REST response whereas a @Controller can return pre-rendered (SSR) views/HTML.

When a request arrives in our application, Spring will automatically run this controller method. Then it will find the index.html file we previously created under the resources and send that file to the client.

Let's confirm that it is working by sending a request to our application. Do not forget to restart first, then send this request:

GET localhost:8080

You should be able to see the Hello World message on the browser.

How to Define Different Types of Amenities

We have the Reservation class but we have not created a way to specify which type of amenity is getting reserved (the pool, sauna, or gym).

There are multiple ways to do this. One of them would be to create an entity called Amenity to store shared data among entities. Then we'd create PoolAmenity, SaunaAmenity, and GymAmenity classes which would then extend the Amenity class.

This is a nice and extendable solution but it feels a bit like overkill for our simple application, since we do not have much data specific to the amenity type. We are only going to have a capacity for each amenity type.

To keep things simple and not to bother ourselves with table inheritance and other complicated stuff, let's just create an enum to indicate the amenity type as a String and let each reservation have one of these.

Let's switch to the model directory from the controller directory and create the enum for AmenityType:

cd ../model
touch AmenityType.java

public enum AmenityType {
    POOL("POOL"), SAUNA("SAUNA"), GYM("GYM");

    private final String name;

    private AmenityType(String value) {
        name = value;
    }

    @Override
    public String toString() {
        return name;
    }
}

In this enum, we define a name variable to hold the name of the enum and create a private constructor to only allow a limited set of types. Notice that the type declarations call the constructor from within the class with their name values.

Now we need to modify the Reservation class to hold a reference to AmenityType:

@Enumerated(EnumType.STRING)
@Column(nullable = false)
private AmenityType amenityType;

We use the @Enumerated annotation to describe how we want to store the enum in our database. We'll also make it not nullable because every Reservation must have an AmenityType.

How to Show a User's Reservations

What is the most crucial feature for our app? Creating reservations and showing a user's reservations.

We do not have a way to authenticate users yet, so we can't really ask the user to login and then show their reservations. But we still want to implement and test the functionality to reserve an amenity and show reservations.

For that purpose, we can ask Spring to put some initial data into our database whenever the application runs. Then we can query that data to test if our queries actually work. We can then proceed to call these services from our Views and add authentication to our application in the next sections.

We will use a CommandLineRunner bean to run the initial code. Whenever Spring Container finds a bean of type CommandLineRunner it will run the code inside it. Before that step, let's add a few methods to our model classes to make object creation easier and less verbose.

Take a look at the model classes' annotations and you should see annotations like @Getter and @Setter. These are Lombok annotations.

Lombok is an annotation processor we can use to make our coding experience better by letting it generate code for us. When we annotate a class with @Getter and @Setter, it generates the getters and setters for each field of this class.

Spring uses getter and setter methods for many trivial operations behind the scenes so these are almost always required. And creating them for every entity easily becomes a hassle without the help of Lombok.

Lombok can do more than that though. We will also add the following annotations to our Reservation and User classes:

@Builder
@NoArgsConstructor
@AllArgsConstructor

With these annotations, Lombok implements the builder creational pattern for this class and also creates 2 constructors: One with no arguments (default constructor) and another one with all arguments. I think it is awesome that we can do so much by adding just a few annotations.

We are now ready to add some initial data. Go to your main class (AmenityReservationSystemApplication.java) and add this method:

package com.amenity_reservation_system;

import com.amenity_reservation_system.model.AmenityType;
import com.amenity_reservation_system.model.Reservation;
import com.amenity_reservation_system.model.User;
import com.amenity_reservation_system.repos.ReservationRepository;
import com.amenity_reservation_system.repos.UserRepository;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.time.LocalDate;
import java.time.LocalTime;
import java.time.ZoneId;
import java.util.Date;


@SpringBootApplication
public class AmenityReservationSystemApplication {

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

    @Bean
    public CommandLineRunner loadData(UserRepository userRepository,
                                      ReservationRepository reservationRepository) {
        return (args) -> {
            User user = userRepository.save(new User());
            DateFormat dateFormat = new SimpleDateFormat("dd/MM/yyyy HH:mm:ss");
            Date date = new Date();
            LocalDate localDate = date.toInstant().atZone(ZoneId.systemDefault()).toLocalDate();
            Reservation reservation = Reservation.builder()
                    .reservationDate(localDate)
                    .startTime(LocalTime.of(12, 00))
                    .endTime(LocalTime.of(13, 00))
                    .user(user)
                    .amenityType(AmenityType.POOL)
                    .build();

            reservationRepository.save(reservation);
        };
    }
}

If you get an error about saving operations such as "Inferred type 'S' for parameter ... does not match", it's because we renamed the domain directory to model. Go to the repository classes and fix the paths of imports to model.User and model.Reservation.

Notice how we used the builder pattern to create the reservation object easily. When the object creation gets complex and a constructor requires so many parameters, it's easy to forget the order of parameters or just mess up the order.

Without the builder pattern, we would either need to call a constructor with so many parameters or call the default constructor and write #properties code to call the setters.

After you are done, run your application again to insert the initial data and connect to H2 console as we learned before to confirm that our date is indeed inserted. If you do not have any errors, you should be able to see that the user and the reservation are inserted successfully.

We have inserted a reservation to be able to test the functionality to list the reservations but our views currently do not have a way to show the reservations and add reservations. We need to create the UI for that.

We do not have an authentication or sign-up mechanism yet, so act like the user with ID 10001 is logged in. Later we will improve on that by dynamically checking who is logged in and showing a different page if the user is not logged in.

How to Create Views with Thymeleaf

Let's get started by creating a simple home page and a navbar for ourselves. We will use Thymeleaf fragments for the navbar code.

Thymeleaf fragments allow us to create reusable component-like structures similar to React/Vue components if you are familiar with them. Let's create a folder for our fragments under templates and call it fragments.

mkdir fragments
touch nav.html

We will put our navbar inside nav.html file. Copy and paste the following code:

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<body>
<nav th:fragment="nav" class="navbar navbar-expand navbar-dark bg-primary">
    <div class="navbar-nav w-100">
        <a class="navbar-brand text-color" href="/">Amenities Reservation System</a>
    </div>
</nav>
</body>
</html>

It is not doing much in its current state, but we may add a login button or some links in the future.

Now let's create a simple home page that will serve the users that are not logged in. We will have our navbar fragment on top and have a login button to ask the user to log in before using the app.

<!DOCTYPE HTML>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8"/>
    <title>Amenities Reservation App</title>

    <link th:rel="stylesheet" th:href="@{/webjars/bootstrap/4.0.0-2/css/bootstrap.min.css} "/>
</head>
<body>

<div>
    <div th:insert="fragments/nav :: nav"></div>
    <div class="text-light" style="background-image: url('https://source.unsplash.com/1920x1080/?nature');
                                   position: absolute;
                                   left: 0;
                                   top: 0;
                                   opacity: 0.6;
                                   z-index: -1;
                                   min-height: 100vh;
                                   min-width: 100vw;">
    </div>

    <div class="container" style="padding-top: 20vh; display: flex; flex-direction: column; align-items: center;">
        <h1 class="display-3">Reservation management made easy.</h1>
        <p class="lead">Lorem, ipsum dolor sit amet consectetur adipisicing elit.
            Numquam in quia natus magnam ducimus quas molestias velit vero maiores.
            Eaque sunt laudantium voluptas. Fugiat molestiae ipsa delectus iusto vel quod.</p>
        <a href="/reservations" class="btn btn-success btn-lg my-2">Reserve an Amenity</a>
    </div>
</div>

<script th:src="@{/webjars/jquery/3.0.0/jquery.min.js}"></script>
<script th:src="@{/webjars/popper.js/1.12.9-1/umd/popper.min.js}"></script>
<script th:src="@{/webjars/bootstrap/4.0.0-2/js/bootstrap.min.js}"></script>

</body>
</html>

It should look like this:

We will create another page to show if the user is already logged in. To keep it simple we will also treat it as a home page, and if the user is logged in, they will be able to see their reservations on the home page.

It is also good in terms of practicality for the user since it decreases the steps they need to take to view their reservations.

We will now create this page as another endpoint. But after adding the login to our application we will show this previous page if the user is not logged in and the next page if they are logged in, dynamically.

Before we start working on our new page, let's add another mapping to HomeController that will return our new page. We will later merge these two controllers:

package com.amenity_reservation_system;

import com.amenity_reservation_system.domain.User;
import com.amenity_reservation_system.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;


@Controller
public class HomeController {

    final UserService userService;

    public HomeController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/")
    public String index(Model model) {
        return "index";
    }

    @GetMapping("/reservations")
    public String reservations(Model model) {
        User user = userService.get(10000L);
        model.addAttribute("user", user);

        return "reservations";
    }
}

If a request is received at "/reservations", this code will call our userService and ask for the user with id 10000L. Then it will add this user to the Model.

View will access this model and present the information about this user's reservations. We have also autowired the user service to use it.

Navigate to the templates folder if you are not already there and create another file called "reservations.html":

touch reservations.html

Copy and paste the following code:

<!DOCTYPE HTML>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8"/>
    <title>Reservations</title>

    <link th:rel="stylesheet" th:href="@{/webjars/bootstrap/4.0.0-2/css/bootstrap.min.css} "/>
</head>
<body>

<div>
    <div th:insert="fragments/nav :: nav"></div>
    <div class="container" style="padding-top: 10vh; display: flex; flex-direction: column; align-items: center;">
        <h3>Welcome <span th:text=" ${user.getFullName()}"></span></h3>
        <br>
        <table class="table">
            <thead>
                <tr>
                    <th scope="col">Amenity</th>
                    <th scope="col">Date</th>
                    <th scope="col">Start Time</th>
                    <th scope="col">End Time</th>
                </tr>
            </thead>
            <tbody>
                <tr th:each="reservation : ${user.getReservations()}">
                    <td th:text="${reservation.getAmenityType()}"></td>
                    <td th:text="${reservation.getReservationDate()}"></td>
                    <td th:text="${reservation.getStartTime()}"></td>
                    <td th:text="${reservation.getEndTime()}"></td>
                </tr>
            </tbody>
        </table>
    </div>
</div>

<script th:src="@{/webjars/jquery/3.0.0/jquery.min.js}"></script>
<script th:src="@{/webjars/popper.js/1.12.9-1/umd/popper.min.js}"></script>
<script th:src="@{/webjars/bootstrap/4.0.0-2/js/bootstrap.min.js}"></script>

</body>
</html>

In this Thymeleaf template, we import Bootstrap and Thymeleaf as before and we access the user variable that was added to the model in our controller by using the ${} syntax.

To access data, Thymeleaf uses the getter methods of the object and we can print that information by using the th:text attribute. Thymeleaf also supports loops. In the tbody we have a th:each loop, which we can think of as a foreach loop over a user's reservations. So we loop over the reservations and display them in a table.

You may have an error that says something like "Could not initialize proxy, ... lazy loading". This is caused by the view trying to access the reservations object while it does not yet exist. To get rid of that we can modify the following lines in User.java:

    @OneToMany(mappedBy = "user", fetch = FetchType.EAGER)
    private Set<Reservation> reservations = new HashSet<>();

We add a statement to tell Java to fetch this object eagerly.

Now you should be able to view the reservations page:

How to Create a Reservation

We also need a way to create new reservations, so let's build that mechanism for our pre-created user like we did with showing the reservations. Then we can alter it to show the reservations of the currently logged-in user.

Before going forward, we need to update the date formats in our Reservation.java file to avoid any format mismatch problems. Make sure your formats for these variables are the same:

    @DateTimeFormat(pattern = "yyyy-MM-dd")
    @Column(nullable = false)
    private LocalDate reservationDate;

    @DateTimeFormat(pattern = "HH:mm")
    @Column
    private LocalTime startTime;

    @DateTimeFormat(pattern = "HH:mm")
    @Column
    private LocalTime endTime;

In the previous section, we created our reservations controller. Now we need to modify it a little bit to add another attribute to the model.

We learned how we can access the objects that are added to the model by using the ${} syntax. Now we are going to do something similar:

@GetMapping("/reservations")
    public String reservations(Model model, HttpSession session) {
        User user = userService.get(10000L);
        session.setAttribute("user", user);
        Reservation reservation = new Reservation();
        model.addAttribute("reservation", reservation);

        return "reservations";
    }

We are updating our reservations controller to move the user object to the session because we want that to be accessible from another controller method and not only from a template.

Think of it like this: once a user is logged in, this user's account will be responsible for every action that's taken after that point. You can think of Session as a global variable that is accessible from everywhere.

We also create a Reservation object and add it to the model. Thymeleaf will access this newly created object in our view template using this model and it will call the setters to set its fields.

Now let's create the view for creating the reservation. We are going to use Bootstrap Modal to display a form modal after a button is clicked.

We can first handle the code to call the modal we are going to create in the next step, move to the reservations.html file, and add this snippet after the table tag we added before:

<button
  type="button"
  class="btn btn-primary"
  data-toggle="modal"
  data-target="#createReservationModal"
>
  Create Reservation
</button>

<!-- Modal -->
<div
  th:insert="fragments/modal :: modal"
  th:with="reservation=${reservation}"
></div>

This button will trigger our modal. In the div, we insert this modal that we are going to create and we use the th:with tag to pass the reservation object that was put in the model in our controller. If we do not do this, the fragment will not know about the reservation object.

We also need to change how we access the user to print their name because we no longer store it in the modal but in session:

<h3>Welcome <span th:text=" ${session.user.getFullName()}"></span></h3>

So your final reservations.html file should be looking like this:

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
  <head>
    <meta charset="UTF-8" />
    <title>Reservations</title>

    <link
      th:rel="stylesheet"
      th:href="@{/webjars/bootstrap/4.0.0-2/css/bootstrap.min.css} "
    />
  </head>
  <body>
    <div>
      <div th:insert="fragments/nav :: nav"></div>
      <div
        class="container"
        style="padding-top: 10vh; display: flex; flex-direction: column; align-items: center;"
      >
        <h3>Welcome <span th:text=" ${session.user.getFullName()}"></span></h3>
        <br />
        <table class="table">
          <thead>
            <tr>
              <th scope="col">Amenity</th>
              <th scope="col">Date</th>
              <th scope="col">Start Time</th>
              <th scope="col">End Time</th>
            </tr>
          </thead>
          <tbody>
            <tr th:each="reservation : ${session.user.getReservations()}">
              <td th:text="${reservation.getAmenityType()}"></td>
              <td th:text="${reservation.getReservationDate()}"></td>
              <td th:text="${reservation.getStartTime()}"></td>
              <td th:text="${reservation.getEndTime()}"></td>
            </tr>
          </tbody>
        </table>

        <button
          type="button"
          class="btn btn-primary"
          data-toggle="modal"
          data-target="#createReservationModal"
        >
          Create Reservation
        </button>

        <!-- Modal -->
        <div
          th:insert="fragments/modal :: modal"
          th:with="reservation=${reservation}"
        ></div>
      </div>
    </div>

    <script th:src="@{/webjars/jquery/3.0.0/jquery.min.js}"></script>
    <script th:src="@{/webjars/popper.js/1.12.9-1/umd/popper.min.js}"></script>
    <script th:src="@{/webjars/bootstrap/4.0.0-2/js/bootstrap.min.js}"></script>
  </body>
</html>

We are now ready to create the modal fragment. We can create a fragment for the modal just like we did with the nav:

pwd
/src/main/resources
cd templates/fragments
touch modal.html

And paste in the following template code:

<html lang="en" xmlns:th="http://www.thymeleaf.org">
  <body>
    <div
      class="modal fade"
      th:fragment="modal"
      id="createReservationModal"
      tabindex="-1"
      role="dialog"
      aria-labelledby="createReservationModalTitle"
      aria-hidden="true"
    >
      <div class="modal-dialog" role="document">
        <div class="modal-content">
          <div class="modal-header">
            <h5 class="modal-title" id="createReservationModalTitle">
              Create Reservation
            </h5>
            <button
              type="button"
              class="close"
              data-dismiss="modal"
              aria-label="Close"
            >
              <span aria-hidden="true">&times;</span>
            </button>
          </div>

          <div class="modal-body">
            <form
              action="#"
              th:action="@{/reservations-submit}"
              th:object="${reservation}"
              method="post"
            >
              <div class="form-group row">
                <label for="type-select" class="col-2 col-form-label"
                  >Amenity</label
                >
                <div class="col-10">
                  <select
                    class="form-control"
                    id="type-select"
                    th:field="*{amenityType}"
                  >
                    <option value="POOL">POOL</option>
                    <option value="SAUNA">SAUNA</option>
                    <option value="GYM">GYM</option>
                  </select>
                </div>
              </div>
              <div class="form-group row">
                <label for="start-date" class="col-2 col-form-label"
                  >Date</label
                >
                <div class="col-10">
                  <input
                    class="form-control"
                    type="date"
                    id="start-date"
                    name="trip-start"
                    th:field="*{reservationDate}"
                    value="2018-07-22"
                    min="2021-05-01"
                    max="2021-12-31"
                  />
                </div>
              </div>
              <div class="form-group row">
                <label for="start-time" class="col-2 col-form-label"
                  >From</label
                >
                <div class="col-10">
                  <input
                    class="form-control"
                    type="time"
                    id="start-time"
                    name="time"
                    th:field="*{startTime}"
                    min="08:00"
                    max="19:30"
                    required
                  />
                </div>
              </div>
              <div class="form-group row">
                <label for="end-time" class="col-2 col-form-label">To</label>
                <div class="col-10">
                  <input
                    class="form-control"
                    type="time"
                    id="end-time"
                    name="time"
                    th:field="*{endTime}"
                    min="08:30"
                    max="20:00"
                    required
                  />
                  <small>Amenities are available from 8 am to 8 pm</small>
                </div>
              </div>
              <div class="modal-footer">
                <button
                  type="button"
                  class="btn btn-secondary"
                  data-dismiss="modal"
                >
                  Close
                </button>
                <button type="submit" class="btn btn-primary" value="Submit">
                  Save changes
                </button>
              </div>
            </form>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>

There are a few important points that you need to take note of here.

Notice how we access the reservation object in the form tag:

<form
  action="#"
  th:action="@{/reservations-submit}"
  th:object="${reservation}"
  method="post"
></form>

The th:object tag associates this form with the reservation object that we have created before. th:action determines where this object will be sent when the form is submitted, and our submission method will be POST. We will create this controller with the mapping to /reservations-submit after this step.

We use the th:field tag to bind the inputs to our reservation object's fields. Thymeleaf calls the setters of the reservation object whenever that input field's value changes.

Now let's create the controller that will receive this form. Go to HomeController and add the following method:

@PostMapping("/reservations-submit")
    public String reservationsSubmit(@ModelAttribute Reservation reservation,
                                     @SessionAttribute("user") User user) {

        // Save to DB after updating
        assert user != null;
        reservation.setUser(user);
        reservationService.create(reservation);
        Set<Reservation> userReservations = user.getReservations();
        userReservations.add(reservation);
        user.setReservations(userReservations);
        userService.update(user.getId(), user);
        return "redirect:/reservations";
    }

And also add the ReservationService to our dependencies:

    final UserService userService;
    final ReservationService reservationService;

    public HomeController(UserService userService, ReservationService reservationService) {
        this.userService = userService;
        this.reservationService = reservationService;
    }

After our modal fragment posts the reservation object to this controller, that object will be bound with the @ModelAttribute annotation. We also need the user so we use @SessionAttribute to get a reference to it.

The fields of the reservation object should be all set by the form. Now we just need to save it to the database.

We do that by calling the create method. Then we add the new Reservation to the user's list of reservations and update the user to reflect these changes. We then redirect the user to the reservations page to show the updated reservations list.

Your reservations page should look like this:

And when you click the button, the create reservation modal should pop up.

How to Add Authentication and Authorization to the App

We will use Spring Security to add authentication and authorization to our application. We want to make sure that nobody can see each other's reservations and that the users must be logged in to create reservations.

If you want to learn more about it, I wrote an article that provides an overview of Spring Security.

We will keep it simple and mostly use the defaults because this is a difficult topic on its own. If you want to learn how to properly set up Spring Security Auth, you can check out my article on that.

We need to add "Spring Security" and "Thymeleaf Spring Security" to our dependencies, so open your pom.xml and add the following to your list of dependencies:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

<dependency>
    <groupId>org.thymeleaf.extras</groupId>
    <artifactId>thymeleaf-extras-springsecurity5</artifactId>
    <version>3.0.4.RELEASE</version>
</dependency>

Now, by default, Spring Security makes all the endpoints protected, so we need to configure it to allow viewing the home page.

Let's create a config folder to contain our WebSecurityConfig file. Assuming you are on the root folder:

cd /src/main/java/com/amenity_reservation_system
mkdir config && cd config
touch WebSecurityConfig.java

This should be the content of your config file:

package com.amenity_reservation_system.config;

import com.amenity_reservation_system.service.UserDetailsServiceImpl;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;

@Configuration
@EnableWebSecurity
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {

    private final UserDetailsServiceImpl userDetailsService;

    private final BCryptPasswordEncoder bCryptPasswordEncoder;

    public WebSecurityConfig(UserDetailsServiceImpl userDetailsService, BCryptPasswordEncoder bCryptPasswordEncoder) {
        this.userDetailsService = userDetailsService;
        this.bCryptPasswordEncoder = bCryptPasswordEncoder;
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .authorizeRequests()
                .antMatchers("/", "/webjars/**").permitAll()
                .anyRequest().authenticated()
                .and()
                .formLogin()
                .permitAll()
                .and()
                .logout()
                .permitAll()
                .logoutSuccessUrl("/");
    }

    public void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.userDetailsService(userDetailsService).passwordEncoder(bCryptPasswordEncoder);
    }

}

I will not go into the details, but here's a summary of what happened here:

• we configured Spring Security to permit all requests made to the home page ("/")
• we configured our styles ("/webjars/**")
• we asked it to provide us with login and logout forms
• and we asked it to permit the requests to them as well and redirect to the home page after logout is successful

Isn't it amazing what you can achieve with just a few statements?

We also configured our AuthenticationManagerBuilder to use bCryptPasswordEncoder and userDetailsService. But wait, we don't have neither of them yet, and your IDE may already be complaining about that. So let's create them.

Before we go on, it may be a good idea to add username and passwordHash fields to our User class. We'll use them to authenticate the user instead of using their full name. Then we'll add it to the constructor.

package com.amenity_reservation_system.model;

import java.time.OffsetDateTime;
import java.util.HashSet;
import java.util.Set;
import javax.persistence.*;

import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;


@Entity
@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
public class User {

    @Id
    @Column(nullable = false, updatable = false)
    @SequenceGenerator(
            name = "primary_sequence",
            sequenceName = "primary_sequence",
            allocationSize = 1,
            initialValue = 10000
    )
    @GeneratedValue(
            strategy = GenerationType.SEQUENCE,
            generator = "primary_sequence"
    )
    private Long id;

    @Column(nullable = false, unique = true)
    private String fullName;

    @Column(nullable = false, unique = true)
    private String username;

    @Column
    private String passwordHash;

    @OneToMany(mappedBy = "user", fetch = FetchType.EAGER)
    private Set<Reservation> reservations = new HashSet<>();

    @Column(nullable = false, updatable = false)
    private OffsetDateTime dateCreated;

    @Column(nullable = false)
    private OffsetDateTime lastUpdated;

    @PrePersist
    public void prePersist() {
        dateCreated = OffsetDateTime.now();
        lastUpdated = dateCreated;
    }

    @PreUpdate
    public void preUpdate() {
        lastUpdated = OffsetDateTime.now();
    }

    public User(String fullName, String username, String passwordHash) {
        this.fullName = fullName;
        this.username = username;
        this.passwordHash = passwordHash;
    }
}

Create a file called UserDetailsServiceImpl under the services folder:

cd service
touch UserDetailsServiceImpl.java

package com.amenity_reservation_system.service;

import com.amenity_reservation_system.model.User;
import com.amenity_reservation_system.repos.UserRepository;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;

@Service
public class UserDetailsServiceImpl implements UserDetailsService {

    private UserRepository userRepository;

    public UserDetailsServiceImpl(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        final User user = userRepository.findUserByUsername(username);

        if (user == null) {
            throw new UsernameNotFoundException(username);
        }

        UserDetails userDetails = org.springframework.security.core.userdetails.User.withUsername(
                user.getUsername()).password(user.getPwHash()).roles("USER").build();

        return userDetails;
    }
}

This basically tells Spring Security that we want to use the User entity we created earlier by getting the User object from our database and using the JPA method on our repository. But again, we do not have the findUserByUsername method on our UserRepository. You can try fixing this on your own as a challenge, it is really simple.

Remember, we do not need to write queries. It is sufficient to provide the signature and let JPA do the work.

package com.amenity_reservation_system.repos;

import com.amenity_reservation_system.model.User;
import org.springframework.data.jpa.repository.JpaRepository;


public interface UserRepository extends JpaRepository<User, Long> {

    User findUserByUsername(String username);
}

We also need a BCryptPasswordEncoder bean to satisfy that dependency in WebSecurityConfig and to make it work. Let's modify our main class to add a bean and change the constructor parameters to give our predefined User a username.

package com.amenity_reservation_system;

import com.amenity_reservation_system.model.AmenityType;
import com.amenity_reservation_system.model.Reservation;
import com.amenity_reservation_system.model.User;
import com.amenity_reservation_system.repos.ReservationRepository;
import com.amenity_reservation_system.repos.UserRepository;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;

import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.time.LocalDate;
import java.time.LocalTime;
import java.time.ZoneId;
import java.util.Date;


@SpringBootApplication
public class AmenityReservationSystemApplication {

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


    @Bean
    public CommandLineRunner loadData(UserRepository userRepository,
                                      ReservationRepository reservationRepository) {
    return (args) -> {
      User user =
          userRepository.save(
              new User("Yigit Kemal Erinc",
                      "yigiterinc",
                      bCryptPasswordEncoder().encode("12345")));
      DateFormat dateFormat = new SimpleDateFormat("dd/MM/yyyy HH:mm:ss");
      Date date = new Date();
      LocalDate localDate = date.toInstant().atZone(ZoneId.systemDefault()).toLocalDate();
      Reservation reservation =
          Reservation.builder()
              .reservationDate(localDate)
              .startTime(LocalTime.of(12, 00))
              .endTime(LocalTime.of(13, 00))
              .user(user)
              .amenityType(AmenityType.POOL)
              .build();

      reservationRepository.save(reservation);
    };
    }

    @Bean
    public BCryptPasswordEncoder bCryptPasswordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

Your application should be ready to compile now and it should already be redirecting you to the login page if you send a request to "/reservations".

It would be nice to have buttons for log-in and log-out on the navbar, and we want to show login if user is not authenticated and logout otherwise. We can do it this way in nav.html:

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org" xmlns:sec="http://www.w3.org/1999/xhtml">
<body>
<nav th:fragment="nav" class="navbar navbar-expand navbar-dark bg-primary">
    <div class="navbar-nav w-100">
        <a class="navbar-brand text-color" href="/">Amenities Reservation System</a>
    </div>
        <a sec:authorize="isAnonymous()"
           class="navbar-brand text-color" th:href="@{/login}">Log in</a>
        <a sec:authorize="isAuthenticated()"
               class="navbar-brand text-color" th:href="@{/logout}">Log out</a>
</nav>
</body>
</html>

The log in link should now be visible on the navbar.

Home page when you are not logged in

How to Show a Logged-in User's Reservations

Our Reservations page is currently displaying the reservations of one hard-coded user and not the reservations of the logged-in user.

    @GetMapping("/reservations")
    public String reservations(Model model, HttpSession session) {
        User user = userService.get(10000L);
        session.setAttribute("user", user);
        Reservation reservation = new Reservation();
        model.addAttribute("reservation", reservation);

        return "reservations";
    }

We need to show the reservations of the currently logged-in user. To achieve that, we should use some Spring Security.

Go to the HomeController (I know, that name is a bit problematic right now) class and change it with the following code:

@GetMapping("/reservations")
    public String reservations(Model model, HttpSession session) {
        UserDetails principal = (UserDetails) SecurityContextHolder.getContext().getAuthentication().getPrincipal();
        String name = principal.getUsername();
        User user = userService.getUserByUsername(name);

        // This should always be the case 
        if (user != null) {
            session.setAttribute("user", user);

            // Empty reservation object in case the user creates a new reservation
            Reservation reservation = new Reservation();
            model.addAttribute("reservation", reservation);

            return "reservations";
        }

        return "index";    
        }

Since we have added Spring Security to the project, it automatically creates the Authentication object behind the scenes – we are getting that from SecurityContextHolder.

We are grabbing the UserDetails object which stores the info related to user. Then we check if the user object is null. This should always be the case since reservations is a protected endpoint and the user must be logged in to see that page – but it is always good to make sure everything is as expected.

Then we call the UserService class to get the User object which has this username – but we have not added the getUserByUsername method yet. So let's move to the UserService and add this simple method.

    public User getUserByUsername(String username) {
        return userRepository.findUserByUsername(username);
    }

Now you should be able to see the logged-in user's reservations. You can try that by adding another user and creating reservations for that user as well.

How to Check the Capacity

We currently don't have a mechanism to store the Capacity of each amenity type. We need to store those somehow and also check that there is enough capacity before we approve a reservation.

For that purpose, let's create a class called Capacity under our model folder.

package com.amenity_reservation_system.model;

import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

import javax.persistence.*;

@Entity
@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
public class Capacity {

    @Id
    @Column(nullable = false, updatable = false)
    @SequenceGenerator(
            name = "primary_sequence",
            sequenceName = "primary_sequence",
            allocationSize = 1,
            initialValue = 10000
    )
    @GeneratedValue(
            strategy = GenerationType.SEQUENCE,
            generator = "primary_sequence"
    )
    private Long id;

    @Column(nullable = false, unique = true)
    @Enumerated(EnumType.STRING)
    private AmenityType amenityType;

    @Column(nullable = false)
    private int capacity;

    public Capacity(AmenityType amenityType, int capacity) {
        this.amenityType = amenityType;
        this.capacity = capacity;
    }
}

This is the entity that will represent our logical construct to be stored in our database. It is basically a map entry with an AmenityType and its corresponding capacity.

We also need a repository to store the Capacity entries, so let's create the CapacityRepository under the repos folder.

package com.amenity_reservation_system.repos;

import com.amenity_reservation_system.model.Capacity;
import org.springframework.data.jpa.repository.JpaRepository;

public interface CapacityRepository extends JpaRepository<Capacity, Long> {
}

We need to populate this new table with the initial capacities. We could read the initial capacities from a config file or something, but let's keep it simple and hardcode it using loadData in our main method.

package com.amenity_reservation_system;

import com.amenity_reservation_system.model.AmenityType;
import com.amenity_reservation_system.model.Capacity;
import com.amenity_reservation_system.model.Reservation;
import com.amenity_reservation_system.model.User;
import com.amenity_reservation_system.repos.CapacityRepository;
import com.amenity_reservation_system.repos.ReservationRepository;
import com.amenity_reservation_system.repos.UserRepository;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;

import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.time.LocalDate;
import java.time.LocalTime;
import java.time.ZoneId;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

@SpringBootApplication
public class AmenityReservationSystemApplication {

  private Map<AmenityType, Integer> initialCapacities =
      new HashMap<>() {
        {
          put(AmenityType.GYM, 20);
          put(AmenityType.POOL, 4);
          put(AmenityType.SAUNA, 1);
        }
      };

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

  @Bean
  public CommandLineRunner loadData(
      UserRepository userRepository,
      CapacityRepository capacityRepository) {
    return (args) -> {
      userRepository.save(
          new User("Yigit Kemal Erinc", "yigiterinc", bCryptPasswordEncoder().encode("12345")));

      for (AmenityType amenityType : initialCapacities.keySet()) {
        capacityRepository.save(new Capacity(amenityType, initialCapacities.get(amenityType)));
      }
    };
  }

  @Bean
  public BCryptPasswordEncoder bCryptPasswordEncoder() {
    return new BCryptPasswordEncoder();
  }
}

I just added the capacities inside the initialCapacities map then saved those to the CapacityRepository inside the loadData method.

We can now check if the number of reservations in the requested time exceeds the capacity and reject the reservation request if it does.

So here is the logic: We need to fetch the number of reservations that are on the same day and overlap with this current request. Then we need to fetch the capacity for this amenity type, and if the capacity is exceeded we can throw an exception.

Therefore we need a query to get the number of potentially overlapping reservations. It is not the easiest query to write, but JPA is very convenient and we can access that query inside our ReservationRepository without needing to write any SQL or HQL (Hibernate Query Language).

I encourage you to try it yourself before moving forward, because this is like the sole reason why I have included this concept of capacity in this tutorial (to show an example of a more advanced JPA query).

So this is how the ReservationService's create method looks. You need to replace the 0 with a call to reservationRepository to get the number of overlapping reservations.

If the current number of overlapping reservations is equal to the capacity, it means that the next one will exceed it so we throw the exception.

public Long create(final Reservation reservation) {
        int capacity = capacityRepository.findByAmenityType(reservation.getAmenityType()).getCapacity();
        int overlappingReservations = 0; // TODO

        if (overlappingReservations >= capacity) {
            // Throw a custom exception
        }

        return reservationRepository.save(reservation).getId();
    }

To find the overlapping reservations there are a few conditions we need to check:

First of all, the reservation date should be the same as the date in the request.

1. Start time can be before the startTime of a new request. In that case, the end time should be later than our request, in order to overlap. (startTimeBeforeAndEndTimeAfter)
2. Or, endTime can be after but the startTime can actually be between the startTime and endTime of the request. (endTimeAfterOrStartTimeBetween)

So our final query should return all reservations which match any of these 2 possibilities.

We can express it like this:

List<Reservation> findReservationsByReservationDateAndStartTimeBeforeAndEndTimeAfterOrStartTimeBetween
            (LocalDate reservationDate, LocalTime startTime, LocalTime endTime, LocalTime betweenStart, LocalTime betweenEnd);

And the final create method looks like this:

 public Long create(final Reservation reservation) {
        int capacity = capacityRepository.findByAmenityType(reservation.getAmenityType()).getCapacity();
        int overlappingReservations = reservationRepository
                .findReservationsByReservationDateAndStartTimeBeforeAndEndTimeAfterOrStartTimeBetween(
                        reservation.getReservationDate(),
                        reservation.getStartTime(), reservation.getEndTime(),
                        reservation.getStartTime(), reservation.getEndTime()).size();

        if (overlappingReservations >= capacity) {
            throw new CapacityFullException("This amenity's capacity is full at desired time");
        }

        return reservationRepository.save(reservation).getId();
    }

You don't need to worry about the custom exception, but if you are interested in that, here is the code:

package com.amenity_reservation_system.exception;

public class CapacityFullException extends RuntimeException {
    public CapacityFullException(String message) {
        super(message);
    }
}

We should normally show an error modal if the capacity is exceeded but I will skip that to avoid repetitive UI stuff. You can try that as a challenge if you wish.

Conclusion

In this tutorial, we have learned about so many technologies that make development with Spring Boot easier and faster.

I believe many people underestimate the framework in terms of development speed and the quality of the resulting work.

Assuming you are fluent with the technology, I would argue that Spring Boot is not any slower (in development) than any other backend framework if you do everything in the modern fashion.

You can find the whole code in this repository:

https://github.com/yigiterinc/amenity-reservation-system.git

If you are interested in reading more content like this, feel free to subscribe to my blog at https://erinc.io to get notified about my new posts.

In this article, I would like to show you how to generate Excel reports in the .xls and .xlsx formats (also known as Open XML) in a Spring Boot REST API with Apache POI and Kotlin.

After finishing this guide, you will have a fundamental understanding of how to create custom cells formats, styles, and fonts. In the end, I will show you how to create Spring Boot REST endpoints so you can easily download generated files.

To better visualize what we'll learn, check out the preview of the resulting file:

Step 1: Add the Necessary Imports

As the first step, let's create a Spring Boot project (I highly recommend using the Spring Initializr page) and add the following imports:

implementation("org.springframework.boot:spring-boot-starter-web")
implementation("org.apache.poi:poi:4.1.2")
implementation("org.apache.poi:poi-ooxml:4.1.2")

Let me explain the purpose of each library:

• The Spring Boot Starter Web is necessary to create the REST API in our application.
• The Apache POI is a complex Java library for working with Excel files. If we would like to work only with the .xls format, then the poi import would be enough. In our case, we would like to add the support for the .xlsx format, so the poi-ooxml component is necessary as well.

Step 2: Create the Models

As the next step, let's create an enum class called CustomCellStyle with 4 constants:

enum class CustomCellStyle {
    GREY_CENTERED_BOLD_ARIAL_WITH_BORDER,
    RIGHT_ALIGNED,
    RED_BOLD_ARIAL_WITH_BORDER,
    RIGHT_ALIGNED_DATE_FORMAT
}

Although the purpose of this enum class might seem a bit enigmatic at the moment, it will all become clear in the next sections.

Step 3: Prepare Cells Styles

The Apache POI library comes with the CellStyle interface, which we can use to define custom styling and formatting within rows, columns, and cells.

Let's create a StylesGenerator component, which will be responsible for preparing a map containing our custom styles:

@Component
class StylesGenerator {

    fun prepareStyles(wb: Workbook): Map<CustomCellStyle, CellStyle> {
        val boldArial = createBoldArialFont(wb)
        val redBoldArial = createRedBoldArialFont(wb)

        val rightAlignedStyle = createRightAlignedStyle(wb)
        val greyCenteredBoldArialWithBorderStyle =
            createGreyCenteredBoldArialWithBorderStyle(wb, boldArial)
        val redBoldArialWithBorderStyle =
            createRedBoldArialWithBorderStyle(wb, redBoldArial)
        val rightAlignedDateFormatStyle =
            createRightAlignedDateFormatStyle(wb)

        return mapOf(
            CustomCellStyle.RIGHT_ALIGNED to rightAlignedStyle,
            CustomCellStyle.GREY_CENTERED_BOLD_ARIAL_WITH_BORDER to greyCenteredBoldArialWithBorderStyle,
            CustomCellStyle.RED_BOLD_ARIAL_WITH_BORDER to redBoldArialWithBorderStyle,
            CustomCellStyle.RIGHT_ALIGNED_DATE_FORMAT to rightAlignedDateFormatStyle
        )
    }
}

As you can see, with this approach, we create each style once and put it inside a map so that we will be able to refer to it later.

There are plenty of design techniques which we could use here, but I believe using a map and enum constants is one of the best ways to keep the code cleaner and easier to modify.

With that being said, let's add some missing functions inside the generator class. Let's start with custom fonts first:

private fun createBoldArialFont(wb: Workbook): Font {
    val font = wb.createFont()
    font.fontName = "Arial"
    font.bold = true
    return font
}

The createBoldArialFont function creates a new bold Arial Font instance, which we will use later.

Similarly, let's implement a createRedBoldArialFont function and set the font color to red:

private fun createRedBoldArialFont(wb: Workbook): Font {
    val font = wb.createFont()
    font.fontName = "Arial"
    font.bold = true
    font.color = IndexedColors.RED.index
    return font
}

After that, we can add other functions responsible for creating individual CellStyle instances:

private fun createRightAlignedStyle(wb: Workbook): CellStyle {
    val style: CellStyle = wb.createCellStyle()
    style.alignment = HorizontalAlignment.RIGHT
    return style
}

private fun createBorderedStyle(wb: Workbook): CellStyle {
    val thin = BorderStyle.THIN
    val black = IndexedColors.BLACK.getIndex()
    val style = wb.createCellStyle()
    style.borderRight = thin
    style.rightBorderColor = black
    style.borderBottom = thin
    style.bottomBorderColor = black
    style.borderLeft = thin
    style.leftBorderColor = black
    style.borderTop = thin
    style.topBorderColor = black
    return style
}

private fun createGreyCenteredBoldArialWithBorderStyle(wb: Workbook, boldArial: Font): CellStyle {
    val style = createBorderedStyle(wb)
    style.alignment = HorizontalAlignment.CENTER
    style.setFont(boldArial)
    style.fillForegroundColor = IndexedColors.GREY_25_PERCENT.getIndex();
    style.fillPattern = FillPatternType.SOLID_FOREGROUND;
    return style
}

private fun createRedBoldArialWithBorderStyle(wb: Workbook, redBoldArial: Font): CellStyle {
    val style = createBorderedStyle(wb)
    style.setFont(redBoldArial)
    return style
}

private fun createRightAlignedDateFormatStyle(wb: Workbook): CellStyle {
    val style = wb.createCellStyle()
    style.alignment = HorizontalAlignment.RIGHT
    style.dataFormat = 14
    return style
}

Please keep in mind that the above examples represent only a small part of CellStyle's possibilities. If you would like to see the full list, please refer to the official documentation here.

Step 4: Create the ReportService Class

As the next step, let's implement a ReportService class responsible for creating .xlsx and .xls files and returning them as ByteArray instances:

@Service
class ReportService(
    private val stylesGenerator: StylesGenerator
) {
    fun generateXlsxReport(): ByteArray {
        val wb = XSSFWorkbook()

        return generateReport(wb)
    }

    fun generateXlsReport(): ByteArray {
        val wb = HSSFWorkbook()

        return generateReport(wb)
    }
 }

As you can see, the only difference between these two formats' generation is the type of Workbook implementation we've. used. For the .xlsx format we will use the XSSFWorkbook class, and for the .xls we will use HSSFWorkbook.

Let's add the rest of the code to the ReportService:

private fun generateReport(wb: Workbook): ByteArray {
    val styles = stylesGenerator.prepareStyles(wb)
    val sheet: Sheet = wb.createSheet("Example sheet name")

    setColumnsWidth(sheet)

    createHeaderRow(sheet, styles)
    createStringsRow(sheet, styles)
    createDoublesRow(sheet, styles)
    createDatesRow(sheet, styles)

    val out = ByteArrayOutputStream()
    wb.write(out)

    out.close()
    wb.close()

    return out.toByteArray()
}

private fun setColumnsWidth(sheet: Sheet) {
    sheet.setColumnWidth(0, 256 * 20)

    for (columnIndex in 1 until 5) {
        sheet.setColumnWidth(columnIndex, 256 * 15)
    }
}

private fun createHeaderRow(sheet: Sheet, styles: Map<CustomCellStyle, CellStyle>) {
    val row = sheet.createRow(0)

    for (columnNumber in 1 until 5) {
        val cell = row.createCell(columnNumber)

        cell.setCellValue("Column $columnNumber")
        cell.cellStyle = styles[CustomCellStyle.GREY_CENTERED_BOLD_ARIAL_WITH_BORDER]
    }
}

private fun createRowLabelCell(row: Row, styles: Map<CustomCellStyle, CellStyle>, label: String) {
    val rowLabel = row.createCell(0)
    rowLabel.setCellValue(label)
    rowLabel.cellStyle = styles[CustomCellStyle.RED_BOLD_ARIAL_WITH_BORDER]
}

private fun createStringsRow(sheet: Sheet, styles: Map<CustomCellStyle, CellStyle>) {
    val row = sheet.createRow(1)
    createRowLabelCell(row, styles, "Strings row")

    for (columnNumber in 1 until 5) {
        val cell = row.createCell(columnNumber)

        cell.setCellValue("String $columnNumber")
        cell.cellStyle = styles[CustomCellStyle.RIGHT_ALIGNED]
    }
}

private fun createDoublesRow(sheet: Sheet, styles: Map<CustomCellStyle, CellStyle>) {
    val row = sheet.createRow(2)
    createRowLabelCell(row, styles, "Doubles row")

    for (columnNumber in 1 until 5) {
        val cell = row.createCell(columnNumber)

        cell.setCellValue(BigDecimal("${columnNumber}.99").toDouble())
        cell.cellStyle = styles[CustomCellStyle.RIGHT_ALIGNED]
    }
}

private fun createDatesRow(sheet: Sheet, styles: Map<CustomCellStyle, CellStyle>) {
    val row = sheet.createRow(3)
    createRowLabelCell(row, styles, "Dates row")

    for (columnNumber in 1 until 5) {
        val cell = row.createCell(columnNumber)

        cell.setCellValue((LocalDate.now()))
        cell.cellStyle = styles[CustomCellStyle.RIGHT_ALIGNED_DATE_FORMAT]
    }
}

As you can see, the first thing the generateReport function does is that it styles the initialization. We pass the Workbook instance to the StylesGenerator and in return, we get a map, which we will use later to obtain appropriate CellStyles.

After that, it creates a new sheet within our workbook and passes a name for it.

Then, it invokes functions responsible for setting the columns' widths and operating on our sheet row by row.

Finally, it writes out our workbook to a ByteArrayOutputStream.

Let's take a minute and analyze what exactly each function does:

private fun setColumnsWidth(sheet: Sheet) {
    sheet.setColumnWidth(0, 256 * 20)

    for (columnIndex in 1 until 5) {
        sheet.setColumnWidth(columnIndex, 256 * 15)
    }
}

As the name suggests, setColumnsWidth is responsible for setting widths of columns in our sheet. The first parameter passed to the setColumnWidth indicates the columnIndex, whereas the second one sets the width (in units of 1/256th of a character width).

private fun createRowLabelCell(row: Row, styles: Map<CustomCellStyle, CellStyle>, label: String) {
    val rowLabel = row.createCell(0)
    rowLabel.setCellValue(label)
    rowLabel.cellStyle = styles[CustomCellStyle.RED_BOLD_ARIAL_WITH_BORDER]
}

The createRowLabelCell function is responsible for adding a cell in the first column of the passed row, alongside setting its value to the specified label and setting the style. I've decided to add this function to slightly reduce the code's redundancy.

All of the below functions are pretty similar. Their purpose is to create a new row, invoking the createRowLabelCell function (except for createHeaderRow) and adding five columns with data to our sheet.

private fun createHeaderRow(sheet: Sheet, styles: Map<CustomCellStyle, CellStyle>) {
    val row = sheet.createRow(0)

    for (columnNumber in 1 until 5) {
        val cell = row.createCell(columnNumber)

        cell.setCellValue("Column $columnNumber")
        cell.cellStyle = styles[CustomCellStyle.GREY_CENTERED_BOLD_ARIAL_WITH_BORDER]
    }
}

private fun createStringsRow(sheet: Sheet, styles: Map<CustomCellStyle, CellStyle>) {
    val row = sheet.createRow(1)
    createRowLabelCell(row, styles, "Strings row")

    for (columnNumber in 1 until 5) {
        val cell = row.createCell(columnNumber)

        cell.setCellValue("String $columnNumber")
        cell.cellStyle = styles[CustomCellStyle.RIGHT_ALIGNED]
    }
}

private fun createDoublesRow(sheet: Sheet, styles: Map<CustomCellStyle, CellStyle>) {
    val row = sheet.createRow(2)
    createRowLabelCell(row, styles, "Doubles row")

    for (columnNumber in 1 until 5) {
        val cell = row.createCell(columnNumber)

        cell.setCellValue(BigDecimal("${columnNumber}.99").toDouble())
        cell.cellStyle = styles[CustomCellStyle.RIGHT_ALIGNED]
    }
}

private fun createDatesRow(sheet: Sheet, styles: Map<CustomCellStyle, CellStyle>) {
    val row = sheet.createRow(3)
    createRowLabelCell(row, styles, "Dates row")

    for (columnNumber in 1 until 5) {
        val cell = row.createCell(columnNumber)

        cell.setCellValue((LocalDate.now()))
        cell.cellStyle = styles[CustomCellStyle.RIGHT_ALIGNED_DATE_FORMAT]
    }
}

Step 5: Implement the REST ReportController

As the last step, we will implement a class named ReportController. It will be responsible for handling POST requests coming to our two REST endpoints:

• /api/report/xlsx - creating a report in a .xlsx format
• /api/report/xls - same as above, but in a .xls format

@RestController
@RequestMapping("/api/report")
class ReportController(
    private val reportService: ReportService
) {

    @PostMapping("/xlsx")
    fun generateXlsxReport(): ResponseEntity<ByteArray> {
        val report = reportService.generateXlsxReport()

        return createResponseEntity(report, "report.xlsx")
    }

    @PostMapping("/xls")
    fun generateXlsReport(): ResponseEntity<ByteArray> {
        val report = reportService.generateXlsReport()

        return createResponseEntity(report, "report.xls")
    }

    private fun createResponseEntity(
        report: ByteArray,
        fileName: String
    ): ResponseEntity<ByteArray> =
        ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"$fileName\"")
            .body(report)

}

The most interesting part of the above code is the createResponseEntity function, which sets the passed ByteArray with its generated report as a response body.

Additionally, we set the Content-Type header of the response as the application/octet-stream, and the Content-Disposition as the attachment; filename=.

Step 6: Test Everything With Postman

Finally, we can run and test our Spring Boot application, for instance with the gradlew command:

./gradlew bootRun

By default, the Spring Boot application will be running on port 8080, so let's open up Postman (or any other tool), specify the POST request to localhost:8080/api/report/xls and hit Send and Download button:

If everything went well, we should see a window allowing us to save the .xls file.

Similarly, let's test the second endpoint:

This time, the file extension should be .xlsx.

Summary

That's all for this article! We've covered the process of generating Excel reports in a Spring Boot REST API with Apache POI and Kotlin.

If you enjoyed it and would like to learn other topics through similar articles, please visit my blog, Codersee.

And the last thing: for the source code of a fully working project, please refer to this GitHub repository.

In this article, I will show you how to embed the JACOB library into your Spring Boot application. This will help you call a COM interface API via the DLL library in your web application.

Also, for illustrative purposes, I will provide a description of a COM API so you can build your application on top of it. You can find all the code snippets in this GitHub repo.

But first, a quick note: at C the Signs we deployed this solution that allowed us to integrate with EMIS Health. It is an electronic patient record system used in primary care in the United Kingdom. For integration we used their provided DLL library.

The approach that I'll show you here (sanitised to avoid leaking any sensitive information) rolled out to production more than two years ago, and has since proven its durability.

Since we recently employed a brand new approach to integrating with EMIS, the old system is going to be shut down in a month or two. So this tutorial is its swan song. Sleep, my little prince.

What is the DLL API?

First, let's start with a clear description of the DLL library. To do this, I prepared a short mock-up of the original technical documentation.

Let's take a look through it to see what the three methods of a COM interface are.

InitialiseWithID Method

This method is a security feature required on-site that lets us obtain a connection to an API server that we want to integrate with the library.

It requires the AccountID (GUID) of the current API user (to access the server) and some other initialization arguments that are listed below.

This function also supports an auto-login feature. If a client has a logged-in version of the running system (the library is a part of that system) and calls the method on the same host, the API will automatically complete the login under that user's account. Then it'll return the SessionID for subsequent API calls.

Otherwise, the client needs to continue with the Logon function (see the next part) using the returned LoginID.

To call the function, use the name InitialiseWithID with the following arguments:

Logon Method

This method determines the authority of the user. The username here is the ID used to log in to the system. The password is the API password set for that username.

In the success scenario, the call returns a SessionID string (GUID) that must be passed into other subsequent calls to authenticate them.

To call the function, use the name Logon with the following arguments:

getMatchedUsers Method

This call lets you find user data records that match specific criteria. The search term can only refer to one field at a time such as last name, first name, or date of birth.

A successful call returns an XML string with the data in it.

To call the function, use the name getMatchedUsers with the following arguments:

DLL Library Application Flow

To make it easier to grasp what we want to implement, I decided to create a simple flow diagram.

It describes a step-by-step scenario of how a web client can interact with our server-based application using its API. It encapsulates interaction with the DLL Library and allows us to get hypothetical users with the provided match term (search criteria):

Application Flow Diagram

Registering COM

Now let's learn how we can access the DLL library. To be able to interact with a 3rd party COM interface, it needs to be added to the registry.

Here's what the docs say:

The registry is a system database that contains information about the configuration of system hardware and software as well as about users of the system. Any Windows-based program can add information to the registry and read information back from the registry. Clients search the registry for interesting components to use.

The registry maintains information about all the COM objects installed in the system. Whenever an application creates an instance of a COM component, the registry is consulted to resolve either the CLSID or ProgID of the component into the pathname of the server DLL or EXE that contains it.

After determining the component's server, Windows either loads the server into the process space of the client application (in-process components) or starts the server in its own process space (local and remote servers).

The server creates an instance of the component and returns to the client a reference to one of the component's interfaces.

To learn how to do that, the official Microsoft documentation says:

You can run a command-line tool called the Assembly Registration Tool (Regasm.exe) to register or unregister an assembly for use with COM.

Regasm.exe adds information about the class to the system registry so COM clients can use the .NET Framework class transparently.

The RegistrationServices class provides the equivalent functionality. A managed component must be registered in the Windows registry before it can be activated from a COM client

Make sure that your host machine has installed the required .NET Framework components. After that, you can execute the following CLI command:

C:\Windows\Microsoft.NET\Framework\v2.0.50727\RegAsm.exe {PATH_TO_YOUR_DLL_FILE} /codebase

A message will display indicating whether the file was successfully registered. Now we're ready for the next step.

Defining the Backbone of the Application

DllApiService

First of all, let's define the interface that describes our DLL library as it is:

public interface DllApiService {

    /**
     * @param accountId identifier for which we trigger initialisation
     * @return Tuple3 from values of Outcome, SessionID/LoginID, error
     * where by the first argument you can understand what is the result of the API call
     */
    Mono<Tuple3<Integer, String, String>> initialiseWithID(String accountId);

    /**
     * @param loginId  is retrieved before using {@link DllApiService#initialiseWithID(String)} call
     * @param username
     * @param password
     * @return Tuple3 from values of Outcome, SessionID, Error
     * where by the first argument you can understand what is the result of the API call
     */
    Mono<Tuple3<Integer, String, String>> logon(String loginId, String username, String password);

    /**
     * @param sessionId is retrieved before using either
     *                  {@link DllApiService#initialiseWithID(String)} or
     *                  {@link DllApiService#logon(String, String, String)} calls
     * @param matchTerm
     * @return Tuple3 from values of Outcome, MatchedList, Error
     * where by the first argument you can understand what is the result of the API call
     */
    Mono<Tuple3<Integer, String, String>> getMatchedUsers(String sessionId, String matchTerm);

    enum COM_API_Method {
        InitialiseWithID, Logon, getMatchedUsers
    }
}

As you might have noticed, all the methods map with the definition of the COM Interface described above, except for the initialiseWithID function.

I decided to omit the address variable in the signature (the IP of the integration server) and inject it as an environment variable which we will be implementing.

SessionIDService Explained

To be able to retrieve any data using the library, first we need to get the SessionID.

According to the flow diagram above, this involves calling the initialiseWithID method first. After that, depending on the result, we will get either the SessionID or LoginID to use in subsequent Logon calls.

So basically this is a two-step process behind the scenes. Now, let's create the interface, and after that, the implementation:

public interface SessionIDService {

    /**
     * @param accountId identifier for which we retrieve SessionID
     * @param username
     * @param password
     * @return Tuple3 containing the following values:
     * result ( Boolean), sessionId (String) and status (HTTP Status depending on the result)
     */
    Mono<Tuple3<Boolean, String, HttpStatus>> getSessionId(String accountId, String username, String password);
}

@Service
@RequiredArgsConstructor
public class SessionIDServiceImpl implements SessionIDService {

    private final DllApiService dll;

    @Override
    public Mono<Tuple3<Boolean, String, HttpStatus>> getSessionId(String accountId, String username, String password) {
        return dll.initialiseWithID(accountId)
                  .flatMap(t4 -> {
                      switch (t4.getT1()) {
                          case -1:
                              return just(of(false, t4.getT3(), SERVICE_UNAVAILABLE));

                          case 1: {

                              return dll.logon(t4.getT2(), username, password)
                                        .map(t3 -> {
                                            switch (t3.getT1()) {
                                                case -1:
                                                    return of(false, t3.getT3(), SERVICE_UNAVAILABLE);
                                                case 1:
                                                    return of(true, t3.getT2(), OK);
                                                case 2:
                                                case 4:
                                                    return of(false, t3.getT3(), FORBIDDEN);
                                                default:
                                                    return of(false, t3.getT3(), BAD_REQUEST);

                                            }
                                        });

                          }

                          case 4:
                              return just(of(true, t4.getT2(), OK));

                          default:
                              return just(of(false, t4.getT3(), BAD_REQUEST));
                      }
                  });

    }
}

API Facade

The next step is to design our web application API. It should represent and encapsulate our interaction with the COM Interface API:

@Configuration
public class DllApiRouter {

    @Bean
    public RouterFunction<ServerResponse> dllApiRoute(DllApiRouterHandler handler) {
        return RouterFunctions.route(GET("/api/sessions/{accountId}"), handler::sessionId)
                              .andRoute(GET("/api/users/{matchTerm}"), handler::matchedUsers);
    }
}

Besides the Router class, let's define an implementation of its handler with logic for retrieving the SessionID and the user records data.

For the second scenario, to be able to make a DLL getMatchedUsers API call according to the design, let's use the mandatory header X-SESSION-ID:

@Slf4j
@Component
@RequiredArgsConstructor
public class DllApiRouterHandler {

    private static final String SESSION_ID_HDR = "X-SESSION-ID";

    private final DllApiService service;
    private final AccountRepo accountRepo;
    private final SessionIDService sessionService;

    public Mono<ServerResponse> sessionId(ServerRequest request) {
        final String accountId = request.pathVariable("accountId");

        return accountRepo.findById(accountId)
                          .flatMap(acc -> sessionService.getSessionId(accountId, acc.getApiUsername(), acc.getApiPassword()))
                          .doOnEach(logNext(t3 -> {
                              if (t3.getT1()) {
                                  log.info(format("SessionId to return %s", t3.getT2()));
                              } else {
                                  log.warn(format("Session Id could not be retrieved. Cause: %s", t3.getT2()));
                              }
                          }))
                          .flatMap(t3 -> status(t3.getT3()).contentType(APPLICATION_JSON)
                                                           .bodyValue(t3.getT1() ? t3.getT2() : Response.error(t3.getT2())))

                          .switchIfEmpty(Mono.just("Account could not be found with provided ID " + accountId)
                                             .doOnEach(logNext(log::info))
                                             .flatMap(msg -> badRequest().bodyValue(Response.error(msg))));
    }

    public Mono<ServerResponse> matchedUsers(ServerRequest request) {

        return sessionIdHeader(request).map(sId -> Tuples.of(sId, request.queryParam("matchTerm")
                                                                         .orElseThrow(() -> new IllegalArgumentException(
                                                                                 "matchTerm query param should be specified"))))
                                       .flatMap(t2 -> service.getMatchedUsers(t2.getT1(), t2.getT2()))
                                       .flatMap(this::handleT3)
                                       .onErrorResume(IllegalArgumentException.class, this::handleIllegalArgumentException);

    }

    private Mono<String> sessionIdHeader(ServerRequest request) {
        return Mono.justOrEmpty(request.headers()
                                       .header(SESSION_ID_HDR)
                                       .stream()
                                       .findFirst()
                                       .orElseThrow(() -> new IllegalArgumentException(SESSION_ID_HDR + " header is mandatory")));
    }

    private Mono<ServerResponse> handleT3(Tuple3<Integer, String, String> t3) {
        switch (t3.getT1()) {
            case 1:
                return ok().contentType(APPLICATION_JSON)
                           .bodyValue(t3.getT2());
            case 2:
                return status(FORBIDDEN).contentType(APPLICATION_JSON)
                                        .bodyValue(Response.error(t3.getT3()));
            default:
                return badRequest().contentType(APPLICATION_JSON)
                                   .bodyValue(Response.error(t3.getT3()));
        }
    }

    private Mono<ServerResponse> handleIllegalArgumentException(IllegalArgumentException e) {
        return Mono.just(Response.error(e.getMessage()))
                   .doOnEach(logNext(res -> log.info(String.join(",", res.getErrors()))))
                   .flatMap(res -> badRequest().contentType(MediaType.APPLICATION_JSON)
                                               .bodyValue(res));
    }

    @Getter
    @Setter
    @NoArgsConstructor
    public static class Response implements Serializable {

        private String message;

        private Set<String> errors;

        private Response(Set<String> errors) {
            this.errors = errors;
        }

        public static Response error(String error) {
            return new Response(singleton(error));
        }
    }
}

Account Entity

As you might have noticed, we've imported AccountRepo in the router's handler to find the entity in a database by the provided accountId. This lets us get the corresponding API user credentials and use all three in the DLL Logon API call.

To get a clearer picture, let's define the managed Account entity as well:

@TypeAlias("Account")
@Document(collection = "accounts")
public class Account {

    @Version
    private Long version;

    /**
     * unique account ID for API, provided by supplier
     * defines restriction for data domain visibility
     * i.e. data from one account is not visible for another
     */
    @Id
    private String accountId;

    /**
     * COM API username, provided by supplier
     */
    private String apiUsername;

    /**
     * COM API password, provided by supplier
     */
    private String apiPassword;


    @CreatedDate
    private Date createdAt;

    @LastModifiedDate
    private Date updatedOn;
}

The JACOB Library Setup

All parts of our application are ready now except the core – the configuration and use of the JACOB library. Let's start with setting up the library.

The library is distributed via sourceforge.net. I did not find it available anywhere on either the Central Maven Repo or any other repositories online. So I decided to import it manually into our project as a local package.

To do that, I downloaded it and put it in the root folder under /libs/jacob-1.19.

After that, put the following maven-install-plugin configuration into pom.xml. This will add the library to the local repository during Maven's install build phase:

<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-install-plugin</artifactId>
   <executions>
      <execution>
         <id>install-jacob</id>
         <phase>validate</phase>
         <configuration>
            <file>${basedir}/libs/jacob-1.19/jacob.jar</file>
            <repositoryLayout>default</repositoryLayout>
            <groupId>net.sf.jacob-project</groupId>
            <artifactId>jacob</artifactId>
            <version>1.19</version>
            <packaging>jar</packaging>
            <generatePom>true</generatePom>
         </configuration>
         <goals>
            <goal>install-file</goal>
         </goals>
      </execution>
   </executions>
</plugin>

That will let you easily add the dependency as usual:

<dependency>
   <groupId>net.sf.jacob-project</groupId>
   <artifactId>jacob</artifactId>
   <version>1.19</version>
</dependency>

The library import is finished. Now let's get it ready to use it.

To interact with the COM component, JACOB provides a wrapper called an ActiveXComponent class (as I mentioned before).

It has a method called invoke(String function, Variant... args) that lets us make exactly what we want.

Generally speaking, our library is set up to create the ActiveXComponent bean so we can use it anywhere we want in the app (and we want it in the implementation of DllApiService).

So let's define a separate Spring @Configuration with all the essential preparations:

@Slf4j
@Configuration
public class JacobCOMConfiguration {

    private static final String COM_INTERFACE_NAME = "NAME_OF_COM_INTERFACE_AS_IN_REGISTRY";

    private static final String JACOB_LIB_PATH = System.getProperty("user.dir") + "\\libs\\jacob-1.19";
    private static final String LIB_FILE = System.getProperty("os.arch")
                                                 .equals("amd64") ? "\\jacob-1.19-x64.dll" : "\\jacob-1.19-x86.dll";

    private File temporaryDll;

    static {
        log.info("JACOB lib path: {}", JACOB_LIB_PATH);
        log.info("JACOB file lib path: {}", JACOB_LIB_PATH + LIB_FILE);
        System.setProperty("java.library.path", JACOB_LIB_PATH);
        System.setProperty("com.jacob.debug", "true");
    }

    @PostConstruct
    public void init() throws IOException {
        InputStream inputStream = new FileInputStream(JACOB_LIB_PATH + LIB_FILE);

        temporaryDll = File.createTempFile("jacob", ".dll");
        FileOutputStream outputStream = new FileOutputStream(temporaryDll);
        byte[] array = new byte[8192];
        for (int i = inputStream.read(array); i != -1; i = inputStream.read(array)) {
            outputStream.write(array, 0, i);
        }
        outputStream.close();

        System.setProperty(LibraryLoader.JACOB_DLL_PATH, temporaryDll.getAbsolutePath());
        LibraryLoader.loadJacobLibrary();
        log.info("JACOB library is loaded and ready to use");
    }

    @Bean
    public ActiveXComponent dllAPI() {
        ActiveXComponent activeXComponent = new ActiveXComponent(COM_INTERFACE_NAME);
        log.info("API COM interface {} wrapped into ActiveXComponent is created and ready to use", COM_INTERFACE_NAME);
        return activeXComponent;
    }

    @PreDestroy
    public void clean() {
        temporaryDll.deleteOnExit();
        log.info("Temporary DLL API library is cleaned on exit");
    }
}

It's worth mentioning that, besides defining the bean, we initialize the library components based on the host machine's ISA (instruction set architecture).

Also, we follow some common recommendations to make a copy of the corresponding library's file. This avoids any potential corruption of the original file during runtime. We also need to cleanup all allocated resources when the applications terminates.

Now the library is set up and ready to use. Finally, we can implement our last main component that helps us interact with the DLL API: DllApiServiceImpl.

How to Implement a DLL Library API Service

As all COM API calls are going to be cooked using a common approach, let's implement InitialiseWithID first. After that, all other methods can be implemented easily in a similar way.

As I mentioned before, to interact with the COM interface, JACOB provides us with the ActiveXComponent class that has the invoke(String function, Variant... args) method.

If you want to know more about the Variant class, the JACOB documentation says the following (you can find it in the archive or under /libs/jacob-1.19 in the project):

The multi-format data type used for all call backs and most communications between Java and COM. It provides a single class that can handle all data types.

This means that all arguments defined in the InitialiseWithID signature should be wrapped with new Variant(java.lang.Object in) and passed to the invoke method. Use the same order as specified in the interface description at the beginning of this article.

The only other important thing we haven't touched on yet is how to distinguish in and out type arguments.

For that purpose, Variant provides a constructor that accepts the data object and information about whether this is by reference or not. This means that after invoke is called, all variants that were initialized as references can be accessed after the call. So we can extract the results from out arguments.

To do that, just pass an extra boolean variable to the constructor as the second parameter: new Variant(java.lang.Object pValueObject, boolean fByRef).

Initializing the Variant object as reference puts an additional requirement on the client to decide when to release the value (so it can be scrapped by the garbage collector).

For that purpose, you have the safeRelease() method that is supposed to be called when the value is taken from the corresponding Variant object.

Putting all the pieces together gives us the following service's implementation:

@RequiredArgsConstructor
public class DllApiServiceImpl implements DllApiService {

    @Value("${DLL_API_ADDRESS}")
    private String address;

    private final ActiveXComponent dll;

    @Override
    public Mono<Tuple3<Integer, String, String>> initialiseWithID(final String accountId) {

        return Mono.just(format("Calling %s(%s, %s, %s, %s, %s, %s)",//
                                InitialiseWithID, address, accountId, "loginId/out", "error/out", "outcome/out", "sessionId/out"))
                   .doOnEach(logNext(log::info))
                   //invoke COM interface method and extract the result mapping it onto corresponding *Out inner class
                   .map(msg -> invoke(InitialiseWithID, vars -> InitialiseWithIDOut.builder()
                                                                                   .loginId(vars[3].toString())
                                                                                   .error(vars[4].toString())
                                                                                   .outcome(valueOf(vars[5].toString()))
                                                                                   .sessionId(vars[6].toString())
                                                                                   .build(), //
                                      new Variant(address), new Variant(accountId), initRef(), initRef(), initRef(), initRef()))
                   //Handle the response according to the documentation
                   .map(out -> {

                       final String errorVal;

                       switch (out.outcome) {
                           case 2:
                               errorVal = "InitialiseWithID method call failed. DLL API request outcome (response code from server via DLL) = 2 " +//
                                       "(Unable to connect to server due to absent server, or incorrect details)";
                               break;
                           case 3:
                               errorVal = "InitialiseWithID method call failed. DLL API request outcome (response code from server via DLLe) = 3 (Unmatched AccountID)";
                               break;
                           default:
                               errorVal = handleOutcome(out.outcome, out.error, InitialiseWithID);
                       }

                       return of(out, errorVal);
                   })
                   .doOnEach(logNext(t2 -> {
                       InitialiseWithIDOut out = t2.getT1();
                       log.info("{} API call result:\noutcome: {}\nsessionId: {}\nerror: {}\nloginId: {}",//
                                InitialiseWithID, out.outcome, out.sessionId, t2.getT2(), out.loginId);
                   }))
                   .map(t2 -> {
                       InitialiseWithIDOut out = t2.getT1();
                       //out.outcome == 4 auto-login successful, SessionID is retrieved
                       return of(out.outcome, out.outcome == 4 ? out.sessionId : out.loginId, t2.getT2());
                   });
    }

    private static Variant initRef() {
        return new Variant("", true);
    }

    private static String handleOutcome(Integer outcome, String error, COM_API_Method method) {
        switch (outcome) {
            case 1:
                return "no error";
            case 2:
                return format("%s method call failed. DLL API request outcome (response code from server via DLL) = 2 (Access denied)", method);
            default:
                return format("%s method call failed. DLL API request outcome (response code from server via DLL) = %s (server technical error). " + //
                                      "DLL API is temporary unavailable (server behind is down), %s", method, outcome, error);
        }

    }

    /**
     * @param method     to be called in COM interface
     * @param returnFunc maps Variants (references) array onto result object that is to be returned by the method
     * @param vars       arguments required for calling COM interface method
     * @param <T>        type of the result object that is to be returned by the method
     * @return result of the COM API method invocation in defined format
     */
    private <T extends Out> T invoke(COM_API_Method method, Function<Variant[], T> returnFunc, Variant... vars) {
        dll.invoke(method.name(), vars);
        T res = returnFunc.apply(vars);
        asList(vars).forEach(Variant::safeRelease);
        return res;
    }

    @SuperBuilder
    private static abstract class Out {
        final Integer outcome;
        final String error;
    }

    @SuperBuilder
    private static class InitialiseWithIDOut extends Out {
        final String loginId;
        final String sessionId;
}

Two other methods, Logon and getMatchedUsers, are implemented accordingly. You can refer to my GitHub repo for a complete version of the service if you want to check it out.

Congratulations – You've Learned a Few Things

We've gone through a step by step scenario that showed us how a hypothetical COM API could be distributed and called in Java.

We also learned how the JACOB library can be configured and effectively used to interact with a DDL library within your Spring Boot 2 application.

A small improvement would be to cache the retrieved SessionID which could improve the general flow. But that's a bit outside the scope of this article.

If you want to investigate further, you can find that on GitHub where it's implemented using Spring's caching mechanism.

Hope you enjoyed going through everything with me and found this tutorial helpful!

In the past month, I had a chance to implement JWT auth for a side project. I have previously worked with JWT in Ruby on Rails, but this was my first time in Spring.

In this post, I will try to explain what I have learned and applied in my project to share my experience and hopefully help some people.

We will start by taking a quick look at the theory behind JWT and how it works. Then we will look at how to implement it in a Spring Boot application.

JWT Basics

JWT, or JSON Web Tokens (RFC 7519), is a standard that is mostly used for securing REST APIs. Despite being a relatively new technology, it is gaining rapid popularity.

In the JWT auth process, the front end (client) firstly sends some credentials to authenticate itself (username and password in our case, since we're working on a web application).

The server (the Spring app in our case) then checks those credentials, and if they are valid, it generates a JWT and returns it.

After this step client has to provide this token in the request’s Authorization header in the “Bearer TOKEN” form. The back end will check the validity of this token and authorize or reject requests. The token may also store user roles and authorize the requests based on the given authorities.

Implementation

Now let’s see how we can implement the JWT login and save mechanism in a real Spring application.

Dependencies

You can see the list of Maven dependencies that our example code uses below. Note that the core dependencies like Spring Boot and Hibernate are not included in this screenshot.

Saving Users

We will start by creating controllers to save users securely and authenticate them based on username and password.

We have a model entity called User. It is a simple entity class that maps to the USER table. You can use whatever properties you need depending on your application.

We also have a simple UserRepository class to save users. We need to override the findByUsername method since we will use it in authentication.

public interface UserRepository extends JpaRepository<User, String>{ 
    User findByUsername(String username); 
}

We should never store plaintext passwords in the database because many users tend to use the same password for multiple sites.

There are many different hashing algorithms, but the most commonly used one is BCrypt and it is a recommended method of secure hashing. You can check out this article for more information on the topic.

To hash the password, we will define a BCrypt bean in @SpringBootApplication and annotate the main class as follows:

@Bean public BCryptPasswordEncoder bCryptPasswordEncoder() {
    return new BCryptPasswordEncoder(); 
}

We will call the methods on this bean when we need to hash a password.

We also need a UserController to save users. We create the controller, annotate it with @RestController, and define the corresponding mapping.

In our application, we save the user based on a DTO object that is passed from the front end. You can also pass a User object in @RequestBody.

After we pass the DTO object, we encrypt the password field using the BCrypt bean we created earlier. You could also do this in the controller, but it is a better practice to put this logic in the service class.

@Transactional(rollbackFor = Exception.class) 
public String saveDto(UserDto userDto) { 
    userDto.setPassword(bCryptPasswordEncoder
           .encode(userDto.getPassword())); 
    return save(new User(userDto)).getId(); 
}

Authentication Filter

We need authentication to make sure that the user is really who they claim to be. We will be using the classic username/password pair to accomplish this.

Here are the steps to implement authentication:

1. Create our Authentication Filter that extends UsernamePasswordAuthenticationFilter
2. Create a security configuration class that extends WebSecurityConfigurerAdapter and apply the filter

Here is the code for our Authentication Filter – as you might know, filters are the backbone of Spring Security.

Let’s go over this code step by step.

This class extends UsernamePasswordAuthenticationFilter which is the default class for password authentication in Spring Security. We extend it to define our custom authentication logic.

We make a call to the setFilterProcessesUrl method in our constructor. This method sets the default login URL to the provided parameter.

If you remove this line, Spring Security creates the “/login” endpoint by default. It defines the login endpoint for us, which is why we will not define a login endpoint in our controller explicitly.

After this line our login endpoint will be /api/services/controller/user/login. You can use this function to stay consistent with your endpoints.

We override the attemptAuthentication and successfulAuthentication methods of the UsernameAuthenticationFilter class.

The attemptAuthentication function runs when the user tries to log in to our application. It reads the credentials, creates a user POJO from them, and then checks the credentials to authenticate.

We pass the username, password, and an empty list. The empty list represents the authorities (roles), and we leave it as is since we do not have any roles in our application yet.

If the authentication is successful, the successfulAuthentication method runs. The parameters of this method are passed by Spring Security behind the scenes.

The attemptAuthentication method returns an Authentication object that contains the authorities we passed while attempting.

We want to return a token to user after authentication is successful, so we create the token using username, secret, and expiration date. We need to define the SECRET and EXPIRATION_DATE now.

We create a class to be a container for our constants. You can set the secret to whatever you want, but the best practice is making the secret key as long as your hash. We use the HS256 algorithm in this example, so our secret key is 256 bits/32 chars.

The expiration time is set to 15 minutes, because it is the best practice against secret key brute-forcing attacks. The time is in milliseconds.

We have prepared our Authentication filter, but it is not active yet. We also need an Authorization filter, and then we will apply them both through a configuration class.

This filter will check the existence and validity of the access token on the Authorization header. We will specify which endpoints will be subject to this filter in our configuration class.

Authorization Filter

The doFilterInternal method intercepts the requests then checks the Authorization header. If the header is not present or doesn’t start with “BEARER”, it proceeds to the filter chain.

If the header is present, the getAuthentication method is invoked. getAuthentication verifies the JWT, and if the token is valid, it returns an access token which Spring will use internally.

This new token is then saved to SecurityContext. You can also pass in Authorities to this token if you need for role-based authorization.

Our filters are ready, and now we need to put them into action with the help of a configuration class.

Configuration

We annotate this class with @EnableWebSecurity and extend WebSecurityConfigureAdapter to implement our custom security logic.

We autowire the BCrypt bean that we defined earlier. We also autowire the UserDetailsService to find the user’s account.

The most important method is the one which accepts an HttpSecurity object. Here we specify the secure endpoints and filters that we want to apply. We configure CORS, and then we permit all post requests to our sign up URL that we defined in the constants class.

You can add other ant matchers to filter based on URL patterns and roles, and you can check this StackOverflow question for examples regarding that. The other method configures the AuthenticationManager to use our encoder object as its password encoder while checking the credentials.

Testing

Let’s send a few requests to test if it works properly.

Here we send a GET request to access a protected resource. Our server responds with a 403 code. This is the expected behavior because we haven’t provided a token in the header. Now let’s create a user:

To create a user, we send a post request with our User DTO data. We will use this user to login and get an access token.

Great! We got the token. After this point, we will use this token to access protected resources.

We provide the token in the Authorization header and we are now allowed access to our protected endpoint.

Conclusion

In this tutorial I have walked you through the steps I took when implementing JWT authorization and password authentication in Spring. We also learned how to save a user securely.

Thank you for reading – I hope it was helpful to you. If you are interested in reading more content like this, feel free to subscribe to my blog at https://erinc.io. :)

This course from Pair Learning will also demonstrate how to use PostgreSQL as the relational database and Spring JdbcTemplate for interacting with that. You will learn how to add authentication using JWT (JSON Web Tokens).

Here are the sections in this course:

• Project Setup & Creating Database Objects
• Persisting User Information on Register
• Login and Hashing Password
• JWT Authentication
• Adding New Categories
• Category - Find & Update Functionality
• Adding Category Transactions
• Transaction - Find and Update
• Deleting - Category & Transactions
• CORS & Testing from Web Client
• Summary and Code

You can watch the full course on the freeCodeCamp.org YouTube channel (2 hour watch).

This course covers:

• HTTP: GET, POST, PUT & DELETE
• Build an in-memory database
• How to structure applications using N Tier Architecture
• Auto wire beans with dependency injections
• Program to interfaces
• Run .jar file so that you can deploy to any server
• Use Postman REST Client
• and more!

You can watch the full video on the freeCodeCamp.org YouTube channel (2 hour watch).

A hexagonal architecture simplifies deferring or changing technology decisions. You want to change to a different framework? Write a new adapter. You want to use a database, instead of storing data in files? Again, write an adapter for it.

Draw a boundary around the business logic. The hexagon. Anything inside the hexagon must be free from technology concerns.
The outside of the hexagon talks with the inside only by using interfaces, called ports. Same the other way around. By changing the implementation of a port, you change the technology.

Isolating business logic inside the hexagon has another benefit. It enables writing fast, stable tests for the business logic. They do not depend on web technology to drive them, for example.

Here’s an example diagram. It shows Spring MVC technology as boxes with dotted lines, ports and adapters as solid boxes, and the hexagon without its internals:

An adapter translates between a specific technology and a technology free port. The PoemController adapter on the left receives requests and sends commands to the IReactToCommands port. The PoemController is a regular Spring MVC Controller. Because it actively uses the port, it's called a driver adapter.

IReactToCommands is called a driver port. Its implementation is inside the hexagon. It's not shown on the diagram.

On the right side, the SpringMvcPublisher adapter implements the IWriteLines port. This time, the hexagon calls the adapter through the port. That's why SpringMvcPublisher is called a driven adapter. And IWriteLines is called a driven port.

I show you how to implement that application. We go all the way from a user story to a domain model inside the hexagon. We start with a simple version of the application that prints to the console. Then we switch to Spring Boot and Spring MVC.

From a user story to ports & adapters

The company FooBars.io decides to build a Poetry App. The product owner and the developers agree on the following user story:

As a reader
I want to read at least one poem each day
So that I thrive as a human being

As acceptance criteria, the team agrees on:

• When the user asks for a poem in a specific language, the system displays a random poem in that language in the console
• It's ok to "simulate" the user at first, i.e. no real user interaction. (This will change in future versions.)
• Supported languages: English, German

The developers meet and draw the following diagram:

So the SimulatedUser sends commands to the IReactToCommands port. It asks for poems in English and German. Here's the code, it's available on Github.

_poem/simple/driver_adapter/SimulatedUser.java_

public class SimulatedUser {
    private IReactToCommands driverPort;

    public SimulatedUser(IReactToCommands driverPort) {
        this.driverPort = driverPort;
    }

    public void run() {
        driverPort.reactTo(new AskForPoem("en"));
        driverPort.reactTo(new AskForPoem("de"));
    }
}

The IReactToCommands port has only one method to receive any kind of command.

_poem/boundary/driver_port/IReactToCommands.java_

public interface IReactToCommands{
    void reactTo(Object command);
}

AskForPoem is the command. Instances are simple, immutable POJOs. They carry the language of the requested poem.

poem/command/AskForPoem.java

public class AskForPoem {
    private String language;

    public AskForPoem(String language) {
        this.language = language;
    }

    public String getLanguage() {
        return language;
    }
}

And that's it for the left, driver side of the hexagon. On to the right, driven side.

When the SimulatedUser asks the IReactToCommands port for a poem, the hexagon:

1. Contacts the IObtainPoems port for a collection of poems
2. Picks a random poem from the collection
3. Tells the IWriteLines port to write the poem to the output device

You can't see Step 2 yet. It happens inside the hexagon, in the domain model. That's the business logic of the example. So we focus on Step 1 and Step 3 first.

In Step 1, the collection of poems is a language dependent, hard coded array. It's provided by the HardcodedPoemLibrary adapter that implements the IObtainPoems port.

_poem/boundary/driven_port/IObtainPoems.java_

public interface IObtainPoems {
    String[] getMePoems(String language);
}

_poem/simple/driven_adapter/HardcodedPoemLibrary.java_

public class HardcodedPoemLibrary implements IObtainPoems {
    public String[] getMePoems(String language) {
        if ("de".equals(language)) {
            return new String[] { /* Omitted for brevity */ };
        } else { 
            return new String[] { /* Omitted for brevity */ };
        }
    }
}

In Step 3, the ConsoleWriter adapter writes the lines of the poems to the output device, i.e. the console.

_poem/boundary/driven_port/IWriteLines.java_

public interface IWriteLines {
    void writeLines(String[] strings);
}

_poem/simple/driven_adapter/ConsoleWriter.java_

public class ConsoleWriter implements IWriteLines {
    public void writeLines(String[] lines) {
        Objects.requireNonNull(lines);
        for (String line : lines) {
            System.out.println(line);
        }
        System.out.println("");
    }
}

We have created all the ports, and a simple implementation of all the adapters. So far, the inside of the hexagon remained a mystery. It's up next.

Command handlers (inside the hexagon)

When a user asks for a poem, the system displays a random poem.
Similar in the code: when the IReactToCommands port receives an AskForPoemcommand, the hexagon calls a DisplayRandomPoem command handler.

The DisplayRandomPoem command handler obtains a list of poems, picks a random one and writes it to the output device. This is exactly the list of steps we talked about in the last clause.

_poem/boundary/internal/command_handler/DisplayRandomPoem.java_

public class DisplayRandomPoem implements Consumer<AskForPoem> {
        /* Omitted for brevity */

    @Override
    public void accept(AskForPoem askForPoem) {
        List<Poem> poems = obtainPoems(askForPoem);
        Optional<Poem> poem = pickRandomPoem(poems);
        writeLines(poem);   
    }

        /* Rest of class omitted for brevity */
}

It's also the job of the command handler to translate between the domain model data and the data used in the port interfaces.

Tying commands to command handlers

In my implementation of a hexagonal architecture, there is only a single driver port, IReactToCommands. It reacts to all types of commands.

public interface IReactToCommands{
    void reactTo(Object command);
}

The Boundary class is the implementation of the IReactToCommands port. It creates a behavior model using a library. The behavior model maps each command type to a command handler. Then, a behavior dispatches the commands based on the behavior model.

poem/boundary/Boundary.java

public class Boundary implements IReactToCommands, BehaviorModel {
  private final IObtainPoems poemObtainer;
  private final IWriteLines lineWriter;
  private final StatelessBehavior behavior;

  private static final Class<AskForPoem> asksForPoem = AskForPoem.class;

  public Boundary(IObtainPoems poemObtainer, IWriteLines lineWriter) {
    this.poemObtainer = poemObtainer;
    this.lineWriter = lineWriter;
    this.behavior = StatelessBehavior.of(this);
  }

  @Override
  public Model model() {
    return Model.builder()
        .user(asksForPoem).system(displaysRandomPoem())
        .build();
  }

  @Override
  public void reactTo(Object commandObject) {
    behavior.reactTo(commandObject);
  }

  private Consumer<AskForPoem> displaysRandomPoem() {
    return new DisplayRandomPoem(poemObtainer, lineWriter);
  }
}

The domain model

The domain model of the example doesn’t have very interesting functionality. The RandomPoemPicker picks a random poem from a list.

A Poem has a constructor that takes a String containing line separators, and splits it into verses.

The really interesting bit about the example domain model: it doesn’t refer to a database or any other technology, not even by interface!

That means that you can test the domain model with plain unit tests. You don’t need to mock anything.

Such a pure domain model is not a necessary property of an application implementing a hexagonal architecture. But I like the decoupling and testability it provides.

Plug adapters into ports, and that's it

A final step remains to make the application work. The application needs a main class that creates the driven adapters. It injects them into the boundary.
It then creates the driver adapter, for the boundary, and runs it.

poem/simple/Main.java

public class Main {
    public static void main(String[] args) {
        new Main().startApplication();
    }

    private void startApplication() {
        // Instantiate driven, right-side adapters
        HardcodedPoemLibrary poemLibrary = new HardcodedPoemLibrary();
        ConsoleWriter consoleWriter = new ConsoleWriter();

        // Inject driven adapters into boundary
        Boundary boundary = new Boundary(poemLibrary, consoleWriter);

        // Start the driver adapter for the application
        new SimulatedUser(boundary).run();
    }
}

And that's it! The team shows the result to the product owner. And she's happy with the progress. Time for a little celebration.

Switching to Spring

The team decides to turn the poem app into a web application. And to store poems in a real database. They agree to use the Spring framework to implement it.
Before they start coding, the team meets and draws the following diagram:

Instead of a SimulatedUser, there is a PoemController now, that sends commands to the hexagon.

_poem/springboot/driver_adapter/PoemController.java_

@Controller
public class PoemController {
    private SpringMvcBoundary springMvcBoundary;

    @Autowired
    public PoemController(SpringMvcBoundary springMvcBoundary) {
        this.springMvcBoundary = springMvcBoundary;
    }

    @GetMapping("/askForPoem")
    public String askForPoem(@RequestParam(name = "lang", required = false, defaultValue = "en") String language,
            Model webModel) {
        springMvcBoundary.basedOn(webModel).reactTo(new AskForPoem(language));

        return "poemView";
    }
}

When receiving a command, the PoemController calls springMvcBoundary.basedOn(webModel). This creates a new Boundary instance, based on the webModel of the request:

poem/springboot/boundary/SpringMvcBoundary.java

public class SpringMvcBoundary {
    private final IObtainPoems poemObtainer;

    public SpringMvcBoundary(IObtainPoems poemObtainer) {
        this.poemObtainer = poemObtainer;
    }

    public IReactToCommands basedOn(Model webModel) {
        SpringMvcPublisher webPublisher = new SpringMvcPublisher(webModel);
        IReactToCommands boundary = new Boundary(poemObtainer, webPublisher);
        return boundary;
    }
}

The call to reactTo() sends the command to the boundary, as before. On the right side of the hexagon, the SpringMvcPublisher adds an attribute lines to the Spring MVC model. That's the value Thymeleaf uses to insert the lines into the web page.

_poem/springboot/driven_adapter/SpringMvcPublisher.java_

public class SpringMvcPublisher implements IWriteLines {
    static final String LINES_ATTRIBUTE = "lines";

    private Model webModel;

    public SpringMvcPublisher(Model webModel) {
        this.webModel = webModel;
    }

    public void writeLines(String[] lines) {
        Objects.requireNonNull(lines);
        webModel.addAttribute(LINES_ATTRIBUTE, lines);
    }
}

The team also implements a PoemRepositoryAdapter to access the PoemRepository. The adapter gets the Poem objects from the database. It returns the texts of all poems as a String array.

_poem/springboot/driven_adapter/PoemRepositoryAdapter.java_

public class PoemRepositoryAdapter implements IObtainPoems {
    private PoemRepository poemRepository;

    public PoemRepositoryAdapter(PoemRepository poemRepository) {
        this.poemRepository = poemRepository;
    }

    @Override
    public String[] getMePoems(String language) {
        Collection<Poem> poems = poemRepository.findByLanguage(language);
        final String[] poemsArray = poems.stream()
            .map(p -> p.getText())
            .collect(Collectors.toList())
            .toArray(new String[0]);
        return poemsArray;
    }
}

Finally, the team implements the Application class that sets up an example repository and plugs the adapters into the ports.

And that's it. The switch to Spring is complete.

Conclusion

There are many ways to implement a hexagonal architecture. I showed you a straightforward approach that provides an easy to use, command driven API for the hexagon. It reduces the number of interfaces you need to implement. And it leads to a pure domain model.

If you want to get more information on the topic, read Alistair Cockburn’s original article on the subject.

The example in this article is inspired by a three part series of talks by Alistair Cockburn on the subject.

Last updated on 30 July 2021.__. If you want to keep up with what I’m doing or drop me a note, follow me on dev.to, LinkedIn or Twitter. Or visit my GitHub project. To learn about agile software development, visit my online course.