spring-boot - freeCodeCamp.org

Database Version Control with Liquibase and Spring Boot

Ashutosh Krishna — Tue, 09 Jun 2026 02:29:12 +0000

Picture this familiar scenario: you're working on a new feature that requires a new database column. You open your local database client, write an ALTER TABLE statement, and execute it. Your code works perfectly. You commit the Java code, push it to the repository, and go grab a coffee.

A few hours later, a teammate pulls your branch, runs the application, and everything crashes.

"Hey," they ask across the room (or in a Slack channel), "did you change the database?"

You quickly realize you forgot to share the SQL script. You paste it into the chat. They run it. Everything works. Then, a week later, the deployment to the staging environment fails for the exact same reason. By the time this code reaches production, everyone is asking a variation of the same terrified question: "Which SQL script should I run?"

This situation is called schema drift. It happens when the state of your database diverges across different environments. Staging has one schema, production has another, and every developer's local machine is a unique snowflake of untested database modifications.

Managing database changes manually is a recipe for deployment headaches and team collaboration challenges. Application code is stateless and easy to replace. Databases are stateful. Databases have surprisingly good memories, and they rarely forget a bad migration.

Liquibase solves this problem by bringing version-control discipline to your database changes. Instead of passing around SQL files and hoping people remember to run them, you define your database changes in code. These changes travel with your application repository and execute automatically.

Here is a high-level look at how this architecture works:

Think about the journey of a single database change. A developer commits their database migration alongside their Java code into Git. When the CI/CD pipeline (or a teammate) pulls that code, the Spring Boot application starts. But before the app fully boots up and accepts web traffic, Liquibase intercepts the process. It acts as a gatekeeper, connecting to the database and applying the required schema changes. This ensures the database exactly matches the code's expectations before a single user makes a request.

Why Database Version Control Matters

If you've spent any time working on team-based applications, you've probably seen a folder structure that looks exactly like this:

project-sql-scripts/
├── create_employee_table.sql
├── create_employee_table_final.sql
├── create_employee_table_final_v2.sql
├── add_email_column.sql
├── latest.sql
└── definitely_latest_use_this_one.sql

The phrase "just run this SQL script manually" has launched many memorable incidents.

When you rely on manual database updates, you guarantee failure at scale. Onboarding a new developer becomes an archeological expedition to figure out how to build the local schema. Deployments become stressful events requiring a checklist of manual queries that must be run in a highly specific order.

Version-controlled database changes treat your schema as code. When your database changes live alongside your application logic, you gain several immediate benefits:

Consistency: Every environment (local, staging, production) applies the exact same changes in the exact same order.
Safety: You eliminate the human error of skipping a script or running an outdated query.
Visibility: You can look at a Git commit and see exactly how the Java code and the database schema changed together to support a new feature.

Git solved version control for code. Liquibase helps prevent databases from becoming the rebellious sibling.

What is Liquibase?

At its core, Liquibase is a database migration tool that tracks and applies schema changes in a predictable and repeatable way.

Instead of writing loose SQL scripts, you write "migrations" (also called changeSets). Liquibase reads these files, compares them against a tracking table inside your actual database, and figures out exactly what needs to be executed to bring the database up to date.

To use Liquibase effectively, you only need to understand a few conceptual terms:

changeLog: The master file. This is essentially a list that tells Liquibase which migration files to execute and in what order.
changeSet: A single, atomic change to your database. Creating a table is one changeSet. Adding a column is another.
Migration History: A table Liquibase automatically creates in your database (called DATABASECHANGELOG) to remember which changeSets have already been executed.
Checksums: A unique hash generated for every changeSet. Liquibase uses this to detect if someone secretly modified a file after it was already executed.

When you integrate Liquibase with Spring Boot, the migration process happens completely automatically during the application startup phase.

During startup, Liquibase takes control before your web server is allowed to receive HTTP traffic. It reaches into the database and checks the tracking table to see which migrations have already run. If it finds new migrations in your local files, it locks the database to prevent concurrent updates, executes the changes, records the new history, and finally releases the lock. Only after this entire process completes does Spring Boot finish booting up.

Because Liquibase runs before Spring Boot fully initializes the web server, your application will never serve traffic with an outdated database schema. If a migration fails, the application fails to start, protecting your system from entering a broken state.

Project Setup

Now that you understand the theory, let's build something real. We're going to build the database layer for an Employee Management API.

For this project we'll use:

Java 17+
Spring Boot 3.x
Maven
Liquibase
H2 Database

We're using H2 because it's an in-memory database that requires zero installation. You can run this project immediately without configuring Docker containers or installing database servers. But everything you learn here applies exactly the same way to PostgreSQL, MySQL, SQL Server, or Oracle.

If you're generating this project via Spring Initializr, select the following dependencies: Spring Web, Spring Data JPA, Liquibase Migration, and H2 Database.

In your pom.xml, you'll see the critical dependencies that make this work:


    
        org.springframework.boot
        spring-boot-starter-web
    
    
        org.springframework.boot
        spring-boot-starter-data-jpa
    

    
        com.h2database
        h2
        runtime
    

    
        org.liquibase
        liquibase-core

Next, configure Spring Boot to talk to H2 and find your Liquibase files. Open your src/main/resources/application.properties file and add the following:

# H2 Database Configuration
spring.datasource.url=jdbc:h2:file:./data/employeedb;DB_CLOSE_DELAY=-1
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

# Enable H2 Console to inspect the database in your browser
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console

# Liquibase Configuration
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml

That last line is the most important. It tells Spring Boot exactly where to find the "master list" of your database changes.

Note: We're using a file-based H2 database instead of an in-memory database. The problem with an in-memory database is that it completely wipes itself clean every time you restart Spring Boot.

While Liquibase will happily rebuild the schema from scratch on every boot, a file-based database is much better for this tutorial (and for real-world local development). With a file-based database, your data, and more importantly, your Liquibase history, will actually persist between application restarts.

Understanding Core Liquibase Concepts

Before we write our first table, we need to understand how Liquibase organizes files. Liquibase uses a hierarchical structure.

Think of it like a book. The changeLog is the table of contents, and the changeSets are the actual chapters.

The Master ChangeLog: This is the entry point. It rarely contains actual database changes. Instead, its only job is to include other files in a specific order.
Child ChangeLogs: These group related changes together.
ChangeSets: These are the actual, atomic database commands (like creating a table or adding a column).

Here's a visual breakdown of how this hierarchy works in a real Spring Boot project:

Liquibase organizes migrations hierarchically. You maintain a single master file that acts as a table of contents. This master file rarely holds actual SQL commands. Instead, it explicitly includes child XML files in a strict execution order. Each of those child files (like 01-create-employees.xml) contains one or more individual database commands, which Liquibase calls changeSets.

A changeSet is uniquely identified by three things:

id: A unique string (often a number or a Jira ticket ID).
author: The person who wrote the migration.
file path: Where the file is located.

When Liquibase runs, it looks at a changeSet, calculates a cryptographic hash of its contents (a checksum), and records the id, author, and checksum in the database. If it sees that exact combination of id, author, and file path in the database again on the next startup, it skips it.

Create the Initial Employee Schema (Version 1)

Let's write our first version. We need a table to store employees.

First, create the master file at src/main/resources/db/changelog/db.changelog-master.xml:

Next, create the actual migration file at src/main/resources/db/changelog/changes/01-create-employees.xml:

Let's look at what we just did. We defined a changeSet with an id of "1" and an author of "ashutoshkrris". Inside, we used Liquibase's XML syntax to define a table.

Why use XML instead of plain SQL? Because Liquibase is database-agnostic. This exact XML will generate the correct auto-increment syntax for PostgreSQL (SERIAL), MySQL (AUTO_INCREMENT), or Oracle (IDENTITY). You define the structure, and Liquibase translates it to the specific database dialect.

Now, run your Spring Boot application. Watch your terminal output. You'll see logs similar to this:

Liquibase realized the database was empty. It automatically created its tracking table (DATABASECHANGELOG), read our changeSet, executed the table creation, and recorded the event.

If you restart the application right now, Liquibase will run again. But this time, it'll check the DATABASECHANGELOG table, see that id="1" and author="ashutoshkrris" has already been executed, and silently skip it. Your database is now safely version-controlled.

What Just Happened?

Up to this point, Liquibase might feel a bit like magic. You dropped an XML file into a folder, started Spring Boot, and your database schema transformed.

But understanding how Liquibase actually works under the hood is critical. If you understand the startup sequence, you'll know exactly how to debug deployments when things eventually go wrong.

When your Spring Boot application starts, it doesn't immediately begin accepting web requests. First, it initializes its internal components. When it creates the Liquibase component, the migration process begins.

Here's exactly what happens during that startup phase:

Let's trace the exact sequence. When Spring Boot initializes Liquibase, the very first thing the tool does is query the lock table to ensure no other application instance is currently migrating the database. If the coast is clear, it claims the lock. It then calculates cryptographic checksums for your local XML files, compares them against the database history, executes any missing changes, and logs them. Finally, it releases the lock so the Tomcat web server can safely start.

This sequence guarantees that your application will never serve a user request before the database schema is completely ready to handle it.

Inspecting the Database: Liquibase Metadata Tables

Let's look at what this history and locking actually looks like inside the database itself. Since we configured the H2 Console earlier, we can inspect the raw tables.

While your Spring Boot application is running, open your browser and navigate to http://localhost:8080/h2-console. Connect using the JDBC URL jdbc:h2:file:./data/employeedb with the username sa and a blank password.

Inside, you'll see your employees table. You'll also see two extra tables created automatically by Liquibase: DATABASECHANGELOG and DATABASECHANGELOGLOCK.

The `DATABASECHANGELOG` Table

This table is the brain of your migration strategy. It acts as the permanent ledger of every database change ever applied to this environment.

If you run SELECT * FROM DATABASECHANGELOG;, you'll see output that looks like this:

ID	AUTHOR	FILENAME	DATEEXECUTED	ORDEREXECUTED	EXECTYPE	MD5SUM	DESCRIPTION	COMMENTS	TAG	LIQUIBASE	CONTEXTS	LABELS	DEPLOYMENT_ID
1	ashutoshkrris	db/changelog/changes/01-create-employees.xml	2026-05-30 13:11:35.937919	1	EXECUTED	9:66e7dcffb2b1902a4e9f01670cb5f192	createTable tableName=employees		null	4.31.1	null	null	0126894849

Let's break down the most important columns:

ID, AUTHOR, FILENAME: These three columns form a composite key. Together, they uniquely identify a single migration.
DATEEXECUTED & ORDEREXECUTED: Tells you exactly when a script ran and in what sequence.
MD5SUM: This is the cryptographic hash of your XML file. When Liquibase starts, it hashes your local XML file and compares it to this column. If you secretly edit a file after it's been executed, this hash won't match, and Liquibase will crash the startup to protect your database.
EXECTYPE: Most of the time, this simply says EXECUTED. But it provides a crucial audit trail: if you use Liquibase commands to intentionally skip a migration but record it as finished, you'll see MARK_RAN. If a migration was skipped because its preconditions failed, you'll see SKIPPED.
TAG: Think of this as a Git tag for your database schema. Before a major, high-risk deployment, you can configure Liquibase to "tag" the current state of the database (for example, v1.4.0). If the deployment fails catastrophically, you can trigger a rollback command telling Liquibase to undo every change applied after the v1.4.0 tag.
CONTEXTS: This is how you manage environment-specific changes. By adding a context attribute to your changeSet (for example, ), that migration will only execute if Spring Boot passes "dev" or "qa" to Liquibase on startup. Production will safely ignore it.
LABELS: While Contexts target environments, Labels target categories of work. You can label a changeSet with a Jira ticket number (issue-842) or a release train (Q3-release). This allows advanced teams to selectively execute or roll back specific subsets of features without affecting the rest of the database.

The `DATABASECHANGELOGLOCK` Table

This table is tiny, but it plays a massive role in modern deployments.

If you run SELECT * FROM DATABASECHANGELOGLOCK;, you'll see a single row:

ID	LOCKED	LOCKGRANTED	LOCKEDBY
1	FALSE	null	null

Imagine you're deploying your Spring Boot application to a Kubernetes cluster. You tell Kubernetes to spin up three identical instances simultaneously. All three instances connect to the exact same database.

If all three instances try to run the CREATE TABLE migration at the exact same millisecond, your database will throw concurrency errors. The lock table prevents this. The very first instance to reach the database sets LOCKED to TRUE. The other two instances check the table, see the lock, and politely wait.

Practical Troubleshooting Tip: Sometimes, a deployment fails catastrophically mid-migration (perhaps the server lost power). When this happens, Liquibase might die before it can set LOCKED back to FALSE.

The next time you start the application, the logs will hang indefinitely, repeating: Waiting for changelog lock....

If you're absolutely certain no other applications are currently running migrations, you can manually fix this by running a simple SQL command in your database client:

UPDATE DATABASECHANGELOGLOCK SET LOCKED = FALSE;

This forces the lock open, allowing your application to resume.

Evolving the Employee API

Software is never finished. Two weeks after your successful Version 1 deployment, the business team comes back with new requirements.

Because you now understand how Liquibase tracks history, evolving the database is simple. You just append new files to your master list.

Version 2: Adding an Email Field

The HR team needs to contact employees. You need an email column.

Create a new file at src/main/resources/db/changelog/changes/02-add-employee-email.xml:

Add this to your db.changelog-master.xml file immediately below your first include:

When you restart the application, Liquibase checks the DATABASECHANGELOG table. It sees that id="1" is already there, so it skips it. It sees id="2" is missing, so it executes it and adds a new row to the tracking table.

Version 3: Adding Departments Support

The company is growing. Employees now belong to departments. You need a departments table and a foreign key constraint linking the two.

Create 03-add-departments.xml:

Notice that we used two separate changeSets in one file. This is a best practice. Each changeSet represents one logical operation. If the foreign key creation (id="4") fails, the department table creation (id="3") will still be recorded as successful, and only id="4" will roll back.

Version 4 & 5: Employee Status and Performance Indexes

Finally, HR wants to track active versus inactive staff, and the database team noticed that searching by last name is getting slow.

Create 04-status-and-indexes.xml:

Remember to add all new files to your db.changelog-master.xml. The order of your include statements is the exact order Liquibase will execute them.

The Golden Rule: Never Modify Executed ChangeSets

Eventually, a developer on your team will look at your 01-create-employees.xml file and notice a mistake. Perhaps they spot a typo in a column name, or perhaps they realize a column is missing a strict non-null constraint.

Their instinct, based on years of writing standard Java code, will be to open that XML file, fix the mistake, save the file, and restart the application.

Let's actually do this and see what happens.

Open your src/main/resources/db/changelog/changes/01-create-employees.xml file. Change the first_name column to given_name:

Save the file and restart your Spring Boot application.

Instead of a smooth startup, your application will instantly crash, and your terminal will vomit a massive stack trace. Look closely at the top of the error logs. You should see this exact message:

Caused by: liquibase.exception.ValidationFailedException: Validation Failed:
     1 changesets check sum
          db/changelog/changes/01-create-employees.xml::1::ashutoshkrris was: 9:66e7dcffb2b1902a4e9f01670cb5f192 but is now: 9:2bd3ef21343d3b5c9448cc50bc35deef

Here's why this happens. Once a changeSet runs against an environment, it becomes immutable history. You can't change the past.

When Liquibase starts up, it calculates a cryptographic hash (an MD5 checksum) of your local XML file. It then queries the DATABASECHANGELOG table and compares the freshly calculated hash against the hash that was recorded when the file originally executed.

If you change even a single character in a file that has already been executed, the hash changes. Liquibase detects the tampering and refuses to start. It does this to protect your data. If your XML code says a column is named first_name but the database was originally built using fist_name, your Spring Data JPA repositories are going to fail anyway.

How to Fix It (The Right Way)

If you made this mistake locally, you might be tempted to go into your database, delete the row from the DATABASECHANGELOG table, and try again. Don't do this. If this code reaches staging or production, you can't manually delete rows on production servers.

The correct way to fix a schema mistake is to roll forward.

First, undo your change in 01-create-employees.xml so the hash matches the database again. Then, write a brand new changeSet to apply the fix:

Include it in your master changelog, restart the application, and the database will safely evolve to the correct state.

Working with Seed Data

Sometimes, a schema change requires initial data to be useful.

For example, in Version 3, we created a departments table. Right now, that table is completely empty. When a new developer clones the repository and spins up the project locally, they have to manually write SQL INSERT statements just to test the API.

We can automate this by making baseline data insertion part of our migration strategy.

Create a new file at src/main/resources/db/changelog/changes/05-seed-departments.xml:

Add the include statement to your db.changelog-master.xml file. When you restart the application, Liquibase will insert these rows. Your API is now instantly usable out of the box.

The Danger of Data Migrations

While seeding data is powerful, it requires discipline. Here is a practical engineering rule of thumb:

Do use Liquibase for:

Static lookup tables (status codes, country lists, default departments).
System configuration flags required for the application to boot.

Do NOT use Liquibase for:

Generating thousands of fake users for testing.
Migrating massive amounts of transactional data (for example, moving 5 million records from one table to another).

Large data migrations can lock up database tables for hours. If you lock a core table during a deployment, your application will experience a massive outage. Keep your changeSets focused on schema structure and essential baseline data. Use dedicated scripts or background jobs for heavy data manipulation.

Rollbacks

In a perfect world, code always works. In reality, you'll eventually deploy a database change that breaks a critical production query or corrupts data. When this happens, you need a way to hit the undo button.

Liquibase supports rollbacks, but you have to understand how it interprets them.

Automatic vs. Explicit Rollbacks

Many Liquibase commands are automatically reversible. For example, if you write a changeSet to or , Liquibase implicitly knows that the opposite of adding a column is dropping a column. You don't have to tell it how to undo these actions.

But some operations are inherently destructive or ambiguous. If you use custom tags, or if you use , Liquibase has no idea how to put the data back. In these cases, you must provide explicit rollback instructions.

Let's simulate a scenario where we add a temporary access code column, but we want to ensure we know exactly how to remove it safely.

Create 06-temporary-access.xml:

Add this to your master file and run the application. The column is added.

If you were deploying this via a CI/CD pipeline and the deployment failed, you could trigger a Liquibase Maven command to roll back by a specific number of steps (for example, mvn liquibase:rollback -Dliquibase.rollbackCount=1), or roll back to a specific tag we discussed earlier.

The Reality Check on Rollbacks

While it's important to know how rollbacks work, here's a practical reality from the trenches of backend engineering: Rollbacks are often discussed but rarely executed cleanly in production.

Dropping a column is mathematically easy. Recovering the customer data that was written to that column during the 15 minutes the bad code was live is incredibly difficult.

Because of this, modern engineering teams often prefer a "roll forward" strategy. If a migration causes an issue, instead of running a scary database rollback command, they quickly write a new changeSet that fixes the issue (for example, adding a missing index or relaxing a constraint) and deploy the application again.

It's highly recommended to design your database changes to be additive and non-destructive to avoid needing complex rollbacks in the first place.

Common Beginner Mistakes

Adopting database version control is a massive step forward for any engineering team, but it comes with a learning curve. When developers transition from writing loose SQL scripts to using Liquibase, they tend to fall into a few predictable traps.

Here are the most common beginner mistakes and exactly how to avoid them.

1. The "Mega" ChangeSet

When starting out, it's tempting to dump your entire initial schema into a single XML file under a single changeSet. You might put 15 createTable statements and 20 addForeignKeyConstraint statements into id="1".

This is a terrible idea for one simple reason: transaction failure.

If your database engine fails on table number 14 (perhaps due to a syntax error), what happens to the first 13 tables? Some database engines support transactional DDL (Data Definition Language), meaning it will roll back all 13 tables automatically. But many databases do not.

If it fails halfway through, your database is now in a fractured state. Liquibase didn't record id="1" as successful, so the next time you start the app, it will try to create all 15 tables again. It will immediately crash because table 1 already exists.

The Fix: Stick to the rule of "one logical operation per changeSet." If you're creating three tables, write three separate changeSets. If one fails, the successful ones are permanently recorded, and you only have to fix the broken one.

2. Manual Database Tweaking (The Phantom Menace)

This is the most dangerous habit to break. A developer spots a missing index in production. Instead of writing a Liquibase migration, going through code review, and deploying, they log directly into the production database and run CREATE INDEX manually to save time.

A week later, another developer writes a proper Liquibase migration to create that exact same index and deploys it. The application crashes on startup. Liquibase tries to execute the CREATE INDEX command, but the database throws an error saying the index already exists.

When you adopt Liquibase, you must accept a fundamental rule: Liquibase is the absolute source of truth for your schema. Human hands should never touch the database structure directly.

The Fix: If someone accidentally does this, you have two options to fix the deployment pipeline. You can manually drop the index from the database so Liquibase can recreate it properly, or you can use the tag in Liquibase to check if the index exists before trying to create it.

3. Ignoring the "From Scratch" Build

When you work on a project for months, your local database accumulates a lot of history. You write migrations assuming certain tables or test data already exist.

Then, a new developer joins the team. They pull the code, spin up an empty database, start Spring Boot, and the migrations crash halfway through.

This happens because the migrations rely on an assumed state (like expecting a specific row to exist before creating a foreign key) rather than a guaranteed state.

The Fix: You should regularly test your migrations against a completely blank database. If you're using Docker, tear down your database container and rebuild it. If you're using a file-based H2 database like we set up earlier, simply delete the ./data/employeedb.mv.db file from your project folder and restart Spring Boot. If the application can't boot successfully from a completely empty state, your migration history is broken.

4. Hardcoding Environment Details

Beginners sometimes hardcode environment-specific details directly into their XML files. For example, they might hardcode a specific schema name (schemaName="dev_schema") or grant permissions to a specific local user (GRANT ALL ON employees TO my_local_user).

When this code goes to staging, the staging database uses a different schema name, and the deployment fails.

The Fix: Keep your migrations abstract. Let Spring Boot handle the connection details via application.properties. If you absolutely must use dynamic values inside your Liquibase files, use property substitution. You can define variables in Liquibase and pass them in from Spring Boot during startup.

5. Messing Up Migration Ordering

Liquibase executes files in the exact order they're listed in your db.changelog-master.xml file.

If developer A creates the departments table in a branch, and developer B creates a foreign key linking to departments in another branch, whoever merges their code first dictates the order. If developer B's code gets included in the master file before developer A's code, Liquibase will try to create the foreign key before the target table exists.

The Fix: The master changelog is the ultimate chokepoint for database changes. During code reviews, always verify that the statements are ordered chronologically and that dependencies make sense.

Liquibase vs Flyway vs Manual SQL Scripts

When you decide to implement database version control, you'll immediately face a choice. Liquibase isn't the only tool in the Java ecosystem. The three most common approaches to managing schema evolution are Liquibase, Flyway, and manual SQL scripts.

You should understand the practical tradeoffs of each so you can choose the right tool for your specific team and project.

1. Manual SQL Scripts (The Baseline)

This is the default approach for most beginners. You write a script.sql file and execute it directly against the database using a tool like DBeaver, pgAdmin, or DataGrip.

Strengths: There is zero setup required. You have total control over the exact syntax, and every backend developer already knows how to write SQL.
Weaknesses: There's absolutely no execution tracking. This approach practically guarantees schema drift across environments. Deployments become stressful because they rely on humans remembering to execute the right scripts in the exact right order.
The Verdict: Manual scripts are perfectly fine for solo weekend projects or rapid prototyping where you don't care if the database gets destroyed. But they become a massive liability the moment a second developer joins the team or a staging environment is created.

2. Flyway (The SQL Purist)

Flyway is the most popular alternative to Liquibase. Instead of using XML or YAML abstractions, Flyway embraces raw SQL. You write pure SQL files with a strict naming convention (for example, V1__Create_employee_table.sql).

Strengths: There's no new syntax to learn. If you know SQL, you already know how to use Flyway. It's incredibly fast to set up, highly opinionated, and integrates flawlessly with Spring Boot.
Weaknesses: Because you write raw SQL, your migrations are intimately tied to your specific database dialect. If you write Flyway scripts for MySQL and later decide to migrate the project to PostgreSQL, you have to manually rewrite your migration history. Furthermore, seamless automated rollbacks are a paid feature in Flyway's commercial tier.
The Verdict: Flyway is excellent for teams that are highly skilled in SQL, are permanently committed to a single database vendor, and prefer strict conventions over flexible configurations.

3. Liquibase (The Abstraction Layer)

As we have seen throughout this tutorial, Liquibase takes a different approach by abstracting database changes into XML, YAML, or JSON.

Strengths: It's truly database-agnostic. You define the logical structure, and Liquibase automatically translates that into the correct SQL dialect for H2, PostgreSQL, or Oracle. It supports powerful automatic rollbacks, preconditions, contexts, and deployment labels out of the box for free.
Weaknesses: It has a steeper learning curve than Flyway. The XML syntax is undeniably verbose and can feel heavy for very simple, single-table applications.
The Verdict: Liquibase shines in complex applications, multi-tenant systems, projects that support multiple database vendors, and enterprise environments that require fine-grained control over CI/CD deployment pipelines.

Liquibase Best Practices

Now that you understand the mechanics of Liquibase, you need to know how to use it in a professional environment. Writing a migration that works on your local machine is only half the battle. Writing a migration that your entire team can safely deploy to production requires discipline.

Here are the engineering best practices you should adopt when managing database changes.

1. One Logical Change Per ChangeSet (The Atomic Rule)

We discussed this in the common mistakes section, but it's important enough to repeat. Never bundle a table creation, an index creation, and a data insertion into a single changeSet.

If you're adding a salary column and an idx_employee_salary index, put them in two separate changeSets within the same file. This ensures that if the index creation fails, the column creation is still safely recorded, and you don't end up in a fractured database state.

2. Meaningful File Organization and Naming

Don't name your files update1.xml or new_changes.xml. Your file names should tell a story about how your database evolved.

Adopt a strict prefix system. In our project, we used 01-create-employees.xml and 02-add-employee-email.xml. In a real team, you might use Jira ticket numbers or release versions (for example, v1.2.0_ticket-482_add_email.xml). Whatever convention you choose, enforce it rigorously during code reviews.

3. Treat Database Changes Like Application Code

Database migrations belong in source control right next to your Java code. They should be reviewed with the exact same level of scrutiny.

When reviewing a pull request that includes a Liquibase file, engineers should ask:

Does this column need an index?
Is this a destructive change (like renaming a column) that will break the currently running application?
Did the author include explicit rollback instructions for custom SQL?

4. Integrate Migrations into CI/CD

Human hands should never run database migrations against a production server. Your deployment pipeline should handle this automatically.

When you merge code into your main branch, your CI/CD pipeline (like GitHub Actions or GitLab CI) should build your Spring Boot application and deploy it. Because we bundled Liquibase into our Spring Boot startup sequence, the application will automatically migrate the production database before it starts accepting web traffic.

Here's what a safe, automated deployment pipeline looks like:

In a mature deployment pipeline, human hands never touch the production database. When you merge a pull request, the CI/CD pipeline builds the code and runs unit tests. It deploys the Spring Boot application to a staging environment, where Liquibase automatically acquires a lock and runs the migrations during startup. Once validated, that exact same artifact is promoted to production, triggering the identical automated migration process.

5. Never Fix Forward by Deleting History

If a migration fails in an upper environment (like staging or production), never log into the database to delete the DATABASECHANGELOG row so you can try again.

You must respect the immutability of the changelog. If you made a mistake, write a new changeSet that drops the broken table or fixes the data type, and push it through your Git workflow just like you would a Java bug fix.

Final Thoughts

Managing database schema changes doesn't have to be a source of anxiety.

By treating your database schema as code, you eliminate the chaos of manual SQL scripts. You prevent the dreaded "schema drift" where every developer's local machine behaves differently. Most importantly, you make your deployments predictable and boring (which is exactly what you want deployments to be).

In this tutorial, you built a practical Spring Boot application from scratch. You learned how Liquibase intercepts the application startup, locks the database, calculates cryptographic checksums, and safely applies incremental changes. You evolved a single table into a relational schema, added seed data, and learned how to avoid the most common traps beginners fall into.

The next time you start a Spring Boot project, don't reach for a manual SQL client. Add the Liquibase dependency, create your master changelog, and start version controlling your database from day one. Your future self (and your team) will thank you.

OpenFeign vs WebClient: How to Choose a REST Client for Your Spring Boot Project

Mario Casari — Thu, 05 Jun 2025 19:40:54 +0000

When building microservices with Spring Boot, you’ll have to decide how the services will communicate with one another. The basic choices in terms of protocols are Messaging and REST. In this article we’ll discuss tools based on REST, which is a common protocol for microservices. Two well-known tools are OpenFeign and WebClient.

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.

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 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.

How to Develop a CRUD App with Spring Boot, Neon Postgres, and Azure App Service

Abhinav Pandey — Fri, 26 Jul 2024 19:14:36 +0000

In this article, we'll explore how to develop a CRUD (Create, Read, Update, Delete) application using Spring Boot and Neon Postgres.

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

What is Neon Postgres?
How to Set Up the Database
- Create the Database
How to Build the Spring Boot CRUD App
How to Deploy on Azure App Service
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 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:///?sslmode=require
spring.datasource.username=
spring.datasource.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:

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

Selecting a branch from Neon project dashboard

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

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.

How to Perform Load Testing in Spring Boot with Gatling

Mario Casari — Mon, 08 Jul 2024 19:46:57 +0000

To evaluate the performance of a system, you need a tool that can simulate its behavior in production.

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.gatlinggroupId>
    <artifactId>gatling-appartifactId>
    <version>3.7.2version>
dependency>


<dependency>
    <groupId>io.gatling.highchartsgroupId>
    <artifactId>gatling-charts-highchartsartifactId>
    <version>3.7.2version>
dependency>    

<dependency>
    <groupId>com.github.javafakergroupId>
    <artifactId>javafakerartifactId>
    <version>0.15version>
dependency>

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

<plugin>
    <groupId>io.gatlinggroupId>
    <artifactId>gatling-maven-pluginartifactId>
    <version>4.2.9version>
    <configuration>
<simulationClass>com.codingstrain.springcloud.sample.libraryapp.books.BookSaveSimulationsimulationClass>
    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<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.

How to Implement an OAuth2 Resource Server with Spring Security

Kunal Nalawade — Wed, 08 May 2024 15:39:37 +0000

Hey everyone! Imagine you are building an awesome application, with lots of cool features. Picture a backend server at its core that hosts a majority of the business logic and exposes functionality through APIs.

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.

What is OAuth2?
How to Set Up the Spring Boot Application
Web Security Configuration
Public and Private APIs
Testing APIs with and without Access Token
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 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 extractClaim() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        Object principal = authentication.getPrincipal();
        Map 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!!

Learn App Development with Spring Boot 3

Beau Carnes — Tue, 19 Mar 2024 14:57:37 +0000

Spring Boot 3 is an advanced framework that simplifies the development of new Spring applications through convention over configuration, providing a range of out-of-the-box functionalities for building enterprise-grade applications efficiently.

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).

Learn Spring Boot and Spring Data JPA

Beau Carnes — Tue, 06 Feb 2024 16:05:20 +0000

By mastering Spring Boot and Spring Data JPA, you'll be equipped to build efficient, scalable, and secure applications with ease, making you a valuable asset in the job market and a more effective developer.

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).

How to Monitor Python APIs using Pyctuator and SpringBootAdmin

Sameer Shukla — Fri, 02 Sep 2022 15:02:51 +0000

Actuator endpoints help us monitor our services. By using actuators, we can gain a lot of information about what’s going on.

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.

How to Perform Integration Testing using JUnit 5 and TestContainers with SpringBoot

Sameer Shukla — Fri, 26 Aug 2022 15:46:39 +0000

TestContainers is a library that helps you run module-specific Docker containers to simplify Integration Testing.

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.

Spring Boot Tutorial – How to Build Fast and Modern Java Apps

freeCodeCamp — Mon, 20 Sep 2021 19:43:06 +0000

By Yiğit Kemal Erinç

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:

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.
The User entity that contains our user model and will have relations with Reservation.
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 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 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 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:


<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.0modelVersion>
    <parent>
        <groupId>org.springframework.bootgroupId>
        <artifactId>spring-boot-starter-parentartifactId>
        <version>2.4.4version>
        <relativePath />
    parent>
    <groupId>comgroupId>
    <artifactId>amenity-reservation-systemartifactId>
    <version>0.0.1-SNAPSHOTversion>
    <name>amenity-reservation-systemname>

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

    <dependencies>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-validationartifactId>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-data-jpaartifactId>
        dependency>
        <dependency>
            <groupId>com.h2databasegroupId>
            <artifactId>h2artifactId>
            <scope>runtimescope>
        dependency>
        <dependency>
            <groupId>org.springdocgroupId>
            <artifactId>springdoc-openapi-uiartifactId>
            <version>1.5.2version>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-devtoolsartifactId>
        dependency>
        <dependency>
            <groupId>org.projectlombokgroupId>
            <artifactId>lombokartifactId>
            <version>1.18.20version>
            <scope>providedscope>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-testartifactId>
            <scope>testscope>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-thymeleafartifactId>
        dependency>

    dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.bootgroupId>
                <artifactId>spring-boot-maven-pluginartifactId>
            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.


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

    <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:

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 Systema>
    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.

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

    <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 Amenitya>
    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:

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

    <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">Amenityth>
                    <th scope="col">Dateth>
                    <th scope="col">Start Timeth>
                    <th scope="col">End Timeth>
                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 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>


<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:

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

    <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">Amenityth>
              <th scope="col">Dateth>
              <th scope="col">Start Timeth>
              <th scope="col">End Timeth>
            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>

        
        <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">×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"
                  >Amenitylabel
                >
                <div class="col-10">
                  <select
                    class="form-control"
                    id="type-select"
                    th:field="*{amenityType}"
                  >
                    <option value="POOL">POOLoption>
                    <option value="SAUNA">SAUNAoption>
                    <option value="GYM">GYMoption>
                  select>
                div>
              div>
              <div class="form-group row">
                <label for="start-date" class="col-2 col-form-label"
                  >Datelabel
                >
                <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"
                  >Fromlabel
                >
                <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">Tolabel>
                <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 pmsmall>
                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 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.bootgroupId>
    <artifactId>spring-boot-starter-securityartifactId>
dependency>

<dependency>
    <groupId>org.thymeleaf.extrasgroupId>
    <artifactId>thymeleaf-extras-springsecurity5artifactId>
    <version>3.0.4.RELEASEversion>
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 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:

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 Systema>
    div>
        <a sec:authorize="isAnonymous()"
           class="navbar-brand text-color" th:href="@{/login}">Log ina>
        <a sec:authorize="isAuthenticated()"
               class="navbar-brand text-color" th:href="@{/logout}">Log outa>
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 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.

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)
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 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.

How to Generate an Excel Report in a Spring Boot REST API with Apache POI and Kotlin

freeCodeCamp — Tue, 08 Dec 2020 01:54:41 +0000

By Piotr Wolak

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 {
        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 {
        val report = reportService.generateXlsxReport()

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

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

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

    private fun createResponseEntity(
        report: ByteArray,
        fileName: String
    ): ResponseEntity =
        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.

COM Interface API Tutorial: Java Spring Boot + JACOB Library

freeCodeCamp — Wed, 30 Sep 2020 05:07:17 +0000

By Serhii Povisenko

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:

Name	In/out	Type	Description
address	In	String	provided integration server IP
AccountID	In	String	provided unique GUID string
LoginID	Out	String	GUID string used for Logon API call
Error	Out	String	Error description
Outcome	Out	Integer	-1 = Refer to error 1 = Successful initialise awaiting logon 2 = Unable to connect to server due to absent server, or incorrect details 3 = Unmatched AccountID 4 = Autologon successful
SessionID	Out	String	GUID used for subsequent interactions (if auto log in successful)

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:

Name	In/out	Type	Description
LoginID	In	String	The login id returned by the initialization method Initialise with ID
username	In	String	provided API username
password	In	String	provided API password
SessionID	Out	String	GUID used for subsequent interactions (if logon successful)
Error	Out	String	Error description
Outcome	Out	Integer	-1 = Technical error 1 = Successful 2 = Expired 3 = Unsuccessful 4 = Invalid login ID or login ID does not have access to this product

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:

Name	In/out	Type	Description
SessionID	In	String	The session id returned by the logon method
MatchTerm	In	String	Search term
MatchedList	Out	String	XML conforming to provided corresponding XSD scheme
SessionID	Out	String	GUID used for subsequent interactions (if logon successful)
Error	Out	String	Error description
Outcome	Out	Integer	-1 = Technical error 1 = Users found 2 = Access denied 3 = No users

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> 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> 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> 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> getSessionId(String accountId, String username, String password);
}

@Service
@RequiredArgsConstructor
public class SessionIDServiceImpl implements SessionIDService {

    private final DllApiService dll;

    @Override
    public Mono> 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 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 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 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 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 handleT3(Tuple3 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 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 errors;

        private Response(Set 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.pluginsgroupId>
   <artifactId>maven-install-pluginartifactId>
   <executions>
      <execution>
         <id>install-jacobid>
         <phase>validatephase>
         <configuration>
            <file>${basedir}/libs/jacob-1.19/jacob.jarfile>
            <repositoryLayout>defaultrepositoryLayout>
            <groupId>net.sf.jacob-projectgroupId>
            <artifactId>jacobartifactId>
            <version>1.19version>
            <packaging>jarpackaging>
            <generatePom>truegeneratePom>
         configuration>
         <goals>
            <goal>install-filegoal>
         goals>
      execution>
   executions>
plugin>

That will let you easily add the dependency as usual:

<dependency>
   <groupId>net.sf.jacob-projectgroupId>
   <artifactId>jacobartifactId>
   <version>1.19version>
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> 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         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 invoke(COM_API_Method method, Function 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!

How to Set Up Java Spring Boot JWT Authorization and Authentication

freeCodeCamp — Wed, 12 Aug 2020 20:00:00 +0000

By Yiğit Kemal Erinç

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:

Create our Authentication Filter that extends UsernamePasswordAuthenticationFilter
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. :)

Use Spring Boot and Java to create a Rest API (Tutorial)

Beau Carnes — Wed, 15 Jul 2020 15:07:17 +0000

Rest APIs are used all over the place. If you are learning the Spring Boot Java-based framework, you will need to know how to create one. We've released a full video course that will teach you how to create a Rest API using Spring Boot.

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).

Spring Boot Tutorial - Learn the popular Java framework

Beau Carnes — Fri, 06 Sep 2019 14:53:10 +0000

Learn Spring Boot in this full course for beginners from Amigoscode. Spring Boot is an amazing framework for building Java applications. It makes it easy to create stand-alone, production-grade Spring based Applications that you can "just run".

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).

spring-boot - freeCodeCamp.org

Database Version Control with Liquibase and Spring Boot

Why Database Version Control Matters

What is Liquibase?

Project Setup

Understanding Core Liquibase Concepts

Create the Initial Employee Schema (Version 1)

What Just Happened?

Inspecting the Database: Liquibase Metadata Tables

The DATABASECHANGELOG Table

The DATABASECHANGELOGLOCK Table

Evolving the Employee API

Version 2: Adding an Email Field

Version 3: Adding Departments Support

Version 4 & 5: Employee Status and Performance Indexes

The Golden Rule: Never Modify Executed ChangeSets

How to Fix It (The Right Way)

Working with Seed Data

The Danger of Data Migrations

Rollbacks

Automatic vs. Explicit Rollbacks

The Reality Check on Rollbacks

Common Beginner Mistakes

1. The "Mega" ChangeSet

2. Manual Database Tweaking (The Phantom Menace)

3. Ignoring the "From Scratch" Build

4. Hardcoding Environment Details

5. Messing Up Migration Ordering

Liquibase vs Flyway vs Manual SQL Scripts

1. Manual SQL Scripts (The Baseline)

2. Flyway (The SQL Purist)

3. Liquibase (The Abstraction Layer)

Liquibase Best Practices

1. One Logical Change Per ChangeSet (The Atomic Rule)

2. Meaningful File Organization and Naming

3. Treat Database Changes Like Application Code

4. Integrate Migrations into CI/CD

5. Never Fix Forward by Deleting History

Final Thoughts

OpenFeign vs WebClient: How to Choose a REST Client for Your Spring Boot Project

Table of Contents

Introduction to OpenFeign

Introduction to WebClient

Main Differences

Programming Model

Synchronous/Asynchronous Calls

Integration with Spring Cloud

Boilerplate Code

Error Handling

Performance Considerations

Use Cases

Conclusion

How to Develop a CRUD App with Spring Boot, Neon Postgres, and Azure App Service

Here's what we'll cover:

Prerequisites

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

Create a User

Get Users

How to Set Up Autoscaling

Autoscaling in Azure

Autoscaling in Neon

How to Configure Database Branches in Neon

Summary

How to Perform Load Testing in Spring Boot with Gatling

Main Concepts

Spring Boot Gatling Integration

Load Test Implementation

How to Run the Test

The `DATABASECHANGELOG` Table

The `DATABASECHANGELOGLOCK` Table