jimena-garbarino

Jimena is an experienced result and value-oriented programmer with a strong engineering background. She excels with Ruby on Rails, Java, and Scrum development. She has worked in web development for 10+ years in many industries and has a master's degree in software engineering from Universidad de Buenos Aires.

Spring Cloud Developer

Jimena Garbarino

Deploy a cloud-native Java Spring Boot microservice stack secured with Auth0 on Google GKE using Terraform and Kubernetes.

Deploy Secure Spring Boot Microservices on Google GKE Using Terraform and Kubernetes

Deploy a cloud-native Java Spring Boot microservice stack secured with Auth0 on Azure AKS using Terraform and Kubernetes.

Deploy Secure Spring Boot Microservices on Azure AKS Using Terraform and Kubernetes

How to add Fine-Grained Authorization (FGA) to a Spring Boot API using the OpenFGA Spring Boot starter.

OpenFGA for Spring Boot Applications

Implementing OpenID Connect authentication in Java Web Applications with Okta Spring Boot Starter and Spring Security support for Authorization Code Flow with PKCE

Proof Key for Code Exchange (PKCE) in Web Applications with Spring Security

Learn how to use Spring Boot, Java, and Auth0 to secure a feature-complete API by implementing authorization in Spring Boot with Auth0.

Add Security and Authorization to a Java Spring Boot API

deepu-sasidharan

Deepu is a polyglot developer, Java Champion, and OSS aficionado. He mainly works with Java, JS, Rust, and Golang. He co-leads JHipster and created the JDL Studio and KDash. He's a Principal Developer Advocate at Okta. He is also an international speaker and a published author.

Principal Developer Advocate

Deepu K Sasidharan

Passkeys and WebAuthn for Java developers. Learn how to get started with passkeys for your Java and Spring Boot applications.

A Passwordless Future: Passkeys for Java Developers

A step-by-step guide for building a secured GraphQL API with Spring Boot and Auth0 authentication in React

How to Build a GraphQL API with Spring Boot

matt-raible

Matt Raible is a well-known figure in the Java community and has been building web applications for most of his adult life. For over 20 years, he has helped developers learn and adopt open source frameworks and use them effectively. He's a web developer, Java Champion, and Developer Advocate at Okta. Matt is a frequent contributor to open source and a big fan of Java, IntelliJ, TypeScript, Angular, and Spring Boot. 

Developer Advocate

Matt Raible

Learn how to build a secure CRUD app with Spring Boot and Angular. You'll use Auth0 for authentication and authorization and Cypress to verify it all works.

Build a Beautiful CRUD App with Spring Boot and Angular

This tutorial shows you how to build a microservices architecture with Spring Boot and Spring Cloud.

Java Microservices with Spring Boot and Spring Cloud

A walk-through of building a microservices architecture with JHipster, Keycloak, Auth0, and Google Kubernetes Engine (GKE) deployment.

Identity in Spring Boot with Kubernetes, Keycloak, and Auth0

Deploy a cloud-native Java Spring Boot microservice stack secured with Auth0 on Amazon EKS using Terraform and Kubernetes.

Deploy Secure Spring Boot Microservices on Amazon EKS Using Terraform and Kubernetes

Learn how to add Auth0 to your Spring Boot application using the Okta Spring Boot Starter.

## Introducing the Okta Spring Boot Starter

In this quick tutorial, you will learn how to add authentication to your Java Spring Boot application using the [Okta Spring Boot Starter](https://github.com/okta/okta-spring-boot) with Auth0 as the Identity Provider (IdP). The Okta Spring Boot Starter makes adding authentication to your Spring Boot application easy and configures the required classes and best practices, so you don't have to worry about them. The starter uses the OAuth 2.0 and OpenID Connect protocols to authenticate users. The starter is compatible with Spring Boot 3.0 and above. You can use the starter with Okta and Auth0 as the IdP starting from version 3.0.3.

## Prerequisites

Before you get started, you will need the following:

- Java 17 or higher. You can use [SDKMAN!](https://sdkman.io/) to install Java if you don't have it already.
- A free Auth0 account. [Sign up](https://a0.to/blog_signup) if you don't have one already.
- The Auth0 CLI. [Install](https://github.com/auth0/auth0-cli#installation) the CLI if you don't have it and log in to your Auth0 account using the `auth0 login` command.

## Create a Spring Boot Application

Create a new Spring Boot application using the [Spring Initializr](https://start.spring.io/). You can use the web version or the curl command below. Use the default for most of the options. For the dependencies, select `web`, `thymeleaf`, and `okta`. For the build tool, select `Gradle`.

```bash
curl https://start.spring.io/starter.tgz \
  -d bootVersion=3.1.0 \
  -d javaVersion=17 \
  -d dependencies=web,thymeleaf,okta \
  -d type=gradle-project \
  -d baseDir=auth0-sample \
 | tar -xzvf -
```

You can also use the [Spring Boot CLI](https://docs.spring.io/spring-boot/docs/current/reference/html/cli.html) to create the application using the following command:

```bash
spring init \
   -b 3.1.0 \
   --build gradle -t gradle-project \
   -l java -j 17 \
   -p jar \
   -d web,thymeleaf,okta
```

The `web` dependency provides Spring Web MVC with basic HTTP REST functionality. The `thymeleaf` dependency provides the Thymeleaf templating engine with which you will build the web pages. The `okta` dependency provides the Okta Spring Boot Starter, which provides the required dependencies and configuration to add OIDC authentication to your application.

### Add a Web Controller

Open the created starter application in your favorite IDE. Add a simple web controller to the application. Create a new file `src/main/java/com/example/demo/HomeController.java` with the following content:

```java
package com.example.demo;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class HomeController {
    @GetMapping("/")
    String home() {
        return "home";
    }
}
```

This controller will handle requests to the `/` path and render the `home` template. Create a template using Thymeleaf that uses [Tailwind CSS](https://tailwindcss.com/) for styling. Add a new file, `src/main/resources/templates/home.html`, with the following content:

```html
<html xmlns:th="http://www.thymeleaf.org">
  <head>
    <title>Home</title>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />

    <script src="https://cdn.tailwindcss.com"></script>
  </head>
  <body id="samples">
    <div class="relative flex min-h-screen flex-col justify-center overflow-hidden bg-gray-50 py-2">
      <div class="relative bg-white p-8 shadow-xl ring-1 ring-gray-900/5 sm:mx-auto sm:rounded-lg">
        <div class="mx-auto">
          <div class="divide-y divide-gray-300/50">
            <div class="space-y-6 py-8 text-base leading-7 text-gray-600">
              <h2 class="text-3xl font-bold">
                Auth0 Universal Login + Spring Boot Example
              </h2>
            </div>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>
```

If you run the application using `./gradlew bootRun`, you will see a login page from the Okta Spring Boot starter instead of your home screen. This is OK, and you will be able to configure this soon. You can comment out the `okta-spring-boot-starter` dependency in the `build.gradle` file if you want to run the application at this point.

## Configure OIDC authentication with Auth0

Let us configure the application to use Auth0 as the IdP. You can use the Auth0 CLI to create a new application. Run the following command to create a new application:

```bash
auth0 apps create \
  --name "Auth0 Spring Boot Sample" \
  --description "Auth0 Spring Boot Sample" \
  --type regular \
  --callbacks http://localhost:8080/login/oauth2/code/okta \
  --logout-urls http://localhost:8080 \
  --reveal-secrets
```

The `--type` option specifies that you use a regular web application. The `--callbacks` option specifies the callback URL for the application. The `--logout-urls` option specifies the logout URL for the application. The `--reveal-secrets` option will display the client secret in the output. You can also use the `auth0 apps update` command to update the application with the callback and logout URLs.

Note down the Auth0 issuer (for example, `https://dev-12345678.us.auth0.com/`), `CLIENT ID`, and `CLIENT SECRET` from the output. You will use these values in the next step.

### Configure the Spring Boot application

Configure the application by updating the `src/main/resources/application.properties` file with the following content:

```yaml
# trailing `/` is important for issuer URI
okta.oauth2.issuer=https://YOUR_AUTH0_ORG_URI/
okta.oauth2.client-id=YOUR_AUTH0_CLIENT_ID
```

> NOTE: The client secret is not added in this file since the file will be committed to git, and it will expose your client secret. You can use the `OKTA_OAUTH2_CLIENT_SECRET` environment variable to provide the client secret securely.
> You can execute `OKTA_OAUTH2_CLIENT_SECRET=YOUR_AUTH0_CLIENT_SECRET ./gradlew bootRun` to run the application with the environment variable.

Create a new class `src/main/java/com/example/demo/SecurityConfiguration.java` with the following content:

```java
package com.example.demo;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.logout.LogoutHandler;
import org.springframework.security.web.util.matcher.AntPathRequestMatcher;
import java.io.IOException;

@Configuration
@EnableMethodSecurity(securedEnabled = true)
public class SecurityConfiguration {

    @Value("${okta.oauth2.issuer}")
    private String issuer;
    @Value("${okta.oauth2.client-id}")
    private String clientId;

    LogoutHandler oidcLogoutHandler() {
        return (request, response, authentication) -> {
            try {
                response.sendRedirect(issuer + "v2/logout?client_id=" + clientId + "&returnTo=http://localhost:8080/");
            } catch (IOException e) {
                throw new RuntimeException(e);
            }
        };
    }

    @Bean
    public SecurityFilterChain configure(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests((requests) -> requests
            // allow anonymous access to the root page
            .requestMatchers("/").permitAll()
            // authenticate all other requests
            .anyRequest().authenticated());
        // configure logout handler
        http.logout(logout -> logout.logoutRequestMatcher(new AntPathRequestMatcher("/logout"))
                .addLogoutHandler(oidcLogoutHandler()));
        // enable OAuth2/OIDC
        http.oauth2Login(withDefaults());

        return http.build();
    }
}
```

The `oidcLogoutHandler()` method configures the logout redirect URL for the application. The `configure()` method configures the application to use OAuth 2.0 and OIDC authentication using Spring Security.

Next, add the `thymeleaf-extras-springsecurity6` dependency to the dependencies section of the `build.gradle` file:

```groovy
dependencies {
    ...
    implementation 'org.thymeleaf.extras:thymeleaf-extras-springsecurity6:3.1.1.RELEASE'
}
```

Next, add the following snippet to the `src/main/resources/templates/home.html` file to add login/logout buttons and welcome messages:

```html
<div class="space-y-6 py-8 text-base leading-7 text-gray-600">
    <h2 class="text-3xl font-bold">Auth0 Universal Login + Spring Boot Example</h2>
    <div th:unless="${#authorization.expression('isAuthenticated()')}">
        <p>Hello!</p>
        <p>If you're viewing this page, then you have successfully configured and started this example
            server.</p>
        <p>This example shows you how to use the 
            <a href="https://github.com/okta/okta-spring-boot" class="text-blue-500">Okta Spring Boot
            Starter</a> to add the Authorization Code Flow using Auth0 to your application.</p>
        <p>When you click the login button below, you will be redirected to the login page on your Auth0
            org. After you authenticate, you will be returned to this application.</p>
    </div>

    <div th:if="${#authorization.expression('isAuthenticated()')}">
        <p>Welcome home, 
            <span th:text="${#authentication.principal.attributes['name']}">Joe Coder</span>!</p>
        <p>You have successfully authenticated against your Auth0 org, and have been redirected back to
            this application.</p>
        <p>Visit the <a th:href="@{/profile}">Profile</a> page in this application to view the
            information retrieved with your OAuth Access Token.</p>
    </div>
</div>
<div class="pt-8 text-base font-semibold leading-7">
    <form method="get" th:action="@{/oauth2/authorization/okta}"
            th:unless="${#authorization.expression('isAuthenticated()')}">
        <button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded-full leading-6"
                type="submit">Login
        </button>
    </form>
    <form method="post" th:action="@{/logout}" th:if="${#authorization.expression('isAuthenticated()')}"
            class="d-flex" style="margin-block-end: inherit">
        <input type="hidden" th:name="${_csrf.parameterName}" th:value="${_csrf.token}"/>
        <button class="bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded-full leading-6"
                type="submit">Logout
        </button>
        <a th:href="@{/profile}" class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded-full leading-6">Profile</a>
    </form>
</div>
```

The `th:if` and `th:unless` attributes are used to display the login/logout buttons and welcome messages based on the user authentication status using the Spring Security [SpEL expressions](https://docs.spring.io/spring-framework/docs/3.0.x/reference/expressions.html).

## Run the application

To run the application, execute the following command:

```bash
OKTA_OAUTH2_CLIENT_SECRET=YOUR_AUTH0_CLIENT_SECRET ./gradlew bootRun
```

The application should start successfully, and you should see the following output:

```bash
...

2023-03-09T18:37:27.829+01:00  INFO 120974 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2023-03-09T18:37:27.834+01:00  INFO 120974 --- [           main] com.example.demo.DemoApplication         : Started DemoApplication in 1.876 seconds (process running for 2.019)
```

Navigate to `http://localhost:8080` in your browser. You should see the login button.

![Home Screen](https://images.ctfassets.net/23aumh6u8s0i/2sbFd8TqxEd7mEmD0lLSj9/28264a293383683227a9a9fa6a456882/auth0-spring-boot-homepage.png)


Click on the **Login** button to be redirected to the Auth0 login page. Once you log in with your Auth0 credentials, you should be redirected back to the application and see the welcome message.

![Welcome Screen](https://images.ctfassets.net/23aumh6u8s0i/01lYjhhZ7xlZIyVt151CqG/6ecb0dbcbb68312a2ba33903b3917d80/auth0-spring-boot-welcome.png)

You should also be able to log out by clicking the logout button.

## Add a Profile Page

Now that you have successfully configured the application to use Auth0 for authentication, let's add a profile page to display the information retrieved from the Auth0 `/userinfo` endpoint. The starter automatically retrieves info from this endpoint.

Add the following snippet to the `src/main/java/com/example/demo/HomeController.java` file:

```java
@GetMapping("/profile")
@PreAuthorize("hasAuthority('SCOPE_profile')")
ModelAndView userDetails(OAuth2AuthenticationToken authentication) {
    return new ModelAndView("profile", Collections.singletonMap("details", authentication.getPrincipal().getAttributes()));
}
```

The `@PreAuthorize("hasAuthority('SCOPE_profile')")` annotation ensures that the `/profile` route cannot be accessed until you have authenticated and have the scope `profile` in your claims. The `userDetails` method retrieves the user information from the `OAuth2AuthenticationToken` and passes it to the `profile.html` template.

Add the following imports to the `src/main/java/com/example/demo/HomeController.java` file:

```java
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.oauth2.client.authentication.OAuth2AuthenticationToken;
import org.springframework.web.servlet.ModelAndView;
```

Now create a new file, `src/main/resources/templates/profile.html` and add the following snippet:

```html
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>Home</title>
    <meta charset="utf-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>

    <script src="https://cdn.tailwindcss.com"></script>
</head>
<body id="samples">

<div class="relative flex min-h-screen flex-col justify-center overflow-hidden bg-gray-50 py-2">
    <div class="relative bg-white p-8 shadow-xl ring-1 ring-gray-900/5 sm:mx-auto sm:rounded-lg">
        <div class="mx-auto">
            <div class="divide-y divide-gray-300/50">
                <div class="space-y-6 py-8 text-base leading-7 text-gray-600">
                    <div>
                        <img class="w-10 h-10 rounded-full" th:src="${details['picture']}" alt="Rounded avatar">
                        <h2>My Profile</h2>
                        <p>Hello, <span th:text="${#authentication.principal.attributes['name']}">Joe Coder</span>.
                            Below is the information that was read with your
                            <a href="https://developer.okta.com/docs/api/resources/oidc.html#get-user-information">Access
                                Token</a>.
                        </p>
                        <p>This route is protected with the annotation 
                            <code>@PreAuthorize("hasAuthority('SCOPE_profile')")</code>,
                            which will ensure that this page cannot be accessed until you have authenticated and have
                            the scope <code>profile</code>.</p>
                    </div>

                    <table class="table table-striped">
                        <thead>
                        <tr>
                            <th>Claim</th>
                            <th>Value</th>
                        </tr>
                        </thead>
                        <tbody>
                        <tr th:each="item : ${details}">
                            <td th:text="${item.key}">Key</td>
                            <td th:id="${'claim-' + item.key}" th:text="${item.value}">Value</td>
                        </tr>
                        </tbody>
                    </table>
                </div>
            </div>
        </div>
    </div>
</div>
</body>
</html>
```

Restart the application and navigate to `http://localhost:8080/profile`. You should see the profile page.

![Profile Screen](https://images.ctfassets.net/23aumh6u8s0i/27l3wLDsHOXD4qWBwcsdy5/369655bdaa7326fb5540bb23eecbf938/auth0-spring-boot-profile.png)

You have successfully configured a Spring Boot application to use Auth0 for authentication. Congrats!

## Use the application as a resource server

Let's go further and use the application as a resource server.

First, add the below snippet to the end of the `configure` method in `src/main/java/com/example/demo/SecurityConfigurations.java` file:

```java
...
// enable Resource Server for API access
http.oauth2ResourceServer(oauth2ResourceServer -> oauth2ResourceServer.jwt(withDefaults()));

return http.build();
```

Next, add a new Rest Controller, `src/main/java/com/example/demo/ResourceController.java`, with the following code

```java
package com.example.demo;

import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ResourceController {
    @GetMapping("/hello")
    String sayHello(@AuthenticationPrincipal Jwt jwt) {
        return String.format("Hello, %s!", jwt.getSubject());
    }
}
```

The `@AuthenticationPrincipal` annotation injects the `Jwt` object into the `sayHello` method. The `Jwt` object contains the claims from the access token.

Add the audience property, for example `https://dev-12345678.us.auth0.com/api/v2/`, to the `src/main/resources/application.properties` file:

```yaml
okta.oauth2.audience=YOUR_AUTH0_ORG_URI/api/v2/
```

Restart the application and try to CURL `http://localhost:8080/hello`. You should see a 401 error message.

```bash
curl -i http://localhost:8080/hello

HTTP/1.1 401
Set-Cookie: JSESSIONID=CC2260CB52A514AEE7DFC326A0CAFE92; Path=/; HttpOnly
WWW-Authenticate: Bearer
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 0
Date: Thu, 09 Mar 2023 18:33:53 GMT
```

Now let's create a token to access this API using the Auth0 CLI.

```bash
auth0 test token -a YOUR_AUTH0_ORG_URI/api/v2/ # for example https://dev-12345678.us.auth0.com/api/v2/
```

Save the access token as an environment variable and try to access the API again using the token.

```bash
TOKEN=YOUR_ACCESS_TOKEN

curl -i --header "Authorization: Bearer $TOKEN" http://localhost:8080/hello
```

You can also use [HTTPie](https://httpie.io/) or [xh](https://github.com/ducaale/xh) instead of curl.

And that's it! You have successfully configured a Spring Boot application to use Auth0 as a resource server.

You can find the complete code from this tutorial on [GitHub](https://github.com/okta-samples/auth0-spring-boot-sample). 

In these blog posts, you can learn more about using the Okta Spring Boot starter.

- [Build a Beautiful CRUD App with Spring Boot and Angular](https://auth0.com/blog/spring-boot-angular-crud/)
- [Build a Simple CRUD App with Spring Boot and Vue.js](https://auth0.com/blog/build-crud-spring-and-vue/)
- [Use React and Spring Boot to Build a Simple CRUD App](https://auth0.com/blog/simple-crud-react-and-spring-boot/)

You can also sign up for our [newsletter](https://a0.to/nl-signup/java) to stay updated on everything Identity and Security.

Get started with Spring Boot and Auth0

React is one of the most popular JavaScript frameworks, and Spring Boot is wildly popular in the Java ecosystem. This article shows you how to use them in the same app and secure it all with Okta.

Use React and Spring Boot to Build a Simple CRUD App

Learn how to build a Spring Boot application that authenticates against Okta and Auth0 with Spring Security's SAML support.

Get Started with Spring Boot and SAML

andrew-hughes

Andrew is a senior web app developer with 15+ years of experience and solid expertise with React, Node, and React Native, as well as tons of SQL/NoSQL knowledge. He has performed complicated back-end API integrations for clients, including payment platforms like Stripe and PayPal along with InfusionSoft and WordPress. His extensive professional background also includes working with PHP, Laravel, Java, and Swift/iOS.

Andrew Hughes

Learn how to use Java and embedded Jetty to create a simple servlet-based web service. Then see how to do it with Spring Boot.

Get Started with Jetty, Java, and OAuth

Create a CRUD (create, read, update, and delete) application using Spring Boot and Vue.js.

Build a Simple CRUD App with Spring Boot and Vue.js

Use JHipster to build a photo-sharing app for web and mobile that has a React front-end with OIDC authentication and a Spring Boot back-end with OAuth2 authorization.

Integrate React Native and Spring Boot Securely

Build an Ionic + Angular frontend for your Spring Boot backend, all using the power of JHipster! Secured by OpenID Connect.

Build Secure Ionic Apps with Angular and JHipster

The newly released JHipster Native blueprint allows you to generate Spring Boot projects with Spring Native support.

Introducing Spring Native for JHipster: Serverless Full-Stack Made Easy

This tutorial shows you how to create a slick-looking, full-stack, secure application using React, Spring Boot, and JHipster.

Full Stack Java with React, Spring Boot, and JHipster

joey devilla headshot 900px

I’m a Senior Developer Advocate at Auth0, and I like to work on various technologies. I’ve developed software for all sorts of platforms, from CD-ROM and the PalmPilot to my current area of focus, mobile phones, IoT devices, and AI. When I’m not looking for strange new platforms to write software for, I’m playing a strange old instrument — the accordion!

Senior Developer Advocate

Joey deVilla

See how easy it is to bootstrap a CRUD API with Spring Initializr, build it with Spring Boot and Kotlin, and secure it with Auth0.

Build and Secure an API with Spring Boot and Kotlin

tadej-slamic

With over a decade in the software industry, I've helped startups launch their first product, assisted FTSE100 enterprises with digital transformation, been a part of the fintech boom, and helped particle accelerators cool down. I enjoy architecting and creating scalable backends and crafting modern mobile, web, and desktop apps.

CTO at Shortcut AS

Tadej Slamic

Learn how to use Spring Boot, Java, and Auth0 to secure a feature-complete API. Learn how to use Auth0 to implement authorization in Spring Boot.

Spring Boot Authorization Tutorial: Secure an API (Java)

apoorv-tyagi-author

I write about algorithmic solutions for software engineering problems, interesting programming tips, tricks & resources. May also include machine learning, NLP & Blockchain.

Software Engineer

Apoorv Tyagi

Learn how you can integrate ELK stack with your Spring Boot application for logs aggregation and monitoring in a centralized way.

Spring Boot Logs Aggregation and Monitoring Using ELK Stack

500x500

I'm a software engineer, but I prefer to call myself Technology Bishop. Spreading knowledge through writing is my mission.

Antonello Zanini

Learn how to implement custom error handling logic in Spring Boot. You will see two approaches based on the @ControllerAdvice annotation. Similarly, you will learn how to deal with authentication and access denied errors in Spring Security.

Get Started with Custom Error Handling in Spring Boot (Java)

maniish_jaiin

I am Manish and I am a Software Engineer by profession. I have been writing on Medium for a year now. I write majorly because it fulfills my desire to share my knowledge and gives me a creativity boost. <br> 
I write on a variety of topics like Software Engineering, Tech, Programming, Developer Productivity, Apple Products, and a few more. I have worked at ThoughtWorks and BCG Digital Ventures and I am currently living in Berlin. 

Manish Jain

Learn how to simulate AWS services locally using LocalStack with a Spring Boot application.

**TL;DR:** This article demonstrates the use of LocalStack and how it can simulate many of the AWS services locally. We will use Spring Cloud Messaging to create a publisher-subscriber sample application. We will use Amazon SNS and SQS to do that.

The sample app can be found [here](https://github.com/maniish-jaiin/spring-cloud-messaging-sample).

## Spring Cloud Messaging With AWS and LocalStack

### Introduction

With an ever-growing demand for cloud services, Spring provides amazing support to integrate with Cloud providers and relevant services. [Spring Cloud for Amazon Web Services](https://spring.io/projects/spring-cloud-aws) is one such project that makes it easy to integrate with AWS services using familiar Spring APIs.

In this article, we will look into a simple application that acts as a message producer and a consumer using Amazon SNS and SQS. On top of that, we will not create an AWS account or use AWS services directly from AWS. We will instead use LocalStack, which will allow us to create AWS resources locally.

The sample app can be found [here](https://github.com/maniish-jaiin/spring-cloud-messaging-sample).

### Pre-requisites:

1. Basic knowledge of AWS, [AWS CLI](https://github.com/aws/aws-cli), and related services like Amazon SQS.
2. Basic knowledge of [Java 11](https://docs.oracle.com/en/java/javase/11/docs/api/index.html) and Spring Boot `2.4.7`.
3. [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) for the setup.

## Introduction to Amazon SNS and SQS

### Amazon SNS

[Amazon SNS](https://aws.amazon.com/sns/) is an acronym for Simple Notification Service. It provides developers with the highly scalable, cost-effective, and flexible capability to publish messages from an application and send them to other applications. It follows the pub-sub architecture to deliver messages from publishers to the subscribers. It is a highly decoupled service that can be linked to a variety of sources. It can be used to publish emails, messages to SQS, SMS, etc.

The Publisher (e.g., CloudWatch Alarm, S3 events, SNS, Micro-service) publishes the message on a Topic which is then published to all the Subscribers (web servers, email addresses, Amazon SQS queues, AWS Lambda)  of that particular topic.

![SNS Architecture](https://images.ctfassets.net/23aumh6u8s0i/35P87aEWHIcpTOQxYTGWbz/03840ff6c13fdc4a94552ec8188c131e/sns_architecture.jpg)

### Amazon SQS

[Amazon SQS](https://aws.amazon.com/sqs/) is an acronym for Simple Queue Service, and the names convey a lot as it is really simple to use as it is a fully managed service from AWS. It follows similar messaging semantics of the producer putting a message on the queue and consumer reading from it.

Once consumed, the message has to be deleted from the queue. Deleting is important because SQS assumes that processing can fail. To prevent that, after the consumer receives a message, it is hidden from the queue for a defined period of time, and after that, if it is not deleted, the message shows up in the queue again.

Both SNS and SQS are fully managed lightweight, easy-to-use APIs. You can use Amazon SQS and SNS to decouple and scale microservices, distributed systems, and serverless applications and improve reliability.

### Introduction to LocalStack

[LocalStack](https://github.com/localstack/localstack) is an open-source mock of the real AWS services. It provides a testing environment on our local machine with the same APIs as the real AWS services. We switch to using the real AWS services only in the integration environment and beyond. There are plenty of reasons to use LocalStack, few out of which are more important than others, such as:

1. The ability to play with AWS services without interacting with AWS. All developers love to get their hands dirty, and what better way to learn something than to try. Localstack allows you to play with S3, SQS, DynamoDB, SNS, and the list goes on.
2. The ability to test the applications in the local dev environment. You can write integration tests for your application using LocalStack, driving down your costs and increasing the confidence in your code.

### Spring Cloud Messaging app linked to LocalStack

Spring Cloud AWS provides [Amazon SQS](https://aws.amazon.com/sqs/) and [Amazon SNS](https://aws.amazon.com/sns/) integration that simplifies the publication and consumption of messages. It reduces a lot of boilerplate code and does the heavy lifting for configuring and SNS and SQS. Let's set up a Spring boot project with support for SNS and SQS.

#### Setting up Spring Boot app

Let us first create a Spring Boot project with the help of the [Spring boot Initializr](https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.4.5.RELEASE&packaging=jar&jvmVersion=11&groupId=io.pratik&artifactId=springcloudsqs&name=springcloudsqs&description=Demo%20project%20for%20Spring%20cloud%20sqs&packageName=io.pratik.springcloudsqs&dependencies=web,lombok), and then open the project in our favorite IDE. Select Maven project and Java language. Last but not least, select Spring boot version `2.4.7`. Fill in the project metadata and click generate.

For Spring Cloud, We need to configure Spring Cloud AWS BOM in our `pom.xml` file using this dependencyManagement block:

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.awspring.cloud</groupId>
            <artifactId>spring-cloud-aws-dependencies</artifactId>
            <version>2.3.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

For adding the support for messaging, we need to include the module dependency for Spring Cloud AWS Messaging into our Maven configuration. We do this by adding the starter module `spring-cloud-starter-aws-messaging`:

```xml
<dependency>
    <groupId>io.awspring.cloud</groupId>
    <artifactId>spring-cloud-starter-aws-messaging</artifactId>
</dependency>
```

These are the dependencies required for Spring Cloud AWS. Next, we add some other dependencies such as Spring boot starter web and [Lombok](https://projectlombok.org/).

```xml
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>2.4.7</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.20</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

This completes our setup process for the Spring boot project.

Let's jump into adding the SNS and SQS configs and start publishing our first message.

Amazon SNS Config:

```java
import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.client.builder.AwsClientBuilder;
import com.amazonaws.services.sns.AmazonSNS;
import com.amazonaws.services.sns.AmazonSNSClientBuilder;
import io.awspring.cloud.messaging.core.NotificationMessagingTemplate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;

import static com.authga.springcloudaws.config.AWSConfigConstants.ACCESS_KEY;
import static com.authga.springcloudaws.config.AWSConfigConstants.SECRET_KEY;

@Configuration
public class SnsConfig {

    @Bean
    public NotificationMessagingTemplate notificationMessagingTemplate(AmazonSNS amazonSNS) {
        return new NotificationMessagingTemplate(amazonSNS);
    }

    @Bean
    @Primary
    public AmazonSNS amazonSNS(final AwsClientBuilder.EndpointConfiguration endpointConfiguration) {
        BasicAWSCredentials credentials = new BasicAWSCredentials(ACCESS_KEY, SECRET_KEY);
        return AmazonSNSClientBuilder
                .standard()
                .withEndpointConfiguration(endpointConfiguration)
                .withCredentials(new AWSStaticCredentialsProvider(credentials))
                .build();
    }
}
```

Here, we create a simple `AmazonSNSClient` with a custom endpoint and credentials. Spring has an auto-configured `AmazonSNSClient`, but that requires valid AWS credentials and actual resources. We instead want to run our service locally with AWS resources using LocalStack. More on this later. Let's finish this setup.

Amazon SQS Config:

```java
import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.client.builder.AwsClientBuilder;
import com.amazonaws.services.sqs.AmazonSQSAsync;
import com.amazonaws.services.sqs.AmazonSQSAsyncClientBuilder;
import io.awspring.cloud.messaging.config.QueueMessageHandlerFactory;
import io.awspring.cloud.messaging.support.NotificationMessageArgumentResolver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.messaging.converter.MappingJackson2MessageConverter;
import org.springframework.messaging.converter.MessageConverter;

import java.util.List;

import static com.authga.springcloudaws.config.AWSConfigConstants.*;

@Configuration
public class SqsConfig {

    @Bean
    public AwsClientBuilder.EndpointConfiguration endpointConfiguration() {
        return new AwsClientBuilder.EndpointConfiguration(ENDPOINT, EU_CENTRAL_1);
    }

    @Bean
    @Primary
    public AmazonSQSAsync amazonSQSAsync(final AwsClientBuilder.EndpointConfiguration endpointConfiguration) {
        BasicAWSCredentials credentials = new BasicAWSCredentials(ACCESS_KEY, SECRET_KEY);
        return AmazonSQSAsyncClientBuilder
                .standard()
                .withEndpointConfiguration(endpointConfiguration)
                .withCredentials(new AWSStaticCredentialsProvider(credentials))
                .build();
    }

    @Bean
    public QueueMessageHandlerFactory queueMessageHandlerFactory(MessageConverter messageConverter) {
        var factory = new QueueMessageHandlerFactory();
        factory.setArgumentResolvers(List.of(new NotificationMessageArgumentResolver(messageConverter)));
        return factory;
    }

    @Bean
    protected MessageConverter messageConverter() {
        var converter = new MappingJackson2MessageConverter();
        converter.setSerializedPayloadClass(String.class);
        converter.setStrictContentTypeMatch(false);
        return converter;
    }
}
```

In the code above, we did the following:

- Similar to the `AmazonSNSClient`, we create the `AmazonSQSClient` with a custom endpoint and credentials.
- Setup `QueueMessageHandlerFactory` so it can convert incoming messages from SQS as String to the actual object we want, in this case, `Event`, using a `MessageConverter`.
- The converter will take care of converting the `String` message to the actual `Event` object.

The `Event` model is described below. I am using [Lombok](https://projectlombok.org/) to reduce the boilerplate code.

`Event.java`

```java
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class Event implements Comparable<Event> {
    private String eventId;
    private String version;
    private String occurredAt;
    private EventData data;

    @Override
    public int compareTo(Event o) {
        int otherVersion = Integer.parseInt(o.getVersion());
        int thisVersion = Integer.parseInt(this.getVersion());
        return Integer.compare(thisVersion, otherVersion);
    }
}
```

`EventData.java`

```java
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class EventData {
    private String orderId;
    private String owner;
    private EventType eventType;
}
```

`EventType.java`

```java
import java.io.Serializable;

public enum EventType implements Serializable {
    ORDER_CREATED, ORDER_CANCELLED
}
```

Producer code:

```java
import com.authga.springcloudaws.model.Event;
import io.awspring.cloud.messaging.core.NotificationMessagingTemplate;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import static com.authga.springcloudaws.config.AWSConfigConstants.ORDER_CREATED_TOPIC;

@Slf4j
@Service
public class SimpleMessageProducer {

    @Autowired
    private NotificationMessagingTemplate notificationMessagingTemplate;

    public void publish(Event event) {
        notificationMessagingTemplate.convertAndSend(ORDER_CREATED_TOPIC, event);
    }
}
```

- We use the `NotificationMessagingTemplate` created in the config above. It gives us several methods to send messages on an SNS topic. We will use the default `convertAndSend()` method that takes care of converting our object to a Message using the `MessageConverter` that we provide in the `SqsConfig` class.

Consumer code:

```java
import com.authga.springcloudaws.model.Event;
import io.awspring.cloud.messaging.config.annotation.NotificationMessage;
import io.awspring.cloud.messaging.listener.SqsMessageDeletionPolicy;
import io.awspring.cloud.messaging.listener.annotation.SqsListener;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Controller;

import static com.authga.springcloudaws.config.AWSConfigConstants.ORDER_QUEUE;

@Slf4j
@Controller
public class SimpleMessageConsumer implements MessageConsumer {

    @Override
    @SqsListener(value = ORDER_QUEUE, deletionPolicy = SqsMessageDeletionPolicy.ON_SUCCESS)
    public void consume(@NotificationMessage Event event) {
        if (event != null) {
            log.info("Received order event for consumer 1: " + event);
        }
    }
}
```

- We only need `@SqsListener` annotation that automatically makes our consume method get the messages from the queue.
- We also add `@NotificationMessage` annotation to have the correct deserialization and extract our Event from the SNS message because the SNS message is wrapped inside a `Message` object.

### Setup LocalStack and create resources

Setting up LocalStack is dead simple; you just need to use the docker-compose file below, and it will start SNS and SQS services locally. Add the `docker compose.yml` to the repository's root directory. Start the LocalStack using: `docker-compose up`.

```yaml
version: '3.0'

services:

  localstack:
    image: localstack/localstack:latest
    environment:
      - AWS_DEFAULT_REGION=eu-central-1
      - EDGE_PORT=4566
      - SERVICES=sqs,sns
    ports:
      - '4566:4566'
```

Once it is up and running, we can create the required AWS resources. We will create one SNS topic to which two SQS queues will be listening. The code to or publishing and listening is simple. Go to your command line, e.g., terminal, and execute the following commands.

To create the topic:

```shell
aws --endpoint-url=http://localhost:4566  sns create-topic  --name  order-created-topic
```

To create the queues:

```shell
aws --endpoint-url=http://localhost:4566  sqs create-queue  --queue-name  order-queue
aws --endpoint-url=http://localhost:4566  sqs create-queue  --queue-name  order-queue-2
```

To subscribe the queues to the topic:

```shell
aws --endpoint-url=http://localhost:4566 sns subscribe
--topic-arn arn:aws:sns:eu-central-1:000000000000:order-created-topic
--protocol sqs
--notification-endpoint arn:aws:sqs:eu-central-1:000000000000:order-queue

aws --endpoint-url=http://localhost:4566 sns subscribe
--topic-arn arn:aws:sns:eu-central-1:000000000000:order-created-topic
--protocol sqs
--notification-endpoint arn:aws:sqs:eu-central-1:000000000000:order-queue-2
```

To verify you can list queues and subscriptions:

```shell
aws --endpoint-url=http://localhost:4566  sqs list-queues
aws --endpoint-url=http://localhost:4566  sns list-subscriptions
```
That's it!

### Verify sending and receiving of events

Run the Spring Boot app:

1. Clone the sample code from the repo. Go to the root directory.
2. Use Maven plugin to run your Spring Boot app using the command in the project directory.

```shell   
mvn spring-boot:run
```

The groundwork is complete now. With the app running, we can send messages to the Amazon SNS Topic and read those messages from the queues. In the repo, I have created a controller to trigger the publishing of events. If you download the sample app, you should be able to run it, and going to [http://localhost:8080/create-order](http://localhost:8080/create-order) will trigger the publisher, which in turn will trigger the consumers. In the application logs, you should be able to see. This means that our producer code publishes the code to the SNS topic. The two queues that are subscribed to the topic receive those messages, and finally, the consumer receives those messages and prints the event.

```
Received order event for consumer 1:
Event{eventId='386cca76-3669-4d36-b2db-01f388bbce5f', version='0',
occurredAt='2021-06-19T13:42:32.946781Z', data=EventData(orderId=9a002b95-f10b-428e-8d39-cae90d1e631d,
owner=SampleProducer, eventType=ORDER_CREATED)}

Received order event for consumer 2:
Event{eventId='386cca76-3669-4d36-b2db-01f388bbce5f', version='0', occurredAt='2021-06-19T13:42:32.946781Z',
data=EventData(orderId=9a002b95-f10b-428e-8d39-cae90d1e631d, owner=SampleProducer, eventType=ORDER_CREATED)}
```

## Conclusion

LocalStack provides a simple and convenient way to simulate AWS services without having an actual AWS account. You can build applications using various AWS services like Amazon SNS, SQS, S3 DynamoDB, and many more.

In this article, we have learned how to build a Spring Cloud Messaging app that utilizes LocalStack. We saw how Spring Cloud Messaging provides a layer of abstraction to create an Amazon SQS listener and SNS publisher with just a few lines of code. Furthermore, we saw how to use Amazon SNS and SQS to create an event-driven application.

You can refer to the repository used in the article on [Github](https://github.com/maniish-jaiin/spring-cloud-messaging-sample).

Spring Cloud Messaging With AWS and LocalStack

Avoid boilerplate code by automatically mapping JPA entities into DTOs in Spring Boot and Java by harnessing MapStruct

Mapping JPA Entities into DTOs in Spring Boot Using MapStruct

Let’s see everything you should know to start dealing with the Cache Abstraction in Spring Boot. We will have a look at its most useful cache-related annotations, as well as the most relevant cache engines

Slow performance is a recurring and complex problem that developers are often faced with. One of the most common approaches to address such a problem is through caching. Indeed, this mechanism allows achieving a substantial improvement in the performance of any type of application. The problem is that dealing with caching is not an easy task. Luckily, caching is provided by Spring Boot transparently thanks to the Spring Boot Cache Abstraction, which is a mechanism allowing consistent use of various caching methods with minimal impact on the code. Let's see everything you should know to start dealing with it.

First, we will introduce the concept of caching. Then, we will study the most common Spring Boot cache-related annotations, understanding what the most important ones are, where, and how to use them. Next, it will be time to see what are the most popular cache engines supported by Spring Boot at the time of writing. Finally, we will see Spring Boot caching in action through an example.

## What is Caching

Caching is a mechanism aimed at enhancing the performance of any kind of application. It relies on a cache, which can be seen as a temporary fast access software or hardware component that stores data to reduce the time required to serve future requests related to the same data. Dealing with caching is complex, but mastering this concept is practically unavoidable for any developer. If you are interested in delving into caching, understanding what it is, how it works, and what are its most important types, you should follow [this](https://auth0.com/blog/what-is-caching-and-how-it-works/) link first. 

## Getting Started

The Spring Boot [Cache Abstraction](https://docs.spring.io/spring-framework/docs/5.0.0.M5/spring-framework-reference/html/cache.html) does not come with the framework natively but requires a few dependencies. Thankfully, you can easily install all of them by adding the [`spring-boot-starter-cache`](https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-cache) to your dependencies.

If you are a Gradle user, add this dependency to your `build.gradle` file:

```
implementation "org.springframework.boot:spring-boot-starter-cache:2.5.0"
```
While if you are a Maven user, add the following dependency to your `pom.xml` file:

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-cache</artifactId>
    <version>2.5.0</version>
</dependency>
```
In detail, `spring-boot-starter-cache` brings the [`spring-context-support`](https://mvnrepository.com/artifact/org.springframework/spring-context-support) module, which transitively depends on [`spring-context`](https://mvnrepository.com/artifact/org.springframework/spring-context). The latter allows Spring to deal with contexts, also called Spring IoC ([Inversion of Control](https://en.wikipedia.org/wiki/Inversion_of_control)) containers, which are responsible for managing objects in a Spring application. In particular, they are in charge of configuring, instantiating, and assembling Beans by reading configuration files and employing annotations. While the  `spring-context-support` module provides support for integrating third-party cache engines, which will be presented later, into a Spring application.
Follow [this](https://docs.spring.io/spring-framework/docs/5.0.0.M5/spring-framework-reference/html/beans.html) link from the Spring official documentation for further reading on the Spring IoC containers and the bean management.  

## Spring Boot Caching Annotations

After adding the dependencies required to start using the Spring Cache Abstraction mechanism, it is time to see how to implement the desired caching logic. This can easily be achieved by marking Java methods with specific caching-related annotations. Let's delve into the most important ones, showing where to use them and how.

### [@EnableCaching](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/EnableCaching.html) 

To enable the Spring Boot caching feature, you need to add the `@EnableCaching` annotation to any of your classes annotated with `@Configuration` or to the boot application class annotated with `@SpringBootApplication`.

```java
@SpringBootApplication  
@EnableCaching   
public class SpringBootCachingApplication {  
  public static void main(String[] args) {  
    SpringApplication.run(SpringBootCachingApplication.class, args);  
  }  
}  
```

`@EnableCaching` automatically sets up a valid instance of the [`CacheManager`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/CacheManager.html) interface, which is needed to enable caching. In particular, this annotation look for one of the many cache engines we will analyze later in the article. If not found, it creates a [`ConcurrentMapCacheManager`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/concurrent/ConcurrentMapCacheManager.html), which provides a default implementation of an in-memory cache based on a [`ConcurrentHashMap`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ConcurrentHashMap.html) object.

### [@Cacheable](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/Cacheable.html)

This method-level annotation lets Spring Boot know that the return value of the annotated method can be cached. Each time a method marked with this `@Cacheable` is called, the caching behavior will be applied. In particular, Spring Boot will check whether the method has been already invoked for the given arguments. This involves looking for a key, which is generated using the method parameters by default. If no value is found in the cache related to the method for the computed key, the target method will be executed normally. Otherwise, the cached value will be returned immediately. 
`@Cacheable` comes with many parameters, but the simplest way to use it is to annotate a method with the annotation and parameterize it with the name of the cache where the results are going to be stored.

```java
@Cacheable("authors")
public List<Author> getAuthors(List<Int> ids) { ... }
```
You can also specify how the key that uniquely identifies each entry in the cache should be generated by harnessing the *key* attribute.

```java
@Cacheable(value="book", key="#isbn")
public Book findBookByISBN(String isbn) { ... }

@Cacheable(value="books", key="#author.id")
public Books findBooksByAuthor(Author author) { ... }
```
Lastly, it is also possible to enable conditional caching as in the following example:

```java
// caching only authors whose full name is less than 15 carachters
@Cacheable(value="authors", condition="#fullName.length < 15")
public Authors findAuthorsByFullName(String fullName) { ... }
```
### [@CachePut](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/CachePut.html)

This method-level annotation should be used when you want to update (put) the cache without avoiding the method from being executed. This means that the method will always be executed — according to the `@CachePut` options — and its result will be stored in the cache. The main difference between `@Cacheable` and `@CachePut` is that the first might avoid executing the method, while the second will run the method and put its results in the cache, even if there is already an existing key associated with the given parameters. Since they have different behaviors, annotating the same method with both `@CachePut` and `@Cacheable` should be avoided.

### [@CacheEvict](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/CacheEvict.html) 

This method-level annotation allows you to remove (evict) data previously stored in the cache.
By annotating a method with `@CacheEvict` you can specify the removal of one or all values so that fresh values can be loaded into the cache again.
If you want to remove a specific value, you should pass the cache key as an argument to the annotation, as in the following example:

```java
@CacheEvict(value="authors", key="#authorId")
public void evictSingleAuthor(Int authorId) { ... }
```
While if you want to clear an entire cache you can the parameter `allEntries` in conjunction with the name of cache to be cleared:

```java
@CacheEvict(value="authors", allEntries=true)
public String evictAllAuthorsCached() { ... }
```

This annotation is extremely important because size is the main problem of caches. A possible solution to this problem is to compress data before caching, as explained [here](https://betterprogramming.pub/how-to-add-compression-to-caching-in-spring-boot-d4d21533167c). On the other hand, the best approach should be to avoid keeping data that you are not using too often in the caches. In fact, since caches can become large very quickly, you should update stale data with `@CachePut` and remove unused data with `@CacheEvict`. In particular, having a method to clean all the caches of your Spring Boot application easily can become essential. If you are interested in implementing an API aimed at this, you can follow [this](https://levelup.gitconnected.com/building-an-api-to-clear-all-the-caches-of-your-spring-boot-application-2d0dfdfe71b3) tutorial.

### [@CacheConfig](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/CacheConfig.html)

This class-level annotation allows you to specify some of the cache configurations in one place, so you do not have to repeat them multiple times:

```java
@CacheConfig(cacheNames={"authors"})
public class AuthorDAO {
    @Cacheable
    publicList<Author> findAuthorsByFullName(String fullName) { ... }
    
    @Cacheable
    public List<Author> findAuthorsByBook(Book book) { ... }
    
    // ...
}
```

## Supported Cache Providers

As mentioned earlier,  Spring Boot uses a [`ConcurrentMapCacheManager`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/concurrent/ConcurrentMapCacheManager.html) object as the default cache engine, but it also provides integration with many third-party cache providers.
Let's have a brief look at the most important ones. 

For more detailed information about the cache providers supported by Spring Boot, read [this](https://docs.spring.io/spring-boot/docs/2.1.6.RELEASE/reference/html/boot-features-caching.html#boot-features-caching-provider) page from the official documentation.

### [Hazelcast](https://hazelcast.com/)

Hazelcast provides a cache-as-a-service for scalable, reliable, and fast caching. By using Hazelcast, developers can separate the caching layer from the application layer without worrying about the cache implementation.

#### Gradle dependency

```
implementation "com.hazelcast:hazelcast-all:4.0.2"
```

#### Maven dependency

```xml
<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast-all</artifactId>
    <version>4.0.2</version>
</dependency>
 ```

### [EhCache](https://www.ehcache.org/)

Ehcache provides an implementation of the [JCache JSR-107](https://www.jcp.org/en/jsr/detail?id=107) standard, and it is the most widely-used Java-based cache manager, well known for being robust, full-featured, and easy to integrate with popular frameworks.

#### Gradle dependencies

```
implementation "javax.cache:cache-api:1.1.1"
implementation "org.ehcache:ehcache:3.9.4"
```

#### Maven dependencies

```xml
<dependency>
    <groupId>javax.cache</groupId>
    <artifactId>cache-api</artifactId>
    <version>1.1.1</version>
</dependency>
<dependency>
    <groupId>org.ehcache</groupId>
    <artifactId>ehcache</artifactId>
    <version>3.9.4</version>
</dependency>
```

### [Infinispan](https://docs.spring.io/spring-boot/docs/2.1.6.RELEASE/reference/html/boot-features-caching.html#boot-features-caching-provider-hazelcast)

Infinispan is an in-memory data grid that offers features for storing, managing, and processing data. It provides a key/value data store that can hold all types of data and be used for caching.

### Gradle dependency

#### Embedded Mode

```
implementation "org.infinispan:infinispan-spring-boot-starter-embedded:12.1.4.Final"
```

#### Remote Client/Server Mode

```
implementation "org.infinispan:infinispan-spring-boot-starter-remote:12.1.4.Final"
```

### Maven dependency

#### Embedded Mode

```xml
<dependency>
  <groupId>org.infinispan</groupId>
  <artifactId>infinispan-spring-boot-starter-embedded</artifactId>
  <version>12.1.4.Final</version>
</dependency>
```

#### Remote Client/Server Mode

```xml
<dependency>
  <groupId>org.infinispan</groupId>
  <artifactId>infinispan-spring-boot-starter-remote</artifactId>
  <version>12.1.4.Final</version>
</dependency>
```

### [Redis](https://redis.io/)

Redis is an in-memory key-value data structure store that can be used as a database, cache, and message broker.

#### Gradle dependency

```
implementation "org.springframework.boot:spring-boot-starter-data-redis:2.5.0"
```

#### Maven dependency

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
    <version>2.5.0</version>
</dependency>
```   

### [Caffeine](https://github.com/ben-manes/caffeine)

Caffeine is a high-performance, near-optimal caching library providing an in-memory cache using a [Google Guava](https://en.wikipedia.org/wiki/Google_Guava) inspired API.

#### Gradle dependency

```
implementation "com.github.ben-manes.caffeine:caffeine:3.0.2"
```

#### Maven dependency

```xml
<dependency>
    <groupId>com.github.ben-manes.caffeine</groupId>
    <artifactId>caffeine</artifactId>
    <version>3.0.2</version>
</dependency>
```

### [Couchbase](https://www.couchbase.com/)

Couchbase is a distributed NoSQL cloud database that also offers a fully integrated caching layer, providing high-speed data access. 

#### Gradle dependency

```
implementation "com.couchbase.client:java-client:3.1.5"
```
#### Maven dependency

```xml
<dependency>
   <groupId>com.couchbase.client</groupId>
   <artifactId>java-client</artifactId>
   <version>3.1.5</version>
</dependency>
```

## Spring Boot Caching in Action

Let's see Spring Boot caching in action with an example. You can either clone the [GitHub repository that supports this article](https://github.com/Tonel/spring-boot-caching-auth0) or continue following this tutorial.

The demo project consists of a single REST service reachable from a GET request. Such an API will return a list of `Author` objects, whose retrieval logic will be simulated thanks to a 3-second delay. When hit for the first time, the API will take more than 3 seconds to respond. On the contrary, on successive calls, the response will be almost instantaneous. This is the effect of the Spring Boot caching system, thanks to which the slow API logic will be avoided when it is possible to retrieve the desired data from a cache.

```java
@Getter
@Setter
public class Author {
    private static int id = 0;
    private String name;
    private String surname;
    private String birthDate;

    public Author() {}

    public Author(
            String name,
            String surname,
            String birthDate
    ) {
        id++;
        this.name = name;
        this.surname = surname;
        this.birthDate = birthDate;
    }
}
```

The [`@Getter`](https://projectlombok.org/features/GetterSetter) and [`@Setter`](https://projectlombok.org/features/GetterSetter) annotations used in the code examples above are part of the [Project Lombok](https://projectlombok.org/). They are used to automatically generate getters and setters. This is not mandatory and just an additional way to avoid boilerplate code. 

```java
@Service
public class AuthorService {

    @Cacheable("authors")
    public List<Author> getAll() {
        // simulating a delay due to the data retrieval operation
        try  {
            System.out.println("Retrieving all the authors...");
            Thread.sleep(3000);
        }
        catch (InterruptedException e) {
            e.printStackTrace();
        }

        // returning a list containing all the authors
        return Arrays.asList(
                new Author("Patricia", "Brown", null),
                new Author("James", "Smith", "1964-07-01"),
                new Author("Mary", "Williams", "1988-11-19")
        );
    }
}
```

Please, note that the `retrieveAll()` service layer method is annotated with `@Cacheable("authors")`. This way, the data returned from this method will be stored in a cache named "authors", as explained earlier.

```java
@RestController
@RequiredArgsConstructor
@RequestMapping("/authors")
public class AuthorController {
    private final AuthorService authorService;

@GetMapping
    public ResponseEntity<List<Author>> getAll() {
        loggingMessage("Request received!");
        // retrieving the desired data
        List<Author> authors = authorService.findAll();
        loggingMessage("Data retrieved!");

        return new ResponseEntity<>(
                authors,
                HttpStatus.OK
        );
    }

    private void loggingMessage(
            String message
    ) {
        System.out.printf("[%s] %s%n", java.time.LocalTime.now().truncatedTo(ChronoUnit.MILLIS), message);
    }
}
```
As you can see from the log below, the first time `http://localhost:8080/authors` is hit, the response time is more than 3 seconds, and the data returned from `retrieveAll` will be stored in the cache name *authors*. Then, when the endpoint is hit again, the desired data is returned immediately, and the method is not executed, as you notice from the missing data retrieving logging message.

```
[21:23:37.919] Request received!
Retrieving all the authors...
[21:23:40.990] Data retrieved!
    
[21:23:42.844] Request received!
[21:23:42.846] Data retrieved!
```
## Conclusion

In this article, we looked at what you should know to start dealing with caching in a Spring Boot application. Caching has become increasingly important in computer science, and implementing a properly defined caching system is not an easy task. Luckily, Spring Boot comes with the Spring Cache Abstraction, which makes everything much easier. As shown, by employing a handful of annotations, you can implement your desired caching logic effortlessly. This would be impossible without using a cache engine, but as we have seen, you can choose your favorite from the many supported by Spring Boot. In conclusion, dealing with caching in Spring Boot is not as complex as you might expect. As a consequence, every Spring Boot developer should master its key aspects, and explaining them is what this article was aimed at.

Thanks for reading! I hope that you found this article helpful. Feel free to reach out to me with any questions, comments, or suggestions.

Spring Boot Caching 101

tonycamp

Tom Camp is a DevRel Engineer at <b><a href="https://ably.com/">Ably</a></b>. His recent interest lies in open realtime data and ways of representing and sharing it. He’s also a member of the Open API and Async API communities which work towards standardizing specifications and capabilities of APIs. In his spare time, Tom loves to play strategy-based games and modding them.

DevRel Engineer at Ably Realtime

Thomas Camp

Learn how to build a realtime chat application with Spring Boot, Auth0 and Ably.

Dependable and Secure Realtime in Spring Boot with Auth0 and Ably

Learn how to use Spring and Java to build a feature-complete API. Learn how to use Spring Boot to create, read, update, delete, and validate data.

Spring Boot Tutorial: Build a CRUD API (Java)

30b8d1b7c0dab4bb311c121a47a6aae9?s=80 avatar

30b8d1b7c0dab4bb311c121a47a6aae9?s=80

Guest Author

Vladimir Fomene

Learn how to build modern web apps using Vue.js for the frontend and a Spring Boot, Kotlin, GraphQL API for the backend.

Vue.js, Spring Boot, Kotlin, and GraphQL: Building Modern Apps - Part 2

Vue.js, Spring Boot, Kotlin, and GraphQL: Building Modern Apps - Part 1

idee

Software Engineer building with Kotlin and Flutter.

Software Engineer at Busha

Idorenyin Obong

Learn how to build modern APIs with Kotlin, the flexible programming language that can run on JVMs.

Building GraphQL APIs with Kotlin, Spring Boot, and MongoDB

bruno-krebs

I am passionate about developing highly scalable, resilient applications. I love everything from the database, to microservices (Kubernetes, Docker, etc), to the frontend. I find amazing to think about how all pieces work together to provide a fast and pleasurable experience to end users, mainly because they have no clue how complex that "simple" app is.

R&D Content Architect

Bruno Krebs

Learn how to develop REST APIs with ease by using Spring Boot and Spring Data REST.

Spring Data REST Tutorial: Developing RESTful APIs with Ease

Learn how to secure your Spring Boot APIs and your SPAs with OAuth 2.0.

Securing Spring Boot APIs and SPAs with OAuth 2.0

Learn how to use Retrofit and Spring Boot to develop a RESTful HTTP client to GitHub's API.

Developing a RESTful Client with Retrofit and Spring Boot

Let's learn how to integrate Spring Data JPA, PostgreSQL, and Liquibase to manage the persistence layer of a Spring Boot application.

Integrating Spring Data JPA, PostgreSQL, and Liquibase

Let's learn how to use Gradle to structure and bootstrap a Spring 5 project running on an embedded Tomcat 8 instance.

Spring 5, Embedded Tomcat 8, and Gradle: a Quick Tutorial

Let's learn how to properly handle exceptions on Spring Boot APIs while providing multi-language support (I18N) for the messages.

Exception Handling and I18N on Spring Boots APIs

Let's learn how ModelMapper can help us automate the mapping process of DTOs into entities on Spring Boot APIs.

Automatically Mapping DTO to Entity on Spring Boot APIs

Let's build and secure a RESTful API with Kotlin and Spring Boot

Developing RESTful APIs with Kotlin

Spring Boot can leverage any type of applications, not only microservices. Let's build a JSF application with Spring Boot.

"spring boot"