This document is also available as multiple HTML pages and as a PDF.
1. Legal
Copyright © 2012-2023
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
2. Getting Help
If you have trouble with Spring Boot, we would like to help.
-
Try the How-to documents. They provide solutions to the most common questions.
-
Learn the Spring basics. Spring Boot builds on many other Spring projects. Check the spring.io web-site for a wealth of reference documentation. If you are starting out with Spring, try one of the guides.
-
Ask a question. We monitor stackoverflow.com for questions tagged with
spring-boot
. -
Report bugs with Spring Boot at github.com/spring-projects/spring-boot/issues.
All of Spring Boot is open source, including the documentation. If you find problems with the docs or if you want to improve them, please get involved. |
3. Documentation Overview
This section provides a brief overview of Spring Boot reference documentation. It serves as a map for the rest of the document.
The latest copy of this document is available at docs.spring.io/spring-boot/docs/current/reference/.
3.1. First Steps
If you are getting started with Spring Boot or 'Spring' in general, start with the following topics:
-
From scratch: Overview | Requirements | Installation
3.2. Upgrading From an Earlier Version
You should always ensure that you are running a supported version of Spring Boot.
Depending on the version that you are upgrading to, you can find some additional tips here:
-
From 1.x: Upgrading from 1.x
-
To a new feature release: Upgrading to New Feature Release
-
Spring Boot CLI: Upgrading the Spring Boot CLI
3.3. Developing With Spring Boot
Ready to actually start using Spring Boot? We have you covered:
-
Best practices: Code Structure | @Configuration | @EnableAutoConfiguration | Beans and Dependency Injection
-
Packaging your app: Production jars
-
Spring Boot CLI: Using the CLI
3.4. Learning About Spring Boot Features
Need more details about Spring Boot’s core features? The following content is for you:
-
Spring Application: SpringApplication
-
External Configuration: External Configuration
-
Profiles: Profiles
-
Logging: Logging
3.5. Web
If you develop Spring Boot web applications, take a look at the following content:
-
Servlet Web Applications: Spring MVC, Jersey, Embedded Servlet Containers
-
Reactive Web Applications: Spring Webflux, Embedded Servlet Containers
-
Graceful Shutdown: Graceful Shutdown
-
Spring Security: Default Security Configuration, Auto-configuration for OAuth2, SAML
-
Spring Session: Auto-configuration for Spring Session
-
Spring HATEOAS: Auto-configuration for Spring HATEOAS
3.7. Messaging
If your application uses any messaging protocol, see one or more of the following sections:
3.8. IO
If your application needs IO capabilities, see one or more of the following sections:
-
Caching: Caching support EhCache, Hazelcast, Infinispan and more
-
Quartz: Quartz Scheduling
-
Mail: Sending Email
-
Validation: JSR-303 Validation
-
REST Clients: Calling REST Services with RestTemplate and WebClient
-
Webservices: Auto-configuration for Spring Web Services
3.9. Container Images
Spring Boot provides first-class support for building efficient container images. You can read more about it here:
-
Efficient Container Images: Tips to optimize container images such as Docker images
-
Dockerfiles: Building container images using dockerfiles
-
Cloud Native Buildpacks: Support for Cloud Native Buildpacks with Maven and Gradle
3.10. Moving to Production
When you are ready to push your Spring Boot application to production, we have some tricks that you might like:
3.11. Advanced Topics
Finally, we have a few topics for more advanced users:
-
Spring Boot Applications Deployment: Cloud Deployment | OS Service
-
Appendix: Application Properties | Configuration Metadata | Auto-configuration Classes | Test Auto-configuration Annotations | Executable Jars | Dependency Versions
4. Getting Started
If you are getting started with Spring Boot, or “Spring” in general, start by reading this section. It answers the basic “what?”, “how?” and “why?” questions. It includes an introduction to Spring Boot, along with installation instructions. We then walk you through building your first Spring Boot application, discussing some core principles as we go.
4.1. Introducing Spring Boot
Spring Boot helps you to create stand-alone, production-grade Spring-based applications that you can run. We take an opinionated view of the Spring platform and third-party libraries, so that you can get started with minimum fuss. Most Spring Boot applications need very little Spring configuration.
You can use Spring Boot to create Java applications that can be started by using java -jar
or more traditional war deployments.
We also provide a command line tool that runs “spring scripts”.
Our primary goals are:
-
Provide a radically faster and widely accessible getting-started experience for all Spring development.
-
Be opinionated out of the box but get out of the way quickly as requirements start to diverge from the defaults.
-
Provide a range of non-functional features that are common to large classes of projects (such as embedded servers, security, metrics, health checks, and externalized configuration).
-
Absolutely no code generation and no requirement for XML configuration.
4.2. System Requirements
Spring Boot 2.7.18 requires Java 8 and is compatible up to and including Java 21. Spring Framework 5.3.31 or above is also required.
Explicit build support is provided for the following build tools:
Build Tool | Version |
---|---|
Maven |
3.5+ |
Gradle |
6.8.x, 6.9.x, 7.x, and 8.x |
4.3. Installing Spring Boot
Spring Boot can be used with “classic” Java development tools or installed as a command line tool. Either way, you need Java SDK v1.8 or higher. Before you begin, you should check your current Java installation by using the following command:
$ java -version
If you are new to Java development or if you want to experiment with Spring Boot, you might want to try the Spring Boot CLI (Command Line Interface) first. Otherwise, read on for “classic” installation instructions.
4.3.1. Installation Instructions for the Java Developer
You can use Spring Boot in the same way as any standard Java library.
To do so, include the appropriate spring-boot-*.jar
files on your classpath.
Spring Boot does not require any special tools integration, so you can use any IDE or text editor.
Also, there is nothing special about a Spring Boot application, so you can run and debug a Spring Boot application as you would any other Java program.
Although you could copy Spring Boot jars, we generally recommend that you use a build tool that supports dependency management (such as Maven or Gradle).
Maven Installation
Spring Boot is compatible with Apache Maven 3.3 or above. If you do not already have Maven installed, you can follow the instructions at maven.apache.org.
On many operating systems, Maven can be installed with a package manager.
If you use OSX Homebrew, try brew install maven .
Ubuntu users can run sudo apt-get install maven .
Windows users with Chocolatey can run choco install maven from an elevated (administrator) prompt.
|
Spring Boot dependencies use the org.springframework.boot
groupId
.
Typically, your Maven POM file inherits from the spring-boot-starter-parent
project and declares dependencies to one or more “Starters”.
Spring Boot also provides an optional Maven plugin to create executable jars.
More details on getting started with Spring Boot and Maven can be found in the Getting Started section of the Maven plugin’s reference guide.
Gradle Installation
Spring Boot is compatible with Gradle 6.8, 6.9, 7.x, and 8.x. If you do not already have Gradle installed, you can follow the instructions at gradle.org.
Spring Boot dependencies can be declared by using the org.springframework.boot
group
.
Typically, your project declares dependencies to one or more “Starters”.
Spring Boot provides a useful Gradle plugin that can be used to simplify dependency declarations and to create executable jars.
More details on getting started with Spring Boot and Gradle can be found in the Getting Started section of the Gradle plugin’s reference guide.
4.3.2. Installing the Spring Boot CLI
The Spring Boot CLI (Command Line Interface) is a command line tool that you can use to quickly prototype with Spring. It lets you run Groovy scripts, which means that you have a familiar Java-like syntax without so much boilerplate code.
You do not need to use the CLI to work with Spring Boot, but it is a quick way to get a Spring application off the ground without an IDE.
Manual Installation
You can download the Spring CLI distribution from one of the following locations:
Once downloaded, follow the INSTALL.txt instructions from the unpacked archive.
In summary, there is a spring
script (spring.bat
for Windows) in a bin/
directory in the .zip
file.
Alternatively, you can use java -jar
with the .jar
file (the script helps you to be sure that the classpath is set correctly).
Installation with SDKMAN!
SDKMAN! (The Software Development Kit Manager) can be used for managing multiple versions of various binary SDKs, including Groovy and the Spring Boot CLI. Get SDKMAN! from sdkman.io and install Spring Boot by using the following commands:
$ sdk install springboot
$ spring --version
Spring CLI v2.7.18
If you develop features for the CLI and want access to the version you built, use the following commands:
$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.7.18-bin/spring-2.7.18/
$ sdk default springboot dev
$ spring --version
Spring CLI v2.7.18
The preceding instructions install a local instance of spring
called the dev
instance.
It points at your target build location, so every time you rebuild Spring Boot, spring
is up-to-date.
You can see it by running the following command:
$ sdk ls springboot
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 2.7.18
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
OSX Homebrew Installation
If you are on a Mac and use Homebrew, you can install the Spring Boot CLI by using the following commands:
$ brew tap spring-io/tap
$ brew install spring-boot
Homebrew installs spring
to /usr/local/bin
.
If you do not see the formula, your installation of brew might be out-of-date.
In that case, run brew update and try again.
|
MacPorts Installation
If you are on a Mac and use MacPorts, you can install the Spring Boot CLI by using the following command:
$ sudo port install spring-boot-cli
Command-line Completion
The Spring Boot CLI includes scripts that provide command completion for the BASH and zsh shells.
You can source
the script (also named spring
) in any shell or put it in your personal or system-wide bash completion initialization.
On a Debian system, the system-wide scripts are in /shell-completion/bash
and all scripts in that directory are executed when a new shell starts.
For example, to run the script manually if you have installed by using SDKMAN!, use the following commands:
$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$ spring <HIT TAB HERE>
grab help jar run test version
If you install the Spring Boot CLI by using Homebrew or MacPorts, the command-line completion scripts are automatically registered with your shell. |
Windows Scoop Installation
If you are on a Windows and use Scoop, you can install the Spring Boot CLI by using the following commands:
> scoop bucket add extras > scoop install springboot
Scoop installs spring
to ~/scoop/apps/springboot/current/bin
.
If you do not see the app manifest, your installation of scoop might be out-of-date.
In that case, run scoop update and try again.
|
Quick-start Spring CLI Example
You can use the following web application to test your installation.
To start, create a file called app.groovy
, as follows:
@RestController
class ThisWillActuallyRun {
@RequestMapping("/")
String home() {
"Hello World!"
}
}
Then run it from a shell, as follows:
$ spring run app.groovy
The first run of your application is slow, as dependencies are downloaded. Subsequent runs are much quicker. |
Open localhost:8080
in your favorite web browser.
You should see the following output:
Hello World!
4.4. Developing Your First Spring Boot Application
This section describes how to develop a small “Hello World!” web application that highlights some of Spring Boot’s key features. We use Maven to build this project, since most IDEs support it.
The spring.io web site contains many “Getting Started” guides that use Spring Boot. If you need to solve a specific problem, check there first. You can shortcut the steps below by going to start.spring.io and choosing the "Web" starter from the dependencies searcher. Doing so generates a new project structure so that you can start coding right away. Check the start.spring.io user guide for more details. |
Before we begin, open a terminal and run the following commands to ensure that you have valid versions of Java and Maven installed:
$ java -version
java version "1.8.0_102"
Java(TM) SE Runtime Environment (build 1.8.0_102-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.102-b14, mixed mode)
$ mvn -v
Apache Maven 3.5.4 (1edded0938998edf8bf061f1ceb3cfdeccf443fe; 2018-06-17T14:33:14-04:00)
Maven home: /usr/local/Cellar/maven/3.3.9/libexec
Java version: 1.8.0_102, vendor: Oracle Corporation
This sample needs to be created in its own directory. Subsequent instructions assume that you have created a suitable directory and that it is your current directory. |
4.4.1. Creating the POM
We need to start by creating a Maven pom.xml
file.
The pom.xml
is the recipe that is used to build your project.
Open your favorite text editor and add the following:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>myproject</artifactId>
<version>0.0.1-SNAPSHOT</version>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.7.18</version>
</parent>
<!-- Additional lines to be added here... -->
</project>
The preceding listing should give you a working build.
You can test it by running mvn package
(for now, you can ignore the “jar will be empty - no content was marked for inclusion!” warning).
At this point, you could import the project into an IDE (most modern Java IDEs include built-in support for Maven). For simplicity, we continue to use a plain text editor for this example. |
4.4.2. Adding Classpath Dependencies
Spring Boot provides a number of “Starters” that let you add jars to your classpath.
Our applications for smoke tests use the spring-boot-starter-parent
in the parent
section of the POM.
The spring-boot-starter-parent
is a special starter that provides useful Maven defaults.
It also provides a dependency-management
section so that you can omit version
tags for “blessed” dependencies.
Other “Starters” provide dependencies that you are likely to need when developing a specific type of application.
Since we are developing a web application, we add a spring-boot-starter-web
dependency.
Before that, we can look at what we currently have by running the following command:
$ mvn dependency:tree
[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT
The mvn dependency:tree
command prints a tree representation of your project dependencies.
You can see that spring-boot-starter-parent
provides no dependencies by itself.
To add the necessary dependencies, edit your pom.xml
and add the spring-boot-starter-web
dependency immediately below the parent
section:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
If you run mvn dependency:tree
again, you see that there are now a number of additional dependencies, including the Tomcat web server and Spring Boot itself.
4.4.3. Writing the Code
To finish our application, we need to create a single Java file.
By default, Maven compiles sources from src/main/java
, so you need to create that directory structure and then add a file named src/main/java/MyApplication.java
to contain the following code:
package com.example;
@RestController
@SpringBootApplication
public class MyApplication {
@RequestMapping("/")
String home() {
return "Hello World!";
}
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}
@RestController
@SpringBootApplication
class MyApplication {
@RequestMapping("/")
fun home() = "Hello World!"
}
fun main(args: Array<String>) {
runApplication<MyApplication>(*args)
}
Although there is not much code here, quite a lot is going on. We step through the important parts in the next few sections.
The @RestController and @RequestMapping Annotations
The first annotation on our MyApplication
class is @RestController
.
This is known as a stereotype annotation.
It provides hints for people reading the code and for Spring that the class plays a specific role.
In this case, our class is a web @Controller
, so Spring considers it when handling incoming web requests.
The @RequestMapping
annotation provides “routing” information.
It tells Spring that any HTTP request with the /
path should be mapped to the home
method.
The @RestController
annotation tells Spring to render the resulting string directly back to the caller.
The @RestController and @RequestMapping annotations are Spring MVC annotations (they are not specific to Spring Boot).
See the MVC section in the Spring Reference Documentation for more details.
|
The @SpringBootApplication Annotation
The second class-level annotation is @SpringBootApplication
.
This annotation is known as a meta-annotation, it combines @SpringBootConfiguration
, @EnableAutoConfiguration
and @ComponentScan
.
Of those, the annotation we’re most interested in here is @EnableAutoConfiguration
.
@EnableAutoConfiguration
tells Spring Boot to “guess” how you want to configure Spring, based on the jar dependencies that you have added.
Since spring-boot-starter-web
added Tomcat and Spring MVC, the auto-configuration assumes that you are developing a web application and sets up Spring accordingly.
The “main” Method
The final part of our application is the main
method.
This is a standard method that follows the Java convention for an application entry point.
Our main method delegates to Spring Boot’s SpringApplication
class by calling run
.
SpringApplication
bootstraps our application, starting Spring, which, in turn, starts the auto-configured Tomcat web server.
We need to pass MyApplication.class
as an argument to the run
method to tell SpringApplication
which is the primary Spring component.
The args
array is also passed through to expose any command-line arguments.
4.4.4. Running the Example
At this point, your application should work.
Since you used the spring-boot-starter-parent
POM, you have a useful run
goal that you can use to start the application.
Type mvn spring-boot:run
from the root project directory to start the application.
You should see output similar to the following:
$ mvn spring-boot:run
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.7.18)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 2.222 seconds (JVM running for 6.514)
If you open a web browser to localhost:8080
, you should see the following output:
Hello World!
To gracefully exit the application, press ctrl-c
.
4.4.5. Creating an Executable Jar
We finish our example by creating a completely self-contained executable jar file that we could run in production. Executable jars (sometimes called “fat jars”) are archives containing your compiled classes along with all of the jar dependencies that your code needs to run.
To create an executable jar, we need to add the spring-boot-maven-plugin
to our pom.xml
.
To do so, insert the following lines just below the dependencies
section:
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
The spring-boot-starter-parent POM includes <executions> configuration to bind the repackage goal.
If you do not use the parent POM, you need to declare this configuration yourself.
See the plugin documentation for details.
|
Save your pom.xml
and run mvn package
from the command line, as follows:
$ mvn package
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myproject 0.0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] .... ..
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ myproject ---
[INFO] Building jar: /Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- spring-boot-maven-plugin:2.7.18:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
If you look in the target
directory, you should see myproject-0.0.1-SNAPSHOT.jar
.
The file should be around 18 MB in size.
If you want to peek inside, you can use jar tvf
, as follows:
$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar
You should also see a much smaller file named myproject-0.0.1-SNAPSHOT.jar.original
in the target
directory.
This is the original jar file that Maven created before it was repackaged by Spring Boot.
To run that application, use the java -jar
command, as follows:
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.7.18)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 2.536 seconds (JVM running for 2.864)
As before, to exit the application, press ctrl-c
.
4.5. What to Read Next
Hopefully, this section provided some of the Spring Boot basics and got you on your way to writing your own applications. If you are a task-oriented type of developer, you might want to jump over to spring.io and follow some of the getting started guides that solve specific “How do I do that with Spring?” problems. We also have Spring Boot-specific “How-to” reference documentation.
Otherwise, the next logical step is to read Developing with Spring Boot. If you are really impatient, you could also jump ahead and read about Spring Boot features.
5. Upgrading Spring Boot
Instructions for how to upgrade from earlier versions of Spring Boot are provided on the project wiki. Follow the links in the release notes section to find the version that you want to upgrade to.
Upgrading instructions are always the first item in the release notes. If you are more than one release behind, please make sure that you also review the release notes of the versions that you jumped.
5.1. Upgrading From 1.x
If you are upgrading from the 1.x
release of Spring Boot, check the “migration guide” on the project wiki that provides detailed upgrade instructions.
Check also the “release notes” for a list of “new and noteworthy” features for each release.
5.2. Upgrading to a New Feature Release
When upgrading to a new feature release, some properties may have been renamed or removed. Spring Boot provides a way to analyze your application’s environment and print diagnostics at startup, but also temporarily migrate properties at runtime for you. To enable that feature, add the following dependency to your project:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-properties-migrator</artifactId>
<scope>runtime</scope>
</dependency>
Properties that are added late to the environment, such as when using @PropertySource , will not be taken into account.
|
Once you finish the migration, please make sure to remove this module from your project’s dependencies. |
5.3. Upgrading the Spring Boot CLI
To upgrade an existing CLI installation, use the appropriate package manager command (for example, brew upgrade
).
If you manually installed the CLI, follow the standard instructions, remembering to update your PATH
environment variable to remove any older references.
5.4. What to Read Next
Once you’ve decided to upgrade your application, you can find detailed information regarding specific features in the rest of the document.
Spring Boot’s documentation is specific to that version, so any information that you find in here will contain the most up-to-date changes that are in that version.
6. Developing with Spring Boot
This section goes into more detail about how you should use Spring Boot. It covers topics such as build systems, auto-configuration, and how to run your applications. We also cover some Spring Boot best practices. Although there is nothing particularly special about Spring Boot (it is just another library that you can consume), there are a few recommendations that, when followed, make your development process a little easier.
If you are starting out with Spring Boot, you should probably read the Getting Started guide before diving into this section.
6.1. Build Systems
It is strongly recommended that you choose a build system that supports dependency management and that can consume artifacts published to the “Maven Central” repository. We would recommend that you choose Maven or Gradle. It is possible to get Spring Boot to work with other build systems (Ant, for example), but they are not particularly well supported.
6.1.1. Dependency Management
Each release of Spring Boot provides a curated list of dependencies that it supports. In practice, you do not need to provide a version for any of these dependencies in your build configuration, as Spring Boot manages that for you. When you upgrade Spring Boot itself, these dependencies are upgraded as well in a consistent way.
You can still specify a version and override Spring Boot’s recommendations if you need to do so. |
The curated list contains all the Spring modules that you can use with Spring Boot as well as a refined list of third party libraries.
The list is available as a standard Bills of Materials (spring-boot-dependencies
) that can be used with both Maven and Gradle.
Each release of Spring Boot is associated with a base version of the Spring Framework. We highly recommend that you not specify its version. |
6.1.2. Maven
To learn about using Spring Boot with Maven, see the documentation for Spring Boot’s Maven plugin:
6.1.3. Gradle
To learn about using Spring Boot with Gradle, see the documentation for Spring Boot’s Gradle plugin:
6.1.4. Ant
It is possible to build a Spring Boot project using Apache Ant+Ivy.
The spring-boot-antlib
“AntLib” module is also available to help Ant create executable jars.
To declare dependencies, a typical ivy.xml
file looks something like the following example:
<ivy-module version="2.0">
<info organisation="org.springframework.boot" module="spring-boot-sample-ant" />
<configurations>
<conf name="compile" description="everything needed to compile this module" />
<conf name="runtime" extends="compile" description="everything needed to run this module" />
</configurations>
<dependencies>
<dependency org="org.springframework.boot" name="spring-boot-starter"
rev="${spring-boot.version}" conf="compile" />
</dependencies>
</ivy-module>
A typical build.xml
looks like the following example:
<project
xmlns:ivy="antlib:org.apache.ivy.ant"
xmlns:spring-boot="antlib:org.springframework.boot.ant"
name="myapp" default="build">
<property name="spring-boot.version" value="2.7.18" />
<target name="resolve" description="--> retrieve dependencies with ivy">
<ivy:retrieve pattern="lib/[conf]/[artifact]-[type]-[revision].[ext]" />
</target>
<target name="classpaths" depends="resolve">
<path id="compile.classpath">
<fileset dir="lib/compile" includes="*.jar" />
</path>
</target>
<target name="init" depends="classpaths">
<mkdir dir="build/classes" />
</target>
<target name="compile" depends="init" description="compile">
<javac srcdir="src/main/java" destdir="build/classes" classpathref="compile.classpath" />
</target>
<target name="build" depends="compile">
<spring-boot:exejar destfile="build/myapp.jar" classes="build/classes">
<spring-boot:lib>
<fileset dir="lib/runtime" />
</spring-boot:lib>
</spring-boot:exejar>
</target>
</project>
If you do not want to use the spring-boot-antlib module, see the Build an Executable Archive From Ant without Using spring-boot-antlib “How-to” .
|
6.1.5. Starters
Starters are a set of convenient dependency descriptors that you can include in your application.
You get a one-stop shop for all the Spring and related technologies that you need without having to hunt through sample code and copy-paste loads of dependency descriptors.
For example, if you want to get started using Spring and JPA for database access, include the spring-boot-starter-data-jpa
dependency in your project.
The starters contain a lot of the dependencies that you need to get a project up and running quickly and with a consistent, supported set of managed transitive dependencies.
The following application starters are provided by Spring Boot under the org.springframework.boot
group:
Name | Description |
---|---|
Core starter, including auto-configuration support, logging and YAML |
|
Starter for JMS messaging using Apache ActiveMQ |
|
Starter for using Spring AMQP and Rabbit MQ |
|
Starter for aspect-oriented programming with Spring AOP and AspectJ |
|
Starter for JMS messaging using Apache Artemis |
|
Starter for using Spring Batch |
|
Starter for using Spring Framework’s caching support |
|
Starter for using Cassandra distributed database and Spring Data Cassandra |
|
Starter for using Cassandra distributed database and Spring Data Cassandra Reactive |
|
Starter for using Couchbase document-oriented database and Spring Data Couchbase |
|
Starter for using Couchbase document-oriented database and Spring Data Couchbase Reactive |
|
Starter for using Elasticsearch search and analytics engine and Spring Data Elasticsearch |
|
Starter for using Spring Data JDBC |
|
Starter for using Spring Data JPA with Hibernate |
|
Starter for using Spring Data LDAP |
|
Starter for using MongoDB document-oriented database and Spring Data MongoDB |
|
Starter for using MongoDB document-oriented database and Spring Data MongoDB Reactive |
|
Starter for using Neo4j graph database and Spring Data Neo4j |
|
Starter for using Spring Data R2DBC |
|
Starter for using Redis key-value data store with Spring Data Redis and the Lettuce client |
|
Starter for using Redis key-value data store with Spring Data Redis reactive and the Lettuce client |
|
Starter for exposing Spring Data repositories over REST using Spring Data REST and Spring MVC |
|
Starter for building MVC web applications using FreeMarker views |
|
Starter for building GraphQL applications with Spring GraphQL |
|
Starter for building MVC web applications using Groovy Templates views |
|
Starter for building hypermedia-based RESTful web application with Spring MVC and Spring HATEOAS |
|
Starter for using Spring Integration |
|
Starter for using JDBC with the HikariCP connection pool |
|
Starter for building RESTful web applications using JAX-RS and Jersey. An alternative to |
|
Starter for using jOOQ to access SQL databases with JDBC. An alternative to |
|
Starter for reading and writing json |
|
Starter for JTA transactions using Atomikos |
|
Starter for using Java Mail and Spring Framework’s email sending support |
|
Starter for building web applications using Mustache views |
|
Starter for using Spring Security’s OAuth2/OpenID Connect client features |
|
Starter for using Spring Security’s OAuth2 resource server features |
|
Starter for using the Quartz scheduler |
|
Starter for building RSocket clients and servers |
|
Starter for using Spring Security |
|
Starter for testing Spring Boot applications with libraries including JUnit Jupiter, Hamcrest and Mockito |
|
Starter for building MVC web applications using Thymeleaf views |
|
Starter for using Java Bean Validation with Hibernate Validator |
|
Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container |
|
Starter for using Spring Web Services |
|
Starter for building WebFlux applications using Spring Framework’s Reactive Web support |
|
Starter for building WebSocket applications using Spring Framework’s MVC WebSocket support |
In addition to the application starters, the following starters can be used to add production ready features:
Name | Description |
---|---|
Starter for using Spring Boot’s Actuator which provides production ready features to help you monitor and manage your application |
Finally, Spring Boot also includes the following starters that can be used if you want to exclude or swap specific technical facets:
Name | Description |
---|---|
Starter for using Jetty as the embedded servlet container. An alternative to |
|
Starter for using Log4j2 for logging. An alternative to |
|
Starter for logging using Logback. Default logging starter |
|
Starter for using Reactor Netty as the embedded reactive HTTP server. |
|
Starter for using Tomcat as the embedded servlet container. Default servlet container starter used by |
|
Starter for using Undertow as the embedded servlet container. An alternative to |
To learn how to swap technical facets, please see the how-to documentation for swapping web server and logging system.
For a list of additional community contributed starters, see the README file in the spring-boot-starters module on GitHub.
|
6.2. Structuring Your Code
Spring Boot does not require any specific code layout to work. However, there are some best practices that help.
6.2.1. Using the “default” Package
When a class does not include a package
declaration, it is considered to be in the “default package”.
The use of the “default package” is generally discouraged and should be avoided.
It can cause particular problems for Spring Boot applications that use the @ComponentScan
, @ConfigurationPropertiesScan
, @EntityScan
, or @SpringBootApplication
annotations, since every class from every jar is read.
We recommend that you follow Java’s recommended package naming conventions and use a reversed domain name (for example, com.example.project ).
|
6.2.2. Locating the Main Application Class
We generally recommend that you locate your main application class in a root package above other classes.
The @SpringBootApplication
annotation is often placed on your main class, and it implicitly defines a base “search package” for certain items.
For example, if you are writing a JPA application, the package of the @SpringBootApplication
annotated class is used to search for @Entity
items.
Using a root package also allows component scan to apply only on your project.
If you do not want to use @SpringBootApplication , the @EnableAutoConfiguration and @ComponentScan annotations that it imports defines that behavior so you can also use those instead.
|
The following listing shows a typical layout:
com +- example +- myapplication +- MyApplication.java | +- customer | +- Customer.java | +- CustomerController.java | +- CustomerService.java | +- CustomerRepository.java | +- order +- Order.java +- OrderController.java +- OrderService.java +- OrderRepository.java
The MyApplication.java
file would declare the main
method, along with the basic @SpringBootApplication
, as follows:
@SpringBootApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}
@SpringBootApplication
class MyApplication
fun main(args: Array<String>) {
runApplication<MyApplication>(*args)
}
6.3. Configuration Classes
Spring Boot favors Java-based configuration.
Although it is possible to use SpringApplication
with XML sources, we generally recommend that your primary source be a single @Configuration
class.
Usually the class that defines the main
method is a good candidate as the primary @Configuration
.
Many Spring configuration examples have been published on the Internet that use XML configuration.
If possible, always try to use the equivalent Java-based configuration.
Searching for Enable* annotations can be a good starting point.
|
6.3.1. Importing Additional Configuration Classes
You need not put all your @Configuration
into a single class.
The @Import
annotation can be used to import additional configuration classes.
Alternatively, you can use @ComponentScan
to automatically pick up all Spring components, including @Configuration
classes.
6.4. Auto-configuration
Spring Boot auto-configuration attempts to automatically configure your Spring application based on the jar dependencies that you have added.
For example, if HSQLDB
is on your classpath, and you have not manually configured any database connection beans, then Spring Boot auto-configures an in-memory database.
You need to opt-in to auto-configuration by adding the @EnableAutoConfiguration
or @SpringBootApplication
annotations to one of your @Configuration
classes.
You should only ever add one @SpringBootApplication or @EnableAutoConfiguration annotation.
We generally recommend that you add one or the other to your primary @Configuration class only.
|
6.4.1. Gradually Replacing Auto-configuration
Auto-configuration is non-invasive.
At any point, you can start to define your own configuration to replace specific parts of the auto-configuration.
For example, if you add your own DataSource
bean, the default embedded database support backs away.
If you need to find out what auto-configuration is currently being applied, and why, start your application with the --debug
switch.
Doing so enables debug logs for a selection of core loggers and logs a conditions report to the console.
6.4.2. Disabling Specific Auto-configuration Classes
If you find that specific auto-configuration classes that you do not want are being applied, you can use the exclude attribute of @SpringBootApplication
to disable them, as shown in the following example:
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class MyApplication {
}
@SpringBootApplication(exclude = [DataSourceAutoConfiguration::class])
class MyApplication
If the class is not on the classpath, you can use the excludeName
attribute of the annotation and specify the fully qualified name instead.
If you prefer to use @EnableAutoConfiguration
rather than @SpringBootApplication
, exclude
and excludeName
are also available.
Finally, you can also control the list of auto-configuration classes to exclude by using the spring.autoconfigure.exclude
property.
You can define exclusions both at the annotation level and by using the property. |
Even though auto-configuration classes are public , the only aspect of the class that is considered public API is the name of the class which can be used for disabling the auto-configuration.
The actual contents of those classes, such as nested configuration classes or bean methods are for internal use only and we do not recommend using those directly.
|
6.4.3. Auto-configuration Packages
Auto-configuration packages are the packages that various auto-configured features look in by default when scanning for things such as entities and Spring Data repositories.
The @EnableAutoConfiguration
annotation (either directly or through its presence on @SpringBootApplication
) determines the default auto-configuration package.
Additional packages can be configured using the @AutoConfigurationPackage
annotation.
6.5. Spring Beans and Dependency Injection
You are free to use any of the standard Spring Framework techniques to define your beans and their injected dependencies.
We generally recommend using constructor injection to wire up dependencies and @ComponentScan
to find beans.
If you structure your code as suggested above (locating your application class in a top package), you can add @ComponentScan
without any arguments or use the @SpringBootApplication
annotation which implicitly includes it.
All of your application components (@Component
, @Service
, @Repository
, @Controller
, and others) are automatically registered as Spring Beans.
The following example shows a @Service
Bean that uses constructor injection to obtain a required RiskAssessor
bean:
@Service
public class MyAccountService implements AccountService {
private final RiskAssessor riskAssessor;
public MyAccountService(RiskAssessor riskAssessor) {
this.riskAssessor = riskAssessor;
}
// ...
}
@Service
class MyAccountService(private val riskAssessor: RiskAssessor) : AccountService
If a bean has more than one constructor, you will need to mark the one you want Spring to use with @Autowired
:
@Service
public class MyAccountService implements AccountService {
private final RiskAssessor riskAssessor;
private final PrintStream out;
@Autowired
public MyAccountService(RiskAssessor riskAssessor) {
this.riskAssessor = riskAssessor;
this.out = System.out;
}
public MyAccountService(RiskAssessor riskAssessor, PrintStream out) {
this.riskAssessor = riskAssessor;
this.out = out;
}
// ...
}
@Service
class MyAccountService : AccountService {
private val riskAssessor: RiskAssessor
private val out: PrintStream
@Autowired
constructor(riskAssessor: RiskAssessor) {
this.riskAssessor = riskAssessor
out = System.out
}
constructor(riskAssessor: RiskAssessor, out: PrintStream) {
this.riskAssessor = riskAssessor
this.out = out
}
// ...
}
Notice how using constructor injection lets the riskAssessor field be marked as final , indicating that it cannot be subsequently changed.
|
6.6. Using the @SpringBootApplication Annotation
Many Spring Boot developers like their apps to use auto-configuration, component scan and be able to define extra configuration on their "application class".
A single @SpringBootApplication
annotation can be used to enable those three features, that is:
-
@EnableAutoConfiguration
: enable Spring Boot’s auto-configuration mechanism -
@ComponentScan
: enable@Component
scan on the package where the application is located (see the best practices) -
@SpringBootConfiguration
: enable registration of extra beans in the context or the import of additional configuration classes. An alternative to Spring’s standard@Configuration
that aids configuration detection in your integration tests.
// Same as @SpringBootConfiguration @EnableAutoConfiguration @ComponentScan
@SpringBootApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}
// same as @SpringBootConfiguration @EnableAutoConfiguration @ComponentScan
@SpringBootApplication
class MyApplication
fun main(args: Array<String>) {
runApplication<MyApplication>(*args)
}
@SpringBootApplication also provides aliases to customize the attributes of @EnableAutoConfiguration and @ComponentScan .
|
None of these features are mandatory and you may choose to replace this single annotation by any of the features that it enables. For instance, you may not want to use component scan or configuration properties scan in your application: Java
Kotlin
In this example, |
6.7. Running Your Application
One of the biggest advantages of packaging your application as a jar and using an embedded HTTP server is that you can run your application as you would any other. The sample applies to debugging Spring Boot applications. You do not need any special IDE plugins or extensions.
This section only covers jar-based packaging. If you choose to package your application as a war file, see your server and IDE documentation. |
6.7.1. Running From an IDE
You can run a Spring Boot application from your IDE as a Java application.
However, you first need to import your project.
Import steps vary depending on your IDE and build system.
Most IDEs can import Maven projects directly.
For example, Eclipse users can select Import…
→ Existing Maven Projects
from the File
menu.
If you cannot directly import your project into your IDE, you may be able to generate IDE metadata by using a build plugin. Maven includes plugins for Eclipse and IDEA. Gradle offers plugins for various IDEs.
If you accidentally run a web application twice, you see a “Port already in use” error.
Spring Tools users can use the Relaunch button rather than the Run button to ensure that any existing instance is closed.
|
6.7.2. Running as a Packaged Application
If you use the Spring Boot Maven or Gradle plugins to create an executable jar, you can run your application using java -jar
, as shown in the following example:
$ java -jar target/myapplication-0.0.1-SNAPSHOT.jar
It is also possible to run a packaged application with remote debugging support enabled. Doing so lets you attach a debugger to your packaged application, as shown in the following example:
$ java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n \
-jar target/myapplication-0.0.1-SNAPSHOT.jar
6.7.3. Using the Maven Plugin
The Spring Boot Maven plugin includes a run
goal that can be used to quickly compile and run your application.
Applications run in an exploded form, as they do in your IDE.
The following example shows a typical Maven command to run a Spring Boot application:
$ mvn spring-boot:run
You might also want to use the MAVEN_OPTS
operating system environment variable, as shown in the following example:
$ export MAVEN_OPTS=-Xmx1024m
6.7.4. Using the Gradle Plugin
The Spring Boot Gradle plugin also includes a bootRun
task that can be used to run your application in an exploded form.
The bootRun
task is added whenever you apply the org.springframework.boot
and java
plugins and is shown in the following example:
$ gradle bootRun
You might also want to use the JAVA_OPTS
operating system environment variable, as shown in the following example:
$ export JAVA_OPTS=-Xmx1024m
6.7.5. Hot Swapping
Since Spring Boot applications are plain Java applications, JVM hot-swapping should work out of the box. JVM hot swapping is somewhat limited with the bytecode that it can replace. For a more complete solution, JRebel can be used.
The spring-boot-devtools
module also includes support for quick application restarts.
See the Hot swapping “How-to” for details.
6.8. Developer Tools
Spring Boot includes an additional set of tools that can make the application development experience a little more pleasant.
The spring-boot-devtools
module can be included in any project to provide additional development-time features.
To include devtools support, add the module dependency to your build, as shown in the following listings for Maven and Gradle:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<optional>true</optional>
</dependency>
</dependencies>
dependencies {
developmentOnly("org.springframework.boot:spring-boot-devtools")
}
Devtools might cause classloading issues, in particular in multi-module projects. Diagnosing Classloading Issues explains how to diagnose and solve them. |
Developer tools are automatically disabled when running a fully packaged application.
If your application is launched from java -jar or if it is started from a special classloader, then it is considered a “production application”.
You can control this behavior by using the spring.devtools.restart.enabled system property.
To enable devtools, irrespective of the classloader used to launch your application, set the -Dspring.devtools.restart.enabled=true system property.
This must not be done in a production environment where running devtools is a security risk.
To disable devtools, exclude the dependency or set the -Dspring.devtools.restart.enabled=false system property.
|
Flagging the dependency as optional in Maven or using the developmentOnly configuration in Gradle (as shown above) prevents devtools from being transitively applied to other modules that use your project.
|
Repackaged archives do not contain devtools by default.
If you want to use a certain remote devtools feature, you need to include it.
When using the Maven plugin, set the excludeDevtools property to false .
When using the Gradle plugin, configure the task’s classpath to include the developmentOnly configuration.
|
6.8.1. Diagnosing Classloading Issues
As described in the Restart vs Reload section, restart functionality is implemented by using two classloaders. For most applications, this approach works well. However, it can sometimes cause classloading issues, in particular in multi-module projects.
To diagnose whether the classloading issues are indeed caused by devtools and its two classloaders, try disabling restart. If this solves your problems, customize the restart classloader to include your entire project.
6.8.2. Property Defaults
Several of the libraries supported by Spring Boot use caches to improve performance. For example, template engines cache compiled templates to avoid repeatedly parsing template files. Also, Spring MVC can add HTTP caching headers to responses when serving static resources.
While caching is very beneficial in production, it can be counter-productive during development, preventing you from seeing the changes you just made in your application. For this reason, spring-boot-devtools disables the caching options by default.
Cache options are usually configured by settings in your application.properties
file.
For example, Thymeleaf offers the spring.thymeleaf.cache
property.
Rather than needing to set these properties manually, the spring-boot-devtools
module automatically applies sensible development-time configuration.
The following table lists all the properties that are applied:
Name | Default Value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If you do not want property defaults to be applied you can set spring.devtools.add-properties to false in your application.properties .
|
Because you need more information about web requests while developing Spring MVC and Spring WebFlux applications, developer tools suggests you to enable DEBUG
logging for the web
logging group.
This will give you information about the incoming request, which handler is processing it, the response outcome, and other details.
If you wish to log all request details (including potentially sensitive information), you can turn on the spring.mvc.log-request-details
or spring.codec.log-request-details
configuration properties.
6.8.3. Automatic Restart
Applications that use spring-boot-devtools
automatically restart whenever files on the classpath change.
This can be a useful feature when working in an IDE, as it gives a very fast feedback loop for code changes.
By default, any entry on the classpath that points to a directory is monitored for changes.
Note that certain resources, such as static assets and view templates, do not need to restart the application.
If you are restarting with Maven or Gradle using the build plugin you must leave the forking set to enabled .
If you disable forking, the isolated application classloader used by devtools will not be created and restarts will not operate properly.
|
Automatic restart works very well when used with LiveReload. See the LiveReload section for details. If you use JRebel, automatic restarts are disabled in favor of dynamic class reloading. Other devtools features (such as LiveReload and property overrides) can still be used. |
DevTools relies on the application context’s shutdown hook to close it during a restart.
It does not work correctly if you have disabled the shutdown hook (SpringApplication.setRegisterShutdownHook(false) ).
|
DevTools needs to customize the ResourceLoader used by the ApplicationContext .
If your application provides one already, it is going to be wrapped.
Direct override of the getResource method on the ApplicationContext is not supported.
|
Automatic restart is not supported when using AspectJ weaving. |
Logging Changes in Condition Evaluation
By default, each time your application restarts, a report showing the condition evaluation delta is logged. The report shows the changes to your application’s auto-configuration as you make changes such as adding or removing beans and setting configuration properties.
To disable the logging of the report, set the following property:
spring.devtools.restart.log-condition-evaluation-delta=false
spring:
devtools:
restart:
log-condition-evaluation-delta: false
Excluding Resources
Certain resources do not necessarily need to trigger a restart when they are changed.
For example, Thymeleaf templates can be edited in-place.
By default, changing resources in /META-INF/maven
, /META-INF/resources
, /resources
, /static
, /public
, or /templates
does not trigger a restart but does trigger a live reload.
If you want to customize these exclusions, you can use the spring.devtools.restart.exclude
property.
For example, to exclude only /static
and /public
you would set the following property:
spring.devtools.restart.exclude=static/**,public/**
spring:
devtools:
restart:
exclude: "static/**,public/**"
If you want to keep those defaults and add additional exclusions, use the spring.devtools.restart.additional-exclude property instead.
|
Watching Additional Paths
You may want your application to be restarted or reloaded when you make changes to files that are not on the classpath.
To do so, use the spring.devtools.restart.additional-paths
property to configure additional paths to watch for changes.
You can use the spring.devtools.restart.exclude
property described earlier to control whether changes beneath the additional paths trigger a full restart or a live reload.
Disabling Restart
If you do not want to use the restart feature, you can disable it by using the spring.devtools.restart.enabled
property.
In most cases, you can set this property in your application.properties
(doing so still initializes the restart classloader, but it does not watch for file changes).
If you need to completely disable restart support (for example, because it does not work with a specific library), you need to set the spring.devtools.restart.enabled
System
property to false
before calling SpringApplication.run(…)
, as shown in the following example:
@SpringBootApplication
public class MyApplication {
public static void main(String[] args) {
System.setProperty("spring.devtools.restart.enabled", "false");
SpringApplication.run(MyApplication.class, args);
}
}
@SpringBootApplication
object MyApplication {
@JvmStatic
fun main(args: Array<String>) {
System.setProperty("spring.devtools.restart.enabled", "false")
SpringApplication.run(MyApplication::class.java, *args)
}
}
Using a Trigger File
If you work with an IDE that continuously compiles changed files, you might prefer to trigger restarts only at specific times. To do so, you can use a “trigger file”, which is a special file that must be modified when you want to actually trigger a restart check.
Any update to the file will trigger a check, but restart only actually occurs if Devtools has detected it has something to do. |
To use a trigger file, set the spring.devtools.restart.trigger-file
property to the name (excluding any path) of your trigger file.
The trigger file must appear somewhere on your classpath.
For example, if you have a project with the following structure:
src +- main +- resources +- .reloadtrigger
Then your trigger-file
property would be:
spring.devtools.restart.trigger-file=.reloadtrigger
spring:
devtools:
restart:
trigger-file: ".reloadtrigger"
Restarts will now only happen when the src/main/resources/.reloadtrigger
is updated.
You might want to set spring.devtools.restart.trigger-file as a global setting, so that all your projects behave in the same way.
|
Some IDEs have features that save you from needing to update your trigger file manually.
Spring Tools for Eclipse and IntelliJ IDEA (Ultimate Edition) both have such support.
With Spring Tools, you can use the “reload” button from the console view (as long as your trigger-file
is named .reloadtrigger
).
For IntelliJ IDEA, you can follow the instructions in their documentation.
Customizing the Restart Classloader
As described earlier in the Restart vs Reload section, restart functionality is implemented by using two classloaders. If this causes issues, you might need to customize what gets loaded by which classloader.
By default, any open project in your IDE is loaded with the “restart” classloader, and any regular .jar
file is loaded with the “base” classloader.
The same is true if you use mvn spring-boot:run
or gradle bootRun
: the project containing your @SpringBootApplication
is loaded with the “restart” classloader, and everything else with the “base” classloader.
You can instruct Spring Boot to load parts of your project with a different classloader by creating a META-INF/spring-devtools.properties
file.
The spring-devtools.properties
file can contain properties prefixed with restart.exclude
and restart.include
.
The include
elements are items that should be pulled up into the “restart” classloader, and the exclude
elements are items that should be pushed down into the “base” classloader.
The value of the property is a regex pattern that is applied to the classpath, as shown in the following example:
restart.exclude.companycommonlibs=/mycorp-common-[\\w\\d-\\.]+\\.jar
restart.include.projectcommon=/mycorp-myproj-[\\w\\d-\\.]+\\.jar
restart:
exclude:
companycommonlibs: "/mycorp-common-[\\w\\d-\\.]+\\.jar"
include:
projectcommon: "/mycorp-myproj-[\\w\\d-\\.]+\\.jar"
All property keys must be unique.
As long as a property starts with restart.include. or restart.exclude. it is considered.
|
All META-INF/spring-devtools.properties from the classpath are loaded.
You can package files inside your project, or in the libraries that the project consumes.
|
Known Limitations
Restart functionality does not work well with objects that are deserialized by using a standard ObjectInputStream
.
If you need to deserialize data, you may need to use Spring’s ConfigurableObjectInputStream
in combination with Thread.currentThread().getContextClassLoader()
.
Unfortunately, several third-party libraries deserialize without considering the context classloader. If you find such a problem, you need to request a fix with the original authors.
6.8.4. LiveReload
The spring-boot-devtools
module includes an embedded LiveReload server that can be used to trigger a browser refresh when a resource is changed.
LiveReload browser extensions are freely available for Chrome, Firefox and Safari.
You can find these extensions by searching 'LiveReload' in the marketplace or store of your chosen browser.
If you do not want to start the LiveReload server when your application runs, you can set the spring.devtools.livereload.enabled
property to false
.
You can only run one LiveReload server at a time. Before starting your application, ensure that no other LiveReload servers are running. If you start multiple applications from your IDE, only the first has LiveReload support. |
To trigger LiveReload when a file changes, Automatic Restart must be enabled. |
6.8.5. Global Settings
You can configure global devtools settings by adding any of the following files to the $HOME/.config/spring-boot
directory:
-
spring-boot-devtools.properties
-
spring-boot-devtools.yaml
-
spring-boot-devtools.yml
Any properties added to these files apply to all Spring Boot applications on your machine that use devtools.
For example, to configure restart to always use a trigger file, you would add the following property to your spring-boot-devtools
file:
spring.devtools.restart.trigger-file=.reloadtrigger
spring:
devtools:
restart:
trigger-file: ".reloadtrigger"
By default, $HOME
is the user’s home directory.
To customize this location, set the SPRING_DEVTOOLS_HOME
environment variable or the spring.devtools.home
system property.
If devtools configuration files are not found in $HOME/.config/spring-boot , the root of the $HOME directory is searched for the presence of a .spring-boot-devtools.properties file.
This allows you to share the devtools global configuration with applications that are on an older version of Spring Boot that does not support the $HOME/.config/spring-boot location.
|
Profiles are not supported in devtools properties/yaml files. Any profiles activated in |
Configuring File System Watcher
FileSystemWatcher works by polling the class changes with a certain time interval, and then waiting for a predefined quiet period to make sure there are no more changes.
Since Spring Boot relies entirely on the IDE to compile and copy files into the location from where Spring Boot can read them, you might find that there are times when certain changes are not reflected when devtools restarts the application.
If you observe such problems constantly, try increasing the spring.devtools.restart.poll-interval
and spring.devtools.restart.quiet-period
parameters to the values that fit your development environment:
spring.devtools.restart.poll-interval=2s
spring.devtools.restart.quiet-period=1s
spring:
devtools:
restart:
poll-interval: "2s"
quiet-period: "1s"
The monitored classpath directories are now polled every 2 seconds for changes, and a 1 second quiet period is maintained to make sure there are no additional class changes.
6.8.6. Remote Applications
The Spring Boot developer tools are not limited to local development. You can also use several features when running applications remotely. Remote support is opt-in as enabling it can be a security risk. It should only be enabled when running on a trusted network or when secured with SSL. If neither of these options is available to you, you should not use DevTools' remote support. You should never enable support on a production deployment.
To enable it, you need to make sure that devtools
is included in the repackaged archive, as shown in the following listing:
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludeDevtools>false</excludeDevtools>
</configuration>
</plugin>
</plugins>
</build>
Then you need to set the spring.devtools.remote.secret
property.
Like any important password or secret, the value should be unique and strong such that it cannot be guessed or brute-forced.
Remote devtools support is provided in two parts: a server-side endpoint that accepts connections and a client application that you run in your IDE.
The server component is automatically enabled when the spring.devtools.remote.secret
property is set.
The client component must be launched manually.
Remote devtools is not supported for Spring WebFlux applications. |
Running the Remote Client Application
The remote client application is designed to be run from within your IDE.
You need to run org.springframework.boot.devtools.RemoteSpringApplication
with the same classpath as the remote project that you connect to.
The application’s single required argument is the remote URL to which it connects.
For example, if you are using Eclipse or Spring Tools and you have a project named my-app
that you have deployed to Cloud Foundry, you would do the following:
-
Select
Run Configurations…
from theRun
menu. -
Create a new
Java Application
“launch configuration”. -
Browse for the
my-app
project. -
Use
org.springframework.boot.devtools.RemoteSpringApplication
as the main class. -
Add
https://myapp.cfapps.io
to theProgram arguments
(or whatever your remote URL is).
A running remote client might resemble the following listing:
. ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ ___ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | | _ \___ _ __ ___| |_ ___ \ \ \ \ \\/ ___)| |_)| | | | | || (_| []::::::[] / -_) ' \/ _ \ _/ -_) ) ) ) ) ' |____| .__|_| |_|_| |_\__, | |_|_\___|_|_|_\___/\__\___|/ / / / =========|_|==============|___/===================================/_/_/_/ :: Spring Boot Remote :: (v2.7.18) 2023-11-23 07:23:21.930 INFO 28462 --- [ main] o.s.b.devtools.RemoteSpringApplication : Starting RemoteSpringApplication v2.7.18 using Java 1.8.0_392 on myhost with PID 28462 (/Users/myuser/.m2/repository/org/springframework/boot/spring-boot-devtools/2.7.18/spring-boot-devtools-2.7.18.jar started by myuser in /opt/apps/) 2023-11-23 07:23:21.936 INFO 28462 --- [ main] o.s.b.devtools.RemoteSpringApplication : No active profile set, falling back to 1 default profile: "default" 2023-11-23 07:23:22.314 INFO 28462 --- [ main] o.s.b.d.a.OptionalLiveReloadServer : LiveReload server is running on port 35729 2023-11-23 07:23:22.338 INFO 28462 --- [ main] o.s.b.devtools.RemoteSpringApplication : Started RemoteSpringApplication in 0.858 seconds (JVM running for 1.35)
Because the remote client is using the same classpath as the real application it can directly read application properties.
This is how the spring.devtools.remote.secret property is read and passed to the server for authentication.
|
It is always advisable to use https:// as the connection protocol, so that traffic is encrypted and passwords cannot be intercepted.
|
If you need to use a proxy to access the remote application, configure the spring.devtools.remote.proxy.host and spring.devtools.remote.proxy.port properties.
|
Remote Update
The remote client monitors your application classpath for changes in the same way as the local restart. Any updated resource is pushed to the remote application and (if required) triggers a restart. This can be helpful if you iterate on a feature that uses a cloud service that you do not have locally. Generally, remote updates and restarts are much quicker than a full rebuild and deploy cycle.
On a slower development environment, it may happen that the quiet period is not enough, and the changes in the classes may be split into batches. The server is restarted after the first batch of class changes is uploaded. The next batch can’t be sent to the application, since the server is restarting.
This is typically manifested by a warning in the RemoteSpringApplication
logs about failing to upload some of the classes, and a consequent retry.
But it may also lead to application code inconsistency and failure to restart after the first batch of changes is uploaded.
If you observe such problems constantly, try increasing the spring.devtools.restart.poll-interval
and spring.devtools.restart.quiet-period
parameters to the values that fit your development environment.
See the Configuring File System Watcher section for configuring these properties.
Files are only monitored when the remote client is running. If you change a file before starting the remote client, it is not pushed to the remote server. |
6.9. Packaging Your Application for Production
Executable jars can be used for production deployment. As they are self-contained, they are also ideally suited for cloud-based deployment.
For additional “production ready” features, such as health, auditing, and metric REST or JMX end-points, consider adding spring-boot-actuator
.
See Production-ready Features for details.
6.10. What to Read Next
You should now understand how you can use Spring Boot and some best practices that you should follow. You can now go on to learn about specific Spring Boot features in depth, or you could skip ahead and read about the “production ready” aspects of Spring Boot.
7. Core Features
This section dives into the details of Spring Boot. Here you can learn about the key features that you may want to use and customize. If you have not already done so, you might want to read the "Getting Started" and "Developing with Spring Boot" sections, so that you have a good grounding of the basics.
7.1. SpringApplication
The SpringApplication
class provides a convenient way to bootstrap a Spring application that is started from a main()
method.
In many situations, you can delegate to the static SpringApplication.run
method, as shown in the following example:
@SpringBootApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}
@SpringBootApplication
class MyApplication
fun main(args: Array<String>) {
runApplication<MyApplication>(*args)
}
When your application starts, you should see something similar to the following output:
. ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v2.7.18) 2023-11-23 07:23:23.238 INFO 28579 --- [ main] o.s.b.d.f.logexample.MyApplication : Starting MyApplication using Java 1.8.0_392 on myhost with PID 28579 (/opt/apps/myapp.jar started by myuser in /opt/apps/) 2023-11-23 07:23:23.245 INFO 28579 --- [ main] o.s.b.d.f.logexample.MyApplication : No active profile set, falling back to 1 default profile: "default" 2023-11-23 07:23:24.552 INFO 28579 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8080 (http) 2023-11-23 07:23:24.567 INFO 28579 --- [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat] 2023-11-23 07:23:24.567 INFO 28579 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/9.0.83] 2023-11-23 07:23:24.658 INFO 28579 --- [ main] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext 2023-11-23 07:23:24.659 INFO 28579 --- [ main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1346 ms 2023-11-23 07:23:25.336 INFO 28579 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path '' 2023-11-23 07:23:25.355 INFO 28579 --- [ main] o.s.b.d.f.logexample.MyApplication : Started MyApplication in 2.63 seconds (JVM running for 3.003)
By default, INFO
logging messages are shown, including some relevant startup details, such as the user that launched the application.
If you need a log level other than INFO
, you can set it, as described in Log Levels.
The application version is determined using the implementation version from the main application class’s package.
Startup information logging can be turned off by setting spring.main.log-startup-info
to false
.
This will also turn off logging of the application’s active profiles.
To add additional logging during startup, you can override logStartupInfo(boolean) in a subclass of SpringApplication .
|
7.1.1. Startup Failure
If your application fails to start, registered FailureAnalyzers
get a chance to provide a dedicated error message and a concrete action to fix the problem.
For instance, if you start a web application on port 8080
and that port is already in use, you should see something similar to the following message:
*************************** APPLICATION FAILED TO START *************************** Description: Embedded servlet container failed to start. Port 8080 was already in use. Action: Identify and stop the process that is listening on port 8080 or configure this application to listen on another port.
Spring Boot provides numerous FailureAnalyzer implementations, and you can add your own.
|
If no failure analyzers are able to handle the exception, you can still display the full conditions report to better understand what went wrong.
To do so, you need to enable the debug
property or enable DEBUG
logging for org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener
.
For instance, if you are running your application by using java -jar
, you can enable the debug
property as follows:
$ java -jar myproject-0.0.1-SNAPSHOT.jar --debug
7.1.2. Lazy Initialization
SpringApplication
allows an application to be initialized lazily.
When lazy initialization is enabled, beans are created as they are needed rather than during application startup.
As a result, enabling lazy initialization can reduce the time that it takes your application to start.
In a web application, enabling lazy initialization will result in many web-related beans not being initialized until an HTTP request is received.
A downside of lazy initialization is that it can delay the discovery of a problem with the application. If a misconfigured bean is initialized lazily, a failure will no longer occur during startup and the problem will only become apparent when the bean is initialized. Care must also be taken to ensure that the JVM has sufficient memory to accommodate all of the application’s beans and not just those that are initialized during startup. For these reasons, lazy initialization is not enabled by default and it is recommended that fine-tuning of the JVM’s heap size is done before enabling lazy initialization.
Lazy initialization can be enabled programmatically using the lazyInitialization
method on SpringApplicationBuilder
or the setLazyInitialization
method on SpringApplication
.
Alternatively, it can be enabled using the spring.main.lazy-initialization
property as shown in the following example:
spring.main.lazy-initialization=true
spring:
main:
lazy-initialization: true
If you want to disable lazy initialization for certain beans while using lazy initialization for the rest of the application, you can explicitly set their lazy attribute to false using the @Lazy(false) annotation.
|
7.1.3. Customizing the Banner
The banner that is printed on start up can be changed by adding a banner.txt
file to your classpath or by setting the spring.banner.location
property to the location of such a file.
If the file has an encoding other than UTF-8, you can set spring.banner.charset
.
In addition to a text file, you can also add a banner.gif
, banner.jpg
, or banner.png
image file to your classpath or set the spring.banner.image.location
property.
Images are converted into an ASCII art representation and printed above any text banner.
Inside your banner.txt
file, you can use any key available in the Environment
as well as any of the following placeholders:
Variable | Description |
---|---|
|
The version number of your application, as declared in |
|
The version number of your application, as declared in |
|
The Spring Boot version that you are using.
For example |
|
The Spring Boot version that you are using, formatted for display (surrounded with brackets and prefixed with |
|
Where |
|
The title of your application, as declared in |
The SpringApplication.setBanner(…) method can be used if you want to generate a banner programmatically.
Use the org.springframework.boot.Banner interface and implement your own printBanner() method.
|
You can also use the spring.main.banner-mode
property to determine if the banner has to be printed on System.out
(console
), sent to the configured logger (log
), or not produced at all (off
).
The printed banner is registered as a singleton bean under the following name: springBootBanner
.
The To use the |
7.1.4. Customizing SpringApplication
If the SpringApplication
defaults are not to your taste, you can instead create a local instance and customize it.
For example, to turn off the banner, you could write:
@SpringBootApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication application = new SpringApplication(MyApplication.class);
application.setBannerMode(Banner.Mode.OFF);
application.run(args);
}
}
@SpringBootApplication
class MyApplication
fun main(args: Array<String>) {
runApplication<MyApplication>(*args) {
setBannerMode(Banner.Mode.OFF)
}
}
The constructor arguments passed to SpringApplication are configuration sources for Spring beans.
In most cases, these are references to @Configuration classes, but they could also be direct references @Component classes.
|
It is also possible to configure the SpringApplication
by using an application.properties
file.
See Externalized Configuration for details.
For a complete list of the configuration options, see the SpringApplication
Javadoc.
7.1.5. Fluent Builder API
If you need to build an ApplicationContext
hierarchy (multiple contexts with a parent/child relationship) or if you prefer using a “fluent” builder API, you can use the SpringApplicationBuilder
.
The SpringApplicationBuilder
lets you chain together multiple method calls and includes parent
and child
methods that let you create a hierarchy, as shown in the following example:
new SpringApplicationBuilder()
.sources(Parent.class)
.child(Application.class)
.bannerMode(Banner.Mode.OFF)
.run(args);
SpringApplicationBuilder()
.sources(Parent::class.java)
.child(Application::class.java)
.bannerMode(Banner.Mode.OFF)
.run(*args)
There are some restrictions when creating an ApplicationContext hierarchy.
For example, Web components must be contained within the child context, and the same Environment is used for both parent and child contexts.
See the SpringApplicationBuilder Javadoc for full details.
|
7.1.6. Application Availability
When deployed on platforms, applications can provide information about their availability to the platform using infrastructure such as Kubernetes Probes. Spring Boot includes out-of-the box support for the commonly used “liveness” and “readiness” availability states. If you are using Spring Boot’s “actuator” support then these states are exposed as health endpoint groups.
In addition, you can also obtain availability states by injecting the ApplicationAvailability
interface into your own beans.
Liveness State
The “Liveness” state of an application tells whether its internal state allows it to work correctly, or recover by itself if it is currently failing. A broken “Liveness” state means that the application is in a state that it cannot recover from, and the infrastructure should restart the application.
In general, the "Liveness" state should not be based on external checks, such as Health checks. If it did, a failing external system (a database, a Web API, an external cache) would trigger massive restarts and cascading failures across the platform. |
The internal state of Spring Boot applications is mostly represented by the Spring ApplicationContext
.
If the application context has started successfully, Spring Boot assumes that the application is in a valid state.
An application is considered live as soon as the context has been refreshed, see Spring Boot application lifecycle and related Application Events.
Readiness State
The “Readiness” state of an application tells whether the application is ready to handle traffic.
A failing “Readiness” state tells the platform that it should not route traffic to the application for now.
This typically happens during startup, while CommandLineRunner
and ApplicationRunner
components are being processed, or at any time if the application decides that it is too busy for additional traffic.
An application is considered ready as soon as application and command-line runners have been called, see Spring Boot application lifecycle and related Application Events.
Tasks expected to run during startup should be executed by CommandLineRunner and ApplicationRunner components instead of using Spring component lifecycle callbacks such as @PostConstruct .
|
Managing the Application Availability State
Application components can retrieve the current availability state at any time, by injecting the ApplicationAvailability
interface and calling methods on it.
More often, applications will want to listen to state updates or update the state of the application.
For example, we can export the "Readiness" state of the application to a file so that a Kubernetes "exec Probe" can look at this file:
@Component
public class MyReadinessStateExporter {
@EventListener
public void onStateChange(AvailabilityChangeEvent<ReadinessState> event) {
switch (event.getState()) {
case ACCEPTING_TRAFFIC:
// create file /tmp/healthy
break;
case REFUSING_TRAFFIC:
// remove file /tmp/healthy
break;
}
}
}
@Component
class MyReadinessStateExporter {
@EventListener
fun onStateChange(event: AvailabilityChangeEvent<ReadinessState?>) {
when (event.state) {
ReadinessState.ACCEPTING_TRAFFIC -> {
// create file /tmp/healthy
}
ReadinessState.REFUSING_TRAFFIC -> {
// remove file /tmp/healthy
}
else -> {
// ...
}
}
}
}
We can also update the state of the application, when the application breaks and cannot recover:
@Component
public class MyLocalCacheVerifier {
private final ApplicationEventPublisher eventPublisher;
public MyLocalCacheVerifier(ApplicationEventPublisher eventPublisher) {
this.eventPublisher = eventPublisher;
}
public void checkLocalCache() {
try {
// ...
}
catch (CacheCompletelyBrokenException ex) {
AvailabilityChangeEvent.publish(this.eventPublisher, ex, LivenessState.BROKEN);
}
}
}
@Component
class MyLocalCacheVerifier(private val eventPublisher: ApplicationEventPublisher) {
fun checkLocalCache() {
try {
// ...
} catch (ex: CacheCompletelyBrokenException) {
AvailabilityChangeEvent.publish(eventPublisher, ex, LivenessState.BROKEN)
}
}
}
Spring Boot provides Kubernetes HTTP probes for "Liveness" and "Readiness" with Actuator Health Endpoints. You can get more guidance about deploying Spring Boot applications on Kubernetes in the dedicated section.
7.1.7. Application Events and Listeners
In addition to the usual Spring Framework events, such as ContextRefreshedEvent
, a SpringApplication
sends some additional application events.
Some events are actually triggered before the If you want those listeners to be registered automatically, regardless of the way the application is created, you can add a org.springframework.context.ApplicationListener=com.example.project.MyListener |
Application events are sent in the following order, as your application runs:
-
An
ApplicationStartingEvent
is sent at the start of a run but before any processing, except for the registration of listeners and initializers. -
An
ApplicationEnvironmentPreparedEvent
is sent when theEnvironment
to be used in the context is known but before the context is created. -
An
ApplicationContextInitializedEvent
is sent when theApplicationContext
is prepared and ApplicationContextInitializers have been called but before any bean definitions are loaded. -
An
ApplicationPreparedEvent
is sent just before the refresh is started but after bean definitions have been loaded. -
An
ApplicationStartedEvent
is sent after the context has been refreshed but before any application and command-line runners have been called. -
An
AvailabilityChangeEvent
is sent right after withLivenessState.CORRECT
to indicate that the application is considered as live. -
An
ApplicationReadyEvent
is sent after any application and command-line runners have been called. -
An
AvailabilityChangeEvent
is sent right after withReadinessState.ACCEPTING_TRAFFIC
to indicate that the application is ready to service requests. -
An
ApplicationFailedEvent
is sent if there is an exception on startup.
The above list only includes SpringApplicationEvent
s that are tied to a SpringApplication
.
In addition to these, the following events are also published after ApplicationPreparedEvent
and before ApplicationStartedEvent
:
-
A
WebServerInitializedEvent
is sent after theWebServer
is ready.ServletWebServerInitializedEvent
andReactiveWebServerInitializedEvent
are the servlet and reactive variants respectively. -
A
ContextRefreshedEvent
is sent when anApplicationContext
is refreshed.
You often need not use application events, but it can be handy to know that they exist. Internally, Spring Boot uses events to handle a variety of tasks. |
Event listeners should not run potentially lengthy tasks as they execute in the same thread by default. Consider using application and command-line runners instead. |
Application events are sent by using Spring Framework’s event publishing mechanism.
Part of this mechanism ensures that an event published to the listeners in a child context is also published to the listeners in any ancestor contexts.
As a result of this, if your application uses a hierarchy of SpringApplication
instances, a listener may receive multiple instances of the same type of application event.
To allow your listener to distinguish between an event for its context and an event for a descendant context, it should request that its application context is injected and then compare the injected context with the context of the event.
The context can be injected by implementing ApplicationContextAware
or, if the listener is a bean, by using @Autowired
.
7.1.8. Web Environment
A SpringApplication
attempts to create the right type of ApplicationContext
on your behalf.
The algorithm used to determine a WebApplicationType
is the following:
-
If Spring MVC is present, an
AnnotationConfigServletWebServerApplicationContext
is used -
If Spring MVC is not present and Spring WebFlux is present, an
AnnotationConfigReactiveWebServerApplicationContext
is used -
Otherwise,
AnnotationConfigApplicationContext
is used
This means that if you are using Spring MVC and the new WebClient
from Spring WebFlux in the same application, Spring MVC will be used by default.
You can override that easily by calling setWebApplicationType(WebApplicationType)
.
It is also possible to take complete control of the ApplicationContext
type that is used by calling setApplicationContextFactory(…)
.
It is often desirable to call setWebApplicationType(WebApplicationType.NONE) when using SpringApplication within a JUnit test.
|
7.1.9. Accessing Application Arguments
If you need to access the application arguments that were passed to SpringApplication.run(…)
, you can inject a org.springframework.boot.ApplicationArguments
bean.
The ApplicationArguments
interface provides access to both the raw String[]
arguments as well as parsed option
and non-option
arguments, as shown in the following example:
@Component
public class MyBean {
public MyBean(ApplicationArguments args) {
boolean debug = args.containsOption("debug");
List<String> files = args.getNonOptionArgs();
if (debug) {
System.out.println(files);
}
// if run with "--debug logfile.txt" prints ["logfile.txt"]
}
}
@Component
class MyBean(args: ApplicationArguments) {
init {
val debug = args.containsOption("debug")
val files = args.nonOptionArgs
if (debug) {
println(files)
}
// if run with "--debug logfile.txt" prints ["logfile.txt"]
}
}
Spring Boot also registers a CommandLinePropertySource with the Spring Environment .
This lets you also inject single application arguments by using the @Value annotation.
|
7.1.10. Using the ApplicationRunner or CommandLineRunner
If you need to run some specific code once the SpringApplication
has started, you can implement the ApplicationRunner
or CommandLineRunner
interfaces.
Both interfaces work in the same way and offer a single run
method, which is called just before SpringApplication.run(…)
completes.
This contract is well suited for tasks that should run after application startup but before it starts accepting traffic. |
The CommandLineRunner
interfaces provides access to application arguments as a string array, whereas the ApplicationRunner
uses the ApplicationArguments
interface discussed earlier.
The following example shows a CommandLineRunner
with a run
method:
@Component
public class MyCommandLineRunner implements CommandLineRunner {
@Override
public void run(String... args) {
// Do something...
}
}
@Component
class MyCommandLineRunner : CommandLineRunner {
override fun run(vararg args: String) {
// Do something...
}
}
If several CommandLineRunner
or ApplicationRunner
beans are defined that must be called in a specific order, you can additionally implement the org.springframework.core.Ordered
interface or use the org.springframework.core.annotation.Order
annotation.
7.1.11. Application Exit
Each SpringApplication
registers a shutdown hook with the JVM to ensure that the ApplicationContext
closes gracefully on exit.
All the standard Spring lifecycle callbacks (such as the DisposableBean
interface or the @PreDestroy
annotation) can be used.
In addition, beans may implement the org.springframework.boot.ExitCodeGenerator
interface if they wish to return a specific exit code when SpringApplication.exit()
is called.
This exit code can then be passed to System.exit()
to return it as a status code, as shown in the following example:
@SpringBootApplication
public class MyApplication {
@Bean
public ExitCodeGenerator exitCodeGenerator() {
return () -> 42;
}
public static void main(String[] args) {
System.exit(SpringApplication.exit(SpringApplication.run(MyApplication.class, args)));
}
}
@SpringBootApplication
class MyApplication {
@Bean
fun exitCodeGenerator() = ExitCodeGenerator { 42 }
}
fun main(args: Array<String>) {
exitProcess(SpringApplication.exit(
runApplication<MyApplication>(*args)))
}
Also, the ExitCodeGenerator
interface may be implemented by exceptions.
When such an exception is encountered, Spring Boot returns the exit code provided by the implemented getExitCode()
method.
If there is more than one ExitCodeGenerator
, the first non-zero exit code that is generated is used.
To control the order in which the generators are called, additionally implement the org.springframework.core.Ordered
interface or use the org.springframework.core.annotation.Order
annotation.
7.1.12. Admin Features
It is possible to enable admin-related features for the application by specifying the spring.application.admin.enabled
property.
This exposes the SpringApplicationAdminMXBean
on the platform MBeanServer
.
You could use this feature to administer your Spring Boot application remotely.
This feature could also be useful for any service wrapper implementation.
If you want to know on which HTTP port the application is running, get the property with a key of local.server.port .
|
7.1.13. Application Startup tracking
During the application startup, the SpringApplication
and the ApplicationContext
perform many tasks related to the application lifecycle,
the beans lifecycle or even processing application events.
With ApplicationStartup
, Spring Framework allows you to track the application startup sequence with StartupStep
objects.
This data can be collected for profiling purposes, or just to have a better understanding of an application startup process.
You can choose an ApplicationStartup
implementation when setting up the SpringApplication
instance.
For example, to use the BufferingApplicationStartup
, you could write:
@SpringBootApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication application = new SpringApplication(MyApplication.class);
application.setApplicationStartup(new BufferingApplicationStartup(2048));
application.run(args);
}
}
@SpringBootApplication
class MyApplication
fun main(args: Array<String>) {
runApplication<MyApplication>(*args) {
applicationStartup = BufferingApplicationStartup(2048)
}
}
The first available implementation, FlightRecorderApplicationStartup
is provided by Spring Framework.
It adds Spring-specific startup events to a Java Flight Recorder session and is meant for profiling applications and correlating their Spring context lifecycle with JVM events (such as allocations, GCs, class loading…).
Once configured, you can record data by running the application with the Flight Recorder enabled:
$ java -XX:StartFlightRecording:filename=recording.jfr,duration=10s -jar demo.jar
Spring Boot ships with the BufferingApplicationStartup
variant; this implementation is meant for buffering the startup steps and draining them into an external metrics system.
Applications can ask for the bean of type BufferingApplicationStartup
in any component.
Spring Boot can also be configured to expose a startup
endpoint that provides this information as a JSON document.
7.2. Externalized Configuration
Spring Boot lets you externalize your configuration so that you can work with the same application code in different environments. You can use a variety of external configuration sources including Java properties files, YAML files, environment variables, and command-line arguments.
Property values can be injected directly into your beans by using the @Value
annotation, accessed through Spring’s Environment
abstraction, or be bound to structured objects through @ConfigurationProperties
.
Spring Boot uses a very particular PropertySource
order that is designed to allow sensible overriding of values.
Later property sources can override the values defined in earlier ones.
Sources are considered in the following order:
-
Default properties (specified by setting
SpringApplication.setDefaultProperties
). -
@PropertySource
annotations on your@Configuration
classes. Please note that such property sources are not added to theEnvironment
until the application context is being refreshed. This is too late to configure certain properties such aslogging.*
andspring.main.*
which are read before refresh begins. -
Config data (such as
application.properties
files). -
A
RandomValuePropertySource
that has properties only inrandom.*
. -
OS environment variables.
-
Java System properties (
System.getProperties()
). -
JNDI attributes from
java:comp/env
. -
ServletContext
init parameters. -
ServletConfig
init parameters. -
Properties from
SPRING_APPLICATION_JSON
(inline JSON embedded in an environment variable or system property). -
Command line arguments.
-
properties
attribute on your tests. Available on@SpringBootTest
and the test annotations for testing a particular slice of your application. -
@DynamicPropertySource
annotations in your tests. -
@TestPropertySource
annotations on your tests. -
Devtools global settings properties in the
$HOME/.config/spring-boot
directory when devtools is active.
Config data files are considered in the following order:
-
Application properties packaged inside your jar (
application.properties
and YAML variants). -
Profile-specific application properties packaged inside your jar (
application-{profile}.properties
and YAML variants). -
Application properties outside of your packaged jar (
application.properties
and YAML variants). -
Profile-specific application properties outside of your packaged jar (
application-{profile}.properties
and YAML variants).
It is recommended to stick with one format for your entire application.
If you have configuration files with both .properties and YAML format in the same location, .properties takes precedence.
|
If you use environment variables rather than system properties, most operating systems disallow period-separated key names, but you can use underscores instead (for example, SPRING_CONFIG_NAME instead of spring.config.name ).
See Binding From Environment Variables for details.
|
If your application runs in a servlet container or application server, then JNDI properties (in java:comp/env ) or servlet context initialization parameters can be used instead of, or as well as, environment variables or system properties.
|
To provide a concrete example, suppose you develop a @Component
that uses a name
property, as shown in the following example:
@Component
public class MyBean {
@Value("${name}")
private String name;
// ...
}
@Component
class MyBean {
@Value("\${name}")
private val name: String? = null
// ...
}
On your application classpath (for example, inside your jar) you can have an application.properties
file that provides a sensible default property value for name
.
When running in a new environment, an application.properties
file can be provided outside of your jar that overrides the name
.
For one-off testing, you can launch with a specific command line switch (for example, java -jar app.jar --name="Spring"
).
The env and configprops endpoints can be useful in determining why a property has a particular value.
You can use these two endpoints to diagnose unexpected property values.
See the "Production ready features" section for details.
|
7.2.1. Accessing Command Line Properties
By default, SpringApplication
converts any command line option arguments (that is, arguments starting with --
, such as --server.port=9000
) to a property
and adds them to the Spring Environment
.
As mentioned previously, command line properties always take precedence over file-based property sources.
If you do not want command line properties to be added to the Environment
, you can disable them by using SpringApplication.setAddCommandLineProperties(false)
.
7.2.2. JSON Application Properties
Environment variables and system properties often have restrictions that mean some property names cannot be used. To help with this, Spring Boot allows you to encode a block of properties into a single JSON structure.
When your application starts, any spring.application.json
or SPRING_APPLICATION_JSON
properties will be parsed and added to the Environment
.
For example, the SPRING_APPLICATION_JSON
property can be supplied on the command line in a UN*X shell as an environment variable:
$ SPRING_APPLICATION_JSON='{"my":{"name":"test"}}' java -jar myapp.jar
In the preceding example, you end up with my.name=test
in the Spring Environment
.
The same JSON can also be provided as a system property:
$ java -Dspring.application.json='{"my":{"name":"test"}}' -jar myapp.jar
Or you could supply the JSON by using a command line argument:
$ java -jar myapp.jar --spring.application.json='{"my":{"name":"test"}}'
If you are deploying to a classic Application Server, you could also use a JNDI variable named java:comp/env/spring.application.json
.
Although null values from the JSON will be added to the resulting property source, the PropertySourcesPropertyResolver treats null properties as missing values.
This means that the JSON cannot override properties from lower order property sources with a null value.
|
7.2.3. External Application Properties
Spring Boot will automatically find and load application.properties
and application.yaml
files from the following locations when your application starts:
-
From the classpath
-
The classpath root
-
The classpath
/config
package
-
-
From the current directory
-
The current directory
-
The
config/
subdirectory in the current directory -
Immediate child directories of the
config/
subdirectory
-
The list is ordered by precedence (with values from lower items overriding earlier ones).
Documents from the loaded files are added as PropertySources
to the Spring Environment
.
If you do not like application
as the configuration file name, you can switch to another file name by specifying a spring.config.name
environment property.
For example, to look for myproject.properties
and myproject.yaml
files you can run your application as follows:
$ java -jar myproject.jar --spring.config.name=myproject
You can also refer to an explicit location by using the spring.config.location
environment property.
This property accepts a comma-separated list of one or more locations to check.
The following example shows how to specify two distinct files:
$ java -jar myproject.jar --spring.config.location=\
optional:classpath:/default.properties,\
optional:classpath:/override.properties
Use the prefix optional: if the locations are optional and you do not mind if they do not exist.
|
spring.config.name , spring.config.location , and spring.config.additional-location are used very early to determine which files have to be loaded.
They must be defined as an environment property (typically an OS environment variable, a system property, or a command-line argument).
|
If spring.config.location
contains directories (as opposed to files), they should end in /
.
At runtime they will be appended with the names generated from spring.config.name
before being loaded.
Files specified in spring.config.location
are imported directly.
Both directory and file location values are also expanded to check for profile-specific files.
For example, if you have a spring.config.location of classpath:myconfig.properties , you will also find appropriate classpath:myconfig-<profile>.properties files are loaded.
|
In most situations, each spring.config.location
item you add will reference a single file or directory.
Locations are processed in the order that they are defined and later ones can override the values of earlier ones.
If you have a complex location setup, and you use profile-specific configuration files, you may need to provide further hints so that Spring Boot knows how they should be grouped.
A location group is a collection of locations that are all considered at the same level.
For example, you might want to group all classpath locations, then all external locations.
Items within a location group should be separated with ;
.
See the example in the “Profile Specific Files” section for more details.
Locations configured by using spring.config.location
replace the default locations.
For example, if spring.config.location
is configured with the value optional:classpath:/custom-config/,optional:file:./custom-config/
, the complete set of locations considered is:
-
optional:classpath:custom-config/
-
optional:file:./custom-config/
If you prefer to add additional locations, rather than replacing them, you can use spring.config.additional-location
.
Properties loaded from additional locations can override those in the default locations.
For example, if spring.config.additional-location
is configured with the value optional:classpath:/custom-config/,optional:file:./custom-config/
, the complete set of locations considered is:
-
optional:classpath:/;optional:classpath:/config/
-
optional:file:./;optional:file:./config/;optional:file:./config/*/
-
optional:classpath:custom-config/
-
optional:file:./custom-config/
This search ordering lets you specify default values in one configuration file and then selectively override those values in another.
You can provide default values for your application in application.properties
(or whatever other basename you choose with spring.config.name
) in one of the default locations.
These default values can then be overridden at runtime with a different file located in one of the custom locations.
Optional Locations
By default, when a specified config data location does not exist, Spring Boot will throw a ConfigDataLocationNotFoundException
and your application will not start.
If you want to specify a location, but you do not mind if it does not always exist, you can use the optional:
prefix.
You can use this prefix with the spring.config.location
and spring.config.additional-location
properties, as well as with spring.config.import
declarations.
For example, a spring.config.import
value of optional:file:./myconfig.properties
allows your application to start, even if the myconfig.properties
file is missing.
If you want to ignore all ConfigDataLocationNotFoundExceptions
and always continue to start your application, you can use the spring.config.on-not-found
property.
Set the value to ignore
using SpringApplication.setDefaultProperties(…)
or with a system/environment variable.
Wildcard Locations
If a config file location includes the *
character for the last path segment, it is considered a wildcard location.
Wildcards are expanded when the config is loaded so that immediate subdirectories are also checked.
Wildcard locations are particularly useful in an environment such as Kubernetes when there are multiple sources of config properties.
For example, if you have some Redis configuration and some MySQL configuration, you might want to keep those two pieces of configuration separate, while requiring that both those are present in an application.properties
file.
This might result in two separate application.properties
files mounted at different locations such as /config/redis/application.properties
and /config/mysql/application.properties
.
In such a case, having a wildcard location of config/*/
, will result in both files being processed.
By default, Spring Boot includes config/*/
in the default search locations.
It means that all subdirectories of the /config
directory outside of your jar will be searched.
You can use wildcard locations yourself with the spring.config.location
and spring.config.additional-location
properties.
A wildcard location must contain only one * and end with */ for search locations that are directories or */<filename> for search locations that are files.
Locations with wildcards are sorted alphabetically based on the absolute path of the file names.
|
Wildcard locations only work with external directories.
You cannot use a wildcard in a classpath: location.
|
Profile Specific Files
As well as application
property files, Spring Boot will also attempt to load profile-specific files using the naming convention application-{profile}
.
For example, if your application activates a profile named prod
and uses YAML files, then both application.yaml
and application-prod.yaml
will be considered.
Profile-specific properties are loaded from the same locations as standard application.properties
, with profile-specific files always overriding the non-specific ones.
If several profiles are specified, a last-wins strategy applies.
For example, if profiles prod,live
are specified by the spring.profiles.active
property, values in application-prod.properties
can be overridden by those in application-live.properties
.
The last-wins strategy applies at the location group level.
A For example, continuing our /cfg application-live.properties /ext application-live.properties application-prod.properties When we have a
When we have
|
The Environment
has a set of default profiles (by default, [default]
) that are used if no active profiles are set.
In other words, if no profiles are explicitly activated, then properties from application-default
are considered.
Properties files are only ever loaded once. If you have already directly imported a profile specific property files then it will not be imported a second time. |
Importing Additional Data
Application properties may import further config data from other locations using the spring.config.import
property.
Imports are processed as they are discovered, and are treated as additional documents inserted immediately below the one that declares the import.
For example, you might have the following in your classpath application.properties
file:
spring.application.name=myapp
spring.config.import=optional:file:./dev.properties
spring:
application:
name: "myapp"
config:
import: "optional:file:./dev.properties"
This will trigger the import of a dev.properties
file in current directory (if such a file exists).
Values from the imported dev.properties
will take precedence over the file that triggered the import.
In the above example, the dev.properties
could redefine spring.application.name
to a different value.
An import will only be imported once no matter how many times it is declared. The order an import is defined inside a single document within the properties/yaml file does not matter. For instance, the two examples below produce the same result:
spring.config.import=my.properties
my.property=value
spring:
config:
import: "my.properties"
my:
property: "value"
my.property=value
spring.config.import=my.properties
my:
property: "value"
spring:
config:
import: "my.properties"
In both of the above examples, the values from the my.properties
file will take precedence over the file that triggered its import.
Several locations can be specified under a single spring.config.import
key.
Locations will be processed in the order that they are defined, with later imports taking precedence.
When appropriate, Profile-specific variants are also considered for import.
The example above would import both my.properties as well as any my-<profile>.properties variants.
|
Spring Boot includes pluggable API that allows various different location addresses to be supported. By default you can import Java Properties, YAML and “configuration trees”. Third-party jars can offer support for additional technologies (there is no requirement for files to be local). For example, you can imagine config data being from external stores such as Consul, Apache ZooKeeper or Netflix Archaius. If you want to support your own locations, see the |
Importing Extensionless Files
Some cloud platforms cannot add a file extension to volume mounted files. To import these extensionless files, you need to give Spring Boot a hint so that it knows how to load them. You can do this by putting an extension hint in square brackets.
For example, suppose you have a /etc/config/myconfig
file that you wish to import as yaml.
You can import it from your application.properties
using the following:
spring.config.import=file:/etc/config/myconfig[.yaml]
spring:
config:
import: "file:/etc/config/myconfig[.yaml]"
Using Configuration Trees
When running applications on a cloud platform (such as Kubernetes) you often need to read config values that the platform supplies. It is not uncommon to use environment variables for such purposes, but this can have drawbacks, especially if the value is supposed to be kept secret.
As an alternative to environment variables, many cloud platforms now allow you to map configuration into mounted data volumes.
For example, Kubernetes can volume mount both ConfigMaps
and Secrets
.
There are two common volume mount patterns that can be used:
-
A single file contains a complete set of properties (usually written as YAML).
-
Multiple files are written to a directory tree, with the filename becoming the ‘key’ and the contents becoming the ‘value’.
For the first case, you can import the YAML or Properties file directly using spring.config.import
as described above.
For the second case, you need to use the configtree:
prefix so that Spring Boot knows it needs to expose all the files as properties.
As an example, let’s imagine that Kubernetes has mounted the following volume:
etc/ config/ myapp/ username password
The contents of the username
file would be a config value, and the contents of password
would be a secret.
To import these properties, you can add the following to your application.properties
or application.yaml
file:
spring.config.import=optional:configtree:/etc/config/
spring:
config:
import: "optional:configtree:/etc/config/"
You can then access or inject myapp.username
and myapp.password
properties from the Environment
in the usual way.
The names of the folders and files under the config tree form the property name.
In the above example, to access the properties as username and password , you can set spring.config.import to optional:configtree:/etc/config/myapp .
|
Filenames with dot notation are also correctly mapped.
For example, in the above example, a file named myapp.username in /etc/config would result in a myapp.username property in the Environment .
|
Configuration tree values can be bound to both string String and byte[] types depending on the contents expected.
|
If you have multiple config trees to import from the same parent folder you can use a wildcard shortcut.
Any configtree:
location that ends with /*/
will import all immediate children as config trees.
As with a non-wildcard import, the names of the folders and files under each config tree form the property name.
For example, given the following volume:
etc/ config/ dbconfig/ db/ username password mqconfig/ mq/ username password
You can use configtree:/etc/config/*/
as the import location:
spring.config.import=optional:configtree:/etc/config/*/
spring:
config:
import: "optional:configtree:/etc/config/*/"
This will add db.username
, db.password
, mq.username
and mq.password
properties.
Directories loaded using a wildcard are sorted alphabetically. If you need a different order, then you should list each location as a separate import |
Configuration trees can also be used for Docker secrets.
When a Docker swarm service is granted access to a secret, the secret gets mounted into the container.
For example, if a secret named db.password
is mounted at location /run/secrets/
, you can make db.password
available to the Spring environment using the following:
spring.config.import=optional:configtree:/run/secrets/
spring:
config:
import: "optional:configtree:/run/secrets/"
Property Placeholders
The values in application.properties
and application.yaml
are filtered through the existing Environment
when they are used, so you can refer back to previously defined values (for example, from System properties or environment variables).
The standard ${name}
property-placeholder syntax can be used anywhere within a value.
Property placeholders can also specify a default value using a :
to separate the default value from the property name, for example ${name:default}
.
The use of placeholders with and without defaults is shown in the following example:
app.name=MyApp
app.description=${app.name} is a Spring Boot application written by ${username:Unknown}
app:
name: "MyApp"
description: "${app.name} is a Spring Boot application written by ${username:Unknown}"
Assuming that the username
property has not been set elsewhere, app.description
will have the value MyApp is a Spring Boot application written by Unknown
.
You should always refer to property names in the placeholder using their canonical form (kebab-case using only lowercase letters).
This will allow Spring Boot to use the same logic as it does when relaxed binding For example, |
You can also use this technique to create “short” variants of existing Spring Boot properties. See the Use ‘Short’ Command Line Arguments how-to for details. |
Working With Multi-Document Files
Spring Boot allows you to split a single physical file into multiple logical documents which are each added independently. Documents are processed in order, from top to bottom. Later documents can override the properties defined in earlier ones.
For application.yaml
files, the standard YAML multi-document syntax is used.
Three consecutive hyphens represent the end of one document, and the start of the next.
For example, the following file has two logical documents:
spring:
application:
name: "MyApp"
---
spring:
application:
name: "MyCloudApp"
config:
activate:
on-cloud-platform: "kubernetes"
For application.properties
files a special #---
or !---
comment is used to mark the document splits:
spring.application.name=MyApp
#---
spring.application.name=MyCloudApp
spring.config.activate.on-cloud-platform=kubernetes
Property file separators must not have any leading whitespace and must have exactly three hyphen characters. The lines immediately before and after the separator must not be same comment prefix. |
Multi-document property files are often used in conjunction with activation properties such as spring.config.activate.on-profile .
See the next section for details.
|
Multi-document property files cannot be loaded by using the @PropertySource or @TestPropertySource annotations.
|
Activation Properties
It is sometimes useful to only activate a given set of properties when certain conditions are met. For example, you might have properties that are only relevant when a specific profile is active.
You can conditionally activate a properties document using spring.config.activate.*
.
The following activation properties are available:
Property | Note |
---|---|
|
A profile expression that must match for the document to be active. |
|
The |
For example, the following specifies that the second document is only active when running on Kubernetes, and only when either the “prod” or “staging” profiles are active:
myprop=always-set
#---
spring.config.activate.on-cloud-platform=kubernetes
spring.config.activate.on-profile=prod | staging
myotherprop=sometimes-set
myprop:
"always-set"
---
spring:
config:
activate:
on-cloud-platform: "kubernetes"
on-profile: "prod | staging"
myotherprop: "sometimes-set"
7.2.4. Encrypting Properties
Spring Boot does not provide any built-in support for encrypting property values, however, it does provide the hook points necessary to modify values contained in the Spring Environment
.
The EnvironmentPostProcessor
interface allows you to manipulate the Environment
before the application starts.
See Customize the Environment or ApplicationContext Before It Starts for details.
If you need a secure way to store credentials and passwords, the Spring Cloud Vault project provides support for storing externalized configuration in HashiCorp Vault.
7.2.5. Working With YAML
YAML is a superset of JSON and, as such, is a convenient format for specifying hierarchical configuration data.
The SpringApplication
class automatically supports YAML as an alternative to properties whenever you have the SnakeYAML library on your classpath.
If you use “Starters”, SnakeYAML is automatically provided by spring-boot-starter .
|
Mapping YAML to Properties
YAML documents need to be converted from their hierarchical format to a flat structure that can be used with the Spring Environment
.
For example, consider the following YAML document:
environments:
dev:
url: "https://dev.example.com"
name: "Developer Setup"
prod:
url: "https://another.example.com"
name: "My Cool App"
In order to access these properties from the Environment
, they would be flattened as follows:
environments.dev.url=https://dev.example.com
environments.dev.name=Developer Setup
environments.prod.url=https://another.example.com
environments.prod.name=My Cool App
Likewise, YAML lists also need to be flattened.
They are represented as property keys with [index]
dereferencers.
For example, consider the following YAML:
my:
servers:
- "dev.example.com"
- "another.example.com"
The preceding example would be transformed into these properties:
my.servers[0]=dev.example.com
my.servers[1]=another.example.com
Properties that use the [index] notation can be bound to Java List or Set objects using Spring Boot’s Binder class.
For more details see the “Type-safe Configuration Properties” section below.
|
YAML files cannot be loaded by using the @PropertySource or @TestPropertySource annotations.
So, in the case that you need to load values that way, you need to use a properties file.
|
Directly Loading YAML
Spring Framework provides two convenient classes that can be used to load YAML documents.
The YamlPropertiesFactoryBean
loads YAML as Properties
and the YamlMapFactoryBean
loads YAML as a Map
.
You can also use the YamlPropertySourceLoader
class if you want to load YAML as a Spring PropertySource
.
7.2.6. Configuring Random Values
The RandomValuePropertySource
is useful for injecting random values (for example, into secrets or test cases).
It can produce integers, longs, uuids, or strings, as shown in the following example:
my.secret=${random.value}
my.number=${random.int}
my.bignumber=${random.long}
my.uuid=${random.uuid}
my.number-less-than-ten=${random.int(10)}
my.number-in-range=${random.int[1024,65536]}
my:
secret: "${random.value}"
number: "${random.int}"
bignumber: "${random.long}"
uuid: "${random.uuid}"
number-less-than-ten: "${random.int(10)}"
number-in-range: "${random.int[1024,65536]}"
The random.int*
syntax is OPEN value (,max) CLOSE
where the OPEN,CLOSE
are any character and value,max
are integers.
If max
is provided, then value
is the minimum value and max
is the maximum value (exclusive).
7.2.7. Configuring System Environment Properties
Spring Boot supports setting a prefix for environment properties.
This is useful if the system environment is shared by multiple Spring Boot applications with different configuration requirements.
The prefix for system environment properties can be set directly on SpringApplication
.
For example, if you set the prefix to input
, a property such as remote.timeout
will also be resolved as input.remote.timeout
in the system environment.
7.2.8. Type-safe Configuration Properties
Using the @Value("${property}")
annotation to inject configuration properties can sometimes be cumbersome, especially if you are working with multiple properties or your data is hierarchical in nature.
Spring Boot provides an alternative method of working with properties that lets strongly typed beans govern and validate the configuration of your application.
JavaBean Properties Binding
It is possible to bind a bean declaring standard JavaBean properties as shown in the following example:
@ConfigurationProperties("my.service")
public class MyProperties {
private boolean enabled;
private InetAddress remoteAddress;
private final Security security = new Security();
public static class Security {
private String username;
private String password;
private List<String> roles = new ArrayList<>(Collections.singleton("USER"));
}
}
@ConfigurationProperties("my.service")
class MyProperties {
var isEnabled = false
var remoteAddress: InetAddress? = null
val security = Security()
class Security {
var username: String? = null
var password: String? = null
var roles: List<String> = ArrayList(setOf("USER"))
}
}
The preceding POJO defines the following properties:
-
my.service.enabled
, with a value offalse
by default. -
my.service.remote-address
, with a type that can be coerced fromString
. -
my.service.security.username
, with a nested "security" object whose name is determined by the name of the property. In particular, the type is not used at all there and could have beenSecurityProperties
. -
my.service.security.password
. -
my.service.security.roles
, with a collection ofString
that defaults toUSER
.
The properties that map to @ConfigurationProperties classes available in Spring Boot, which are configured through properties files, YAML files, environment variables, and other mechanisms, are public API but the accessors (getters/setters) of the class itself are not meant to be used directly.
|
Such arrangement relies on a default empty constructor and getters and setters are usually mandatory, since binding is through standard Java Beans property descriptors, just like in Spring MVC. A setter may be omitted in the following cases:
Some people use Project Lombok to add getters and setters automatically. Make sure that Lombok does not generate any particular constructor for such a type, as it is used automatically by the container to instantiate the object. Finally, only standard Java Bean properties are considered and binding on static properties is not supported. |
Constructor Binding
The example in the previous section can be rewritten in an immutable fashion as shown in the following example:
@ConstructorBinding
@ConfigurationProperties("my.service")
public class MyProperties {
public MyProperties(boolean enabled, InetAddress remoteAddress, Security security) {
this.enabled = enabled;
this.remoteAddress = remoteAddress;
this.security = security;
}
public static class Security {
public Security(String username, String password, @DefaultValue("USER") List<String> roles) {
this.username = username;
this.password = password;
this.roles = roles;
}
}
}
@ConstructorBinding
@ConfigurationProperties("my.service")
class MyProperties(val enabled: Boolean, val remoteAddress: InetAddress,
val security: Security) {
class Security(val username: String, val password: String,
@param:DefaultValue("USER") val roles: List<String>)
}
In this setup, the @ConstructorBinding
annotation is used to indicate that constructor binding should be used.
This means that the binder will expect to find a constructor with the parameters that you wish to have bound.
If you are using Java 16 or later, constructor binding can be used with records.
In this case, unless your record has multiple constructors, there is no need to use @ConstructorBinding
.
Nested members of a @ConstructorBinding
class (such as Security
in the example above) will also be bound through their constructor.
Default values can be specified using @DefaultValue
on a constructor parameter or, when using Java 16 or later, a record component.
The conversion service will be applied to coerce the String
value to the target type of a missing property.
Referring to the previous example, if no properties are bound to Security
, the MyProperties
instance will contain a null
value for security
.
To make it contain a non-null instance of Security
even when no properties are bound to it (when using Kotlin, this will require the username
and password
parameters of Security
to be declared as nullable as they do not have default values), use an empty @DefaultValue
annotation:
public MyProperties(boolean enabled, InetAddress remoteAddress, @DefaultValue Security security) {
this.enabled = enabled;
this.remoteAddress = remoteAddress;
this.security = security;
}
class MyProperties(val enabled: Boolean, val remoteAddress: InetAddress,
@DefaultValue val security: Security) {
class Security(val username: String?, val password: String?,
@param:DefaultValue("USER") val roles: List<String>)
}
To use constructor binding the class must be enabled using @EnableConfigurationProperties or configuration property scanning.
You cannot use constructor binding with beans that are created by the regular Spring mechanisms (for example @Component beans, beans created by using @Bean methods or beans loaded by using @Import )
|
If you have more than one constructor for your class you can also use @ConstructorBinding directly on the constructor that should be bound.
|
The use of java.util.Optional with @ConfigurationProperties is not recommended as it is primarily intended for use as a return type.
As such, it is not well-suited to configuration property injection.
For consistency with properties of other types, if you do declare an Optional property and it has no value, null rather than an empty Optional will be bound.
|
Enabling @ConfigurationProperties-annotated Types
Spring Boot provides infrastructure to bind @ConfigurationProperties
types and register them as beans.
You can either enable configuration properties on a class-by-class basis or enable configuration property scanning that works in a similar manner to component scanning.
Sometimes, classes annotated with @ConfigurationProperties
might not be suitable for scanning, for example, if you’re developing your own auto-configuration or you want to enable them conditionally.
In these cases, specify the list of types to process using the @EnableConfigurationProperties
annotation.
This can be done on any @Configuration
class, as shown in the following example:
@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(SomeProperties.class)
public class MyConfiguration {
}
@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(SomeProperties::class)
class MyConfiguration
@ConfigurationProperties("some.properties")
public class SomeProperties {
}
@ConfigurationProperties("some.properties")
class SomeProperties
To use configuration property scanning, add the @ConfigurationPropertiesScan
annotation to your application.
Typically, it is added to the main application class that is annotated with @SpringBootApplication
but it can be added to any @Configuration
class.
By default, scanning will occur from the package of the class that declares the annotation.
If you want to define specific packages to scan, you can do so as shown in the following example:
@SpringBootApplication
@ConfigurationPropertiesScan({ "com.example.app", "com.example.another" })
public class MyApplication {
}
@SpringBootApplication
@ConfigurationPropertiesScan("com.example.app", "com.example.another")
class MyApplication
When the Assuming that it is in the |
We recommend that @ConfigurationProperties
only deal with the environment and, in particular, does not inject other beans from the context.
For corner cases, setter injection can be used or any of the *Aware
interfaces provided by the framework (such as EnvironmentAware
if you need access to the Environment
).
If you still want to inject other beans using the constructor, the configuration properties bean must be annotated with @Component
and use JavaBean-based property binding.
Using @ConfigurationProperties-annotated Types
This style of configuration works particularly well with the SpringApplication
external YAML configuration, as shown in the following example:
my:
service:
remote-address: 192.168.1.1
security:
username: "admin"
roles:
- "USER"
- "ADMIN"
To work with @ConfigurationProperties
beans, you can inject them in the same way as any other bean, as shown in the following example:
@Service
public class MyService {
private final MyProperties properties;
public MyService(MyProperties properties) {
this.properties = properties;
}
public void openConnection() {
Server server = new Server(this.properties.getRemoteAddress());
server.start();
// ...
}
// ...
}
@Service
class MyService(val properties: MyProperties) {
fun openConnection() {
val server = Server(properties.remoteAddress)
server.start()
// ...
}
// ...
}
Using @ConfigurationProperties also lets you generate metadata files that can be used by IDEs to offer auto-completion for your own keys.
See the appendix for details.
|
Third-party Configuration
As well as using @ConfigurationProperties
to annotate a class, you can also use it on public @Bean
methods.
Doing so can be particularly useful when you want to bind properties to third-party components that are outside of your control.
To configure a bean from the Environment
properties, add @ConfigurationProperties
to its bean registration, as shown in the following example:
@Configuration(proxyBeanMethods = false)
public class ThirdPartyConfiguration {
@Bean
@ConfigurationProperties(prefix = "another")
public AnotherComponent anotherComponent() {
return new AnotherComponent();
}
}
@Configuration(proxyBeanMethods = false)
class ThirdPartyConfiguration {
@Bean
@ConfigurationProperties(prefix = "another")
fun anotherComponent(): AnotherComponent = AnotherComponent()
}
Any JavaBean property defined with the another
prefix is mapped onto that AnotherComponent
bean in manner similar to the preceding SomeProperties
example.
Relaxed Binding
Spring Boot uses some relaxed rules for binding Environment
properties to @ConfigurationProperties
beans, so there does not need to be an exact match between the Environment
property name and the bean property name.
Common examples where this is useful include dash-separated environment properties (for example, context-path
binds to contextPath
), and capitalized environment properties (for example, PORT
binds to port
).
As an example, consider the following @ConfigurationProperties
class:
@ConfigurationProperties(prefix = "my.main-project.person")
public class MyPersonProperties {
private String firstName;
public String getFirstName() {
return this.firstName;
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
}
@ConfigurationProperties(prefix = "my.main-project.person")
class MyPersonProperties {
var firstName: String? = null
}
With the preceding code, the following properties names can all be used:
Property | Note |
---|---|
|
Kebab case, which is recommended for use in |
|
Standard camel case syntax. |
|
Underscore notation, which is an alternative format for use in |
|
Upper case format, which is recommended when using system environment variables. |
The prefix value for the annotation must be in kebab case (lowercase and separated by - , such as my.main-project.person ).
|
Property Source | Simple | List |
---|---|---|
Properties Files |
Camel case, kebab case, or underscore notation |
Standard list syntax using |
YAML Files |
Camel case, kebab case, or underscore notation |
Standard YAML list syntax or comma-separated values |
Environment Variables |
Upper case format with underscore as the delimiter (see Binding From Environment Variables). |
Numeric values surrounded by underscores (see Binding From Environment Variables) |
System properties |
Camel case, kebab case, or underscore notation |
Standard list syntax using |
We recommend that, when possible, properties are stored in lower-case kebab format, such as my.person.first-name=Rod .
|
Binding Maps
When binding to Map
properties you may need to use a special bracket notation so that the original key
value is preserved.
If the key is not surrounded by []
, any characters that are not alpha-numeric, -
or .
are removed.
For example, consider binding the following properties to a Map<String,String>
:
my.map.[/key1]=value1
my.map.[/key2]=value2
my.map./key3=value3
my:
map:
"[/key1]": "value1"
"[/key2]": "value2"
"/key3": "value3"
For YAML files, the brackets need to be surrounded by quotes for the keys to be parsed properly. |
The properties above will bind to a Map
with /key1
, /key2
and key3
as the keys in the map.
The slash has been removed from key3
because it was not surrounded by square brackets.
When binding to scalar values, keys with .
in them do not need to be surrounded by []
.
Scalar values include enums and all types in the java.lang
package except for Object
.
Binding a.b=c
to Map<String, String>
will preserve the .
in the key and return a Map with the entry {"a.b"="c"}
.
For any other types you need to use the bracket notation if your key
contains a .
.
For example, binding a.b=c
to Map<String, Object>
will return a Map with the entry {"a"={"b"="c"}}
whereas [a.b]=c
will return a Map with the entry {"a.b"="c"}
.
Binding From Environment Variables
Most operating systems impose strict rules around the names that can be used for environment variables.
For example, Linux shell variables can contain only letters (a
to z
or A
to Z
), numbers (0
to 9
) or the underscore character (_
).
By convention, Unix shell variables will also have their names in UPPERCASE.
Spring Boot’s relaxed binding rules are, as much as possible, designed to be compatible with these naming restrictions.
To convert a property name in the canonical-form to an environment variable name you can follow these rules:
-
Replace dots (
.
) with underscores (_
). -
Remove any dashes (
-
). -
Convert to uppercase.
For example, the configuration property spring.main.log-startup-info
would be an environment variable named SPRING_MAIN_LOGSTARTUPINFO
.
Environment variables can also be used when binding to object lists.
To bind to a List
, the element number should be surrounded with underscores in the variable name.
For example, the configuration property my.service[0].other
would use an environment variable named MY_SERVICE_0_OTHER
.
Merging Complex Types
When lists are configured in more than one place, overriding works by replacing the entire list.
For example, assume a MyPojo
object with name
and description
attributes that are null
by default.
The following example exposes a list of MyPojo
objects from MyProperties
:
@ConfigurationProperties("my")
public class MyProperties {
private final List<MyPojo> list = new ArrayList<>();
public List<MyPojo> getList() {
return this.list;
}
}
@ConfigurationProperties("my")
class MyProperties {
val list: List<MyPojo> = ArrayList()
}
Consider the following configuration:
my.list[0].name=my name
my.list[0].description=my description
#---
spring.config.activate.on-profile=dev
my.list[0].name=my another name
my:
list:
- name: "my name"
description: "my description"
---
spring:
config:
activate:
on-profile: "dev"
my:
list:
- name: "my another name"
If the dev
profile is not active, MyProperties.list
contains one MyPojo
entry, as previously defined.
If the dev
profile is enabled, however, the list
still contains only one entry (with a name of my another name
and a description of null
).
This configuration does not add a second MyPojo
instance to the list, and it does not merge the items.
When a List
is specified in multiple profiles, the one with the highest priority (and only that one) is used.
Consider the following example:
my.list[0].name=my name
my.list[0].description=my description
my.list[1].name=another name
my.list[1].description=another description
#---
spring.config.activate.on-profile=dev
my.list[0].name=my another name
my:
list:
- name: "my name"
description: "my description"
- name: "another name"
description: "another description"
---
spring:
config:
activate:
on-profile: "dev"
my:
list:
- name: "my another name"
In the preceding example, if the dev
profile is active, MyProperties.list
contains one MyPojo
entry (with a name of my another name
and a description of null
).
For YAML, both comma-separated lists and YAML lists can be used for completely overriding the contents of the list.
For Map
properties, you can bind with property values drawn from multiple sources.
However, for the same property in multiple sources, the one with the highest priority is used.
The following example exposes a Map<String, MyPojo>
from MyProperties
:
@ConfigurationProperties("my")
public class MyProperties {
private final Map<String, MyPojo> map = new LinkedHashMap<>();
public Map<String, MyPojo> getMap() {
return this.map;
}
}
@ConfigurationProperties("my")
class MyProperties {
val map: Map<String, MyPojo> = LinkedHashMap()
}
Consider the following configuration:
my.map.key1.name=my name 1
my.map.key1.description=my description 1
#---
spring.config.activate.on-profile=dev
my.map.key1.name=dev name 1
my.map.key2.name=dev name 2
my.map.key2.description=dev description 2
my:
map:
key1:
name: "my name 1"
description: "my description 1"
---
spring:
config:
activate:
on-profile: "dev"
my:
map:
key1:
name: "dev name 1"
key2:
name: "dev name 2"
description: "dev description 2"
If the dev
profile is not active, MyProperties.map
contains one entry with key key1
(with a name of my name 1
and a description of my description 1
).
If the dev
profile is enabled, however, map
contains two entries with keys key1
(with a name of dev name 1
and a description of my description 1
) and key2
(with a name of dev name 2
and a description of dev description 2
).
The preceding merging rules apply to properties from all property sources, and not just files. |
Properties Conversion
Spring Boot attempts to coerce the external application properties to the right type when it binds to the @ConfigurationProperties
beans.
If you need custom type conversion, you can provide a ConversionService
bean (with a bean named conversionService
) or custom property editors (through a CustomEditorConfigurer
bean) or custom Converters
(with bean definitions annotated as @ConfigurationPropertiesBinding
).
As this bean is requested very early during the application lifecycle, make sure to limit the dependencies that your ConversionService is using.
Typically, any dependency that you require may not be fully initialized at creation time.
You may want to rename your custom ConversionService if it is not required for configuration keys coercion and only rely on custom converters qualified with @ConfigurationPropertiesBinding .
|
Converting Durations
Spring Boot has dedicated support for expressing durations.
If you expose a java.time.Duration
property, the following formats in application properties are available:
-
A regular
long
representation (using milliseconds as the default unit unless a@DurationUnit
has been specified) -
The standard ISO-8601 format used by
java.time.Duration
-
A more readable format where the value and the unit are coupled (
10s
means 10 seconds)
Consider the following example:
@ConfigurationProperties("my")
public class MyProperties {
@DurationUnit(ChronoUnit.SECONDS)
private Duration sessionTimeout = Duration.ofSeconds(30);
private Duration readTimeout = Duration.ofMillis(1000);
}
@ConfigurationProperties("my")
class MyProperties {
@DurationUnit(ChronoUnit.SECONDS)
var sessionTimeout = Duration.ofSeconds(30)
var readTimeout = Duration.ofMillis(1000)
}
To specify a session timeout of 30 seconds, 30
, PT30S
and 30s
are all equivalent.
A read timeout of 500ms can be specified in any of the following form: 500
, PT0.5S
and 500ms
.
You can also use any of the supported units. These are:
-
ns
for nanoseconds -
us
for microseconds -
ms
for milliseconds -
s
for seconds -
m
for minutes -
h
for hours -
d
for days
The default unit is milliseconds and can be overridden using @DurationUnit
as illustrated in the sample above.
If you prefer to use constructor binding, the same properties can be exposed, as shown in the following example:
@ConfigurationProperties("my")
@ConstructorBinding
public class MyProperties {
public MyProperties(@DurationUnit(ChronoUnit.SECONDS) @DefaultValue("30s") Duration sessionTimeout,
@DefaultValue("1000ms") Duration readTimeout) {
this.sessionTimeout = sessionTimeout;
this.readTimeout = readTimeout;
}
}
@ConfigurationProperties("my")
@ConstructorBinding
class MyProperties(@param:DurationUnit(ChronoUnit.SECONDS) @param:DefaultValue("30s") val sessionTimeout: Duration,
@param:DefaultValue("1000ms") val readTimeout: Duration)
If you are upgrading a Long property, make sure to define the unit (using @DurationUnit ) if it is not milliseconds.
Doing so gives a transparent upgrade path while supporting a much richer format.
|
Converting Periods
In addition to durations, Spring Boot can also work with java.time.Period
type.
The following formats can be used in application properties:
-
An regular
int
representation (using days as the default unit unless a@PeriodUnit
has been specified) -
The standard ISO-8601 format used by
java.time.Period
-
A simpler format where the value and the unit pairs are coupled (
1y3d
means 1 year and 3 days)
The following units are supported with the simple format:
-
y
for years -
m
for months -
w
for weeks -
d
for days
The java.time.Period type never actually stores the number of weeks, it is a shortcut that means “7 days”.
|
Converting Data Sizes
Spring Framework has a DataSize
value type that expresses a size in bytes.
If you expose a DataSize
property, the following formats in application properties are available:
-
A regular
long
representation (using bytes as the default unit unless a@DataSizeUnit
has been specified) -
A more readable format where the value and the unit are coupled (
10MB
means 10 megabytes)
Consider the following example:
@ConfigurationProperties("my")
public class MyProperties {
@DataSizeUnit(DataUnit.MEGABYTES)
private DataSize bufferSize = DataSize.ofMegabytes(2);
private DataSize sizeThreshold = DataSize.ofBytes(512);
}
@ConfigurationProperties("my")
class MyProperties {
@DataSizeUnit(DataUnit.MEGABYTES)
var bufferSize = DataSize.ofMegabytes(2)
var sizeThreshold = DataSize.ofBytes(512)
}
To specify a buffer size of 10 megabytes, 10
and 10MB
are equivalent.
A size threshold of 256 bytes can be specified as 256
or 256B
.
You can also use any of the supported units. These are:
-
B
for bytes -
KB
for kilobytes -
MB
for megabytes -
GB
for gigabytes -
TB
for terabytes
The default unit is bytes and can be overridden using @DataSizeUnit
as illustrated in the sample above.
If you prefer to use constructor binding, the same properties can be exposed, as shown in the following example:
@ConfigurationProperties("my")
@ConstructorBinding
public class MyProperties {
public MyProperties(@DataSizeUnit(DataUnit.MEGABYTES) @DefaultValue("2MB") DataSize bufferSize,
@DefaultValue("512B") DataSize sizeThreshold) {
this.bufferSize = bufferSize;
this.sizeThreshold = sizeThreshold;
}
}
@ConfigurationProperties("my")
@ConstructorBinding
class MyProperties(@param:DataSizeUnit(DataUnit.MEGABYTES) @param:DefaultValue("2MB") val bufferSize: DataSize,
@param:DefaultValue("512B") val sizeThreshold: DataSize)
If you are upgrading a Long property, make sure to define the unit (using @DataSizeUnit ) if it is not bytes.
Doing so gives a transparent upgrade path while supporting a much richer format.
|
@ConfigurationProperties Validation
Spring Boot attempts to validate @ConfigurationProperties
classes whenever they are annotated with Spring’s @Validated
annotation.
You can use JSR-303 javax.validation
constraint annotations directly on your configuration class.
To do so, ensure that a compliant JSR-303 implementation is on your classpath and then add constraint annotations to your fields, as shown in the following example:
@ConfigurationProperties("my.service")
@Validated
public class MyProperties {
@NotNull
private InetAddress remoteAddress;
}
@ConfigurationProperties("my.service")
@Validated
class MyProperties {
var remoteAddress: @NotNull InetAddress? = null
}
You can also trigger validation by annotating the @Bean method that creates the configuration properties with @Validated .
|
To ensure that validation is always triggered for nested properties, even when no properties are found, the associated field must be annotated with @Valid
.
The following example builds on the preceding MyProperties
example:
@ConfigurationProperties("my.service")
@Validated
public class MyProperties {
@NotNull
private InetAddress remoteAddress;
@Valid
private final Security security = new Security();
public static class Security {
@NotEmpty
private String username;
}
}
@ConfigurationProperties("my.service")
@Validated
class MyProperties {
var remoteAddress: @NotNull InetAddress? = null
@Valid
val security = Security()
class Security {
@NotEmpty
var username: String? = null
}
}
You can also add a custom Spring Validator
by creating a bean definition called configurationPropertiesValidator
.
The @Bean
method should be declared static
.
The configuration properties validator is created very early in the application’s lifecycle, and declaring the @Bean
method as static lets the bean be created without having to instantiate the @Configuration
class.
Doing so avoids any problems that may be caused by early instantiation.
The spring-boot-actuator module includes an endpoint that exposes all @ConfigurationProperties beans.
Point your web browser to /actuator/configprops or use the equivalent JMX endpoint.
See the "Production ready features" section for details.
|
@ConfigurationProperties vs. @Value
The @Value
annotation is a core container feature, and it does not provide the same features as type-safe configuration properties.
The following table summarizes the features that are supported by @ConfigurationProperties
and @Value
:
Feature | @ConfigurationProperties |
@Value |
---|---|---|
Yes |
Limited (see note below) |
|
Yes |
No |
|
|
No |
Yes |
If you do want to use For example, |
If you define a set of configuration keys for your own components, we recommend you group them in a POJO annotated with @ConfigurationProperties
.
Doing so will provide you with structured, type-safe object that you can inject into your own beans.
SpEL
expressions from application property files are not processed at time of parsing these files and populating the environment.
However, it is possible to write a SpEL
expression in @Value
.
If the value of a property from an application property file is a SpEL
expression, it will be evaluated when consumed through @Value
.
7.3. Profiles
Spring Profiles provide a way to segregate parts of your application configuration and make it be available only in certain environments.
Any @Component
, @Configuration
or @ConfigurationProperties
can be marked with @Profile
to limit when it is loaded, as shown in the following example:
@Configuration(proxyBeanMethods = false)
@Profile("production")
public class ProductionConfiguration {
// ...
}
@Configuration(proxyBeanMethods = false)
@Profile("production")
class ProductionConfiguration {
// ...
}
If @ConfigurationProperties beans are registered through @EnableConfigurationProperties instead of automatic scanning, the @Profile annotation needs to be specified on the @Configuration class that has the @EnableConfigurationProperties annotation.
In the case where @ConfigurationProperties are scanned, @Profile can be specified on the @ConfigurationProperties class itself.
|
You can use a spring.profiles.active
Environment
property to specify which profiles are active.
You can specify the property in any of the ways described earlier in this chapter.
For example, you could include it in your application.properties
, as shown in the following example:
spring.profiles.active=dev,hsqldb
spring:
profiles:
active: "dev,hsqldb"
You could also specify it on the command line by using the following switch: --spring.profiles.active=dev,hsqldb
.
If no profile is active, a default profile is enabled.
The name of the default profile is default
and it can be tuned using the spring.profiles.default
Environment
property, as shown in the following example:
spring.profiles.default=none
spring:
profiles:
default: "none"
spring.profiles.active
and spring.profiles.default
can only be used in non-profile specific documents.
This means they cannot be included in profile specific files or documents activated by spring.config.activate.on-profile
.
For example, the second document configuration is invalid:
# this document is valid
spring.profiles.active=prod
#---
# this document is invalid
spring.config.activate.on-profile=prod
spring.profiles.active=metrics
# this document is valid
spring:
profiles:
active: "prod"
---
# this document is invalid
spring:
config:
activate:
on-profile: "prod"
profiles:
active: "metrics"
7.3.1. Adding Active Profiles
The spring.profiles.active
property follows the same ordering rules as other properties: The highest PropertySource
wins.
This means that you can specify active profiles in application.properties
and then replace them by using the command line switch.
Sometimes, it is useful to have properties that add to the active profiles rather than replace them.
The spring.profiles.include
property can be used to add active profiles on top of those activated by the spring.profiles.active
property.
The SpringApplication
entry point also has a Java API for setting additional profiles.
See the setAdditionalProfiles()
method in SpringApplication.
For example, when an application with the following properties is run, the common and local profiles will be activated even when it runs using the --spring.profiles.active switch:
spring.profiles.include[0]=common
spring.profiles.include[1]=local
spring:
profiles:
include:
- "common"
- "local"
Similar to spring.profiles.active , spring.profiles.include can only be used in non-profile specific documents.
This means it cannot be included in profile specific files or documents activated by spring.config.activate.on-profile .
|
Profile groups, which are described in the next section can also be used to add active profiles if a given profile is active.
7.3.2. Profile Groups
Occasionally the profiles that you define and use in your application are too fine-grained and become cumbersome to use.
For example, you might have proddb
and prodmq
profiles that you use to enable database and messaging features independently.
To help with this, Spring Boot lets you define profile groups. A profile group allows you to define a logical name for a related group of profiles.
For example, we can create a production
group that consists of our proddb
and prodmq
profiles.
spring.profiles.group.production[0]=proddb
spring.profiles.group.production[1]=prodmq
spring:
profiles:
group:
production:
- "proddb"
- "prodmq"
Our application can now be started using --spring.profiles.active=production
to active the production
, proddb
and prodmq
profiles in one hit.
7.3.3. Programmatically Setting Profiles
You can programmatically set active profiles by calling SpringApplication.setAdditionalProfiles(…)
before your application runs.
It is also possible to activate profiles by using Spring’s ConfigurableEnvironment
interface.
7.3.4. Profile-specific Configuration Files
Profile-specific variants of both application.properties
(or application.yaml
) and files referenced through @ConfigurationProperties
are considered as files and loaded.
See "Profile Specific Files" for details.
7.4. Logging
Spring Boot uses Commons Logging for all internal logging but leaves the underlying log implementation open. Default configurations are provided for Java Util Logging, Log4J2, and Logback. In each case, loggers are pre-configured to use console output with optional file output also available.
By default, if you use the “Starters”, Logback is used for logging. Appropriate Logback routing is also included to ensure that dependent libraries that use Java Util Logging, Commons Logging, Log4J, or SLF4J all work correctly.
There are a lot of logging frameworks available for Java. Do not worry if the above list seems confusing. Generally, you do not need to change your logging dependencies and the Spring Boot defaults work just fine. |
When you deploy your application to a servlet container or application server, logging performed with the Java Util Logging API is not routed into your application’s logs. This prevents logging performed by the container or other applications that have been deployed to it from appearing in your application’s logs. |
7.4.1. Log Format
The default log output from Spring Boot resembles the following example:
2023-11-23 07:23:18.861 INFO 28351 --- [ main] o.s.b.d.f.logexample.MyApplication : Starting MyApplication using Java 1.8.0_392 on myhost with PID 28351 (/opt/apps/myapp.jar started by myuser in /opt/apps/) 2023-11-23 07:23:18.868 INFO 28351 --- [ main] o.s.b.d.f.logexample.MyApplication : No active profile set, falling back to 1 default profile: "default" 2023-11-23 07:23:20.194 INFO 28351 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8080 (http) 2023-11-23 07:23:20.209 INFO 28351 --- [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat] 2023-11-23 07:23:20.209 INFO 28351 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/9.0.83] 2023-11-23 07:23:20.342 INFO 28351 --- [ main] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext 2023-11-23 07:23:20.342 INFO 28351 --- [ main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1404 ms 2023-11-23 07:23:20.946 INFO 28351 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path '' 2023-11-23 07:23:20.962 INFO 28351 --- [ main] o.s.b.d.f.logexample.MyApplication : Started MyApplication in 2.7 seconds (JVM running for 3.157)
The following items are output:
-
Date and Time: Millisecond precision and easily sortable.
-
Log Level:
ERROR
,WARN
,INFO
,DEBUG
, orTRACE
. -
Process ID.
-
A
---
separator to distinguish the start of actual log messages. -
Thread name: Enclosed in square brackets (may be truncated for console output).
-
Logger name: This is usually the source class name (often abbreviated).
-
The log message.
Logback does not have a FATAL level.
It is mapped to ERROR .
|
7.4.2. Console Output
The default log configuration echoes messages to the console as they are written.
By default, ERROR
-level, WARN
-level, and INFO
-level messages are logged.
You can also enable a “debug” mode by starting your application with a --debug
flag.
$ java -jar myapp.jar --debug
You can also specify debug=true in your application.properties .
|
When the debug mode is enabled, a selection of core loggers (embedded container, Hibernate, and Spring Boot) are configured to output more information.
Enabling the debug mode does not configure your application to log all messages with DEBUG
level.
Alternatively, you can enable a “trace” mode by starting your application with a --trace
flag (or trace=true
in your application.properties
).
Doing so enables trace logging for a selection of core loggers (embedded container, Hibernate schema generation, and the whole Spring portfolio).
Color-coded Output
If your terminal supports ANSI, color output is used to aid readability.
You can set spring.output.ansi.enabled
to a supported value to override the auto-detection.
Color coding is configured by using the %clr
conversion word.
In its simplest form, the converter colors the output according to the log level, as shown in the following example:
%clr(%5p)
The following table describes the mapping of log levels to colors:
Level | Color |
---|---|
|
Red |
|
Red |
|
Yellow |
|
Green |
|
Green |
|
Green |
Alternatively, you can specify the color or style that should be used by providing it as an option to the conversion. For example, to make the text yellow, use the following setting:
%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){yellow}
The following colors and styles are supported:
-
blue
-
cyan
-
faint
-
green
-
magenta
-
red
-
yellow
7.4.3. File Output
By default, Spring Boot logs only to the console and does not write log files.
If you want to write log files in addition to the console output, you need to set a logging.file.name
or logging.file.path
property (for example, in your application.properties
).
The following table shows how the logging.*
properties can be used together:
logging.file.name |
logging.file.path |
Example | Description |
---|---|---|---|
(none) |
(none) |
Console only logging. |
|
Specific file |
(none) |
|
Writes to the specified log file. Names can be an exact location or relative to the current directory. |
(none) |
Specific directory |
|
Writes |
Log files rotate when they reach 10 MB and, as with console output, ERROR
-level, WARN
-level, and INFO
-level messages are logged by default.
Logging properties are independent of the actual logging infrastructure.
As a result, specific configuration keys (such as logback.configurationFile for Logback) are not managed by spring Boot.
|
7.4.4. File Rotation
If you are using the Logback, it is possible to fine-tune log rotation settings using your application.properties
or application.yaml
file.
For all other logging system, you will need to configure rotation settings directly yourself (for example, if you use Log4J2 then you could add a log4j2.xml
or log4j2-spring.xml
file).
The following rotation policy properties are supported:
Name | Description |
---|---|
|
The filename pattern used to create log archives. |
|
If log archive cleanup should occur when the application starts. |
|
The maximum size of log file before it is archived. |
|
The maximum amount of size log archives can take before being deleted. |
|
The maximum number of archive log files to keep (defaults to 7). |
7.4.5. Log Levels
All the supported logging systems can have the logger levels set in the Spring Environment
(for example, in application.properties
) by using logging.level.<logger-name>=<level>
where level
is one of TRACE, DEBUG, INFO, WARN, ERROR, FATAL, or OFF.
The root
logger can be configured by using logging.level.root
.
The following example shows potential logging settings in application.properties
:
logging.level.root=warn
logging.level.org.springframework.web=debug
logging.level.org.hibernate=error
logging:
level:
root: "warn"
org.springframework.web: "debug"
org.hibernate: "error"
It is also possible to set logging levels using environment variables.
For example, LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG
will set org.springframework.web
to DEBUG
.
The above approach will only work for package level logging.
Since relaxed binding always converts environment variables to lowercase, it is not possible to configure logging for an individual class in this way.
If you need to configure logging for a class, you can use the SPRING_APPLICATION_JSON variable.
|
7.4.6. Log Groups
It is often useful to be able to group related loggers together so that they can all be configured at the same time. For example, you might commonly change the logging levels for all Tomcat related loggers, but you can not easily remember top level packages.
To help with this, Spring Boot allows you to define logging groups in your Spring Environment
.
For example, here is how you could define a “tomcat” group by adding it to your application.properties
:
logging.group.tomcat=org.apache.catalina,org.apache.coyote,org.apache.tomcat
logging:
group:
tomcat: "org.apache.catalina,org.apache.coyote,org.apache.tomcat"
Once defined, you can change the level for all the loggers in the group with a single line:
logging.level.tomcat=trace
logging:
level:
tomcat: "trace"
Spring Boot includes the following pre-defined logging groups that can be used out-of-the-box:
Name | Loggers |
---|---|
web |
|
sql |
|
7.4.7. Using a Log Shutdown Hook
In order to release logging resources when your application terminates, a shutdown hook that will trigger log system cleanup when the JVM exits is provided.
This shutdown hook is registered automatically unless your application is deployed as a war file.
If your application has complex context hierarchies the shutdown hook may not meet your needs.
If it does not, disable the shutdown hook and investigate the options provided directly by the underlying logging system.
For example, Logback offers context selectors which allow each Logger to be created in its own context.
You can use the logging.register-shutdown-hook
property to disable the shutdown hook.
Setting it to false
will disable the registration.
You can set the property in your application.properties
or application.yaml
file:
logging.register-shutdown-hook=false
logging:
register-shutdown-hook: false
7.4.8. Custom Log Configuration
The various logging systems can be activated by including the appropriate libraries on the classpath and can be further customized by providing a suitable configuration file in the root of the classpath or in a location specified by the following Spring Environment
property: logging.config
.
You can force Spring Boot to use a particular logging system by using the org.springframework.boot.logging.LoggingSystem
system property.
The value should be the fully qualified class name of a LoggingSystem
implementation.
You can also disable Spring Boot’s logging configuration entirely by using a value of none
.
Since logging is initialized before the ApplicationContext is created, it is not possible to control logging from @PropertySources in Spring @Configuration files.
The only way to change the logging system or disable it entirely is through System properties.
|
Depending on your logging system, the following files are loaded:
Logging System | Customization |
---|---|
Logback |
|
Log4j2 |
|
JDK (Java Util Logging) |
|
When possible, we recommend that you use the -spring variants for your logging configuration (for example, logback-spring.xml rather than logback.xml ).
If you use standard configuration locations, Spring cannot completely control log initialization.
|
There are known classloading issues with Java Util Logging that cause problems when running from an 'executable jar'. We recommend that you avoid it when running from an 'executable jar' if at all possible. |
To help with the customization, some other properties are transferred from the Spring Environment
to System properties.
This allows the properties to be consumed by logging system configuration. For example, setting logging.file.name
in application.properties
or LOGGING_FILE_NAME
as an environment variable will result in the LOG_FILE
System property being set.
The properties that are transferred are described in the following table:
Spring Environment | System Property | Comments |
---|---|---|
|
|
The conversion word used when logging exceptions. |
|
|
If defined, it is used in the default log configuration. |
|
|
If defined, it is used in the default log configuration. |
|
|
The log pattern to use on the console (stdout). |
|
|
Appender pattern for log date format. |
|
|
The charset to use for console logging. |
|
|
The log pattern to use in a file (if |
|
|
The charset to use for file logging (if |
|
|
The format to use when rendering the log level (default |
|
|
The current process ID (discovered if possible and when not already defined as an OS environment variable). |
If you use Logback, the following properties are also transferred:
Spring Environment | System Property | Comments |
---|---|---|
|
|
Pattern for rolled-over log file names (default |
|
|
Whether to clean the archive log files on startup. |
|
|
Maximum log file size. |
|
|
Total size of log backups to be kept. |
|
|
Maximum number of archive log files to keep. |
All the supported logging systems can consult System properties when parsing their configuration files.
See the default configurations in spring-boot.jar
for examples:
If you want to use a placeholder in a logging property, you should use Spring Boot’s syntax and not the syntax of the underlying framework.
Notably, if you use Logback, you should use |
You can add MDC and other ad-hoc content to log lines by overriding only the 2019-08-30 12:30:04.031 user:someone INFO 22174 --- [ nio-8080-exec-0] demo.Controller Handling authenticated request |
7.4.9. Logback Extensions
Spring Boot includes a number of extensions to Logback that can help with advanced configuration.
You can use these extensions in your logback-spring.xml
configuration file.
Because the standard logback.xml configuration file is loaded too early, you cannot use extensions in it.
You need to either use logback-spring.xml or define a logging.config property.
|
The extensions cannot be used with Logback’s configuration scanning. If you attempt to do so, making changes to the configuration file results in an error similar to one of the following being logged: |
ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProperty], current ElementPath is [[configuration][springProperty]] ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProfile], current ElementPath is [[configuration][springProfile]]
Profile-specific Configuration
The <springProfile>
tag lets you optionally include or exclude sections of configuration based on the active Spring profiles.
Profile sections are supported anywhere within the <configuration>
element.
Use the name
attribute to specify which profile accepts the configuration.
The <springProfile>
tag can contain a profile name (for example staging
) or a profile expression.
A profile expression allows for more complicated profile logic to be expressed, for example production & (eu-central | eu-west)
.
Check the reference guide for more details.
The following listing shows three sample profiles:
<springProfile name="staging">
<!-- configuration to be enabled when the "staging" profile is active -->
</springProfile>
<springProfile name="dev | staging">
<!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
</springProfile>
<springProfile name="!production">
<!-- configuration to be enabled when the "production" profile is not active -->
</springProfile>
Environment Properties
The <springProperty>
tag lets you expose properties from the Spring Environment
for use within Logback.
Doing so can be useful if you want to access values from your application.properties
file in your Logback configuration.
The tag works in a similar way to Logback’s standard <property>
tag.
However, rather than specifying a direct value
, you specify the source
of the property (from the Environment
).
If you need to store the property somewhere other than in local
scope, you can use the scope
attribute.
If you need a fallback value (in case the property is not set in the Environment
), you can use the defaultValue
attribute.
The following example shows how to expose properties for use within Logback:
<springProperty scope="context" name="fluentHost" source="myapp.fluentd.host"
defaultValue="localhost"/>
<appender name="FLUENT" class="ch.qos.logback.more.appenders.DataFluentAppender">
<remoteHost>${fluentHost}</remoteHost>
...
</appender>
The source must be specified in kebab case (such as my.property-name ).
However, properties can be added to the Environment by using the relaxed rules.
|
7.5. Internationalization
Spring Boot supports localized messages so that your application can cater to users of different language preferences.
By default, Spring Boot looks for the presence of a messages
resource bundle at the root of the classpath.
The auto-configuration applies when the default properties file for the configured resource bundle is available (messages.properties by default).
If your resource bundle contains only language-specific properties files, you are required to add the default.
If no properties file is found that matches any of the configured base names, there will be no auto-configured MessageSource .
|
The basename of the resource bundle as well as several other attributes can be configured using the spring.messages
namespace, as shown in the following example:
spring.messages.basename=messages,config.i18n.messages
spring.messages.fallback-to-system-locale=false
spring:
messages:
basename: "messages,config.i18n.messages"
fallback-to-system-locale: false
spring.messages.basename supports comma-separated list of locations, either a package qualifier or a resource resolved from the classpath root.
|
See MessageSourceProperties
for more supported options.
7.6. Aspect-Oriented Programming
Spring Boot provides auto-configuration for aspect-oriented programming (AOP). You can learn more about AOP with Spring in the Spring Framework reference documentation.
By default, Spring Boot’s auto-configuration configures Spring AOP to use CGLib proxies.
To use JDK proxies instead, set configprop:spring.aop.proxy-target-class
to false
.
If AspectJ is on the classpath, Spring Boot’s auto-configuration will automatically enable AspectJ auto proxy such that @EnableAspectJAutoProxy
is not required.
7.7. JSON
Spring Boot provides integration with three JSON mapping libraries:
-
Gson
-
Jackson
-
JSON-B
Jackson is the preferred and default library.
7.7.1. Jackson
Auto-configuration for Jackson is provided and Jackson is part of spring-boot-starter-json
.
When Jackson is on the classpath an ObjectMapper
bean is automatically configured.
Several configuration properties are provided for customizing the configuration of the ObjectMapper
.
Custom Serializers and Deserializers
If you use Jackson to serialize and deserialize JSON data, you might want to write your own JsonSerializer
and JsonDeserializer
classes.
Custom serializers are usually registered with Jackson through a module, but Spring Boot provides an alternative @JsonComponent
annotation that makes it easier to directly register Spring Beans.
You can use the @JsonComponent
annotation directly on JsonSerializer
, JsonDeserializer
or KeyDeserializer
implementations.
You can also use it on classes that contain serializers/deserializers as inner classes, as shown in the following example:
@JsonComponent
public class MyJsonComponent {
public static class Serializer extends JsonSerializer<MyObject> {
@Override
public void serialize(MyObject value, JsonGenerator jgen, SerializerProvider serializers) throws IOException {
jgen.writeStartObject();
jgen.writeStringField("name", value.getName());
jgen.writeNumberField("age", value.getAge());
jgen.writeEndObject();
}
}
public static class Deserializer extends JsonDeserializer<MyObject> {
@Override
public MyObject deserialize(JsonParser jsonParser, DeserializationContext ctxt) throws IOException {
ObjectCodec codec = jsonParser.getCodec();
JsonNode tree = codec.readTree(jsonParser);
String name = tree.get("name").textValue();
int age = tree.get("age").intValue();
return new MyObject(name, age);
}
}
}
@JsonComponent
class MyJsonComponent {
class Serializer : JsonSerializer<MyObject>() {
@Throws(IOException::class)
override fun serialize(value: MyObject, jgen: JsonGenerator, serializers: SerializerProvider) {
jgen.writeStartObject()
jgen.writeStringField("name", value.name)
jgen.writeNumberField("age", value.age)
jgen.writeEndObject()
}
}
class Deserializer : JsonDeserializer<MyObject>() {
@Throws(IOException::class, JsonProcessingException::class)
override fun deserialize(jsonParser: JsonParser, ctxt: DeserializationContext): MyObject {
val codec = jsonParser.codec
val tree = codec.readTree<JsonNode>(jsonParser)
val name = tree["name"].textValue()
val age = tree["age"].intValue()
return MyObject(name, age)
}
}
}
All @JsonComponent
beans in the ApplicationContext
are automatically registered with Jackson.
Because @JsonComponent
is meta-annotated with @Component
, the usual component-scanning rules apply.
Spring Boot also provides JsonObjectSerializer
and JsonObjectDeserializer
base classes that provide useful alternatives to the standard Jackson versions when serializing objects.
See JsonObjectSerializer
and JsonObjectDeserializer
in the Javadoc for details.
The example above can be rewritten to use JsonObjectSerializer
/JsonObjectDeserializer
as follows:
@JsonComponent
public class MyJsonComponent {
public static class Serializer extends JsonObjectSerializer<MyObject> {
@Override
protected void serializeObject(MyObject value, JsonGenerator jgen, SerializerProvider provider)
throws IOException {
jgen.writeStringField("name", value.getName());
jgen.writeNumberField("age", value.getAge());
}
}
public static class Deserializer extends JsonObjectDeserializer<MyObject> {
@Override
protected MyObject deserializeObject(JsonParser jsonParser, DeserializationContext context, ObjectCodec codec,
JsonNode tree) throws IOException {
String name = nullSafeValue(tree.get("name"), String.class);
int age = nullSafeValue(tree.get("age"), Integer.class);
return new MyObject(name, age);
}
}
}
`object`
@JsonComponent
class MyJsonComponent {
class Serializer : JsonObjectSerializer<MyObject>() {
@Throws(IOException::class)
override fun serializeObject(value: MyObject, jgen: JsonGenerator, provider: SerializerProvider) {
jgen.writeStringField("name", value.name)
jgen.writeNumberField("age", value.age)
}
}
class Deserializer : JsonObjectDeserializer<MyObject>() {
@Throws(IOException::class)
override fun deserializeObject(jsonParser: JsonParser, context: DeserializationContext,
codec: ObjectCodec, tree: JsonNode): MyObject {
val name = nullSafeValue(tree["name"], String::class.java)
val age = nullSafeValue(tree["age"], Int::class.java)
return MyObject(name, age)
}
}
}
Mixins
Jackson has support for mixins that can be used to mix additional annotations into those already declared on a target class.
Spring Boot’s Jackson auto-configuration will scan your application’s packages for classes annotated with @JsonMixin
and register them with the auto-configured ObjectMapper
.
The registration is performed by Spring Boot’s JsonMixinModule
.
7.8. Task Execution and Scheduling
In the absence of an Executor
bean in the context, Spring Boot auto-configures a ThreadPoolTaskExecutor
with sensible defaults that can be automatically associated to asynchronous task execution (@EnableAsync
) and Spring MVC asynchronous request processing.
If you have defined a custom The auto-configured |
The thread pool uses 8 core threads that can grow and shrink according to the load.
Those default settings can be fine-tuned using the spring.task.execution
namespace, as shown in the following example:
spring.task.execution.pool.max-size=16
spring.task.execution.pool.queue-capacity=100
spring.task.execution.pool.keep-alive=10s
spring:
task:
execution:
pool:
max-size: 16
queue-capacity: 100
keep-alive: "10s"
This changes the thread pool to use a bounded queue so that when the queue is full (100 tasks), the thread pool increases to maximum 16 threads. Shrinking of the pool is more aggressive as threads are reclaimed when they are idle for 10 seconds (rather than 60 seconds by default).
A ThreadPoolTaskScheduler
can also be auto-configured if need to be associated to scheduled task execution (using @EnableScheduling
for instance).
The thread pool uses one thread by default and its settings can be fine-tuned using the spring.task.scheduling
namespace, as shown in the following example:
spring.task.scheduling.thread-name-prefix=scheduling-
spring.task.scheduling.pool.size=2
spring:
task:
scheduling:
thread-name-prefix: "scheduling-"
pool:
size: 2
Both a TaskExecutorBuilder
bean and a TaskSchedulerBuilder
bean are made available in the context if a custom executor or scheduler needs to be created.
7.9. Testing
Spring Boot provides a number of utilities and annotations to help when testing your application.
Test support is provided by two modules: spring-boot-test
contains core items, and spring-boot-test-autoconfigure
supports auto-configuration for tests.
Most developers use the spring-boot-starter-test
“Starter”, which imports both Spring Boot test modules as well as JUnit Jupiter, AssertJ, Hamcrest, and a number of other useful libraries.
If you have tests that use JUnit 4, JUnit 5’s vintage engine can be used to run them.
To use the vintage engine, add a dependency on
|
hamcrest-core
is excluded in favor of org.hamcrest:hamcrest
that is part of spring-boot-starter-test
.
7.9.1. Test Scope Dependencies
The spring-boot-starter-test
“Starter” (in the test
scope
) contains the following provided libraries:
-
JUnit 5: The de-facto standard for unit testing Java applications.
-
Spring Test & Spring Boot Test: Utilities and integration test support for Spring Boot applications.
-
AssertJ: A fluent assertion library.
-
Hamcrest: A library of matcher objects (also known as constraints or predicates).
-
Mockito: A Java mocking framework.
-
JSONassert: An assertion library for JSON.
-
JsonPath: XPath for JSON.
We generally find these common libraries to be useful when writing tests. If these libraries do not suit your needs, you can add additional test dependencies of your own.
7.9.2. Testing Spring Applications
One of the major advantages of dependency injection is that it should make your code easier to unit test.
You can instantiate objects by using the new
operator without even involving Spring.
You can also use mock objects instead of real dependencies.
Often, you need to move beyond unit testing and start integration testing (with a Spring ApplicationContext
).
It is useful to be able to perform integration testing without requiring deployment of your application or needing to connect to other infrastructure.
The Spring Framework includes a dedicated test module for such integration testing.
You can declare a dependency directly to org.springframework:spring-test
or use the spring-boot-starter-test
“Starter” to pull it in transitively.
If you have not used the spring-test
module before, you should start by reading the relevant section of the Spring Framework reference documentation.
7.9.3. Testing Spring Boot Applications
A Spring Boot application is a Spring ApplicationContext
, so nothing very special has to be done to test it beyond what you would normally do with a vanilla Spring context.
External properties, logging, and other features of Spring Boot are installed in the context by default only if you use SpringApplication to create it.
|
Spring Boot provides a @SpringBootTest
annotation, which can be used as an alternative to the standard spring-test
@ContextConfiguration
annotation when you need Spring Boot features.
The annotation works by creating the ApplicationContext
used in your tests through SpringApplication
.
In addition to @SpringBootTest
a number of other annotations are also provided for testing more specific slices of an application.
If you are using JUnit 4, do not forget to also add @RunWith(SpringRunner.class) to your test, otherwise the annotations will be ignored.
If you are using JUnit 5, there is no need to add the equivalent @ExtendWith(SpringExtension.class) as @SpringBootTest and the other @…Test annotations are already annotated with it.
|
By default, @SpringBootTest
will not start a server.
You can use the webEnvironment
attribute of @SpringBootTest
to further refine how your tests run:
-
MOCK
(Default) : Loads a webApplicationContext
and provides a mock web environment. Embedded servers are not started when using this annotation. If a web environment is not available on your classpath, this mode transparently falls back to creating a regular non-webApplicationContext
. It can be used in conjunction with@AutoConfigureMockMvc
or@AutoConfigureWebTestClient
for mock-based testing of your web application. -
RANDOM_PORT
: Loads aWebServerApplicationContext
and provides a real web environment. Embedded servers are started and listen on a random port. -
DEFINED_PORT
: Loads aWebServerApplicationContext
and provides a real web environment. Embedded servers are started and listen on a defined port (from yourapplication.properties
) or on the default port of8080
. -
NONE
: Loads anApplicationContext
by usingSpringApplication
but does not provide any web environment (mock or otherwise).
If your test is @Transactional , it rolls back the transaction at the end of each test method by default.
However, as using this arrangement with either RANDOM_PORT or DEFINED_PORT implicitly provides a real servlet environment, the HTTP client and server run in separate threads and, thus, in separate transactions.
Any transaction initiated on the server does not roll back in this case.
|
@SpringBootTest with webEnvironment = WebEnvironment.RANDOM_PORT will also start the management server on a separate random port if your application uses a different port for the management server.
|
Detecting Web Application Type
If Spring MVC is available, a regular MVC-based application context is configured. If you have only Spring WebFlux, we will detect that and configure a WebFlux-based application context instead.
If both are present, Spring MVC takes precedence.
If you want to test a reactive web application in this scenario, you must set the spring.main.web-application-type
property:
@SpringBootTest(properties = "spring.main.web-application-type=reactive")
class MyWebFluxTests {
// ...
}
@SpringBootTest(properties = ["spring.main.web-application-type=reactive"])
class MyWebFluxTests {
// ...
}
Detecting Test Configuration
If you are familiar with the Spring Test Framework, you may be used to using @ContextConfiguration(classes=…)
in order to specify which Spring @Configuration
to load.
Alternatively, you might have often used nested @Configuration
classes within your test.
When testing Spring Boot applications, this is often not required.
Spring Boot’s @*Test
annotations search for your primary configuration automatically whenever you do not explicitly define one.
The search algorithm works up from the package that contains the test until it finds a class annotated with @SpringBootApplication
or @SpringBootConfiguration
.
As long as you structured your code in a sensible way, your main configuration is usually found.
If you use a test annotation to test a more specific slice of your application, you should avoid adding configuration settings that are specific to a particular area on the main method’s application class. The underlying component scan configuration of |
If you want to customize the primary configuration, you can use a nested @TestConfiguration
class.
Unlike a nested @Configuration
class, which would be used instead of your application’s primary configuration, a nested @TestConfiguration
class is used in addition to your application’s primary configuration.
Spring’s test framework caches application contexts between tests. Therefore, as long as your tests share the same configuration (no matter how it is discovered), the potentially time-consuming process of loading the context happens only once. |
Excluding Test Configuration
If your application uses component scanning (for example, if you use @SpringBootApplication
or @ComponentScan
), you may find top-level configuration classes that you created only for specific tests accidentally get picked up everywhere.
As we have seen earlier, @TestConfiguration
can be used on an inner class of a test to customize the primary configuration.
@TestConfiguration
can also be used on a top-level class. Doing so indicates that the class should not be picked up by scanning.
You can then import the class explicitly where it is required, as shown in the following example:
@SpringBootTest
@Import(MyTestsConfiguration.class)
class MyTests {
@Test
void exampleTest() {
// ...
}
}
@SpringBootTest
@Import(MyTestsConfiguration::class)
class MyTests {
@Test
fun exampleTest() {
// ...
}
}
If you directly use @ComponentScan (that is, not through @SpringBootApplication ) you need to register the TypeExcludeFilter with it.
See the Javadoc for details.
|
An imported @TestConfiguration is processed earlier than an inner-class @TestConfiguration and an imported @TestConfiguration will be processed before any configuration found through component scanning.
Generally speaking, this difference in ordering has no noticeable effect but it is something to be aware of if you’re relying on bean overriding.
|
Using Application Arguments
If your application expects arguments, you can
have @SpringBootTest
inject them using the args
attribute.
@SpringBootTest(args = "--app.test=one")
class MyApplicationArgumentTests {
@Test
void applicationArgumentsPopulated(@Autowired ApplicationArguments args) {
assertThat(args.getOptionNames()).containsOnly("app.test");
assertThat(args.getOptionValues("app.test")).containsOnly("one");
}
}
@SpringBootTest(args = ["--app.test=one"])
class MyApplicationArgumentTests {
@Test
fun applicationArgumentsPopulated(@Autowired args: ApplicationArguments) {
assertThat(args.optionNames).containsOnly("app.test")
assertThat(args.getOptionValues("app.test")).containsOnly("one")
}
}
Testing With a Mock Environment
By default, @SpringBootTest
does not start the server but instead sets up a mock environment for testing web endpoints.
With Spring MVC, we can query our web endpoints using MockMvc
or WebTestClient
, as shown in the following example:
@SpringBootTest
@AutoConfigureMockMvc
class MyMockMvcTests {
@Test
void testWithMockMvc(@Autowired MockMvc mvc) throws Exception {
mvc.perform(get("/")).andExpect(status().isOk()).andExpect(content().string("Hello World"));
}
// If Spring WebFlux is on the classpath, you can drive MVC tests with a WebTestClient
@Test
void testWithWebTestClient(@Autowired WebTestClient webClient) {
webClient
.get().uri("/")
.exchange()
.expectStatus().isOk()
.expectBody(String.class).isEqualTo("Hello World");
}
}
@SpringBootTest
@AutoConfigureMockMvc
class MyMockMvcTests {
@Test
fun testWithMockMvc(@Autowired mvc: MockMvc) {
mvc.perform(MockMvcRequestBuilders.get("/")).andExpect(MockMvcResultMatchers.status().isOk)
.andExpect(MockMvcResultMatchers.content().string("Hello World"))
}
// If Spring WebFlux is on the classpath, you can drive MVC tests with a WebTestClient
@Test
fun testWithWebTestClient(@Autowired webClient: WebTestClient) {
webClient
.get().uri("/")
.exchange()
.expectStatus().isOk
.expectBody<String>().isEqualTo("Hello World")
}
}
If you want to focus only on the web layer and not start a complete ApplicationContext , consider using @WebMvcTest instead.
|
With Spring WebFlux endpoints, you can use WebTestClient
as shown in the following example:
@SpringBootTest
@AutoConfigureWebTestClient
class MyMockWebTestClientTests {
@Test
void exampleTest(@Autowired WebTestClient webClient) {
webClient
.get().uri("/")
.exchange()
.expectStatus().isOk()
.expectBody(String.class).isEqualTo("Hello World");
}
}
@SpringBootTest
@AutoConfigureWebTestClient
class MyMockWebTestClientTests {
@Test
fun exampleTest(@Autowired webClient: WebTestClient) {
webClient
.get().uri("/")
.exchange()
.expectStatus().isOk
.expectBody<String>().isEqualTo("Hello World")
}
}
Testing within a mocked environment is usually faster than running with a full servlet container. However, since mocking occurs at the Spring MVC layer, code that relies on lower-level servlet container behavior cannot be directly tested with MockMvc. For example, Spring Boot’s error handling is based on the “error page” support provided by the servlet container. This means that, whilst you can test your MVC layer throws and handles exceptions as expected, you cannot directly test that a specific custom error page is rendered. If you need to test these lower-level concerns, you can start a fully running server as described in the next section. |
Testing With a Running Server
If you need to start a full running server, we recommend that you use random ports.
If you use @SpringBootTest(webEnvironment=WebEnvironment.RANDOM_PORT)
, an available port is picked at random each time your test runs.
The @LocalServerPort
annotation can be used to inject the actual port used into your test.
For convenience, tests that need to make REST calls to the started server can additionally @Autowire
a WebTestClient
, which resolves relative links to the running server and comes with a dedicated API for verifying responses, as shown in the following example:
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyRandomPortWebTestClientTests {
@Test
void exampleTest(@Autowired WebTestClient webClient) {
webClient
.get().uri("/")
.exchange()
.expectStatus().isOk()
.expectBody(String.class).isEqualTo("Hello World");
}
}
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyRandomPortWebTestClientTests {
@Test
fun exampleTest(@Autowired webClient: WebTestClient) {
webClient
.get().uri("/")
.exchange()
.expectStatus().isOk
.expectBody<String>().isEqualTo("Hello World")
}
}
WebTestClient can also used with a mock environment, removing the need for a running server, by annotating your test class with @AutoConfigureWebTestClient .
|
This setup requires spring-webflux
on the classpath.
If you can not or will not add webflux, Spring Boot also provides a TestRestTemplate
facility:
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyRandomPortTestRestTemplateTests {
@Test
void exampleTest(@Autowired TestRestTemplate restTemplate) {
String body = restTemplate.getForObject("/", String.class);
assertThat(body).isEqualTo("Hello World");
}
}
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyRandomPortTestRestTemplateTests {
@Test
fun exampleTest(@Autowired restTemplate: TestRestTemplate) {
val body = restTemplate.getForObject("/", String::class.java)
assertThat(body).isEqualTo("Hello World")
}
}
Customizing WebTestClient
To customize the WebTestClient
bean, configure a WebTestClientBuilderCustomizer
bean.
Any such beans are called with the WebTestClient.Builder
that is used to create the WebTestClient
.
Using JMX
As the test context framework caches context, JMX is disabled by default to prevent identical components to register on the same domain.
If such test needs access to an MBeanServer
, consider marking it dirty as well:
@SpringBootTest(properties = "spring.jmx.enabled=true")
@DirtiesContext
class MyJmxTests {
@Autowired
private MBeanServer mBeanServer;
@Test
void exampleTest() {
assertThat(this.mBeanServer.getDomains()).contains("java.lang");
// ...
}
}
@SpringBootTest(properties = ["spring.jmx.enabled=true"])
@DirtiesContext
class MyJmxTests(@Autowired val mBeanServer: MBeanServer) {
@Test
fun exampleTest() {
assertThat(mBeanServer.domains).contains("java.lang")
// ...
}
}
Using Metrics
Regardless of your classpath, meter registries, except the in-memory backed, are not auto-configured when using @SpringBootTest
.
If you need to export metrics to a different backend as part of an integration test, annotate it with @AutoConfigureMetrics
.
Mocking and Spying Beans
When running tests, it is sometimes necessary to mock certain components within your application context. For example, you may have a facade over some remote service that is unavailable during development. Mocking can also be useful when you want to simulate failures that might be hard to trigger in a real environment.
Spring Boot includes a @MockBean
annotation that can be used to define a Mockito mock for a bean inside your ApplicationContext
.
You can use the annotation to add new beans or replace a single existing bean definition.
The annotation can be used directly on test classes, on fields within your test, or on @Configuration
classes and fields.
When used on a field, the instance of the created mock is also injected.
Mock beans are automatically reset after each test method.
If your test uses one of Spring Boot’s test annotations (such as Java
Kotlin
|
The following example replaces an existing RemoteService
bean with a mock implementation:
@SpringBootTest
class MyTests {
@Autowired
private Reverser reverser;
@MockBean
private RemoteService remoteService;
@Test
void exampleTest() {
given(this.remoteService.getValue()).willReturn("spring");
String reverse = this.reverser.getReverseValue(); // Calls injected RemoteService
assertThat(reverse).isEqualTo("gnirps");
}
}
@SpringBootTest
class MyTests(@Autowired val reverser: Reverser, @MockBean val remoteService: RemoteService) {
@Test
fun exampleTest() {
given(remoteService.value).willReturn("spring")
val reverse = reverser.reverseValue // Calls injected RemoteService
assertThat(reverse).isEqualTo("gnirps")
}
}
@MockBean cannot be used to mock the behavior of a bean that is exercised during application context refresh.
By the time the test is executed, the application context refresh has completed and it is too late to configure the mocked behavior.
We recommend using a @Bean method to create and configure the mock in this situation.
|
Additionally, you can use @SpyBean
to wrap any existing bean with a Mockito spy
.
See the Javadoc for full details.
CGLib proxies, such as those created for scoped beans, declare the proxied methods as final .
This stops Mockito from functioning correctly as it cannot mock or spy on final methods in its default configuration.
If you want to mock or spy on such a bean, configure Mockito to use its inline mock maker by adding org.mockito:mockito-inline to your application’s test dependencies.
This allows Mockito to mock and spy on final methods.
|
While Spring’s test framework caches application contexts between tests and reuses a context for tests sharing the same configuration, the use of @MockBean or @SpyBean influences the cache key, which will most likely increase the number of contexts.
|
If you are using @SpyBean to spy on a bean with @Cacheable methods that refer to parameters by name, your application must be compiled with -parameters .
This ensures that the parameter names are available to the caching infrastructure once the bean has been spied upon.
|
When you are using @SpyBean to spy on a bean that is proxied by Spring, you may need to remove Spring’s proxy in some situations, for example when setting expectations using given or when .
Use AopTestUtils.getTargetObject(yourProxiedSpy) to do so.
|
Auto-configured Tests
Spring Boot’s auto-configuration system works well for applications but can sometimes be a little too much for tests. It often helps to load only the parts of the configuration that are required to test a “slice” of your application. For example, you might want to test that Spring MVC controllers are mapping URLs correctly, and you do not want to involve database calls in those tests, or you might want to test JPA entities, and you are not interested in the web layer when those tests run.
The spring-boot-test-autoconfigure
module includes a number of annotations that can be used to automatically configure such “slices”.
Each of them works in a similar way, providing a @…Test
annotation that loads the ApplicationContext
and one or more @AutoConfigure…
annotations that can be used to customize auto-configuration settings.
Each slice restricts component scan to appropriate components and loads a very restricted set of auto-configuration classes.
If you need to exclude one of them, most @…Test annotations provide an excludeAutoConfiguration attribute.
Alternatively, you can use @ImportAutoConfiguration#exclude .
|
Including multiple “slices” by using several @…Test annotations in one test is not supported.
If you need multiple “slices”, pick one of the @…Test annotations and include the @AutoConfigure… annotations of the other “slices” by hand.
|
It is also possible to use the @AutoConfigure… annotations with the standard @SpringBootTest annotation.
You can use this combination if you are not interested in “slicing” your application but you want some of the auto-configured test beans.
|
Auto-configured JSON Tests
To test that object JSON serialization and deserialization is working as expected, you can use the @JsonTest
annotation.
@JsonTest
auto-configures the available supported JSON mapper, which can be one of the following libraries:
-
Jackson
ObjectMapper
, any@JsonComponent
beans and any JacksonModule
s -
Gson
-
Jsonb
A list of the auto-configurations that are enabled by @JsonTest can be found in the appendix.
|
If you need to configure elements of the auto-configuration, you can use the @AutoConfigureJsonTesters
annotation.
Spring Boot includes AssertJ-based helpers that work with the JSONAssert and JsonPath libraries to check that JSON appears as expected.
The JacksonTester
, GsonTester
, JsonbTester
, and BasicJsonTester
classes can be used for Jackson, Gson, Jsonb, and Strings respectively.
Any helper fields on the test class can be @Autowired
when using @JsonTest
.
The following example shows a test class for Jackson:
@JsonTest
class MyJsonTests {
@Autowired
private JacksonTester<VehicleDetails> json;
@Test
void serialize() throws Exception {
VehicleDetails details = new VehicleDetails("Honda", "Civic");
// Assert against a `.json` file in the same package as the test
assertThat(this.json.write(details)).isEqualToJson("expected.json");
// Or use JSON path based assertions
assertThat(this.json.write(details)).hasJsonPathStringValue("@.make");
assertThat(this.json.write(details)).extractingJsonPathStringValue("@.make").isEqualTo("Honda");
}
@Test
void deserialize() throws Exception {
String content = "{\"make\":\"Ford\",\"model\":\"Focus\"}";
assertThat(this.json.parse(content)).isEqualTo(new VehicleDetails("Ford", "Focus"));
assertThat(this.json.parseObject(content).getMake()).isEqualTo("Ford");
}
}
@JsonTest
class MyJsonTests(@Autowired val json: JacksonTester<VehicleDetails>) {
@Test
fun serialize() {
val details = VehicleDetails("Honda", "Civic")
// Assert against a `.json` file in the same package as the test
assertThat(json.write(details)).isEqualToJson("expected.json")
// Or use JSON path based assertions
assertThat(json.write(details)).hasJsonPathStringValue("@.make")
assertThat(json.write(details)).extractingJsonPathStringValue("@.make").isEqualTo("Honda")
}
@Test
fun deserialize() {
val content = "{\"make\":\"Ford\",\"model\":\"Focus\"}"
assertThat(json.parse(content)).isEqualTo(VehicleDetails("Ford", "Focus"))
assertThat(json.parseObject(content).make).isEqualTo("Ford")
}
}
JSON helper classes can also be used directly in standard unit tests.
To do so, call the initFields method of the helper in your @Before method if you do not use @JsonTest .
|
If you use Spring Boot’s AssertJ-based helpers to assert on a number value at a given JSON path, you might not be able to use isEqualTo
depending on the type.
Instead, you can use AssertJ’s satisfies
to assert that the value matches the given condition.
For instance, the following example asserts that the actual number is a float value close to 0.15
within an offset of 0.01
.
@Test
void someTest() throws Exception {
SomeObject value = new SomeObject(0.152f);
assertThat(this.json.write(value)).extractingJsonPathNumberValue("@.test.numberValue")
.satisfies((number) -> assertThat(number.floatValue()).isCloseTo(0.15f, within(0.01f)));
}
@Test
fun someTest() {
val value = SomeObject(0.152f)
assertThat(json.write(value)).extractingJsonPathNumberValue("@.test.numberValue")
.satisfies(ThrowingConsumer { number ->
assertThat(number.toFloat()).isCloseTo(0.15f, within(0.01f))
})
}
Auto-configured Spring MVC Tests
To test whether Spring MVC controllers are working as expected, use the @WebMvcTest
annotation.
@WebMvcTest
auto-configures the Spring MVC infrastructure and limits scanned beans to @Controller
, @ControllerAdvice
, @JsonComponent
, Converter
, GenericConverter
, Filter
, HandlerInterceptor
, WebMvcConfigurer
, WebMvcRegistrations
, and HandlerMethodArgumentResolver
.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @WebMvcTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
A list of the auto-configuration settings that are enabled by @WebMvcTest can be found in the appendix.
|
If you need to register extra components, such as the Jackson Module , you can import additional configuration classes by using @Import on your test.
|
Often, @WebMvcTest
is limited to a single controller and is used in combination with @MockBean
to provide mock implementations for required collaborators.
@WebMvcTest
also auto-configures MockMvc
.
Mock MVC offers a powerful way to quickly test MVC controllers without needing to start a full HTTP server.
You can also auto-configure MockMvc in a non-@WebMvcTest (such as @SpringBootTest ) by annotating it with @AutoConfigureMockMvc .
The following example uses MockMvc :
|
@WebMvcTest(UserVehicleController.class)
class MyControllerTests {
@Autowired
private MockMvc mvc;
@MockBean
private UserVehicleService userVehicleService;
@Test
void testExample() throws Exception {
given(this.userVehicleService.getVehicleDetails("sboot"))
.willReturn(new VehicleDetails("Honda", "Civic"));
this.mvc.perform(get("/sboot/vehicle").accept(MediaType.TEXT_PLAIN))
.andExpect(status().isOk())
.andExpect(content().string("Honda Civic"));
}
}
@WebMvcTest(UserVehicleController::class)
class MyControllerTests(@Autowired val mvc: MockMvc) {
@MockBean
lateinit var userVehicleService: UserVehicleService
@Test
fun testExample() {
given(userVehicleService.getVehicleDetails("sboot"))
.willReturn(VehicleDetails("Honda", "Civic"))
mvc.perform(MockMvcRequestBuilders.get("/sboot/vehicle").accept(MediaType.TEXT_PLAIN))
.andExpect(MockMvcResultMatchers.status().isOk)
.andExpect(MockMvcResultMatchers.content().string("Honda Civic"))
}
}
If you need to configure elements of the auto-configuration (for example, when servlet filters should be applied) you can use attributes in the @AutoConfigureMockMvc annotation.
|
If you use HtmlUnit and Selenium, auto-configuration also provides an HtmlUnit WebClient
bean and/or a Selenium WebDriver
bean.
The following example uses HtmlUnit:
@WebMvcTest(UserVehicleController.class)
class MyHtmlUnitTests {
@Autowired
private WebClient webClient;
@MockBean
private UserVehicleService userVehicleService;
@Test
void testExample() throws Exception {
given(this.userVehicleService.getVehicleDetails("sboot")).willReturn(new VehicleDetails("Honda", "Civic"));
HtmlPage page = this.webClient.getPage("/sboot/vehicle.html");
assertThat(page.getBody().getTextContent()).isEqualTo("Honda Civic");
}
}
@WebMvcTest(UserVehicleController::class)
class MyHtmlUnitTests(@Autowired val webClient: WebClient) {
@MockBean
lateinit var userVehicleService: UserVehicleService
@Test
fun testExample() {
given(userVehicleService.getVehicleDetails("sboot")).willReturn(VehicleDetails("Honda", "Civic"))
val page = webClient.getPage<HtmlPage>("/sboot/vehicle.html")
assertThat(page.body.textContent).isEqualTo("Honda Civic")
}
}
By default, Spring Boot puts WebDriver beans in a special “scope” to ensure that the driver exits after each test and that a new instance is injected.
If you do not want this behavior, you can add @Scope("singleton") to your WebDriver @Bean definition.
|
The webDriver scope created by Spring Boot will replace any user defined scope of the same name.
If you define your own webDriver scope you may find it stops working when you use @WebMvcTest .
|
If you have Spring Security on the classpath, @WebMvcTest
will also scan WebSecurityConfigurer
beans.
Instead of disabling security completely for such tests, you can use Spring Security’s test support.
More details on how to use Spring Security’s MockMvc
support can be found in this Testing With Spring Security how-to section.
Sometimes writing Spring MVC tests is not enough; Spring Boot can help you run full end-to-end tests with an actual server. |
Auto-configured Spring WebFlux Tests
To test that Spring WebFlux controllers are working as expected, you can use the @WebFluxTest
annotation.
@WebFluxTest
auto-configures the Spring WebFlux infrastructure and limits scanned beans to @Controller
, @ControllerAdvice
, @JsonComponent
, Converter
, GenericConverter
, WebFilter
, and WebFluxConfigurer
.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @WebFluxTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
A list of the auto-configurations that are enabled by @WebFluxTest can be found in the appendix.
|
If you need to register extra components, such as Jackson Module , you can import additional configuration classes using @Import on your test.
|
Often, @WebFluxTest
is limited to a single controller and used in combination with the @MockBean
annotation to provide mock implementations for required collaborators.
@WebFluxTest
also auto-configures WebTestClient
, which offers a powerful way to quickly test WebFlux controllers without needing to start a full HTTP server.
You can also auto-configure WebTestClient in a non-@WebFluxTest (such as @SpringBootTest ) by annotating it with @AutoConfigureWebTestClient .
The following example shows a class that uses both @WebFluxTest and a WebTestClient :
|
@WebFluxTest(UserVehicleController.class)
class MyControllerTests {
@Autowired
private WebTestClient webClient;
@MockBean
private UserVehicleService userVehicleService;
@Test
void testExample() {
given(this.userVehicleService.getVehicleDetails("sboot"))
.willReturn(new VehicleDetails("Honda", "Civic"));
this.webClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN).exchange()
.expectStatus().isOk()
.expectBody(String.class).isEqualTo("Honda Civic");
}
}
@WebFluxTest(UserVehicleController::class)
class MyControllerTests(@Autowired val webClient: WebTestClient) {
@MockBean
lateinit var userVehicleService: UserVehicleService
@Test
fun testExample() {
given(userVehicleService.getVehicleDetails("sboot"))
.willReturn(VehicleDetails("Honda", "Civic"))
webClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN).exchange()
.expectStatus().isOk
.expectBody<String>().isEqualTo("Honda Civic")
}
}
This setup is only supported by WebFlux applications as using WebTestClient in a mocked web application only works with WebFlux at the moment.
|
@WebFluxTest cannot detect routes registered through the functional web framework.
For testing RouterFunction beans in the context, consider importing your RouterFunction yourself by using @Import or by using @SpringBootTest .
|
@WebFluxTest cannot detect custom security configuration registered as a @Bean of type SecurityWebFilterChain .
To include that in your test, you will need to import the configuration that registers the bean by using @Import or by using @SpringBootTest .
|
Sometimes writing Spring WebFlux tests is not enough; Spring Boot can help you run full end-to-end tests with an actual server. |
Auto-configured Spring GraphQL Tests
Spring GraphQL offers a dedicated testing support module; you’ll need to add it to your project:
<dependencies>
<dependency>
<groupId>org.springframework.graphql</groupId>
<artifactId>spring-graphql-test</artifactId>
<scope>test</scope>
</dependency>
<!-- Unless already present in the compile scope -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
dependencies {
testImplementation("org.springframework.graphql:spring-graphql-test")
// Unless already present in the implementation configuration
testImplementation("org.springframework.boot:spring-boot-starter-webflux")
}
This testing module ships the GraphQlTester.
The tester is heavily used in test, so be sure to become familiar with using it.
There are GraphQlTester
variants and Spring Boot will auto-configure them depending on the type of tests:
-
the
ExecutionGraphQlServiceTester
performs tests on the server side, without a client nor a transport -
the
HttpGraphQlTester
performs tests with a client that connects to a server, with or without a live server
Spring Boot helps you to test your Spring GraphQL Controllers with the @GraphQlTest
annotation.
@GraphQlTest
auto-configures the Spring GraphQL infrastructure, without any transport nor server being involved.
This limits scanned beans to @Controller
, RuntimeWiringConfigurer
, JsonComponent
, Converter
, GenericConverter
, DataFetcherExceptionResolver
, Instrumentation
and GraphQlSourceBuilderCustomizer
.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @GraphQlTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
A list of the auto-configurations that are enabled by @GraphQlTest can be found in the appendix.
|
If you need to register extra components, such as Jackson Module , you can import additional configuration classes using @Import on your test.
|
Often, @GraphQlTest
is limited to a set of controllers and used in combination with the @MockBean
annotation to provide mock implementations for required collaborators.
@GraphQlTest(GreetingController.class)
class GreetingControllerTests {
@Autowired
private GraphQlTester graphQlTester;
@Test
void shouldGreetWithSpecificName() {
this.graphQlTester.document("{ greeting(name: \"Alice\") } ")
.execute()
.path("greeting")
.entity(String.class)
.isEqualTo("Hello, Alice!");
}
@Test
void shouldGreetWithDefaultName() {
this.graphQlTester.document("{ greeting } ")
.execute()
.path("greeting")
.entity(String.class)
.isEqualTo("Hello, Spring!");
}
}
@GraphQlTest(GreetingController::class)
internal class GreetingControllerTests {
@Autowired
lateinit var graphQlTester: GraphQlTester
@Test
fun shouldGreetWithSpecificName() {
graphQlTester.document("{ greeting(name: \"Alice\") } ").execute().path("greeting").entity(String::class.java)
.isEqualTo("Hello, Alice!")
}
@Test
fun shouldGreetWithDefaultName() {
graphQlTester.document("{ greeting } ").execute().path("greeting").entity(String::class.java)
.isEqualTo("Hello, Spring!")
}
}
@SpringBootTest
tests are full integration tests and involve the entire application.
When using a random or defined port, a live server is configured and an HttpGraphQlTester
bean is contributed automatically so you can use it to test your server.
When a MOCK environment is configured, you can also request an HttpGraphQlTester
bean by annotating your test class with @AutoConfigureHttpGraphQlTester
:
@AutoConfigureHttpGraphQlTester
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK)
class GraphQlIntegrationTests {
@Test
void shouldGreetWithSpecificName(@Autowired HttpGraphQlTester graphQlTester) {
HttpGraphQlTester authenticatedTester = graphQlTester.mutate()
.webTestClient((client) -> client.defaultHeaders((headers) -> headers.setBasicAuth("admin", "ilovespring")))
.build();
authenticatedTester.document("{ greeting(name: \"Alice\") } ")
.execute()
.path("greeting")
.entity(String.class)
.isEqualTo("Hello, Alice!");
}
}
@AutoConfigureHttpGraphQlTester
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK)
class GraphQlIntegrationTests {
@Test
fun shouldGreetWithSpecificName(@Autowired graphQlTester: HttpGraphQlTester) {
val authenticatedTester = graphQlTester.mutate()
.webTestClient { client: WebTestClient.Builder ->
client.defaultHeaders { headers: HttpHeaders ->
headers.setBasicAuth("admin", "ilovespring")
}
}.build()
authenticatedTester.document("{ greeting(name: \"Alice\") } ").execute()
.path("greeting").entity(String::class.java).isEqualTo("Hello, Alice!")
}
}
Auto-configured Data Cassandra Tests
You can use @DataCassandraTest
to test Cassandra applications.
By default, it configures a CassandraTemplate
, scans for @Table
classes, and configures Spring Data Cassandra repositories.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @DataCassandraTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
(For more about using Cassandra with Spring Boot, see "Cassandra".)
A list of the auto-configuration settings that are enabled by @DataCassandraTest can be found in the appendix.
|
The following example shows a typical setup for using Cassandra tests in Spring Boot:
@DataCassandraTest
class MyDataCassandraTests {
@Autowired
private SomeRepository repository;
}
@DataCassandraTest
class MyDataCassandraTests(@Autowired val repository: SomeRepository)
Auto-configured Data Couchbase Tests
You can use @DataCouchbaseTest
to test Couchbase applications.
By default, it configures a CouchbaseTemplate
or ReactiveCouchbaseTemplate
, scans for @Document
classes, and configures Spring Data Couchbase repositories.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @DataCouchbaseTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
(For more about using Couchbase with Spring Boot, see "Couchbase", earlier in this chapter.)
A list of the auto-configuration settings that are enabled by @DataCouchbaseTest can be found in the appendix.
|
The following example shows a typical setup for using Couchbase tests in Spring Boot:
@DataCouchbaseTest
class MyDataCouchbaseTests {
@Autowired
private SomeRepository repository;
// ...
}
@DataCouchbaseTest
class MyDataCouchbaseTests(@Autowired val repository: SomeRepository) {
// ...
}
Auto-configured Data Elasticsearch Tests
You can use @DataElasticsearchTest
to test Elasticsearch applications.
By default, it configures an ElasticsearchRestTemplate
, scans for @Document
classes, and configures Spring Data Elasticsearch repositories.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @DataElasticsearchTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
(For more about using Elasticsearch with Spring Boot, see "Elasticsearch", earlier in this chapter.)
A list of the auto-configuration settings that are enabled by @DataElasticsearchTest can be found in the appendix.
|
The following example shows a typical setup for using Elasticsearch tests in Spring Boot:
@DataElasticsearchTest
class MyDataElasticsearchTests {
@Autowired
private SomeRepository repository;
// ...
}
@DataElasticsearchTest
class MyDataElasticsearchTests(@Autowired val repository: SomeRepository) {
// ...
}
Auto-configured Data JPA Tests
You can use the @DataJpaTest
annotation to test JPA applications.
By default, it scans for @Entity
classes and configures Spring Data JPA repositories.
If an embedded database is available on the classpath, it configures one as well.
SQL queries are logged by default by setting the spring.jpa.show-sql
property to true
.
This can be disabled using the showSql()
attribute of the annotation.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @DataJpaTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
A list of the auto-configuration settings that are enabled by @DataJpaTest can be found in the appendix.
|
By default, data JPA tests are transactional and roll back at the end of each test. See the relevant section in the Spring Framework Reference Documentation for more details. If that is not what you want, you can disable transaction management for a test or for the whole class as follows:
@DataJpaTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyNonTransactionalTests {
// ...
}
@DataJpaTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyNonTransactionalTests {
// ...
}
Data JPA tests may also inject a TestEntityManager
bean, which provides an alternative to the standard JPA EntityManager
that is specifically designed for tests.
TestEntityManager can also be auto-configured to any of your Spring-based test class by adding @AutoConfigureTestEntityManager .
When doing so, make sure that your test is running in a transaction, for instance by adding @Transactional on your test class or method.
|
A JdbcTemplate
is also available if you need that.
The following example shows the @DataJpaTest
annotation in use:
@DataJpaTest
class MyRepositoryTests {
@Autowired
private TestEntityManager entityManager;
@Autowired
private UserRepository repository;
@Test
void testExample() {
this.entityManager.persist(new User("sboot", "1234"));
User user = this.repository.findByUsername("sboot");
assertThat(user.getUsername()).isEqualTo("sboot");
assertThat(user.getEmployeeNumber()).isEqualTo("1234");
}
}
@DataJpaTest
class MyRepositoryTests(@Autowired val entityManager: TestEntityManager, @Autowired val repository: UserRepository) {
@Test
fun testExample() {
entityManager.persist(User("sboot", "1234"))
val user = repository.findByUsername("sboot")
assertThat(user?.username).isEqualTo("sboot")
assertThat(user?.employeeNumber).isEqualTo("1234")
}
}
In-memory embedded databases generally work well for tests, since they are fast and do not require any installation.
If, however, you prefer to run tests against a real database you can use the @AutoConfigureTestDatabase
annotation, as shown in the following example:
@DataJpaTest
@AutoConfigureTestDatabase(replace = Replace.NONE)
class MyRepositoryTests {
// ...
}
@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class MyRepositoryTests {
// ...
}
Auto-configured JDBC Tests
@JdbcTest
is similar to @DataJpaTest
but is for tests that only require a DataSource
and do not use Spring Data JDBC.
By default, it configures an in-memory embedded database and a JdbcTemplate
.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @JdbcTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
A list of the auto-configurations that are enabled by @JdbcTest can be found in the appendix.
|
By default, JDBC tests are transactional and roll back at the end of each test. See the relevant section in the Spring Framework Reference Documentation for more details. If that is not what you want, you can disable transaction management for a test or for the whole class, as follows:
@JdbcTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyTransactionalTests {
}
@JdbcTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyTransactionalTests
If you prefer your test to run against a real database, you can use the @AutoConfigureTestDatabase
annotation in the same way as for @DataJpaTest
.
(See "Auto-configured Data JPA Tests".)
Auto-configured Data JDBC Tests
@DataJdbcTest
is similar to @JdbcTest
but is for tests that use Spring Data JDBC repositories.
By default, it configures an in-memory embedded database, a JdbcTemplate
, and Spring Data JDBC repositories.
Only AbstractJdbcConfiguration
sub-classes are scanned when the @DataJdbcTest
annotation is used, regular @Component
and @ConfigurationProperties
beans are not scanned.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
A list of the auto-configurations that are enabled by @DataJdbcTest can be found in the appendix.
|
By default, Data JDBC tests are transactional and roll back at the end of each test. See the relevant section in the Spring Framework Reference Documentation for more details. If that is not what you want, you can disable transaction management for a test or for the whole test class as shown in the JDBC example.
If you prefer your test to run against a real database, you can use the @AutoConfigureTestDatabase
annotation in the same way as for @DataJpaTest
.
(See "Auto-configured Data JPA Tests".)
Auto-configured Data R2DBC Tests
@DataR2dbcTest
is similar to @DataJdbcTest
but is for tests that use Spring Data R2DBC repositories.
By default, it configures an in-memory embedded database, an R2dbcEntityTemplate
, and Spring Data R2DBC repositories.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @DataR2dbcTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
A list of the auto-configurations that are enabled by @DataR2dbcTest can be found in the appendix.
|
By default, Data R2DBC tests are not transactional.
If you prefer your test to run against a real database, you can use the @AutoConfigureTestDatabase
annotation in the same way as for @DataJpaTest
.
(See "Auto-configured Data JPA Tests".)
Auto-configured jOOQ Tests
You can use @JooqTest
in a similar fashion as @JdbcTest
but for jOOQ-related tests.
As jOOQ relies heavily on a Java-based schema that corresponds with the database schema, the existing DataSource
is used.
If you want to replace it with an in-memory database, you can use @AutoConfigureTestDatabase
to override those settings.
(For more about using jOOQ with Spring Boot, see "Using jOOQ".)
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @JooqTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
A list of the auto-configurations that are enabled by @JooqTest can be found in the appendix.
|
@JooqTest
configures a DSLContext
.
The following example shows the @JooqTest
annotation in use:
@JooqTest
class MyJooqTests {
@Autowired
private DSLContext dslContext;
// ...
}
@JooqTest
class MyJooqTests(@Autowired val dslContext: DSLContext) {
// ...
}
JOOQ tests are transactional and roll back at the end of each test by default. If that is not what you want, you can disable transaction management for a test or for the whole test class as shown in the JDBC example.
Auto-configured Data MongoDB Tests
You can use @DataMongoTest
to test MongoDB applications.
By default, it configures an in-memory embedded MongoDB (if available), configures a MongoTemplate
, scans for @Document
classes, and configures Spring Data MongoDB repositories.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @DataMongoTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
(For more about using MongoDB with Spring Boot, see "MongoDB".)
A list of the auto-configuration settings that are enabled by @DataMongoTest can be found in the appendix.
|
The following class shows the @DataMongoTest
annotation in use:
@DataMongoTest
class MyDataMongoDbTests {
@Autowired
private MongoTemplate mongoTemplate;
// ...
}
@DataMongoTest
class MyDataMongoDbTests(@Autowired val mongoTemplate: MongoTemplate) {
// ...
}
In-memory embedded MongoDB generally works well for tests, since it is fast and does not require any developer installation. If, however, you prefer to run tests against a real MongoDB server, you should exclude the embedded MongoDB auto-configuration, as shown in the following example:
@DataMongoTest(excludeAutoConfiguration = EmbeddedMongoAutoConfiguration.class)
class MyDataMongoDbTests {
// ...
}
@DataMongoTest(excludeAutoConfiguration = [EmbeddedMongoAutoConfiguration::class])
class MyDataMongoDbTests {
// ...
}
Auto-configured Data Neo4j Tests
You can use @DataNeo4jTest
to test Neo4j applications.
By default, it scans for @Node
classes, and configures Spring Data Neo4j repositories.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @DataNeo4jTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
(For more about using Neo4J with Spring Boot, see "Neo4j".)
A list of the auto-configuration settings that are enabled by @DataNeo4jTest can be found in the appendix.
|
The following example shows a typical setup for using Neo4J tests in Spring Boot:
@DataNeo4jTest
class MyDataNeo4jTests {
@Autowired
private SomeRepository repository;
// ...
}
@DataNeo4jTest
class MyDataNeo4jTests(@Autowired val repository: SomeRepository) {
// ...
}
By default, Data Neo4j tests are transactional and roll back at the end of each test. See the relevant section in the Spring Framework Reference Documentation for more details. If that is not what you want, you can disable transaction management for a test or for the whole class, as follows:
@DataNeo4jTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyDataNeo4jTests {
}
@DataNeo4jTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyDataNeo4jTests
Transactional tests are not supported with reactive access.
If you are using this style, you must configure @DataNeo4jTest tests as described above.
|
Auto-configured Data Redis Tests
You can use @DataRedisTest
to test Redis applications.
By default, it scans for @RedisHash
classes and configures Spring Data Redis repositories.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @DataRedisTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
(For more about using Redis with Spring Boot, see "Redis".)
A list of the auto-configuration settings that are enabled by @DataRedisTest can be found in the appendix.
|
The following example shows the @DataRedisTest
annotation in use:
@DataRedisTest
class MyDataRedisTests {
@Autowired
private SomeRepository repository;
// ...
}
@DataRedisTest
class MyDataRedisTests(@Autowired val repository: SomeRepository) {
// ...
}
Auto-configured Data LDAP Tests
You can use @DataLdapTest
to test LDAP applications.
By default, it configures an in-memory embedded LDAP (if available), configures an LdapTemplate
, scans for @Entry
classes, and configures Spring Data LDAP repositories.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @DataLdapTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
(For more about using LDAP with Spring Boot, see "LDAP".)
A list of the auto-configuration settings that are enabled by @DataLdapTest can be found in the appendix.
|
The following example shows the @DataLdapTest
annotation in use:
@DataLdapTest
class MyDataLdapTests {
@Autowired
private LdapTemplate ldapTemplate;
// ...
}
@DataLdapTest
class MyDataLdapTests(@Autowired val ldapTemplate: LdapTemplate) {
// ...
}
In-memory embedded LDAP generally works well for tests, since it is fast and does not require any developer installation. If, however, you prefer to run tests against a real LDAP server, you should exclude the embedded LDAP auto-configuration, as shown in the following example:
@DataLdapTest(excludeAutoConfiguration = EmbeddedLdapAutoConfiguration.class)
class MyDataLdapTests {
// ...
}
@DataLdapTest(excludeAutoConfiguration = [EmbeddedLdapAutoConfiguration::class])
class MyDataLdapTests {
// ...
}
Auto-configured REST Clients
You can use the @RestClientTest
annotation to test REST clients.
By default, it auto-configures Jackson, GSON, and Jsonb support, configures a RestTemplateBuilder
, and adds support for MockRestServiceServer
.
Regular @Component
and @ConfigurationProperties
beans are not scanned when the @RestClientTest
annotation is used.
@EnableConfigurationProperties
can be used to include @ConfigurationProperties
beans.
A list of the auto-configuration settings that are enabled by @RestClientTest can be found in the appendix.
|
The specific beans that you want to test should be specified by using the value
or components
attribute of @RestClientTest
, as shown in the following example:
@RestClientTest(RemoteVehicleDetailsService.class)
class MyRestClientTests {
@Autowired
private RemoteVehicleDetailsService service;
@Autowired
private MockRestServiceServer server;
@Test
void getVehicleDetailsWhenResultIsSuccessShouldReturnDetails() {
this.server.expect(requestTo("/greet/details")).andRespond(withSuccess("hello", MediaType.TEXT_PLAIN));
String greeting = this.service.callRestService();
assertThat(greeting).isEqualTo("hello");
}
}
@RestClientTest(RemoteVehicleDetailsService::class)
class MyRestClientTests(
@Autowired val service: RemoteVehicleDetailsService,
@Autowired val server: MockRestServiceServer) {
@Test
fun getVehicleDetailsWhenResultIsSuccessShouldReturnDetails(): Unit {
server.expect(MockRestRequestMatchers.requestTo("/greet/details"))
.andRespond(MockRestResponseCreators.withSuccess("hello", MediaType.TEXT_PLAIN))
val greeting = service.callRestService()
assertThat(greeting).isEqualTo("hello")
}
}
Auto-configured Spring REST Docs Tests
You can use the @AutoConfigureRestDocs
annotation to use Spring REST Docs in your tests with Mock MVC, REST Assured, or WebTestClient.
It removes the need for the JUnit extension in Spring REST Docs.
@AutoConfigureRestDocs
can be used to override the default output directory (target/generated-snippets
if you are using Maven or build/generated-snippets
if you are using Gradle).
It can also be used to configure the host, scheme, and port that appears in any documented URIs.
Auto-configured Spring REST Docs Tests With Mock MVC
@AutoConfigureRestDocs
customizes the MockMvc
bean to use Spring REST Docs when testing servlet-based web applications.
You can inject it by using @Autowired
and use it in your tests as you normally would when using Mock MVC and Spring REST Docs, as shown in the following example:
@WebMvcTest(UserController.class)
@AutoConfigureRestDocs
class MyUserDocumentationTests {
@Autowired
private MockMvc mvc;
@Test
void listUsers() throws Exception {
this.mvc.perform(get("/users").accept(MediaType.TEXT_PLAIN))
.andExpect(status().isOk())
.andDo(document("list-users"));
}
}
@WebMvcTest(UserController::class)
@AutoConfigureRestDocs
class MyUserDocumentationTests(@Autowired val mvc: MockMvc) {
@Test
fun listUsers() {
mvc.perform(MockMvcRequestBuilders.get("/users").accept(MediaType.TEXT_PLAIN))
.andExpect(MockMvcResultMatchers.status().isOk)
.andDo(MockMvcRestDocumentation.document("list-users"))
}
}
If you require more control over Spring REST Docs configuration than offered by the attributes of @AutoConfigureRestDocs
, you can use a RestDocsMockMvcConfigurationCustomizer
bean, as shown in the following example:
@TestConfiguration(proxyBeanMethods = false)
public class MyRestDocsConfiguration implements RestDocsMockMvcConfigurationCustomizer {
@Override
public void customize(MockMvcRestDocumentationConfigurer configurer) {
configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
}
}
@TestConfiguration(proxyBeanMethods = false)
class MyRestDocsConfiguration : RestDocsMockMvcConfigurationCustomizer {
override fun customize(configurer: MockMvcRestDocumentationConfigurer) {
configurer.snippets().withTemplateFormat(TemplateFormats.markdown())
}
}
If you want to make use of Spring REST Docs support for a parameterized output directory, you can create a RestDocumentationResultHandler
bean.
The auto-configuration calls alwaysDo
with this result handler, thereby causing each MockMvc
call to automatically generate the default snippets.
The following example shows a RestDocumentationResultHandler
being defined:
@TestConfiguration(proxyBeanMethods = false)
public class MyResultHandlerConfiguration {
@Bean
public RestDocumentationResultHandler restDocumentation() {
return MockMvcRestDocumentation.document("{method-name}");
}
}
@TestConfiguration(proxyBeanMethods = false)
class MyResultHandlerConfiguration {
@Bean
fun restDocumentation(): RestDocumentationResultHandler {
return MockMvcRestDocumentation.document("{method-name}")
}
}
Auto-configured Spring REST Docs Tests With WebTestClient
@AutoConfigureRestDocs
can also be used with WebTestClient
when testing reactive web applications.
You can inject it by using @Autowired
and use it in your tests as you normally would when using @WebFluxTest
and Spring REST Docs, as shown in the following example:
@WebFluxTest
@AutoConfigureRestDocs
class MyUsersDocumentationTests {
@Autowired
private WebTestClient webTestClient;
@Test
void listUsers() {
this.webTestClient
.get().uri("/")
.exchange()
.expectStatus()
.isOk()
.expectBody()
.consumeWith(document("list-users"));
}
}
@WebFluxTest
@AutoConfigureRestDocs
class MyUsersDocumentationTests(@Autowired val webTestClient: WebTestClient) {
@Test
fun listUsers() {
webTestClient
.get().uri("/")
.exchange()
.expectStatus()
.isOk
.expectBody()
.consumeWith(WebTestClientRestDocumentation.document("list-users"))
}
}
If you require more control over Spring REST Docs configuration than offered by the attributes of @AutoConfigureRestDocs
, you can use a RestDocsWebTestClientConfigurationCustomizer
bean, as shown in the following example:
@TestConfiguration(proxyBeanMethods = false)
public class MyRestDocsConfiguration implements RestDocsWebTestClientConfigurationCustomizer {
@Override
public void customize(WebTestClientRestDocumentationConfigurer configurer) {
configurer.snippets().withEncoding("UTF-8");
}
}
@TestConfiguration(proxyBeanMethods = false)
class MyRestDocsConfiguration : RestDocsWebTestClientConfigurationCustomizer {
override fun customize(configurer: WebTestClientRestDocumentationConfigurer) {
configurer.snippets().withEncoding("UTF-8")
}
}
If you want to make use of Spring REST Docs support for a parameterized output directory, you can use a WebTestClientBuilderCustomizer
to configure a consumer for every entity exchange result.
The following example shows such a WebTestClientBuilderCustomizer
being defined:
@TestConfiguration(proxyBeanMethods = false)
public class MyWebTestClientBuilderCustomizerConfiguration {
@Bean
public WebTestClientBuilderCustomizer restDocumentation() {
return (builder) -> builder.entityExchangeResultConsumer(document("{method-name}"));
}
}
@TestConfiguration(proxyBeanMethods = false)
class MyWebTestClientBuilderCustomizerConfiguration {
@Bean
fun restDocumentation(): WebTestClientBuilderCustomizer {
return WebTestClientBuilderCustomizer { builder: WebTestClient.Builder ->
builder.entityExchangeResultConsumer(
WebTestClientRestDocumentation.document("{method-name}")
)
}
}
}
Auto-configured Spring REST Docs Tests With REST Assured
@AutoConfigureRestDocs
makes a RequestSpecification
bean, preconfigured to use Spring REST Docs, available to your tests.
You can inject it by using @Autowired
and use it in your tests as you normally would when using REST Assured and Spring REST Docs, as shown in the following example:
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureRestDocs
class MyUserDocumentationTests {
@Test
void listUsers(@Autowired RequestSpecification documentationSpec, @LocalServerPort int port) {
given(documentationSpec)
.filter(document("list-users"))
.when()
.port(port)
.get("/")
.then().assertThat()
.statusCode(is(200));
}
}
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureRestDocs
class MyUserDocumentationTests {
@Test
fun listUsers(@Autowired documentationSpec: RequestSpecification?, @LocalServerPort port: Int) {
RestAssured.given(documentationSpec)
.filter(RestAssuredRestDocumentation.document("list-users"))
.`when`()
.port(port)["/"]
.then().assertThat()
.statusCode(Matchers.`is`(200))
}
}
If you require more control over Spring REST Docs configuration than offered by the attributes of @AutoConfigureRestDocs
, a RestDocsRestAssuredConfigurationCustomizer
bean can be used, as shown in the following example:
@TestConfiguration(proxyBeanMethods = false)
public class MyRestDocsConfiguration implements RestDocsRestAssuredConfigurationCustomizer {
@Override
public void customize(RestAssuredRestDocumentationConfigurer configurer) {
configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
}
}
@TestConfiguration(proxyBeanMethods = false)
class MyRestDocsConfiguration : RestDocsRestAssuredConfigurationCustomizer {
override fun customize(configurer: RestAssuredRestDocumentationConfigurer) {
configurer.snippets().withTemplateFormat(TemplateFormats.markdown())
}
}
Auto-configured Spring Web Services Tests
Auto-configured Spring Web Services Client Tests
You can use @WebServiceClientTest
to test applications that call web services using the Spring Web Services project.
By default, it configures a mock WebServiceServer
bean and automatically customizes your WebServiceTemplateBuilder
.
(For more about using Web Services with Spring Boot, see "Web Services".)
A list of the auto-configuration settings that are enabled by @WebServiceClientTest can be found in the appendix.
|
The following example shows the @WebServiceClientTest
annotation in use:
@WebServiceClientTest(SomeWebService.class)
class MyWebServiceClientTests {
@Autowired
private MockWebServiceServer server;
@Autowired
private SomeWebService someWebService;
@Test
void mockServerCall() {
this.server
.expect(payload(new StringSource("<request/>")))
.andRespond(withPayload(new StringSource("<response><status>200</status></response>")));
assertThat(this.someWebService.test())
.extracting(Response::getStatus)
.isEqualTo(200);
}
}
@WebServiceClientTest(SomeWebService::class)
class MyWebServiceClientTests(@Autowired val server: MockWebServiceServer, @Autowired val someWebService: SomeWebService) {
@Test
fun mockServerCall() {
server
.expect(RequestMatchers.payload(StringSource("<request/>")))
.andRespond(ResponseCreators.withPayload(StringSource("<response><status>200</status></response>")))
assertThat(this.someWebService.test()).extracting(Response::status).isEqualTo(200)
}
}
Auto-configured Spring Web Services Server Tests
You can use @WebServiceServerTest
to test applications that implement web services using the Spring Web Services project.
By default, it configures a MockWebServiceClient
bean that can be used to call your web service endpoints.
(For more about using Web Services with Spring Boot, see "Web Services".)
A list of the auto-configuration settings that are enabled by @WebServiceServerTest can be found in the appendix.
|
The following example shows the @WebServiceServerTest
annotation in use:
@WebServiceServerTest(ExampleEndpoint.class)
class MyWebServiceServerTests {
@Autowired
private MockWebServiceClient client;
@Test
void mockServerCall() {
this.client
.sendRequest(RequestCreators.withPayload(new StringSource("<ExampleRequest/>")))
.andExpect(ResponseMatchers.payload(new StringSource("<ExampleResponse>42</ExampleResponse>")));
}
}
@WebServiceServerTest(ExampleEndpoint::class)
class MyWebServiceServerTests(@Autowired val client: MockWebServiceClient) {
@Test
fun mockServerCall() {
client
.sendRequest(RequestCreators.withPayload(StringSource("<ExampleRequest/>")))
.andExpect(ResponseMatchers.payload(StringSource("<ExampleResponse>42</ExampleResponse>")))
}
}
Additional Auto-configuration and Slicing
Each slice provides one or more @AutoConfigure…
annotations that namely defines the auto-configurations that should be included as part of a slice.
Additional auto-configurations can be added on a test-by-test basis by creating a custom @AutoConfigure…
annotation or by adding @ImportAutoConfiguration
to the test as shown in the following example:
@JdbcTest
@ImportAutoConfiguration(IntegrationAutoConfiguration.class)
class MyJdbcTests {
}
@JdbcTest
@ImportAutoConfiguration(IntegrationAutoConfiguration::class)
class MyJdbcTests
Make sure to not use the regular @Import annotation to import auto-configurations as they are handled in a specific way by Spring Boot.
|
Alternatively, additional auto-configurations can be added for any use of a slice annotation by registering them in a file stored in META-INF/spring
as shown in the following example:
com.example.IntegrationAutoConfiguration
In this example, the com.example.IntegrationAutoConfiguration
is enabled on every test annotated with @JdbcTest
.
You can use comments with # in this file.
|
A slice or @AutoConfigure… annotation can be customized this way as long as it is meta-annotated with @ImportAutoConfiguration .
|
User Configuration and Slicing
If you structure your code in a sensible way, your @SpringBootApplication
class is used by default as the configuration of your tests.
It then becomes important not to litter the application’s main class with configuration settings that are specific to a particular area of its functionality.
Assume that you are using Spring Batch and you rely on the auto-configuration for it.
You could define your @SpringBootApplication
as follows:
@SpringBootApplication
@EnableBatchProcessing
public class MyApplication {
// ...
}
@SpringBootApplication
@EnableBatchProcessing
class MyApplication {
// ...
}
Because this class is the source configuration for the test, any slice test actually tries to start Spring Batch, which is definitely not what you want to do.
A recommended approach is to move that area-specific configuration to a separate @Configuration
class at the same level as your application, as shown in the following example:
@Configuration(proxyBeanMethods = false)
@EnableBatchProcessing
public class MyBatchConfiguration {
// ...
}
@Configuration(proxyBeanMethods = false)
@EnableBatchProcessing
class MyBatchConfiguration {
// ...
}
Depending on the complexity of your application, you may either have a single @Configuration class for your customizations or one class per domain area.
The latter approach lets you enable it in one of your tests, if necessary, with the @Import annotation.
See this how-to section for more details on when you might want to enable specific @Configuration classes for slice tests.
|
Test slices exclude @Configuration
classes from scanning.
For example, for a @WebMvcTest
, the following configuration will not include the given WebMvcConfigurer
bean in the application context loaded by the test slice:
@Configuration(proxyBeanMethods = false)
public class MyWebConfiguration {
@Bean
public WebMvcConfigurer testConfigurer() {
return new WebMvcConfigurer() {
// ...
};
}
}
@Configuration(proxyBeanMethods = false)
class MyWebConfiguration {
@Bean
fun testConfigurer(): WebMvcConfigurer {
return object : WebMvcConfigurer {
// ...
}
}
}
The configuration below will, however, cause the custom WebMvcConfigurer
to be loaded by the test slice.
@Component
public class MyWebMvcConfigurer implements WebMvcConfigurer {
// ...
}
@Component
class MyWebMvcConfigurer : WebMvcConfigurer {
// ...
}
Another source of confusion is classpath scanning. Assume that, while you structured your code in a sensible way, you need to scan an additional package. Your application may resemble the following code:
@SpringBootApplication
@ComponentScan({ "com.example.app", "com.example.another" })
public class MyApplication {
// ...
}
@SpringBootApplication
@ComponentScan("com.example.app", "com.example.another")
class MyApplication {
// ...
}
Doing so effectively overrides the default component scan directive with the side effect of scanning those two packages regardless of the slice that you chose.
For instance, a @DataJpaTest
seems to suddenly scan components and user configurations of your application.
Again, moving the custom directive to a separate class is a good way to fix this issue.
If this is not an option for you, you can create a @SpringBootConfiguration somewhere in the hierarchy of your test so that it is used instead.
Alternatively, you can specify a source for your test, which disables the behavior of finding a default one.
|
Using Spock to Test Spring Boot Applications
Spock 2.x can be used to test a Spring Boot application.
To do so, add a dependency on Spock’s spock-spring
module to your application’s build.
spock-spring
integrates Spring’s test framework into Spock.
See the documentation for Spock’s Spring module for further details.
7.9.4. Test Utilities
A few test utility classes that are generally useful when testing your application are packaged as part of spring-boot
.
ConfigDataApplicationContextInitializer
ConfigDataApplicationContextInitializer
is an ApplicationContextInitializer
that you can apply to your tests to load Spring Boot application.properties
files.
You can use it when you do not need the full set of features provided by @SpringBootTest
, as shown in the following example:
@ContextConfiguration(classes = Config.class, initializers = ConfigDataApplicationContextInitializer.class)
class MyConfigFileTests {
// ...
}
@ContextConfiguration(classes = [Config::class], initializers = [ConfigDataApplicationContextInitializer::class])
class MyConfigFileTests {
// ...
}
Using ConfigDataApplicationContextInitializer alone does not provide support for @Value("${…}") injection.
Its only job is to ensure that application.properties files are loaded into Spring’s Environment .
For @Value support, you need to either additionally configure a PropertySourcesPlaceholderConfigurer or use @SpringBootTest , which auto-configures one for you.
|
TestPropertyValues
TestPropertyValues
lets you quickly add properties to a ConfigurableEnvironment
or ConfigurableApplicationContext
.
You can call it with key=value
strings, as follows:
class MyEnvironmentTests {
@Test
void testPropertySources() {
MockEnvironment environment = new MockEnvironment();
TestPropertyValues.of("org=Spring", "name=Boot").applyTo(environment);
assertThat(environment.getProperty("name")).isEqualTo("Boot");
}
}
class MyEnvironmentTests {
@Test
fun testPropertySources() {
val environment = MockEnvironment()
TestPropertyValues.of("org=Spring", "name=Boot").applyTo(environment)
assertThat(environment.getProperty("name")).isEqualTo("Boot")
}
}
OutputCapture
OutputCapture
is a JUnit Extension
that you can use to capture System.out
and System.err
output.
To use add @ExtendWith(OutputCaptureExtension.class)
and inject CapturedOutput
as an argument to your test class constructor or test method as follows:
@ExtendWith(OutputCaptureExtension.class)
class MyOutputCaptureTests {
@Test
void testName(CapturedOutput output) {
System.out.println("Hello World!");
assertThat(output).contains("World");
}
}
@ExtendWith(OutputCaptureExtension::class)
class MyOutputCaptureTests {
@Test
fun testName(output: CapturedOutput?) {
println("Hello World!")
assertThat(output).contains("World")
}
}
TestRestTemplate
TestRestTemplate
is a convenience alternative to Spring’s RestTemplate
that is useful in integration tests.
You can get a vanilla template or one that sends Basic HTTP authentication (with a username and password).
In either case, the template is fault tolerant.
This means that it behaves in a test-friendly way by not throwing exceptions on 4xx and 5xx errors.
Instead, such errors can be detected through the returned ResponseEntity
and its status code.
Spring Framework 5.0 provides a new WebTestClient that works for WebFlux integration tests and both WebFlux and MVC end-to-end testing.
It provides a fluent API for assertions, unlike TestRestTemplate .
|
It is recommended, but not mandatory, to use the Apache HTTP Client (version 4.3.2 or better).
If you have that on your classpath, the TestRestTemplate
responds by configuring the client appropriately.
If you do use Apache’s HTTP client, some additional test-friendly features are enabled:
-
Redirects are not followed (so you can assert the response location).
-
Cookies are ignored (so the template is stateless).
TestRestTemplate
can be instantiated directly in your integration tests, as shown in the following example:
class MyTests {
private final TestRestTemplate template = new TestRestTemplate();
@Test
void testRequest() {
ResponseEntity<String> headers = this.template.getForEntity("https://myhost.example.com/example", String.class);
assertThat(headers.getHeaders().getLocation()).hasHost("other.example.com");
}
}
class MyTests {
private val template = TestRestTemplate()
@Test
fun testRequest() {
val headers = template.getForEntity("https://myhost.example.com/example", String::class.java)
assertThat(headers.headers.location).hasHost("other.example.com")
}
}
Alternatively, if you use the @SpringBootTest
annotation with WebEnvironment.RANDOM_PORT
or WebEnvironment.DEFINED_PORT
, you can inject a fully configured TestRestTemplate
and start using it.
If necessary, additional customizations can be applied through the RestTemplateBuilder
bean.
Any URLs that do not specify a host and port automatically connect to the embedded server, as shown in the following example:
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MySpringBootTests {
@Autowired
private TestRestTemplate template;
@Test
void testRequest() {
HttpHeaders headers = this.template.getForEntity("/example", String.class).getHeaders();
assertThat(headers.getLocation()).hasHost("other.example.com");
}
@TestConfiguration(proxyBeanMethods = false)
static class RestTemplateBuilderConfiguration {
@Bean
RestTemplateBuilder restTemplateBuilder() {
return new RestTemplateBuilder().setConnectTimeout(Duration.ofSeconds(1))
.setReadTimeout(Duration.ofSeconds(1));
}
}
}
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MySpringBootTests(@Autowired val template: TestRestTemplate) {
@Test
fun testRequest() {
val headers = template.getForEntity("/example", String::class.java).headers
assertThat(headers.location).hasHost("other.example.com")
}
@TestConfiguration(proxyBeanMethods = false)
internal class RestTemplateBuilderConfiguration {
@Bean
fun restTemplateBuilder(): RestTemplateBuilder {
return RestTemplateBuilder().setConnectTimeout(Duration.ofSeconds(1))
.setReadTimeout(Duration.ofSeconds(1))
}
}
}
7.10. Creating Your Own Auto-configuration
If you work in a company that develops shared libraries, or if you work on an open-source or commercial library, you might want to develop your own auto-configuration. Auto-configuration classes can be bundled in external jars and still be picked-up by Spring Boot.
Auto-configuration can be associated to a “starter” that provides the auto-configuration code as well as the typical libraries that you would use with it. We first cover what you need to know to build your own auto-configuration and then we move on to the typical steps required to create a custom starter.
7.10.1. Understanding Auto-configured Beans
Classes that implement auto-configuration are annotated with @AutoConfiguration
.
This annotation itself is meta-annotated with @Configuration
, making auto-configurations standard @Configuration
classes.
Additional @Conditional
annotations are used to constrain when the auto-configuration should apply.
Usually, auto-configuration classes use @ConditionalOnClass
and @ConditionalOnMissingBean
annotations.
This ensures that auto-configuration applies only when relevant classes are found and when you have not declared your own @Configuration
.
You can browse the source code of spring-boot-autoconfigure
to see the @AutoConfiguration
classes that Spring provides (see the META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
file).
7.10.2. Locating Auto-configuration Candidates
Spring Boot checks for the presence of a META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
file within your published jar.
The file should list your configuration classes, with one class name per line, as shown in the following example:
com.mycorp.libx.autoconfigure.LibXAutoConfiguration com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration
You can add comments to the imports file using the # character.
|
Auto-configurations must be loaded only by being named in the imports file.
Make sure that they are defined in a specific package space and that they are never the target of component scanning.
Furthermore, auto-configuration classes should not enable component scanning to find additional components.
Specific @Import s should be used instead.
|
If your configuration needs to be applied in a specific order, you can use the before
, beforeName
, after
and afterName
attributes on the @AutoConfiguration
annotation or the dedicated @AutoConfigureBefore
and @AutoConfigureAfter
annotations.
For example, if you provide web-specific configuration, your class may need to be applied after WebMvcAutoConfiguration
.
If you want to order certain auto-configurations that should not have any direct knowledge of each other, you can also use @AutoConfigureOrder
.
That annotation has the same semantic as the regular @Order
annotation but provides a dedicated order for auto-configuration classes.
As with standard @Configuration
classes, the order in which auto-configuration classes are applied only affects the order in which their beans are defined.
The order in which those beans are subsequently created is unaffected and is determined by each bean’s dependencies and any @DependsOn
relationships.
7.10.3. Condition Annotations
You almost always want to include one or more @Conditional
annotations on your auto-configuration class.
The @ConditionalOnMissingBean
annotation is one common example that is used to allow developers to override auto-configuration if they are not happy with your defaults.
Spring Boot includes a number of @Conditional
annotations that you can reuse in your own code by annotating @Configuration
classes or individual @Bean
methods.
These annotations include:
Class Conditions
The @ConditionalOnClass
and @ConditionalOnMissingClass
annotations let @Configuration
classes be included based on the presence or absence of specific classes.
Due to the fact that annotation metadata is parsed by using ASM, you can use the value
attribute to refer to the real class, even though that class might not actually appear on the running application classpath.
You can also use the name
attribute if you prefer to specify the class name by using a String
value.
This mechanism does not apply the same way to @Bean
methods where typically the return type is the target of the condition: before the condition on the method applies, the JVM will have loaded the class and potentially processed method references which will fail if the class is not present.
To handle this scenario, a separate @Configuration
class can be used to isolate the condition, as shown in the following example:
@AutoConfiguration
// Some conditions ...
public class MyAutoConfiguration {
// Auto-configured beans ...
@Configuration(proxyBeanMethods = false)
@ConditionalOnClass(SomeService.class)
public static class SomeServiceConfiguration {
@Bean
@ConditionalOnMissingBean
public SomeService someService() {
return new SomeService();
}
}
}
@Configuration(proxyBeanMethods = false)
// Some conditions ...
class MyAutoConfiguration {
// Auto-configured beans ...
@Configuration(proxyBeanMethods = false)
@ConditionalOnClass(SomeService::class)
class SomeServiceConfiguration {
@Bean
@ConditionalOnMissingBean
fun someService(): SomeService {
return SomeService()
}
}
}
If you use @ConditionalOnClass or @ConditionalOnMissingClass as a part of a meta-annotation to compose your own composed annotations, you must use name as referring to the class in such a case is not handled.
|
Bean Conditions
The @ConditionalOnBean
and @ConditionalOnMissingBean
annotations let a bean be included based on the presence or absence of specific beans.
You can use the value
attribute to specify beans by type or name
to specify beans by name.
The search
attribute lets you limit the ApplicationContext
hierarchy that should be considered when searching for beans.
When placed on a @Bean
method, the target type defaults to the return type of the method, as shown in the following example:
@AutoConfiguration
public class MyAutoConfiguration {
@Bean
@ConditionalOnMissingBean
public SomeService someService() {
return new SomeService();
}
}
@Configuration(proxyBeanMethods = false)
class MyAutoConfiguration {
@Bean
@ConditionalOnMissingBean
fun someService(): SomeService {
return SomeService()
}
}
In the preceding example, the someService
bean is going to be created if no bean of type SomeService
is already contained in the ApplicationContext
.
You need to be very careful about the order in which bean definitions are added, as these conditions are evaluated based on what has been processed so far.
For this reason, we recommend using only @ConditionalOnBean and @ConditionalOnMissingBean annotations on auto-configuration classes (since these are guaranteed to load after any user-defined bean definitions have been added).
|
@ConditionalOnBean and @ConditionalOnMissingBean do not prevent @Configuration classes from being created.
The only difference between using these conditions at the class level and marking each contained @Bean method with the annotation is that the former prevents registration of the @Configuration class as a bean if the condition does not match.
|
When declaring a @Bean method, provide as much type information as possible in the method’s return type.
For example, if your bean’s concrete class implements an interface the bean method’s return type should be the concrete class and not the interface.
Providing as much type information as possible in @Bean methods is particularly important when using bean conditions as their evaluation can only rely upon to type information that is available in the method signature.
|
Property Conditions
The @ConditionalOnProperty
annotation lets configuration be included based on a Spring Environment property.
Use the prefix
and name
attributes to specify the property that should be checked.
By default, any property that exists and is not equal to false
is matched.
You can also create more advanced checks by using the havingValue
and matchIfMissing
attributes.
Resource Conditions
The @ConditionalOnResource
annotation lets configuration be included only when a specific resource is present.
Resources can be specified by using the usual Spring conventions, as shown in the following example: file:/home/user/test.dat
.
Web Application Conditions
The @ConditionalOnWebApplication
and @ConditionalOnNotWebApplication
annotations let configuration be included depending on whether the application is a web application.
A servlet-based web application is any application that uses a Spring WebApplicationContext
, defines a session
scope, or has a ConfigurableWebEnvironment
.
A reactive web application is any application that uses a ReactiveWebApplicationContext
, or has a ConfigurableReactiveWebEnvironment
.
The @ConditionalOnWarDeployment
and @ConditionalOnNotWarDeployment
annotations let configuration be included depending on whether the application is a traditional WAR application that is deployed to a servlet container.
This condition will not match for applications that are run with an embedded web server.
SpEL Expression Conditions
The @ConditionalOnExpression
annotation lets configuration be included based on the result of a SpEL expression.
Referencing a bean in the expression will cause that bean to be initialized very early in context refresh processing. As a result, the bean won’t be eligible for post-processing (such as configuration properties binding) and its state may be incomplete. |
7.10.4. Testing your Auto-configuration
An auto-configuration can be affected by many factors: user configuration (@Bean
definition and Environment
customization), condition evaluation (presence of a particular library), and others.
Concretely, each test should create a well defined ApplicationContext
that represents a combination of those customizations.
ApplicationContextRunner
provides a great way to achieve that.
ApplicationContextRunner
is usually defined as a field of the test class to gather the base, common configuration.
The following example makes sure that MyServiceAutoConfiguration
is always invoked:
private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(MyServiceAutoConfiguration.class));
val contextRunner = ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(MyServiceAutoConfiguration::class.java))
If multiple auto-configurations have to be defined, there is no need to order their declarations as they are invoked in the exact same order as when running the application. |
Each test can use the runner to represent a particular use case.
For instance, the sample below invokes a user configuration (UserConfiguration
) and checks that the auto-configuration backs off properly.
Invoking run
provides a callback context that can be used with AssertJ
.
@Test
void defaultServiceBacksOff() {
this.contextRunner.withUserConfiguration(UserConfiguration.class).run((context) -> {
assertThat(context).hasSingleBean(MyService.class);
assertThat(context).getBean("myCustomService").isSameAs(context.getBean(MyService.class));
});
}
@Configuration(proxyBeanMethods = false)
static class UserConfiguration {
@Bean
MyService myCustomService() {
return new MyService("mine");
}
}
@Test
fun defaultServiceBacksOff() {
contextRunner.withUserConfiguration(UserConfiguration::class.java)
.run { context: AssertableApplicationContext ->
assertThat(context).hasSingleBean(MyService::class.java)
assertThat(context).getBean("myCustomService")
.isSameAs(context.getBean(MyService::class.java))
}
}
@Configuration(proxyBeanMethods = false)
internal class UserConfiguration {
@Bean
fun myCustomService(): MyService {
return MyService("mine")
}
}
It is also possible to easily customize the Environment
, as shown in the following example:
@Test
void serviceNameCanBeConfigured() {
this.contextRunner.withPropertyValues("user.name=test123").run((context) -> {
assertThat(context).hasSingleBean(MyService.class);
assertThat(context.getBean(MyService.class).getName()).isEqualTo("test123");
});
}
@Test
fun serviceNameCanBeConfigured() {
contextRunner.withPropertyValues("user.name=test123").run { context: AssertableApplicationContext ->
assertThat(context).hasSingleBean(MyService::class.java)
assertThat(context.getBean(MyService::class.java).name).isEqualTo("test123")
}
}
The runner can also be used to display the ConditionEvaluationReport
.
The report can be printed at INFO
or DEBUG
level.
The following example shows how to use the ConditionEvaluationReportLoggingListener
to print the report in auto-configuration tests.
class MyConditionEvaluationReportingTests {
@Test
void autoConfigTest() {
new ApplicationContextRunner()
.withInitializer(new ConditionEvaluationReportLoggingListener(LogLevel.INFO))
.run((context) -> {
// Test something...
});
}
}
class MyConditionEvaluationReportingTests {
@Test
fun autoConfigTest() {
ApplicationContextRunner()
.withInitializer(ConditionEvaluationReportLoggingListener(LogLevel.INFO))
.run { context: AssertableApplicationContext? -> }
}
}
Simulating a Web Context
If you need to test an auto-configuration that only operates in a servlet or reactive web application context, use the WebApplicationContextRunner
or ReactiveWebApplicationContextRunner
respectively.
Overriding the Classpath
It is also possible to test what happens when a particular class and/or package is not present at runtime.
Spring Boot ships with a FilteredClassLoader
that can easily be used by the runner.
In the following example, we assert that if MyService
is not present, the auto-configuration is properly disabled:
@Test
void serviceIsIgnoredIfLibraryIsNotPresent() {
this.contextRunner.withClassLoader(new FilteredClassLoader(MyService.class))
.run((context) -> assertThat(context).doesNotHaveBean("myService"));
}
@Test
fun serviceIsIgnoredIfLibraryIsNotPresent() {
contextRunner.withClassLoader(FilteredClassLoader(MyService::class.java))
.run { context: AssertableApplicationContext? ->
assertThat(context).doesNotHaveBean("myService")
}
}
7.10.5. Creating Your Own Starter
A typical Spring Boot starter contains code to auto-configure and customize the infrastructure of a given technology, let’s call that "acme". To make it easily extensible, a number of configuration keys in a dedicated namespace can be exposed to the environment. Finally, a single "starter" dependency is provided to help users get started as easily as possible.
Concretely, a custom starter can contain the following:
-
The
autoconfigure
module that contains the auto-configuration code for "acme". -
The
starter
module that provides a dependency to theautoconfigure
module as well as "acme" and any additional dependencies that are typically useful. In a nutshell, adding the starter should provide everything needed to start using that library.
This separation in two modules is in no way necessary.
If "acme" has several flavors, options or optional features, then it is better to separate the auto-configuration as you can clearly express the fact some features are optional.
Besides, you have the ability to craft a starter that provides an opinion about those optional dependencies.
At the same time, others can rely only on the autoconfigure
module and craft their own starter with different opinions.
If the auto-configuration is relatively straightforward and does not have optional feature, merging the two modules in the starter is definitely an option.
Naming
You should make sure to provide a proper namespace for your starter.
Do not start your module names with spring-boot
, even if you use a different Maven groupId
.
We may offer official support for the thing you auto-configure in the future.
As a rule of thumb, you should name a combined module after the starter.
For example, assume that you are creating a starter for "acme" and that you name the auto-configure module acme-spring-boot
and the starter acme-spring-boot-starter
.
If you only have one module that combines the two, name it acme-spring-boot-starter
.
Configuration keys
If your starter provides configuration keys, use a unique namespace for them.
In particular, do not include your keys in the namespaces that Spring Boot uses (such as server
, management
, spring
, and so on).
If you use the same namespace, we may modify these namespaces in the future in ways that break your modules.
As a rule of thumb, prefix all your keys with a namespace that you own (for example acme
).
Make sure that configuration keys are documented by adding field javadoc for each property, as shown in the following example:
@ConfigurationProperties("acme")
public class AcmeProperties {
/**
* Whether to check the location of acme resources.
*/
private boolean checkLocation = true;
/**
* Timeout for establishing a connection to the acme server.
*/
private Duration loginTimeout = Duration.ofSeconds(3);
}
@ConfigurationProperties("acme")
class AcmeProperties(
/**
* Whether to check the location of acme resources.
*/
var isCheckLocation: Boolean = true,
/**
* Timeout for establishing a connection to the acme server.
*/
var loginTimeout:Duration = Duration.ofSeconds(3))
You should only use plain text with @ConfigurationProperties field Javadoc, since they are not processed before being added to the JSON.
|
Here are some rules we follow internally to make sure descriptions are consistent:
-
Do not start the description by "The" or "A".
-
For
boolean
types, start the description with "Whether" or "Enable". -
For collection-based types, start the description with "Comma-separated list"
-
Use
java.time.Duration
rather thanlong
and describe the default unit if it differs from milliseconds, such as "If a duration suffix is not specified, seconds will be used". -
Do not provide the default value in the description unless it has to be determined at runtime.
Make sure to trigger meta-data generation so that IDE assistance is available for your keys as well.
You may want to review the generated metadata (META-INF/spring-configuration-metadata.json
) to make sure your keys are properly documented.
Using your own starter in a compatible IDE is also a good idea to validate that quality of the metadata.
The “autoconfigure” Module
The autoconfigure
module contains everything that is necessary to get started with the library.
It may also contain configuration key definitions (such as @ConfigurationProperties
) and any callback interface that can be used to further customize how the components are initialized.
You should mark the dependencies to the library as optional so that you can include the autoconfigure module in your projects more easily.
If you do it that way, the library is not provided and, by default, Spring Boot backs off.
|
Spring Boot uses an annotation processor to collect the conditions on auto-configurations in a metadata file (META-INF/spring-autoconfigure-metadata.properties
).
If that file is present, it is used to eagerly filter auto-configurations that do not match, which will improve startup time.
When building with Maven, it is recommended to add the following dependency in a module that contains auto-configurations:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-autoconfigure-processor</artifactId>
<optional>true</optional>
</dependency>
If you have defined auto-configurations directly in your application, make sure to configure the spring-boot-maven-plugin
to prevent the repackage
goal from adding the dependency into the fat jar:
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludes>
<exclude>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-autoconfigure-processor</artifactId>
</exclude>
</excludes>
</configuration>
</plugin>
</plugins>
</build>
</project>
With Gradle, the dependency should be declared in the annotationProcessor
configuration, as shown in the following example:
dependencies {
annotationProcessor "org.springframework.boot:spring-boot-autoconfigure-processor"
}
Starter Module
The starter is really an empty jar. Its only purpose is to provide the necessary dependencies to work with the library. You can think of it as an opinionated view of what is required to get started.
Do not make assumptions about the project in which your starter is added. If the library you are auto-configuring typically requires other starters, mention them as well. Providing a proper set of default dependencies may be hard if the number of optional dependencies is high, as you should avoid including dependencies that are unnecessary for a typical usage of the library. In other words, you should not include optional dependencies.
Either way, your starter must reference the core Spring Boot starter (spring-boot-starter ) directly or indirectly (there is no need to add it if your starter relies on another starter).
If a project is created with only your custom starter, Spring Boot’s core features will be honoured by the presence of the core starter.
|
7.11. Kotlin Support
Kotlin is a statically-typed language targeting the JVM (and other platforms) which allows writing concise and elegant code while providing interoperability with existing libraries written in Java.
Spring Boot provides Kotlin support by leveraging the support in other Spring projects such as Spring Framework, Spring Data, and Reactor. See the Spring Framework Kotlin support documentation for more information.
The easiest way to start with Spring Boot and Kotlin is to follow this comprehensive tutorial.
You can create new Kotlin projects by using start.spring.io.
Feel free to join the #spring channel of Kotlin Slack or ask a question with the spring
and kotlin
tags on Stack Overflow if you need support.
7.11.1. Requirements
Spring Boot requires at least Kotlin 1.3.x and manages a suitable Kotlin version through dependency management.
To use Kotlin, org.jetbrains.kotlin:kotlin-stdlib
and org.jetbrains.kotlin:kotlin-reflect
must be present on the classpath.
The kotlin-stdlib
variants kotlin-stdlib-jdk7
and kotlin-stdlib-jdk8
can also be used.
Since Kotlin classes are final by default, you are likely to want to configure kotlin-spring plugin in order to automatically open Spring-annotated classes so that they can be proxied.
Jackson’s Kotlin module is required for serializing / deserializing JSON data in Kotlin. It is automatically registered when found on the classpath. A warning message is logged if Jackson and Kotlin are present but the Jackson Kotlin module is not.
These dependencies and plugins are provided by default if one bootstraps a Kotlin project on start.spring.io. |
7.11.2. Null-safety
One of Kotlin’s key features is null-safety.
It deals with null
values at compile time rather than deferring the problem to runtime and encountering a NullPointerException
.
This helps to eliminate a common source of bugs without paying the cost of wrappers like Optional
.
Kotlin also allows using functional constructs with nullable values as described in this comprehensive guide to null-safety in Kotlin.
Although Java does not allow one to express null-safety in its type system, Spring Framework, Spring Data, and Reactor now provide null-safety of their API through tooling-friendly annotations. By default, types from Java APIs used in Kotlin are recognized as platform types for which null-checks are relaxed. Kotlin’s support for JSR 305 annotations combined with nullability annotations provide null-safety for the related Spring API in Kotlin.
The JSR 305 checks can be configured by adding the -Xjsr305
compiler flag with the following options: -Xjsr305={strict|warn|ignore}
.
The default behavior is the same as -Xjsr305=warn
.
The strict
value is required to have null-safety taken in account in Kotlin types inferred from Spring API but should be used with the knowledge that Spring API nullability declaration could evolve even between minor releases and more checks may be added in the future).
Generic type arguments, varargs and array elements nullability are not yet supported. See SPR-15942 for up-to-date information. Also be aware that Spring Boot’s own API is not yet annotated. |
7.11.3. Kotlin API
runApplication
Spring Boot provides an idiomatic way to run an application with runApplication<MyApplication>(*args)
as shown in the following example:
@SpringBootApplication
class MyApplication
fun main(args: Array<String>) {
runApplication<MyApplication>(*args)
}
This is a drop-in replacement for SpringApplication.run(MyApplication::class.java, *args)
.
It also allows customization of the application as shown in the following example:
runApplication<MyApplication>(*args) {
setBannerMode(OFF)
}
Extensions
Kotlin extensions provide the ability to extend existing classes with additional functionality. The Spring Boot Kotlin API makes use of these extensions to add new Kotlin specific conveniences to existing APIs.
TestRestTemplate
extensions, similar to those provided by Spring Framework for RestOperations
in Spring Framework, are provided.
Among other things, the extensions make it possible to take advantage of Kotlin reified type parameters.
7.11.4. Dependency management
In order to avoid mixing different versions of Kotlin dependencies on the classpath, Spring Boot imports the Kotlin BOM.
With Maven, the Kotlin version can be customized by setting the kotlin.version
property and plugin management is provided for kotlin-maven-plugin
.
With Gradle, the Spring Boot plugin automatically aligns the kotlin.version
with the version of the Kotlin plugin.
Spring Boot also manages the version of Coroutines dependencies by importing the Kotlin Coroutines BOM.
The version can be customized by setting the kotlin-coroutines.version
property.
org.jetbrains.kotlinx:kotlinx-coroutines-reactor dependency is provided by default if one bootstraps a Kotlin project with at least one reactive dependency on start.spring.io.
|
7.11.5. @ConfigurationProperties
@ConfigurationProperties
when used in combination with @ConstructorBinding
supports classes with immutable val
properties as shown in the following example:
@ConstructorBinding
@ConfigurationProperties("example.kotlin")
data class KotlinExampleProperties(
val name: String,
val description: String,
val myService: MyService) {
data class MyService(
val apiToken: String,
val uri: URI
)
}
To generate your own metadata using the annotation processor, kapt should be configured with the spring-boot-configuration-processor dependency.
Note that some features (such as detecting the default value or deprecated items) are not working due to limitations in the model kapt provides.
|
7.11.6. Testing
While it is possible to use JUnit 4 to test Kotlin code, JUnit 5 is provided by default and is recommended.
JUnit 5 enables a test class to be instantiated once and reused for all of the class’s tests.
This makes it possible to use @BeforeAll
and @AfterAll
annotations on non-static methods, which is a good fit for Kotlin.
To mock Kotlin classes, MockK is recommended.
If you need the MockK
equivalent of the Mockito specific @MockBean
and @SpyBean
annotations, you can use SpringMockK which provides similar @MockkBean
and @SpykBean
annotations.
7.11.7. Resources
Further reading
-
Kotlin Slack (with a dedicated #spring channel)
-
Tutorial: building web applications with Spring Boot and Kotlin
-
A Geospatial Messenger with Kotlin, Spring Boot and PostgreSQL
Examples
-
spring-boot-kotlin-demo: regular Spring Boot + Spring Data JPA project
-
mixit: Spring Boot 2 + WebFlux + Reactive Spring Data MongoDB
-
spring-kotlin-fullstack: WebFlux Kotlin fullstack example with Kotlin2js for frontend instead of JavaScript or TypeScript
-
spring-petclinic-kotlin: Kotlin version of the Spring PetClinic Sample Application
-
spring-kotlin-deepdive: a step by step migration for Boot 1.0 + Java to Boot 2.0 + Kotlin
-
spring-boot-coroutines-demo: Coroutines sample project
7.12. What to Read Next
If you want to learn more about any of the classes discussed in this section, see the Spring Boot API documentation or you can browse the source code directly. If you have specific questions, see the how-to section.
If you are comfortable with Spring Boot’s core features, you can continue on and read about production-ready features.
8. Web
Spring Boot is well suited for web application development.
You can create a self-contained HTTP server by using embedded Tomcat, Jetty, Undertow, or Netty.
Most web applications use the spring-boot-starter-web
module to get up and running quickly.
You can also choose to build reactive web applications by using the spring-boot-starter-webflux
module.
If you have not yet developed a Spring Boot web application, you can follow the "Hello World!" example in the Getting started section.
8.1. Servlet Web Applications
If you want to build servlet-based web applications, you can take advantage of Spring Boot’s auto-configuration for Spring MVC or Jersey.
8.1.1. The “Spring Web MVC Framework”
The Spring Web MVC framework (often referred to as “Spring MVC”) is a rich “model view controller” web framework.
Spring MVC lets you create special @Controller
or @RestController
beans to handle incoming HTTP requests.
Methods in your controller are mapped to HTTP by using @RequestMapping
annotations.
The following code shows a typical @RestController
that serves JSON data:
@RestController
@RequestMapping("/users")
public class MyRestController {
private final UserRepository userRepository;
private final CustomerRepository customerRepository;
public MyRestController(UserRepository userRepository, CustomerRepository customerRepository) {
this.userRepository = userRepository;
this.customerRepository = customerRepository;
}
@GetMapping("/{userId}")
public User getUser(@PathVariable Long userId) {
return this.userRepository.findById(userId).get();
}
@GetMapping("/{userId}/customers")
public List<Customer> getUserCustomers(@PathVariable Long userId) {
return this.userRepository.findById(userId).map(this.customerRepository::findByUser).get();
}
@DeleteMapping("/{userId}")
public void deleteUser(@PathVariable Long userId) {
this.userRepository.deleteById(userId);
}
}
@RestController
@RequestMapping("/users")
class MyRestController(private val userRepository: UserRepository, private val customerRepository: CustomerRepository) {
@GetMapping("/{userId}")
fun getUser(@PathVariable userId: Long): User {
return userRepository.findById(userId).get()
}
@GetMapping("/{userId}/customers")
fun getUserCustomers(@PathVariable userId: Long): List<Customer> {
return userRepository.findById(userId).map(customerRepository::findByUser).get()
}
@DeleteMapping("/{userId}")
fun deleteUser(@PathVariable userId: Long) {
userRepository.deleteById(userId)
}
}
“WebMvc.fn”, the functional variant, separates the routing configuration from the actual handling of the requests, as shown in the following example:
@Configuration(proxyBeanMethods = false)
public class MyRoutingConfiguration {
private static final RequestPredicate ACCEPT_JSON = accept(MediaType.APPLICATION_JSON);
@Bean
public RouterFunction<ServerResponse> routerFunction(MyUserHandler userHandler) {
return route()
.GET("/{user}", ACCEPT_JSON, userHandler::getUser)
.GET("/{user}/customers", ACCEPT_JSON, userHandler::getUserCustomers)
.DELETE("/{user}", ACCEPT_JSON, userHandler::deleteUser)
.build();
}
}
@Configuration(proxyBeanMethods = false)
class MyRoutingConfiguration {
@Bean
fun routerFunction(userHandler: MyUserHandler): RouterFunction<ServerResponse> {
return RouterFunctions.route()
.GET("/{user}", ACCEPT_JSON, userHandler::getUser)
.GET("/{user}/customers", ACCEPT_JSON, userHandler::getUserCustomers)
.DELETE("/{user}", ACCEPT_JSON, userHandler::deleteUser)
.build()
}
companion object {
private val ACCEPT_JSON = accept(MediaType.APPLICATION_JSON)
}
}
@Component
public class MyUserHandler {
public ServerResponse getUser(ServerRequest request) {
...
return ServerResponse.ok().build();
}
public ServerResponse getUserCustomers(ServerRequest request) {
...
return ServerResponse.ok().build();
}
public ServerResponse deleteUser(ServerRequest request) {
...
return ServerResponse.ok().build();
}
}
@Component
class MyUserHandler {
fun getUser(request: ServerRequest?): ServerResponse {
return ServerResponse.ok().build()
}
fun getUserCustomers(request: ServerRequest?): ServerResponse {
return ServerResponse.ok().build()
}
fun deleteUser(request: ServerRequest?): ServerResponse {
return ServerResponse.ok().build()
}
}
Spring MVC is part of the core Spring Framework, and detailed information is available in the reference documentation. There are also several guides that cover Spring MVC available at spring.io/guides.
You can define as many RouterFunction beans as you like to modularize the definition of the router.
Beans can be ordered if you need to apply a precedence.
|
Spring MVC Auto-configuration
Spring Boot provides auto-configuration for Spring MVC that works well with most applications.
It replaces the need for @EnableWebMvc
and the two cannot be used together.
In addition to Spring MVC’s defaults, the auto-configuration provides the following features:
-
Inclusion of
ContentNegotiatingViewResolver
andBeanNameViewResolver
beans. -
Support for serving static resources, including support for WebJars (covered later in this document).
-
Automatic registration of
Converter
,GenericConverter
, andFormatter
beans. -
Support for
HttpMessageConverters
(covered later in this document). -
Automatic registration of
MessageCodesResolver
(covered later in this document). -
Static
index.html
support. -
Automatic use of a
ConfigurableWebBindingInitializer
bean (covered later in this document).
If you want to keep those Spring Boot MVC customizations and make more MVC customizations (interceptors, formatters, view controllers, and other features), you can add your own @Configuration
class of type WebMvcConfigurer
but without @EnableWebMvc
.
If you want to provide custom instances of RequestMappingHandlerMapping
, RequestMappingHandlerAdapter
, or ExceptionHandlerExceptionResolver
, and still keep the Spring Boot MVC customizations, you can declare a bean of type WebMvcRegistrations
and use it to provide custom instances of those components.
The custom instances will be subject to further initialization and configuration by Spring MVC.
To participate in, and if desired, override that subsequent processing, a WebMvcConfigurer
should be used.
If you do not want to use the auto-configuration and want to take complete control of Spring MVC, add your own @Configuration
annotated with @EnableWebMvc
.
Alternatively, add your own @Configuration
-annotated DelegatingWebMvcConfiguration
as described in the Javadoc of @EnableWebMvc
.
Spring MVC Conversion Service
Spring MVC uses a different ConversionService
to the one used to convert values from your application.properties
or application.yaml
file.
It means that Period
, Duration
and DataSize
converters are not available and that @DurationUnit
and @DataSizeUnit
annotations will be ignored.
If you want to customize the ConversionService
used by Spring MVC, you can provide a WebMvcConfigurer
bean with an addFormatters
method.
From this method you can register any converter that you like, or you can delegate to the static methods available on ApplicationConversionService
.
Conversion can also be customized using the spring.mvc.format.*
configuration properties.
When not configured, the following defaults are used:
Property | DateTimeFormatter |
---|---|
|
|
|
|
|
|
HttpMessageConverters
Spring MVC uses the HttpMessageConverter
interface to convert HTTP requests and responses.
Sensible defaults are included out of the box.
For example, objects can be automatically converted to JSON (by using the Jackson library) or XML (by using the Jackson XML extension, if available, or by using JAXB if the Jackson XML extension is not available).
By default, strings are encoded in UTF-8
.
If you need to add or customize converters, you can use Spring Boot’s HttpMessageConverters
class, as shown in the following listing:
@Configuration(proxyBeanMethods = false)
public class MyHttpMessageConvertersConfiguration {
@Bean
public HttpMessageConverters customConverters() {
HttpMessageConverter<?> additional = new AdditionalHttpMessageConverter();
HttpMessageConverter<?> another = new AnotherHttpMessageConverter();
return new HttpMessageConverters(additional, another);
}
}
@Configuration(proxyBeanMethods = false)
class MyHttpMessageConvertersConfiguration {
@Bean
fun customConverters(): HttpMessageConverters {
val additional: HttpMessageConverter<*> = AdditionalHttpMessageConverter()
val another: HttpMessageConverter<*> = AnotherHttpMessageConverter()
return HttpMessageConverters(additional, another)
}
}
Any HttpMessageConverter
bean that is present in the context is added to the list of converters.
You can also override default converters in the same way.
MessageCodesResolver
Spring MVC has a strategy for generating error codes for rendering error messages from binding errors: MessageCodesResolver
.
If you set the spring.mvc.message-codes-resolver-format
property PREFIX_ERROR_CODE
or POSTFIX_ERROR_CODE
, Spring Boot creates one for you (see the enumeration in DefaultMessageCodesResolver.Format
).
Static Content
By default, Spring Boot serves static content from a directory called /static
(or /public
or /resources
or /META-INF/resources
) in the classpath or from the root of the ServletContext
.
It uses the ResourceHttpRequestHandler
from Spring MVC so that you can modify that behavior by adding your own WebMvcConfigurer
and overriding the addResourceHandlers
method.
In a stand-alone web application, the default servlet from the container is not enabled.
It can be enabled using the server.servlet.register-default-servlet
property.
The default servlet acts as a fallback, serving content from the root of the ServletContext
if Spring decides not to handle it.
Most of the time, this does not happen (unless you modify the default MVC configuration), because Spring can always handle requests through the DispatcherServlet
.
By default, resources are mapped on /**
, but you can tune that with the spring.mvc.static-path-pattern
property.
For instance, relocating all resources to /resources/**
can be achieved as follows:
spring.mvc.static-path-pattern=/resources/**
spring:
mvc:
static-path-pattern: "/resources/**"
You can also customize the static resource locations by using the spring.web.resources.static-locations
property (replacing the default values with a list of directory locations).
The root servlet context path, "/"
, is automatically added as a location as well.
In addition to the “standard” static resource locations mentioned earlier, a special case is made for Webjars content.
Any resources with a path in /webjars/**
are served from jar files if they are packaged in the Webjars format.
Do not use the src/main/webapp directory if your application is packaged as a jar.
Although this directory is a common standard, it works only with war packaging, and it is silently ignored by most build tools if you generate a jar.
|
Spring Boot also supports the advanced resource handling features provided by Spring MVC, allowing use cases such as cache-busting static resources or using version agnostic URLs for Webjars.
To use version agnostic URLs for Webjars, add the webjars-locator-core
dependency.
Then declare your Webjar.
Using jQuery as an example, adding "/webjars/jquery/jquery.min.js"
results in "/webjars/jquery/x.y.z/jquery.min.js"
where x.y.z
is the Webjar version.
If you use JBoss, you need to declare the webjars-locator-jboss-vfs dependency instead of the webjars-locator-core .
Otherwise, all Webjars resolve as a 404 .
|
To use cache busting, the following configuration configures a cache busting solution for all static resources, effectively adding a content hash, such as <link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>
, in URLs:
spring.web.resources.chain.strategy.content.enabled=true
spring.web.resources.chain.strategy.content.paths=/**
spring:
web:
resources:
chain:
strategy:
content:
enabled: true
paths: "/**"
Links to resources are rewritten in templates at runtime, thanks to a ResourceUrlEncodingFilter that is auto-configured for Thymeleaf and FreeMarker.
You should manually declare this filter when using JSPs.
Other template engines are currently not automatically supported but can be with custom template macros/helpers and the use of the ResourceUrlProvider .
|
When loading resources dynamically with, for example, a JavaScript module loader, renaming files is not an option. That is why other strategies are also supported and can be combined. A "fixed" strategy adds a static version string in the URL without changing the file name, as shown in the following example:
spring.web.resources.chain.strategy.content.enabled=true
spring.web.resources.chain.strategy.content.paths=/**
spring.web.resources.chain.strategy.fixed.enabled=true
spring.web.resources.chain.strategy.fixed.paths=/js/lib/
spring.web.resources.chain.strategy.fixed.version=v12
spring:
web:
resources:
chain:
strategy:
content:
enabled: true
paths: "/**"
fixed:
enabled: true
paths: "/js/lib/"
version: "v12"
With this configuration, JavaScript modules located under "/js/lib/"
use a fixed versioning strategy ("/v12/js/lib/mymodule.js"
), while other resources still use the content one (<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>
).
See WebProperties.Resources
for more supported options.
This feature has been thoroughly described in a dedicated blog post and in Spring Framework’s reference documentation. |
Welcome Page
Spring Boot supports both static and templated welcome pages.
It first looks for an index.html
file in the configured static content locations.
If one is not found, it then looks for an index
template.
If either is found, it is automatically used as the welcome page of the application.
Custom Favicon
As with other static resources, Spring Boot checks for a favicon.ico
in the configured static content locations.
If such a file is present, it is automatically used as the favicon of the application.
Path Matching and Content Negotiation
Spring MVC can map incoming HTTP requests to handlers by looking at the request path and matching it to the mappings defined in your application (for example, @GetMapping
annotations on Controller methods).
Spring Boot chooses to disable suffix pattern matching by default, which means that requests like "GET /projects/spring-boot.json"
will not be matched to @GetMapping("/projects/spring-boot")
mappings.
This is considered as a best practice for Spring MVC applications.
This feature was mainly useful in the past for HTTP clients which did not send proper "Accept" request headers; we needed to make sure to send the correct Content Type to the client.
Nowadays, Content Negotiation is much more reliable.
There are other ways to deal with HTTP clients that do not consistently send proper "Accept" request headers.
Instead of using suffix matching, we can use a query parameter to ensure that requests like "GET /projects/spring-boot?format=json"
will be mapped to @GetMapping("/projects/spring-boot")
:
spring.mvc.contentnegotiation.favor-parameter=true
spring:
mvc:
contentnegotiation:
favor-parameter: true
Or if you prefer to use a different parameter name:
spring.mvc.contentnegotiation.favor-parameter=true
spring.mvc.contentnegotiation.parameter-name=myparam
spring:
mvc:
contentnegotiation:
favor-parameter: true
parameter-name: "myparam"
Most standard media types are supported out-of-the-box, but you can also define new ones:
spring.mvc.contentnegotiation.media-types.markdown=text/markdown
spring:
mvc:
contentnegotiation:
media-types:
markdown: "text/markdown"
Suffix pattern matching is deprecated and will be removed in a future release. If you understand the caveats and would still like your application to use suffix pattern matching, the following configuration is required:
spring.mvc.contentnegotiation.favor-path-extension=true
spring.mvc.pathmatch.use-suffix-pattern=true
spring:
mvc:
contentnegotiation:
favor-path-extension: true
pathmatch:
use-suffix-pattern: true
Alternatively, rather than open all suffix patterns, it is more secure to only support registered suffix patterns:
spring.mvc.contentnegotiation.favor-path-extension=true
spring.mvc.pathmatch.use-registered-suffix-pattern=true
spring:
mvc:
contentnegotiation:
favor-path-extension: true
pathmatch:
use-registered-suffix-pattern: true
As of Spring Framework 5.3, Spring MVC supports two strategies for matching request paths to controllers.
By default, Spring Boot uses the PathPatternParser
strategy.
PathPatternParser
is an optimized implementation but comes with some restrictions compared to the AntPathMatcher
strategy.
PathPatternParser
restricts usage of some path pattern variants.
It is also incompatible with suffix pattern matching (spring.mvc.pathmatch.use-suffix-pattern
, spring.mvc.pathmatch.use-registered-suffix-pattern
) and configuring the DispatcherServlet
with a path prefix (spring.mvc.servlet.path
).
The strategy can be configured using the spring.mvc.pathmatch.matching-strategy
configuration property, as shown in the following example:
spring.mvc.pathmatch.matching-strategy=ant-path-matcher
spring:
mvc:
pathmatch:
matching-strategy: "ant-path-matcher"
By default, Spring MVC will send a 404 Not Found error response if a handler is not found for a request.
To have a NoHandlerFoundException
thrown instead, set configprop:spring.mvc.throw-exception-if-no-handler-found to true
.
Note that, by default, the serving of static content is mapped to /**
and will, therefore, provide a handler for all requests.
For a NoHandlerFoundException
to be thrown, you must also set spring.mvc.static-path-pattern
to a more specific value such as /resources/**
or set spring.web.resources.add-mappings
to false
to disable serving of static content entirely.
ConfigurableWebBindingInitializer
Spring MVC uses a WebBindingInitializer
to initialize a WebDataBinder
for a particular request.
If you create your own ConfigurableWebBindingInitializer
@Bean
, Spring Boot automatically configures Spring MVC to use it.
Template Engines
As well as REST web services, you can also use Spring MVC to serve dynamic HTML content. Spring MVC supports a variety of templating technologies, including Thymeleaf, FreeMarker, and JSPs. Also, many other templating engines include their own Spring MVC integrations.
Spring Boot includes auto-configuration support for the following templating engines:
If possible, JSPs should be avoided. There are several known limitations when using them with embedded servlet containers. |
When you use one of these templating engines with the default configuration, your templates are picked up automatically from src/main/resources/templates
.
Depending on how you run your application, your IDE may order the classpath differently. Running your application in the IDE from its main method results in a different ordering than when you run your application by using Maven or Gradle or from its packaged jar. This can cause Spring Boot to fail to find the expected template. If you have this problem, you can reorder the classpath in the IDE to place the module’s classes and resources first. |
Error Handling
By default, Spring Boot provides an /error
mapping that handles all errors in a sensible way, and it is registered as a “global” error page in the servlet container.
For machine clients, it produces a JSON response with details of the error, the HTTP status, and the exception message.
For browser clients, there is a “whitelabel” error view that renders the same data in HTML format (to customize it, add a View
that resolves to error
).
There are a number of server.error
properties that can be set if you want to customize the default error handling behavior.
See the “Server Properties” section of the Appendix.
To replace the default behavior completely, you can implement ErrorController
and register a bean definition of that type or add a bean of type ErrorAttributes
to use the existing mechanism but replace the contents.
The BasicErrorController can be used as a base class for a custom ErrorController .
This is particularly useful if you want to add a handler for a new content type (the default is to handle text/html specifically and provide a fallback for everything else).
To do so, extend BasicErrorController , add a public method with a @RequestMapping that has a produces attribute, and create a bean of your new type.
|
You can also define a class annotated with @ControllerAdvice
to customize the JSON document to return for a particular controller and/or exception type, as shown in the following example:
@ControllerAdvice(basePackageClasses = SomeController.class)
public class MyControllerAdvice extends ResponseEntityExceptionHandler {
@ResponseBody
@ExceptionHandler(MyException.class)
public ResponseEntity<?> handleControllerException(HttpServletRequest request, Throwable ex) {
HttpStatus status = getStatus(request);
return new ResponseEntity<>(new MyErrorBody(status.value(), ex.getMessage()), status);
}
private HttpStatus getStatus(HttpServletRequest request) {
Integer code = (Integer) request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
HttpStatus status = HttpStatus.resolve(code);
return (status != null) ? status : HttpStatus.INTERNAL_SERVER_ERROR;
}
}
@ControllerAdvice(basePackageClasses = [SomeController::class])
class MyControllerAdvice : ResponseEntityExceptionHandler() {
@ResponseBody
@ExceptionHandler(MyException::class)
fun handleControllerException(request: HttpServletRequest, ex: Throwable): ResponseEntity<*> {
val status = getStatus(request)
return ResponseEntity(MyErrorBody(status.value(), ex.message), status)
}
private fun getStatus(request: HttpServletRequest): HttpStatus {
val code = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE) as Int
val status = HttpStatus.resolve(code)
return status ?: HttpStatus.INTERNAL_SERVER_ERROR
}
}
In the preceding example, if MyException
is thrown by a controller defined in the same package as SomeController
, a JSON representation of the MyErrorBody
POJO is used instead of the ErrorAttributes
representation.
In some cases, errors handled at the controller level are not recorded by the metrics infrastructure. Applications can ensure that such exceptions are recorded with the request metrics by setting the handled exception as a request attribute:
@Controller
public class MyController {
@ExceptionHandler(CustomException.class)
String handleCustomException(HttpServletRequest request, CustomException ex) {
request.setAttribute(ErrorAttributes.ERROR_ATTRIBUTE, ex);
return "errorView";
}
}
@Controller
class MyController {
@ExceptionHandler(CustomException::class)
fun handleCustomException(request: HttpServletRequest, ex: CustomException?): String {
request.setAttribute(ErrorAttributes.ERROR_ATTRIBUTE, ex)
return "errorView"
}
}
Custom Error Pages
If you want to display a custom HTML error page for a given status code, you can add a file to an /error
directory.
Error pages can either be static HTML (that is, added under any of the static resource directories) or be built by using templates.
The name of the file should be the exact status code or a series mask.
For example, to map 404
to a static HTML file, your directory structure would be as follows:
src/ +- main/ +- java/ | + <source code> +- resources/ +- public/ +- error/ | +- 404.html +- <other public assets>
To map all 5xx
errors by using a FreeMarker template, your directory structure would be as follows:
src/ +- main/ +- java/ | + <source code> +- resources/ +- templates/ +- error/ | +- 5xx.ftlh +- <other templates>
For more complex mappings, you can also add beans that implement the ErrorViewResolver
interface, as shown in the following example:
public class MyErrorViewResolver implements ErrorViewResolver {
@Override
public ModelAndView resolveErrorView(HttpServletRequest request, HttpStatus status, Map<String, Object> model) {
// Use the request or status to optionally return a ModelAndView
if (status == HttpStatus.INSUFFICIENT_STORAGE) {
// We could add custom model values here
new ModelAndView("myview");
}
return null;
}
}
class MyErrorViewResolver : ErrorViewResolver {
override fun resolveErrorView(request: HttpServletRequest, status: HttpStatus,
model: Map<String, Any>): ModelAndView? {
// Use the request or status to optionally return a ModelAndView
if (status == HttpStatus.INSUFFICIENT_STORAGE) {
// We could add custom model values here
return ModelAndView("myview")
}
return null
}
}
You can also use regular Spring MVC features such as @ExceptionHandler
methods and @ControllerAdvice
.
The ErrorController
then picks up any unhandled exceptions.
Mapping Error Pages Outside of Spring MVC
For applications that do not use Spring MVC, you can use the ErrorPageRegistrar
interface to directly register ErrorPages
.
This abstraction works directly with the underlying embedded servlet container and works even if you do not have a Spring MVC DispatcherServlet
.
@Configuration(proxyBeanMethods = false)
public class MyErrorPagesConfiguration {
@Bean
public ErrorPageRegistrar errorPageRegistrar() {
return this::registerErrorPages;
}
private void registerErrorPages(ErrorPageRegistry registry) {
registry.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400"));
}
}
@Configuration(proxyBeanMethods = false)
class MyErrorPagesConfiguration {
@Bean
fun errorPageRegistrar(): ErrorPageRegistrar {
return ErrorPageRegistrar { registry: ErrorPageRegistry -> registerErrorPages(registry) }
}
private fun registerErrorPages(registry: ErrorPageRegistry) {
registry.addErrorPages(ErrorPage(HttpStatus.BAD_REQUEST, "/400"))
}
}
If you register an ErrorPage with a path that ends up being handled by a Filter (as is common with some non-Spring web frameworks, like Jersey and Wicket), then the Filter has to be explicitly registered as an ERROR dispatcher, as shown in the following example:
|
@Configuration(proxyBeanMethods = false)
public class MyFilterConfiguration {
@Bean
public FilterRegistrationBean<MyFilter> myFilter() {
FilterRegistrationBean<MyFilter> registration = new FilterRegistrationBean<>(new MyFilter());
// ...
registration.setDispatcherTypes(EnumSet.allOf(DispatcherType.class));
return registration;
}
}
@Configuration(proxyBeanMethods = false)
class MyFilterConfiguration {
@Bean
fun myFilter(): FilterRegistrationBean<MyFilter> {
val registration = FilterRegistrationBean(MyFilter())
// ...
registration.setDispatcherTypes(EnumSet.allOf(DispatcherType::class.java))
return registration
}
}
Note that the default FilterRegistrationBean
does not include the ERROR
dispatcher type.
Error Handling in a WAR Deployment
When deployed to a servlet container, Spring Boot uses its error page filter to forward a request with an error status to the appropriate error page. This is necessary as the servlet specification does not provide an API for registering error pages. Depending on the container that you are deploying your war file to and the technologies that your application uses, some additional configuration may be required.
The error page filter can only forward the request to the correct error page if the response has not already been committed.
By default, WebSphere Application Server 8.0 and later commits the response upon successful completion of a servlet’s service method.
You should disable this behavior by setting com.ibm.ws.webcontainer.invokeFlushAfterService
to false
.
If you are using Spring Security and want to access the principal in an error page, you must configure Spring Security’s filter to be invoked on error dispatches.
To do so, set the spring.security.filter.dispatcher-types
property to async, error, forward, request
.
CORS Support
Cross-origin resource sharing (CORS) is a W3C specification implemented by most browsers that lets you specify in a flexible way what kind of cross-domain requests are authorized, instead of using some less secure and less powerful approaches such as IFRAME or JSONP.
As of version 4.2, Spring MVC supports CORS.
Using controller method CORS configuration with @CrossOrigin
annotations in your Spring Boot application does not require any specific configuration.
Global CORS configuration can be defined by registering a WebMvcConfigurer
bean with a customized addCorsMappings(CorsRegistry)
method, as shown in the following example:
@Configuration(proxyBeanMethods = false)
public class MyCorsConfiguration {
@Bean
public WebMvcConfigurer corsConfigurer() {
return new WebMvcConfigurer() {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**");
}
};
}
}
@Configuration(proxyBeanMethods = false)
class MyCorsConfiguration {
@Bean
fun corsConfigurer(): WebMvcConfigurer {
return object : WebMvcConfigurer {
override fun addCorsMappings(registry: CorsRegistry) {
registry.addMapping("/api/**")
}
}
}
}
8.1.2. JAX-RS and Jersey
If you prefer the JAX-RS programming model for REST endpoints, you can use one of the available implementations instead of Spring MVC.
Jersey and Apache CXF work quite well out of the box.
CXF requires you to register its Servlet
or Filter
as a @Bean
in your application context.
Jersey has some native Spring support, so we also provide auto-configuration support for it in Spring Boot, together with a starter.
To get started with Jersey, include the spring-boot-starter-jersey
as a dependency and then you need one @Bean
of type ResourceConfig
in which you register all the endpoints, as shown in the following example:
@Component
public class MyJerseyConfig extends ResourceConfig {
public MyJerseyConfig() {
register(MyEndpoint.class);
}
}
@Component
class MyJerseyConfig : ResourceConfig() {
init {
register(MyEndpoint::class.java)
}
}
Jersey’s support for scanning executable archives is rather limited.
For example, it cannot scan for endpoints in a package found in a fully executable jar file or in WEB-INF/classes when running an executable war file.
To avoid this limitation, the packages method should not be used, and endpoints should be registered individually by using the register method, as shown in the preceding example.
|
For more advanced customizations, you can also register an arbitrary number of beans that implement ResourceConfigCustomizer
.
All the registered endpoints should be @Components
with HTTP resource annotations (@GET
and others), as shown in the following example:
@Component
@Path("/hello")
public class MyEndpoint {
@GET
public String message() {
return "Hello";
}
}
@Component
@Path("/hello")
class MyEndpoint {
@GET
fun message(): String {
return "Hello"
}
}
Since the Endpoint
is a Spring @Component
, its lifecycle is managed by Spring and you can use the @Autowired
annotation to inject dependencies and use the @Value
annotation to inject external configuration.
By default, the Jersey servlet is registered and mapped to /*
.
You can change the mapping by adding @ApplicationPath
to your ResourceConfig
.
By default, Jersey is set up as a servlet in a @Bean
of type ServletRegistrationBean
named jerseyServletRegistration
.
By default, the servlet is initialized lazily, but you can customize that behavior by setting spring.jersey.servlet.load-on-startup
.
You can disable or override that bean by creating one of your own with the same name.
You can also use a filter instead of a servlet by setting spring.jersey.type=filter
(in which case, the @Bean
to replace or override is jerseyFilterRegistration
).
The filter has an @Order
, which you can set with spring.jersey.filter.order
.
When using Jersey as a filter, a servlet that will handle any requests that are not intercepted by Jersey must be present.
If your application does not contain such a servlet, you may want to enable the default servlet by setting server.servlet.register-default-servlet
to true
.
Both the servlet and the filter registrations can be given init parameters by using spring.jersey.init.*
to specify a map of properties.
8.1.3. Embedded Servlet Container Support
For servlet application, Spring Boot includes support for embedded Tomcat, Jetty, and Undertow servers.
Most developers use the appropriate “Starter” to obtain a fully configured instance.
By default, the embedded server listens for HTTP requests on port 8080
.
Servlets, Filters, and Listeners
When using an embedded servlet container, you can register servlets, filters, and all the listeners (such as HttpSessionListener
) from the servlet spec, either by using Spring beans or by scanning for servlet components.
Registering Servlets, Filters, and Listeners as Spring Beans
Any Servlet
, Filter
, or servlet *Listener
instance that is a Spring bean is registered with the embedded container.
This can be particularly convenient if you want to refer to a value from your application.properties
during configuration.
By default, if the context contains only a single Servlet, it is mapped to /
.
In the case of multiple servlet beans, the bean name is used as a path prefix.
Filters map to /*
.
If convention-based mapping is not flexible enough, you can use the ServletRegistrationBean
, FilterRegistrationBean
, and ServletListenerRegistrationBean
classes for complete control.
It is usually safe to leave filter beans unordered.
If a specific order is required, you should annotate the Filter
with @Order
or make it implement Ordered
.
You cannot configure the order of a Filter
by annotating its bean method with @Order
.
If you cannot change the Filter
class to add @Order
or implement Ordered
, you must define a FilterRegistrationBean
for the Filter
and set the registration bean’s order using the setOrder(int)
method.
Avoid configuring a filter that reads the request body at Ordered.HIGHEST_PRECEDENCE
, since it might go against the character encoding configuration of your application.
If a servlet filter wraps the request, it should be configured with an order that is less than or equal to OrderedFilter.REQUEST_WRAPPER_FILTER_MAX_ORDER
.
To see the order of every Filter in your application, enable debug level logging for the web logging group (logging.level.web=debug ).
Details of the registered filters, including their order and URL patterns, will then be logged at startup.
|
Take care when registering Filter beans since they are initialized very early in the application lifecycle.
If you need to register a Filter that interacts with other beans, consider using a DelegatingFilterProxyRegistrationBean instead.
|
Servlet Context Initialization
Embedded servlet containers do not directly execute the servlet 3.0+ javax.servlet.ServletContainerInitializer
interface or Spring’s org.springframework.web.WebApplicationInitializer
interface.
This is an intentional design decision intended to reduce the risk that third party libraries designed to run inside a war may break Spring Boot applications.
If you need to perform servlet context initialization in a Spring Boot application, you should register a bean that implements the org.springframework.boot.web.servlet.ServletContextInitializer
interface.
The single onStartup
method provides access to the ServletContext
and, if necessary, can easily be used as an adapter to an existing WebApplicationInitializer
.
Scanning for Servlets, Filters, and listeners
When using an embedded container, automatic registration of classes annotated with @WebServlet
, @WebFilter
, and @WebListener
can be enabled by using @ServletComponentScan
.
@ServletComponentScan has no effect in a standalone container, where the container’s built-in discovery mechanisms are used instead.
|
The ServletWebServerApplicationContext
Under the hood, Spring Boot uses a different type of ApplicationContext
for embedded servlet container support.
The ServletWebServerApplicationContext
is a special type of WebApplicationContext
that bootstraps itself by searching for a single ServletWebServerFactory
bean.
Usually a TomcatServletWebServerFactory
, JettyServletWebServerFactory
, or UndertowServletWebServerFactory
has been auto-configured.
You usually do not need to be aware of these implementation classes.
Most applications are auto-configured, and the appropriate ApplicationContext and ServletWebServerFactory are created on your behalf.
|
In an embedded container setup, the ServletContext
is set as part of server startup which happens during application context initialization.
Because of this beans in the ApplicationContext
cannot be reliably initialized with a ServletContext
.
One way to get around this is to inject ApplicationContext
as a dependency of the bean and access the ServletContext
only when it is needed.
Another way is to use a callback once the server has started.
This can be done using an ApplicationListener
which listens for the ApplicationStartedEvent
as follows:
public class MyDemoBean implements ApplicationListener<ApplicationStartedEvent> {
private ServletContext servletContext;
@Override
public void onApplicationEvent(ApplicationStartedEvent event) {
ApplicationContext applicationContext = event.getApplicationContext();
this.servletContext = ((WebApplicationContext) applicationContext).getServletContext();
}
}
Customizing Embedded Servlet Containers
Common servlet container settings can be configured by using Spring Environment
properties.
Usually, you would define the properties in your application.properties
or application.yaml
file.
Common server settings include:
-
Network settings: Listen port for incoming HTTP requests (
server.port
), interface address to bind toserver.address
, and so on. -
Session settings: Whether the session is persistent (
server.servlet.session.persistent
), session timeout (server.servlet.session.timeout
), location of session data (server.servlet.session.store-dir
), and session-cookie configuration (server.servlet.session.cookie.*
). -
Error management: Location of the error page (
server.error.path
) and so on.
Spring Boot tries as much as possible to expose common settings, but this is not always possible.
For those cases, dedicated namespaces offer server-specific customizations (see server.tomcat
and server.undertow
).
For instance, access logs can be configured with specific features of the embedded servlet container.
See the ServerProperties class for a complete list.
|
SameSite Cookies
The SameSite
cookie attribute can be used by web browsers to control if and how cookies are submitted in cross-site requests.
The attribute is particularly relevant for modern web browsers which have started to change the default value that is used when the attribute is missing.
If you want to change the SameSite
attribute of your session cookie, you can use the server.servlet.session.cookie.same-site
property.
This property is supported by auto-configured Tomcat, Jetty and Undertow servers.
It is also used to configure Spring Session servlet based SessionRepository
beans.
For example, if you want your session cookie to have a SameSite
attribute of None
, you can add the following to your application.properties
or application.yaml
file:
server.servlet.session.cookie.same-site=none
server:
servlet:
session:
cookie:
same-site: "none"
If you want to change the SameSite
attribute on other cookies added to your HttpServletResponse
, you can use a CookieSameSiteSupplier
.
The CookieSameSiteSupplier
is passed a Cookie
and may return a SameSite
value, or null
.
There are a number of convenience factory and filter methods that you can use to quickly match specific cookies.
For example, adding the following bean will automatically apply a SameSite
of Lax
for all cookies with a name that matches the regular expression myapp.*
.
@Configuration(proxyBeanMethods = false)
public class MySameSiteConfiguration {
@Bean
public CookieSameSiteSupplier applicationCookieSameSiteSupplier() {
return CookieSameSiteSupplier.ofLax().whenHasNameMatching("myapp.*");
}
}
@Configuration(proxyBeanMethods = false)
class MySameSiteConfiguration {
@Bean
fun applicationCookieSameSiteSupplier(): CookieSameSiteSupplier {
return CookieSameSiteSupplier.ofLax().whenHasNameMatching("myapp.*")
}
}
Character Encoding
The character encoding behavior of the embedded servlet container for request and response handling can be configured using the server.servlet.encoding.*
configuration properties.
When a request’s Accept-Language
header indicates a locale for the request it will be automatically mapped to a charset by the servlet container.
Each containers providers default locale to charset mappings and you should verify that they meet your application’s needs.
When they do not, use the server.servlet.encoding.mapping
configuration property to customize the mappings, as shown in the following example:
server.servlet.encoding.mapping.ko=UTF-8
server:
servlet:
encoding:
mapping:
ko: "UTF-8"
In the preceding example, the ko
(Korean) locale has been mapped to UTF-8
.
This is equivalent to a <locale-encoding-mapping-list>
entry in a web.xml
file of a traditional war deployment.
Programmatic Customization
If you need to programmatically configure your embedded servlet container, you can register a Spring bean that implements the WebServerFactoryCustomizer
interface.
WebServerFactoryCustomizer
provides access to the ConfigurableServletWebServerFactory
, which includes numerous customization setter methods.
The following example shows programmatically setting the port:
@Component
public class MyWebServerFactoryCustomizer implements WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> {
@Override
public void customize(ConfigurableServletWebServerFactory server) {
server.setPort(9000);
}
}
@Component
class MyWebServerFactoryCustomizer : WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> {
override fun customize(server: ConfigurableServletWebServerFactory) {
server.setPort(9000)
}
}
TomcatServletWebServerFactory
, JettyServletWebServerFactory
and UndertowServletWebServerFactory
are dedicated variants of ConfigurableServletWebServerFactory
that have additional customization setter methods for Tomcat, Jetty and Undertow respectively.
The following example shows how to customize TomcatServletWebServerFactory
that provides access to Tomcat-specific configuration options:
@Component
public class MyTomcatWebServerFactoryCustomizer implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
@Override
public void customize(TomcatServletWebServerFactory server) {
server.addConnectorCustomizers((connector) -> connector.setAsyncTimeout(Duration.ofSeconds(20).toMillis()));
}
}
@Component
class MyTomcatWebServerFactoryCustomizer : WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
override fun customize(server: TomcatServletWebServerFactory) {
server.addConnectorCustomizers({ connector -> connector.asyncTimeout = Duration.ofSeconds(20).toMillis() })
}
}
Customizing ConfigurableServletWebServerFactory Directly
For more advanced use cases that require you to extend from ServletWebServerFactory
, you can expose a bean of such type yourself.
Setters are provided for many configuration options. Several protected method “hooks” are also provided should you need to do something more exotic. See the source code documentation for details.
Auto-configured customizers are still applied on your custom factory, so use that option carefully. |
JSP Limitations
When running a Spring Boot application that uses an embedded servlet container (and is packaged as an executable archive), there are some limitations in the JSP support.
-
With Jetty and Tomcat, it should work if you use war packaging. An executable war will work when launched with
java -jar
, and will also be deployable to any standard container. JSPs are not supported when using an executable jar. -
Undertow does not support JSPs.
-
Creating a custom
error.jsp
page does not override the default view for error handling. Custom error pages should be used instead.
8.2. Reactive Web Applications
Spring Boot simplifies development of reactive web applications by providing auto-configuration for Spring Webflux.
8.2.1. The “Spring WebFlux Framework”
Spring WebFlux is the new reactive web framework introduced in Spring Framework 5.0. Unlike Spring MVC, it does not require the servlet API, is fully asynchronous and non-blocking, and implements the Reactive Streams specification through the Reactor project.
Spring WebFlux comes in two flavors: functional and annotation-based. The annotation-based one is quite close to the Spring MVC model, as shown in the following example:
@RestController
@RequestMapping("/users")
public class MyRestController {
private final UserRepository userRepository;
private final CustomerRepository customerRepository;
public MyRestController(UserRepository userRepository, CustomerRepository customerRepository) {
this.userRepository = userRepository;
this.customerRepository = customerRepository;
}
@GetMapping("/{userId}")
public Mono<User> getUser(@PathVariable Long userId) {
return this.userRepository.findById(userId);
}
@GetMapping("/{userId}/customers")
public Flux<Customer> getUserCustomers(@PathVariable Long userId) {
return this.userRepository.findById(userId).flatMapMany(this.customerRepository::findByUser);
}
@DeleteMapping("/{userId}")
public Mono<Void> deleteUser(@PathVariable Long userId) {
return this.userRepository.deleteById(userId);
}
}
@RestController
@RequestMapping("/users")
class MyRestController(private val userRepository: UserRepository, private val customerRepository: CustomerRepository) {
@GetMapping("/{userId}")
fun getUser(@PathVariable userId: Long): Mono<User?> {
return userRepository.findById(userId)
}
@GetMapping("/{userId}/customers")
fun getUserCustomers(@PathVariable userId: Long): Flux<Customer> {
return userRepository.findById(userId).flatMapMany { user: User? ->
customerRepository.findByUser(user)
}
}
@DeleteMapping("/{userId}")
fun deleteUser(@PathVariable userId: Long): Mono<Void> {
return userRepository.deleteById(userId)
}
}
“WebFlux.fn”, the functional variant, separates the routing configuration from the actual handling of the requests, as shown in the following example:
@Configuration(proxyBeanMethods = false)
public class MyRoutingConfiguration {
private static final RequestPredicate ACCEPT_JSON = accept(MediaType.APPLICATION_JSON);
@Bean
public RouterFunction<ServerResponse> monoRouterFunction(MyUserHandler userHandler) {
return route()
.GET("/{user}", ACCEPT_JSON, userHandler::getUser)
.GET("/{user}/customers", ACCEPT_JSON, userHandler::getUserCustomers)
.DELETE("/{user}", ACCEPT_JSON, userHandler::deleteUser)
.build();
}
}
@Configuration(proxyBeanMethods = false)
class MyRoutingConfiguration {
@Bean
fun monoRouterFunction(userHandler: MyUserHandler): RouterFunction<ServerResponse> {
return RouterFunctions.route(
GET("/{user}").and(ACCEPT_JSON), userHandler::getUser).andRoute(
GET("/{user}/customers").and(ACCEPT_JSON), userHandler::getUserCustomers).andRoute(
DELETE("/{user}").and(ACCEPT_JSON), userHandler::deleteUser)
}
companion object {
private val ACCEPT_JSON = accept(MediaType.APPLICATION_JSON)
}
}
@Component
public class MyUserHandler {
public Mono<ServerResponse> getUser(ServerRequest request) {
...
}
public Mono<ServerResponse> getUserCustomers(ServerRequest request) {
...
}
public Mono<ServerResponse> deleteUser(ServerRequest request) {
...
}
}
@Component
class MyUserHandler {
fun getUser(request: ServerRequest?): Mono<ServerResponse> {
return ServerResponse.ok().build()
}
fun getUserCustomers(request: ServerRequest?): Mono<ServerResponse> {
return ServerResponse.ok().build()
}
fun deleteUser(request: ServerRequest?): Mono<ServerResponse> {
return ServerResponse.ok().build()
}
}
WebFlux is part of the Spring Framework and detailed information is available in its reference documentation.
You can define as many RouterFunction beans as you like to modularize the definition of the router.
Beans can be ordered if you need to apply a precedence.
|
To get started, add the spring-boot-starter-webflux
module to your application.
Adding both spring-boot-starter-web and spring-boot-starter-webflux modules in your application results in Spring Boot auto-configuring Spring MVC, not WebFlux.
This behavior has been chosen because many Spring developers add spring-boot-starter-webflux to their Spring MVC application to use the reactive WebClient .
You can still enforce your choice by setting the chosen application type to SpringApplication.setWebApplicationType(WebApplicationType.REACTIVE) .
|
Spring WebFlux Auto-configuration
Spring Boot provides auto-configuration for Spring WebFlux that works well with most applications.
The auto-configuration adds the following features on top of Spring’s defaults:
-
Configuring codecs for
HttpMessageReader
andHttpMessageWriter
instances (described later in this document). -
Support for serving static resources, including support for WebJars (described later in this document).
If you want to keep Spring Boot WebFlux features and you want to add additional WebFlux configuration, you can add your own @Configuration
class of type WebFluxConfigurer
but without @EnableWebFlux
.
If you want to take complete control of Spring WebFlux, you can add your own @Configuration
annotated with @EnableWebFlux
.
Spring WebFlux Conversion Service
If you want to customize the ConversionService
used by Spring WebFlux, you can provide a WebFluxConfigurer
bean with an addFormatters
method.
Conversion can also be customized using the spring.webflux.format.*
configuration properties.
When not configured, the following defaults are used:
Property | DateTimeFormatter |
---|---|
|
|
|
|
|
|
HTTP Codecs with HttpMessageReaders and HttpMessageWriters
Spring WebFlux uses the HttpMessageReader
and HttpMessageWriter
interfaces to convert HTTP requests and responses.
They are configured with CodecConfigurer
to have sensible defaults by looking at the libraries available in your classpath.
Spring Boot provides dedicated configuration properties for codecs, spring.codec.*
.
It also applies further customization by using CodecCustomizer
instances.
For example, spring.jackson.*
configuration keys are applied to the Jackson codec.
If you need to add or customize codecs, you can create a custom CodecCustomizer
component, as shown in the following example:
@Configuration(proxyBeanMethods = false)
public class MyCodecsConfiguration {
@Bean
public CodecCustomizer myCodecCustomizer() {
return (configurer) -> {
configurer.registerDefaults(false);
configurer.customCodecs().register(new ServerSentEventHttpMessageReader());
// ...
};
}
}
class MyCodecsConfiguration {
@Bean
fun myCodecCustomizer(): CodecCustomizer {
return CodecCustomizer { configurer: CodecConfigurer ->
configurer.registerDefaults(false)
configurer.customCodecs().register(ServerSentEventHttpMessageReader())
}
}
}
You can also leverage Boot’s custom JSON serializers and deserializers.
Static Content
By default, Spring Boot serves static content from a directory called /static
(or /public
or /resources
or /META-INF/resources
) in the classpath.
It uses the ResourceWebHandler
from Spring WebFlux so that you can modify that behavior by adding your own WebFluxConfigurer
and overriding the addResourceHandlers
method.
By default, resources are mapped on /**
, but you can tune that by setting the spring.webflux.static-path-pattern
property.
For instance, relocating all resources to /resources/**
can be achieved as follows:
spring.webflux.static-path-pattern=/resources/**
spring:
webflux:
static-path-pattern: "/resources/**"
You can also customize the static resource locations by using spring.web.resources.static-locations
.
Doing so replaces the default values with a list of directory locations.
If you do so, the default welcome page detection switches to your custom locations.
So, if there is an index.html
in any of your locations on startup, it is the home page of the application.
In addition to the “standard” static resource locations listed earlier, a special case is made for Webjars content.
Any resources with a path in /webjars/**
are served from jar files if they are packaged in the Webjars format.
Spring WebFlux applications do not strictly depend on the servlet API, so they cannot be deployed as war files and do not use the src/main/webapp directory.
|
Welcome Page
Spring Boot supports both static and templated welcome pages.
It first looks for an index.html
file in the configured static content locations.
If one is not found, it then looks for an index
template.
If either is found, it is automatically used as the welcome page of the application.
Template Engines
As well as REST web services, you can also use Spring WebFlux to serve dynamic HTML content. Spring WebFlux supports a variety of templating technologies, including Thymeleaf, FreeMarker, and Mustache.
Spring Boot includes auto-configuration support for the following templating engines:
When you use one of these templating engines with the default configuration, your templates are picked up automatically from src/main/resources/templates
.
Error Handling
Spring Boot provides a WebExceptionHandler
that handles all errors in a sensible way.
Its position in the processing order is immediately before the handlers provided by WebFlux, which are considered last.
For machine clients, it produces a JSON response with details of the error, the HTTP status, and the exception message.
For browser clients, there is a “whitelabel” error handler that renders the same data in HTML format.
You can also provide your own HTML templates to display errors (see the next section).
The first step to customizing this feature often involves using the existing mechanism but replacing or augmenting the error contents.
For that, you can add a bean of type ErrorAttributes
.
To change the error handling behavior, you can implement ErrorWebExceptionHandler
and register a bean definition of that type.
Because an ErrorWebExceptionHandler
is quite low-level, Spring Boot also provides a convenient AbstractErrorWebExceptionHandler
to let you handle errors in a WebFlux functional way, as shown in the following example:
@Component
public class MyErrorWebExceptionHandler extends AbstractErrorWebExceptionHandler {
public MyErrorWebExceptionHandler(ErrorAttributes errorAttributes, WebProperties webProperties,
ApplicationContext applicationContext, ServerCodecConfigurer serverCodecConfigurer) {
super(errorAttributes, webProperties.getResources(), applicationContext);
setMessageReaders(serverCodecConfigurer.getReaders());
setMessageWriters(serverCodecConfigurer.getWriters());
}
@Override
protected RouterFunction<ServerResponse> getRoutingFunction(ErrorAttributes errorAttributes) {
return RouterFunctions.route(this::acceptsXml, this::handleErrorAsXml);
}
private boolean acceptsXml(ServerRequest request) {
return request.headers().accept().contains(MediaType.APPLICATION_XML);
}
public Mono<ServerResponse> handleErrorAsXml(ServerRequest request) {
BodyBuilder builder = ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR);
// ... additional builder calls
return builder.build();
}
}
@Component
class MyErrorWebExceptionHandler(
errorAttributes: ErrorAttributes, webProperties: WebProperties,
applicationContext: ApplicationContext, serverCodecConfigurer: ServerCodecConfigurer
) : AbstractErrorWebExceptionHandler(errorAttributes, webProperties.resources, applicationContext) {
init {
setMessageReaders(serverCodecConfigurer.readers)
setMessageWriters(serverCodecConfigurer.writers)
}
override fun getRoutingFunction(errorAttributes: ErrorAttributes): RouterFunction<ServerResponse> {
return RouterFunctions.route(this::acceptsXml, this::handleErrorAsXml)
}
private fun acceptsXml(request: ServerRequest): Boolean {
return request.headers().accept().contains(MediaType.APPLICATION_XML)
}
fun handleErrorAsXml(request: ServerRequest): Mono<ServerResponse> {
val builder = ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
// ... additional builder calls
return builder.build()
}
}
For a more complete picture, you can also subclass DefaultErrorWebExceptionHandler
directly and override specific methods.
In some cases, errors handled at the controller or handler function level are not recorded by the metrics infrastructure. Applications can ensure that such exceptions are recorded with the request metrics by setting the handled exception as a request attribute:
@Controller
public class MyExceptionHandlingController {
@GetMapping("/profile")
public Rendering userProfile() {
// ...
throw new IllegalStateException();
}
@ExceptionHandler(IllegalStateException.class)
public Rendering handleIllegalState(ServerWebExchange exchange, IllegalStateException exc) {
exchange.getAttributes().putIfAbsent(ErrorAttributes.ERROR_ATTRIBUTE, exc);
return Rendering.view("errorView").modelAttribute("message", exc.getMessage()).build();
}
}
@Controller
class MyExceptionHandlingController {
@GetMapping("/profile")
fun userProfile(): Rendering {
// ...
throw IllegalStateException()
}
@ExceptionHandler(IllegalStateException::class)
fun handleIllegalState(exchange: ServerWebExchange, exc: IllegalStateException): Rendering {
exchange.attributes.putIfAbsent(ErrorAttributes.ERROR_ATTRIBUTE, exc)
return Rendering.view("errorView").modelAttribute("message", exc.message ?: "").build()
}
}
Custom Error Pages
If you want to display a custom HTML error page for a given status code, you can add views that resolve from error/*
, for example by adding files to a /error
directory.
Error pages can either be static HTML (that is, added under any of the static resource directories) or built with templates.
The name of the file should be the exact status code, a status code series mask, or error
for a default if nothing else matches.
Note that the path to the default error view is error/error
, whereas with Spring MVC the default error view is error
.
For example, to map 404
to a static HTML file, your directory structure would be as follows:
src/
+- main/
+- java/
| + <source code>
+- resources/
+- public/
+- error/
| +- 404.html
+- <other public assets>
To map all 5xx
errors by using a Mustache template, your directory structure would be as follows:
src/
+- main/
+- java/
| + <source code>
+- resources/
+- templates/
+- error/
| +- 5xx.mustache
+- <other templates>
Web Filters
Spring WebFlux provides a WebFilter
interface that can be implemented to filter HTTP request-response exchanges.
WebFilter
beans found in the application context will be automatically used to filter each exchange.
Where the order of the filters is important they can implement Ordered
or be annotated with @Order
.
Spring Boot auto-configuration may configure web filters for you.
When it does so, the orders shown in the following table will be used:
Web Filter | Order |
---|---|
|
|
|
|
|
|
8.2.2. Embedded Reactive Server Support
Spring Boot includes support for the following embedded reactive web servers: Reactor Netty, Tomcat, Jetty, and Undertow. Most developers use the appropriate “Starter” to obtain a fully configured instance. By default, the embedded server listens for HTTP requests on port 8080.
Customizing Reactive Servers
Common reactive web server settings can be configured by using Spring Environment
properties.
Usually, you would define the properties in your application.properties
or application.yaml
file.
Common server settings include:
-
Network settings: Listen port for incoming HTTP requests (
server.port
), interface address to bind toserver.address
, and so on. -
Error management: Location of the error page (
server.error.path
) and so on.
Spring Boot tries as much as possible to expose common settings, but this is not always possible.
For those cases, dedicated namespaces such as server.netty.*
offer server-specific customizations.
See the ServerProperties class for a complete list.
|
Programmatic Customization
If you need to programmatically configure your reactive web server, you can register a Spring bean that implements the WebServerFactoryCustomizer
interface.
WebServerFactoryCustomizer
provides access to the ConfigurableReactiveWebServerFactory
, which includes numerous customization setter methods.
The following example shows programmatically setting the port:
@Component
public class MyWebServerFactoryCustomizer implements WebServerFactoryCustomizer<ConfigurableReactiveWebServerFactory> {
@Override
public void customize(ConfigurableReactiveWebServerFactory server) {
server.setPort(9000);
}
}
@Component
class MyWebServerFactoryCustomizer : WebServerFactoryCustomizer<ConfigurableReactiveWebServerFactory> {
override fun customize(server: ConfigurableReactiveWebServerFactory) {
server.setPort(9000)
}
}
JettyReactiveWebServerFactory
, NettyReactiveWebServerFactory
, TomcatReactiveWebServerFactory
, and UndertowServletWebServerFactory
are dedicated variants of ConfigurableReactiveWebServerFactory
that have additional customization setter methods for Jetty, Reactor Netty, Tomcat, and Undertow respectively.
The following example shows how to customize NettyReactiveWebServerFactory
that provides access to Reactor Netty-specific configuration options:
@Component
public class MyNettyWebServerFactoryCustomizer implements WebServerFactoryCustomizer<NettyReactiveWebServerFactory> {
@Override
public void customize(NettyReactiveWebServerFactory factory) {
factory.addServerCustomizers((server) -> server.idleTimeout(Duration.ofSeconds(20)));
}
}
@Component
class MyNettyWebServerFactoryCustomizer : WebServerFactoryCustomizer<NettyReactiveWebServerFactory> {
override fun customize(factory: NettyReactiveWebServerFactory) {
factory.addServerCustomizers({ server -> server.idleTimeout(Duration.ofSeconds(20)) })
}
}
Customizing ConfigurableReactiveWebServerFactory Directly
For more advanced use cases that require you to extend from ReactiveWebServerFactory
, you can expose a bean of such type yourself.
Setters are provided for many configuration options. Several protected method “hooks” are also provided should you need to do something more exotic. See the source code documentation for details.
Auto-configured customizers are still applied on your custom factory, so use that option carefully. |
8.2.3. Reactive Server Resources Configuration
When auto-configuring a Reactor Netty or Jetty server, Spring Boot will create specific beans that will provide HTTP resources to the server instance: ReactorResourceFactory
or JettyResourceFactory
.
By default, those resources will be also shared with the Reactor Netty and Jetty clients for optimal performances, given:
-
the same technology is used for server and client
-
the client instance is built using the
WebClient.Builder
bean auto-configured by Spring Boot
Developers can override the resource configuration for Jetty and Reactor Netty by providing a custom ReactorResourceFactory
or JettyResourceFactory
bean - this will be applied to both clients and servers.
You can learn more about the resource configuration on the client side in the WebClient Runtime section.
8.3. Graceful Shutdown
Graceful shutdown is supported with all four embedded web servers (Jetty, Reactor Netty, Tomcat, and Undertow) and with both reactive and servlet-based web applications.
It occurs as part of closing the application context and is performed in the earliest phase of stopping SmartLifecycle
beans.
This stop processing uses a timeout which provides a grace period during which existing requests will be allowed to complete but no new requests will be permitted.
The exact way in which new requests are not permitted varies depending on the web server that is being used.
Jetty, Reactor Netty, and Tomcat will stop accepting requests at the network layer.
Undertow will accept requests but respond immediately with a service unavailable (503) response.
Graceful shutdown with Tomcat requires Tomcat 9.0.33 or later. |
To enable graceful shutdown, configure the server.shutdown
property, as shown in the following example:
server.shutdown=graceful
server:
shutdown: "graceful"
To configure the timeout period, configure the spring.lifecycle.timeout-per-shutdown-phase
property, as shown in the following example:
spring.lifecycle.timeout-per-shutdown-phase=20s
spring:
lifecycle:
timeout-per-shutdown-phase: "20s"
Using graceful shutdown with your IDE may not work properly if it does not send a proper SIGTERM signal.
See the documentation of your IDE for more details.
|
8.4. Spring Security
If Spring Security is on the classpath, then web applications are secured by default.
Spring Boot relies on Spring Security’s content-negotiation strategy to determine whether to use httpBasic
or formLogin
.
To add method-level security to a web application, you can also add @EnableGlobalMethodSecurity
with your desired settings.
Additional information can be found in the Spring Security Reference Guide.
The default UserDetailsService
has a single user.
The user name is user
, and the password is random and is printed at WARN level when the application starts, as shown in the following example:
Using generated security password: 78fa095d-3f4c-48b1-ad50-e24c31d5cf35 This generated password is for development use only. Your security configuration must be updated before running your application in production.
If you fine-tune your logging configuration, ensure that the org.springframework.boot.autoconfigure.security category is set to log WARN -level messages.
Otherwise, the default password is not printed.
|
You can change the username and password by providing a spring.security.user.name
and spring.security.user.password
.
The basic features you get by default in a web application are:
-
A
UserDetailsService
(orReactiveUserDetailsService
in case of a WebFlux application) bean with in-memory store and a single user with a generated password (seeSecurityProperties.User
for the properties of the user). -
Form-based login or HTTP Basic security (depending on the
Accept
header in the request) for the entire application (including actuator endpoints if actuator is on the classpath). -
A
DefaultAuthenticationEventPublisher
for publishing authentication events.
You can provide a different AuthenticationEventPublisher
by adding a bean for it.
8.4.1. MVC Security
The default security configuration is implemented in SecurityAutoConfiguration
and UserDetailsServiceAutoConfiguration
.
SecurityAutoConfiguration
imports SpringBootWebSecurityConfiguration
for web security and UserDetailsServiceAutoConfiguration
configures authentication, which is also relevant in non-web applications.
To switch off the default web application security configuration completely or to combine multiple Spring Security components such as OAuth2 Client and Resource Server, add a bean of type SecurityFilterChain
(doing so does not disable the UserDetailsService
configuration or Actuator’s security).
To also switch off the UserDetailsService
configuration, you can add a bean of type UserDetailsService
, AuthenticationProvider
, or AuthenticationManager
.
Access rules can be overridden by adding a custom SecurityFilterChain
or WebSecurityConfigurerAdapter
bean.
Spring Boot provides convenience methods that can be used to override access rules for actuator endpoints and static resources.
EndpointRequest
can be used to create a RequestMatcher
that is based on the management.endpoints.web.base-path
property.
PathRequest
can be used to create a RequestMatcher
for resources in commonly used locations.
8.4.2. WebFlux Security
Similar to Spring MVC applications, you can secure your WebFlux applications by adding the spring-boot-starter-security
dependency.
The default security configuration is implemented in ReactiveSecurityAutoConfiguration
and UserDetailsServiceAutoConfiguration
.
ReactiveSecurityAutoConfiguration
imports WebFluxSecurityConfiguration
for web security and UserDetailsServiceAutoConfiguration
configures authentication, which is also relevant in non-web applications.
To switch off the default web application security configuration completely, you can add a bean of type WebFilterChainProxy
(doing so does not disable the UserDetailsService
configuration or Actuator’s security).
To also switch off the UserDetailsService
configuration, you can add a bean of type ReactiveUserDetailsService
or ReactiveAuthenticationManager
.
Access rules and the use of multiple Spring Security components such as OAuth 2 Client and Resource Server can be configured by adding a custom SecurityWebFilterChain
bean.
Spring Boot provides convenience methods that can be used to override access rules for actuator endpoints and static resources.
EndpointRequest
can be used to create a ServerWebExchangeMatcher
that is based on the management.endpoints.web.base-path
property.
PathRequest
can be used to create a ServerWebExchangeMatcher
for resources in commonly used locations.
For example, you can customize your security configuration by adding something like:
@Configuration(proxyBeanMethods = false)
public class MyWebFluxSecurityConfiguration {
@Bean
public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
http.authorizeExchange((exchange) -> {
exchange.matchers(PathRequest.toStaticResources().atCommonLocations()).permitAll();
exchange.pathMatchers("/foo", "/bar").authenticated();
});
http.formLogin(withDefaults());
return http.build();
}
}
@Configuration(proxyBeanMethods = false)
class MyWebFluxSecurityConfiguration {
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
http.authorizeExchange { spec ->
spec.matchers(PathRequest.toStaticResources().atCommonLocations()).permitAll()
spec.pathMatchers("/foo", "/bar").authenticated()
}
http.formLogin()
return http.build()
}
}
8.4.3. OAuth2
OAuth2 is a widely used authorization framework that is supported by Spring.
Client
If you have spring-security-oauth2-client
on your classpath, you can take advantage of some auto-configuration to set up OAuth2/Open ID Connect clients.
This configuration makes use of the properties under OAuth2ClientProperties
.
The same properties are applicable to both servlet and reactive applications.
You can register multiple OAuth2 clients and providers under the spring.security.oauth2.client
prefix, as shown in the following example:
spring.security.oauth2.client.registration.my-client-1.client-id=abcd
spring.security.oauth2.client.registration.my-client-1.client-secret=password
spring.security.oauth2.client.registration.my-client-1.client-name=Client for user scope
spring.security.oauth2.client.registration.my-client-1.provider=my-oauth-provider
spring.security.oauth2.client.registration.my-client-1.scope=user
spring.security.oauth2.client.registration.my-client-1.redirect-uri=https://my-redirect-uri.com
spring.security.oauth2.client.registration.my-client-1.client-authentication-method=basic
spring.security.oauth2.client.registration.my-client-1.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.my-client-2.client-id=abcd
spring.security.oauth2.client.registration.my-client-2.client-secret=password
spring.security.oauth2.client.registration.my-client-2.client-name=Client for email scope
spring.security.oauth2.client.registration.my-client-2.provider=my-oauth-provider
spring.security.oauth2.client.registration.my-client-2.scope=email
spring.security.oauth2.client.registration.my-client-2.redirect-uri=https://my-redirect-uri.com
spring.security.oauth2.client.registration.my-client-2.client-authentication-method=basic
spring.security.oauth2.client.registration.my-client-2.authorization-grant-type=authorization_code
spring.security.oauth2.client.provider.my-oauth-provider.authorization-uri=https://my-auth-server/oauth/authorize
spring.security.oauth2.client.provider.my-oauth-provider.token-uri=https://my-auth-server/oauth/token
spring.security.oauth2.client.provider.my-oauth-provider.user-info-uri=https://my-auth-server/userinfo
spring.security.oauth2.client.provider.my-oauth-provider.user-info-authentication-method=header
spring.security.oauth2.client.provider.my-oauth-provider.jwk-set-uri=https://my-auth-server/token_keys
spring.security.oauth2.client.provider.my-oauth-provider.user-name-attribute=name
spring:
security:
oauth2:
client:
registration:
my-client-1:
client-id: "abcd"
client-secret: "password"
client-name: "Client for user scope"
provider: "my-oauth-provider"
scope: "user"
redirect-uri: "https://my-redirect-uri.com"
client-authentication-method: "basic"
authorization-grant-type: "authorization_code"
my-client-2:
client-id: "abcd"
client-secret: "password"
client-name: "Client for email scope"
provider: "my-oauth-provider"
scope: "email"
redirect-uri: "https://my-redirect-uri.com"
client-authentication-method: "basic"
authorization-grant-type: "authorization_code"
provider:
my-oauth-provider:
authorization-uri: "https://my-auth-server/oauth/authorize"
token-uri: "https://my-auth-server/oauth/token"
user-info-uri: "https://my-auth-server/userinfo"
user-info-authentication-method: "header"
jwk-set-uri: "https://my-auth-server/token_keys"
user-name-attribute: "name"
For OpenID Connect providers that support OpenID Connect discovery, the configuration can be further simplified.
The provider needs to be configured with an issuer-uri
which is the URI that it asserts as its Issuer Identifier.
For example, if the issuer-uri
provided is "https://example.com", then an OpenID Provider Configuration Request
will be made to "https://example.com/.well-known/openid-configuration".
The result is expected to be an OpenID Provider Configuration Response
.
The following example shows how an OpenID Connect Provider can be configured with the issuer-uri
:
spring.security.oauth2.client.provider.oidc-provider.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/
spring:
security:
oauth2:
client:
provider:
oidc-provider:
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
By default, Spring Security’s OAuth2LoginAuthenticationFilter
only processes URLs matching /login/oauth2/code/*
.
If you want to customize the redirect-uri
to use a different pattern, you need to provide configuration to process that custom pattern.
For example, for servlet applications, you can add your own SecurityFilterChain
that resembles the following:
@Configuration(proxyBeanMethods = false)
public class MyOAuthClientConfiguration {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http.authorizeRequests((requests) -> requests.anyRequest().authenticated());
http.oauth2Login((login) -> login.redirectionEndpoint().baseUri("custom-callback"));
return http.build();
}
}
@Configuration(proxyBeanMethods = false)
class MyOAuthClientConfiguration {
@Bean
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
http.authorizeRequests().anyRequest().authenticated()
http.oauth2Login().redirectionEndpoint().baseUri("custom-callback")
return http.build()
}
}
Spring Boot auto-configures an InMemoryOAuth2AuthorizedClientService which is used by Spring Security for the management of client registrations.
The InMemoryOAuth2AuthorizedClientService has limited capabilities and we recommend using it only for development environments.
For production environments, consider using a JdbcOAuth2AuthorizedClientService or creating your own implementation of OAuth2AuthorizedClientService .
|
OAuth2 Client Registration for Common Providers
For common OAuth2 and OpenID providers, including Google, Github, Facebook, and Okta, we provide a set of provider defaults (google
, github
, facebook
, and okta
, respectively).
If you do not need to customize these providers, you can set the provider
attribute to the one for which you need to infer defaults.
Also, if the key for the client registration matches a default supported provider, Spring Boot infers that as well.
In other words, the two configurations in the following example use the Google provider:
spring.security.oauth2.client.registration.my-client.client-id=abcd
spring.security.oauth2.client.registration.my-client.client-secret=password
spring.security.oauth2.client.registration.my-client.provider=google
spring.security.oauth2.client.registration.google.client-id=abcd
spring.security.oauth2.client.registration.google.client-secret=password
spring:
security:
oauth2:
client:
registration:
my-client:
client-id: "abcd"
client-secret: "password"
provider: "google"
google:
client-id: "abcd"
client-secret: "password"
Resource Server
If you have spring-security-oauth2-resource-server
on your classpath, Spring Boot can set up an OAuth2 Resource Server.
For JWT configuration, a JWK Set URI or OIDC Issuer URI needs to be specified, as shown in the following examples:
spring.security.oauth2.resourceserver.jwt.jwk-set-uri=https://example.com/oauth2/default/v1/keys
spring:
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: "https://example.com/oauth2/default/v1/keys"
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
If the authorization server does not support a JWK Set URI, you can configure the resource server with the Public Key used for verifying the signature of the JWT.
This can be done using the spring.security.oauth2.resourceserver.jwt.public-key-location property, where the value needs to point to a file containing the public key in the PEM-encoded x509 format.
|
The spring.security.oauth2.resourceserver.jwt.audiences
property can be used to specifify the expected values of the aud claim in JWTs.
For example, to require JWTs to contain an aud claim with the value my-audience
:
spring.security.oauth2.resourceserver.jwt.audiences[0]=my-audience
spring:
security:
oauth2:
resourceserver:
jwt:
audiences:
- "my-audience"
The same properties are applicable for both servlet and reactive applications.
Alternatively, you can define your own JwtDecoder
bean for servlet applications or a ReactiveJwtDecoder
for reactive applications.
In cases where opaque tokens are used instead of JWTs, you can configure the following properties to validate tokens through introspection:
spring.security.oauth2.resourceserver.opaquetoken.introspection-uri=https://example.com/check-token
spring.security.oauth2.resourceserver.opaquetoken.client-id=my-client-id
spring.security.oauth2.resourceserver.opaquetoken.client-secret=my-client-secret
spring:
security:
oauth2:
resourceserver:
opaquetoken:
introspection-uri: "https://example.com/check-token"
client-id: "my-client-id"
client-secret: "my-client-secret"
Again, the same properties are applicable for both servlet and reactive applications.
Alternatively, you can define your own OpaqueTokenIntrospector
bean for servlet applications or a ReactiveOpaqueTokenIntrospector
for reactive applications.
Authorization Server
Currently, Spring Security does not provide support for implementing an OAuth 2.0 Authorization Server.
However, this functionality is available from the Spring Security OAuth project, which will eventually be superseded by Spring Security completely.
Until then, you can use the spring-security-oauth2-autoconfigure
module to easily set up an OAuth 2.0 authorization server; see its documentation for instructions.
8.4.4. SAML 2.0
Relying Party
If you have spring-security-saml2-service-provider
on your classpath, you can take advantage of some auto-configuration to set up a SAML 2.0 Relying Party.
This configuration makes use of the properties under Saml2RelyingPartyProperties
.
A relying party registration represents a paired configuration between an Identity Provider, IDP, and a Service Provider, SP.
You can register multiple relying parties under the spring.security.saml2.relyingparty
prefix, as shown in the following example:
spring.security.saml2.relyingparty.registration.my-relying-party1.signing.credentials[0].private-key-location=path-to-private-key
spring.security.saml2.relyingparty.registration.my-relying-party1.signing.credentials[0].certificate-location=path-to-certificate
spring.security.saml2.relyingparty.registration.my-relying-party1.decryption.credentials[0].private-key-location=path-to-private-key
spring.security.saml2.relyingparty.registration.my-relying-party1.decryption.credentials[0].certificate-location=path-to-certificate
spring.security.saml2.relyingparty.registration.my-relying-party1.singlelogout.url=https://myapp/logout/saml2/slo
spring.security.saml2.relyingparty.registration.my-relying-party1.singlelogout.response-url=https://remoteidp2.slo.url
spring.security.saml2.relyingparty.registration.my-relying-party1.singlelogout.binding=POST
spring.security.saml2.relyingparty.registration.my-relying-party1.assertingparty.verification.credentials[0].certificate-location=path-to-verification-cert
spring.security.saml2.relyingparty.registration.my-relying-party1.assertingparty.entity-id=remote-idp-entity-id1
spring.security.saml2.relyingparty.registration.my-relying-party1.assertingparty.sso-url=https://remoteidp1.sso.url
spring.security.saml2.relyingparty.registration.my-relying-party2.signing.credentials[0].private-key-location=path-to-private-key
spring.security.saml2.relyingparty.registration.my-relying-party2.signing.credentials[0].certificate-location=path-to-certificate
spring.security.saml2.relyingparty.registration.my-relying-party2.decryption.credentials[0].private-key-location=path-to-private-key
spring.security.saml2.relyingparty.registration.my-relying-party2.decryption.credentials[0].certificate-location=path-to-certificate
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.verification.credentials[0].certificate-location=path-to-other-verification-cert
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.entity-id=remote-idp-entity-id2
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.sso-url=https://remoteidp2.sso.url
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.singlelogout.url=https://remoteidp2.slo.url
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.singlelogout.reponse-url=https://myapp/logout/saml2/slo
spring.security.saml2.relyingparty.registration.my-relying-party2.assertingparty.singlelogout.binding=POST
spring:
security:
saml2:
relyingparty:
registration:
my-relying-party1:
signing:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
decryption:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
singlelogout:
url: "https://myapp/logout/saml2/slo"
response-url: "https://remoteidp2.slo.url"
binding: "POST"
assertingparty:
verification:
credentials:
- certificate-location: "path-to-verification-cert"
entity-id: "remote-idp-entity-id1"
sso-url: "https://remoteidp1.sso.url"
my-relying-party2:
signing:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
decryption:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
assertingparty:
verification:
credentials:
- certificate-location: "path-to-other-verification-cert"
entity-id: "remote-idp-entity-id2"
sso-url: "https://remoteidp2.sso.url"
singlelogout:
url: "https://remoteidp2.slo.url"
reponse-url: "https://myapp/logout/saml2/slo"
binding: "POST"
For SAML2 logout, by default, Spring Security’s Saml2LogoutRequestFilter
and Saml2LogoutResponseFilter
only process URLs matching /logout/saml2/slo
.
If you want to customize the url
to which AP-initiated logout requests get sent to or the response-url
to which an AP sends logout responses to, to use a different pattern, you need to provide configuration to process that custom pattern.
For example, for servlet applications, you can add your own SecurityFilterChain
that resembles the following:
@Configuration(proxyBeanMethods = false)
public class MySamlRelyingPartyConfiguration {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http.authorizeRequests().anyRequest().authenticated();
http.saml2Login();
http.saml2Logout((saml2) -> saml2.logoutRequest((request) -> request.logoutUrl("/SLOService.saml2"))
.logoutResponse((response) -> response.logoutUrl("/SLOService.saml2")));
return http.build();
}
}
8.5. Spring Session
Spring Boot provides Spring Session auto-configuration for a wide range of data stores. When building a servlet web application, the following stores can be auto-configured:
-
JDBC
-
Redis
-
Hazelcast
-
MongoDB
Additionally, Spring Boot for Apache Geode provides auto-configuration for using Apache Geode as a session store.
The servlet auto-configuration replaces the need to use @Enable*HttpSession
.
When building a reactive web application, the following stores can be auto-configured:
-
Redis
-
MongoDB
The reactive auto-configuration replaces the need to use @Enable*WebSession
.
If a single Spring Session module is present on the classpath, Spring Boot uses that store implementation automatically.
If you have more than one implementation, you must choose the StoreType
that you wish to use to store the sessions.
For instance, to use JDBC as the back-end store, you can configure your application as follows:
spring.session.store-type=jdbc
spring:
session:
store-type: "jdbc"
You can disable Spring Session by setting the store-type to none .
|
Each store has specific additional settings. For instance, it is possible to customize the name of the table for the JDBC store, as shown in the following example:
spring.session.jdbc.table-name=SESSIONS
spring:
session:
jdbc:
table-name: "SESSIONS"
For setting the timeout of the session you can use the spring.session.timeout
property.
If that property is not set with a servlet web application, the auto-configuration falls back to the value of server.servlet.session.timeout
.
You can take control over Spring Session’s configuration using @Enable*HttpSession
(servlet) or @Enable*WebSession
(reactive).
This will cause the auto-configuration to back off.
Spring Session can then be configured using the annotation’s attributes rather than the previously described configuration properties.
8.6. Spring for GraphQL
If you want to build GraphQL applications, you can take advantage of Spring Boot’s auto-configuration for Spring for GraphQL.
The Spring for GraphQL project is based on GraphQL Java.
You’ll need the spring-boot-starter-graphql
starter at a minimum.
Because GraphQL is transport-agnostic, you’ll also need to have one or more additional starters in your application to expose your GraphQL API over the web:
Starter | Transport | Implementation |
---|---|---|
|
HTTP |
Spring MVC |
|
WebSocket |
WebSocket for Servlet apps |
|
HTTP, WebSocket |
Spring WebFlux |
|
TCP, WebSocket |
Spring WebFlux on Reactor Netty |
8.6.1. GraphQL Schema
A Spring GraphQL application requires a defined schema at startup.
By default, you can write ".graphqls" or ".gqls" schema files under src/main/resources/graphql/**
and Spring Boot will pick them up automatically.
You can customize the locations with spring.graphql.schema.locations
and the file extensions with spring.graphql.schema.file-extensions
.
If you want Spring Boot to detect schema files in all your application modules and dependencies for that location,
you can set spring.graphql.schema.locations to "classpath*:graphql/**/" (note the classpath*: prefix).
|
In the following sections, we’ll consider this sample GraphQL schema, defining two types and two queries:
type Query {
greeting(name: String! = "Spring"): String!
project(slug: ID!): Project
}
""" A Project in the Spring portfolio """
type Project {
""" Unique string id used in URLs """
slug: ID!
""" Project name """
name: String!
""" URL of the git repository """
repositoryUrl: String!
""" Current support status """
status: ProjectStatus!
}
enum ProjectStatus {
""" Actively supported by the Spring team """
ACTIVE
""" Supported by the community """
COMMUNITY
""" Prototype, not officially supported yet """
INCUBATING
""" Project being retired, in maintenance mode """
ATTIC
""" End-Of-Lifed """
EOL
}
By default, field introspection will be allowed on the schema as it is required for tools such as GraphiQL.
If you wish to not expose information about the schema, you can disable introspection by setting spring.graphql.schema.introspection.enabled to false .
|
8.6.2. GraphQL RuntimeWiring
The GraphQL Java RuntimeWiring.Builder
can be used to register custom scalar types, directives, type resolvers, DataFetcher
s, and more.
You can declare RuntimeWiringConfigurer
beans in your Spring config to get access to the RuntimeWiring.Builder
.
Spring Boot detects such beans and adds them to the GraphQlSource builder.
Typically, however, applications will not implement DataFetcher
directly and will instead create annotated controllers.
Spring Boot will automatically detect @Controller
classes with annotated handler methods and register those as DataFetcher
s.
Here’s a sample implementation for our greeting query with a @Controller
class:
@Controller
public class GreetingController {
@QueryMapping
public String greeting(@Argument String name) {
return "Hello, " + name + "!";
}
}
;
@Controller
class GreetingController {
@QueryMapping
fun greeting(@Argument name: String): String {
return "Hello, $name!"
}
}
8.6.3. Querydsl and QueryByExample Repositories Support
Spring Data offers support for both Querydsl and QueryByExample repositories.
Spring GraphQL can configure Querydsl and QueryByExample repositories as DataFetcher
.
Spring Data repositories annotated with @GraphQlRepository
and extending one of:
-
QuerydslPredicateExecutor
-
ReactiveQuerydslPredicateExecutor
-
QueryByExampleExecutor
-
ReactiveQueryByExampleExecutor
are detected by Spring Boot and considered as candidates for DataFetcher
for matching top-level queries.
8.6.4. Transports
HTTP and WebSocket
The GraphQL HTTP endpoint is at HTTP POST /graphql
by default.
The path can be customized with spring.graphql.path
.
The HTTP endpoint for both Spring MVC and Spring WebFlux is provided by a RouterFunction bean with an @Order of 0 .
If you define your own RouterFunction beans, you may want to add appropriate @Order annotations to ensure that they are sorted correctly.
|
The GraphQL WebSocket endpoint is off by default. To enable it:
-
For a Servlet application, add the WebSocket starter
spring-boot-starter-websocket
-
For a WebFlux application, no additional dependency is required
-
For both, the
spring.graphql.websocket.path
application property must be set
Spring GraphQL provides a Web Interception model.
This is quite useful for retrieving information from an HTTP request header and set it in the GraphQL context or fetching information from the same context and writing it to a response header.
With Spring Boot, you can declare a WebInterceptor
bean to have it registered with the web transport.
Spring MVC and Spring WebFlux support CORS (Cross-Origin Resource Sharing) requests. CORS is a critical part of the web config for GraphQL applications that are accessed from browsers using different domains.
Spring Boot supports many configuration properties under the spring.graphql.cors.*
namespace; here’s a short configuration sample:
spring.graphql.cors.allowed-origins=https://example.org
spring.graphql.cors.allowed-methods=GET,POST
spring.graphql.cors.max-age=1800s
spring:
graphql:
cors:
allowed-origins: "https://example.org"
allowed-methods: GET,POST
max-age: 1800s
RSocket
RSocket is also supported as a transport, on top of WebSocket or TCP.
Once the RSocket server is configured, we can configure our GraphQL handler on a particular route using spring.graphql.rsocket.mapping
.
For example, configuring that mapping as "graphql"
means we can use that as a route when sending requests with the RSocketGraphQlClient
.
Spring Boot auto-configures a RSocketGraphQlClient.Builder<?>
bean that you can inject in your components:
@Component
public class RSocketGraphQlClientExample {
private final RSocketGraphQlClient graphQlClient;
public RSocketGraphQlClientExample(RSocketGraphQlClient.Builder<?> builder) {
this.graphQlClient = builder.tcp("example.spring.io", 8181).route("graphql").build();
}
@Component
class RSocketGraphQlClientExample(private val builder: RSocketGraphQlClient.Builder<*>) {
And then send a request:
Mono<Book> book = this.graphQlClient.document("{ bookById(id: \"book-1\"){ id name pageCount author } }")
.retrieve("bookById")
.toEntity(Book.class);
val book = graphQlClient.document(
"""
{
bookById(id: "book-1"){
id
name
pageCount
author
}
}
"""
)
.retrieve("bookById").toEntity(Book::class.java)
8.6.5. Exception Handling
Spring GraphQL enables applications to register one or more Spring DataFetcherExceptionResolver
components that are invoked sequentially.
The Exception must be resolved to a list of graphql.GraphQLError
objects, see Spring GraphQL exception handling documentation.
Spring Boot will automatically detect DataFetcherExceptionResolver
beans and register them with the GraphQlSource.Builder
.
8.6.6. GraphiQL and Schema printer
Spring GraphQL offers infrastructure for helping developers when consuming or developing a GraphQL API.
Spring GraphQL ships with a default GraphiQL page that is exposed at "/graphiql"
by default.
This page is disabled by default and can be turned on with the spring.graphql.graphiql.enabled
property.
Many applications exposing such a page will prefer a custom build.
A default implementation is very useful during development, this is why it is exposed automatically with spring-boot-devtools
during development.
You can also choose to expose the GraphQL schema in text format at /graphql/schema
when the spring.graphql.schema.printer.enabled
property is enabled.
8.7. Spring HATEOAS
If you develop a RESTful API that makes use of hypermedia, Spring Boot provides auto-configuration for Spring HATEOAS that works well with most applications.
The auto-configuration replaces the need to use @EnableHypermediaSupport
and registers a number of beans to ease building hypermedia-based applications, including a LinkDiscoverers
(for client side support) and an ObjectMapper
configured to correctly marshal responses into the desired representation.
The ObjectMapper
is customized by setting the various spring.jackson.*
properties or, if one exists, by a Jackson2ObjectMapperBuilder
bean.
You can take control of Spring HATEOAS’s configuration by using @EnableHypermediaSupport
.
Note that doing so disables the ObjectMapper
customization described earlier.
spring-boot-starter-hateoas is specific to Spring MVC and should not be combined with Spring WebFlux.
In order to use Spring HATEOAS with Spring WebFlux, you can add a direct dependency on org.springframework.hateoas:spring-hateoas along with spring-boot-starter-webflux .
|
By default, requests that accept application/json
will receive an application/hal+json
response.
To disable this behavior set spring.hateoas.use-hal-as-default-json-media-type
to false
and define a HypermediaMappingInformation
or HalConfiguration
to configure Spring HATEOAS to meet the needs of your application and its clients.
8.8. What to Read Next
You should now have a good understanding of how to develop web applications with Spring Boot. The next few sections describe how Spring Boot integrates with various data technologies, messaging systems, and other IO capabilities. You can pick any of these based on your application’s needs.
9. Data
Spring Boot integrates with a number of data technologies, both SQL and NoSQL.
9.1. SQL Databases
The Spring Framework provides extensive support for working with SQL databases, from direct JDBC access using JdbcTemplate
to complete “object relational mapping” technologies such as Hibernate.
Spring Data provides an additional level of functionality: creating Repository
implementations directly from interfaces and using conventions to generate queries from your method names.
9.1.1. Configure a DataSource
Java’s javax.sql.DataSource
interface provides a standard method of working with database connections.
Traditionally, a 'DataSource' uses a URL
along with some credentials to establish a database connection.
See the “How-to” section for more advanced examples, typically to take full control over the configuration of the DataSource. |
Embedded Database Support
It is often convenient to develop applications by using an in-memory embedded database. Obviously, in-memory databases do not provide persistent storage. You need to populate your database when your application starts and be prepared to throw away data when your application ends.
The “How-to” section includes a section on how to initialize a database. |
Spring Boot can auto-configure embedded H2, HSQL, and Derby databases.
You need not provide any connection URLs.
You need only include a build dependency to the embedded database that you want to use.
If there are multiple embedded databases on the classpath, set the spring.datasource.embedded-database-connection
configuration property to control which one is used.
Setting the property to none
disables auto-configuration of an embedded database.
If you are using this feature in your tests, you may notice that the same database is reused by your whole test suite regardless of the number of application contexts that you use.
If you want to make sure that each context has a separate embedded database, you should set |
For example, the typical POM dependencies would be as follows:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.hsqldb</groupId>
<artifactId>hsqldb</artifactId>
<scope>runtime</scope>
</dependency>
You need a dependency on spring-jdbc for an embedded database to be auto-configured.
In this example, it is pulled in transitively through spring-boot-starter-data-jpa .
|
If, for whatever reason, you do configure the connection URL for an embedded database, take care to ensure that the database’s automatic shutdown is disabled.
If you use H2, you should use DB_CLOSE_ON_EXIT=FALSE to do so.
If you use HSQLDB, you should ensure that shutdown=true is not used.
Disabling the database’s automatic shutdown lets Spring Boot control when the database is closed, thereby ensuring that it happens once access to the database is no longer needed.
|
Connection to a Production Database
Production database connections can also be auto-configured by using a pooling DataSource
.
DataSource Configuration
DataSource configuration is controlled by external configuration properties in spring.datasource.*
.
For example, you might declare the following section in application.properties
:
spring.datasource.url=jdbc:mysql://localhost/test
spring.datasource.username=dbuser
spring.datasource.password=dbpass
spring:
datasource:
url: "jdbc:mysql://localhost/test"
username: "dbuser"
password: "dbpass"
You should at least specify the URL by setting the spring.datasource.url property.
Otherwise, Spring Boot tries to auto-configure an embedded database.
|
Spring Boot can deduce the JDBC driver class for most databases from the URL.
If you need to specify a specific class, you can use the spring.datasource.driver-class-name property.
|
For a pooling DataSource to be created, we need to be able to verify that a valid Driver class is available, so we check for that before doing anything.
In other words, if you set spring.datasource.driver-class-name=com.mysql.jdbc.Driver , then that class has to be loadable.
|
See DataSourceProperties
for more of the supported options.
These are the standard options that work regardless of the actual implementation.
It is also possible to fine-tune implementation-specific settings by using their respective prefix (spring.datasource.hikari.*
, spring.datasource.tomcat.*
, spring.datasource.dbcp2.*
, and spring.datasource.oracleucp.*
).
See the documentation of the connection pool implementation you are using for more details.
For instance, if you use the Tomcat connection pool, you could customize many additional settings, as shown in the following example:
spring.datasource.tomcat.max-wait=10000
spring.datasource.tomcat.max-active=50
spring.datasource.tomcat.test-on-borrow=true
spring:
datasource:
tomcat:
max-wait: 10000
max-active: 50
test-on-borrow: true
This will set the pool to wait 10000ms before throwing an exception if no connection is available, limit the maximum number of connections to 50 and validate the connection before borrowing it from the pool.
Supported Connection Pools
Spring Boot uses the following algorithm for choosing a specific implementation:
-
We prefer HikariCP for its performance and concurrency. If HikariCP is available, we always choose it.
-
Otherwise, if the Tomcat pooling
DataSource
is available, we use it. -
Otherwise, if Commons DBCP2 is available, we use it.
-
If none of HikariCP, Tomcat, and DBCP2 are available and if Oracle UCP is available, we use it.
If you use the spring-boot-starter-jdbc or spring-boot-starter-data-jpa “starters”, you automatically get a dependency to HikariCP .
|
You can bypass that algorithm completely and specify the connection pool to use by setting the spring.datasource.type
property.
This is especially important if you run your application in a Tomcat container, as tomcat-jdbc
is provided by default.
Additional connection pools can always be configured manually, using DataSourceBuilder
.
If you define your own DataSource
bean, auto-configuration does not occur.
The following connection pools are supported by DataSourceBuilder
:
-
HikariCP
-
Tomcat pooling
Datasource
-
Commons DBCP2
-
Oracle UCP &
OracleDataSource
-
Spring Framework’s
SimpleDriverDataSource
-
H2
JdbcDataSource
-
PostgreSQL
PGSimpleDataSource
-
C3P0
Connection to a JNDI DataSource
If you deploy your Spring Boot application to an Application Server, you might want to configure and manage your DataSource by using your Application Server’s built-in features and access it by using JNDI.
The spring.datasource.jndi-name
property can be used as an alternative to the spring.datasource.url
, spring.datasource.username
, and spring.datasource.password
properties to access the DataSource
from a specific JNDI location.
For example, the following section in application.properties
shows how you can access a JBoss AS defined DataSource
:
spring.datasource.jndi-name=java:jboss/datasources/customers
spring:
datasource:
jndi-name: "java:jboss/datasources/customers"
9.1.2. Using JdbcTemplate
Spring’s JdbcTemplate
and NamedParameterJdbcTemplate
classes are auto-configured, and you can @Autowire
them directly into your own beans, as shown in the following example:
@Component
public class MyBean {
private final JdbcTemplate jdbcTemplate;
public MyBean(JdbcTemplate jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
public void doSomething() {
this.jdbcTemplate ...
}
}
@Component
class MyBean(private val jdbcTemplate: JdbcTemplate) {
fun doSomething() {
jdbcTemplate.execute("delete from customer")
}
}
You can customize some properties of the template by using the spring.jdbc.template.*
properties, as shown in the following example:
spring.jdbc.template.max-rows=500
spring:
jdbc:
template:
max-rows: 500
The NamedParameterJdbcTemplate reuses the same JdbcTemplate instance behind the scenes.
If more than one JdbcTemplate is defined and no primary candidate exists, the NamedParameterJdbcTemplate is not auto-configured.
|
9.1.3. JPA and Spring Data JPA
The Java Persistence API is a standard technology that lets you “map” objects to relational databases.
The spring-boot-starter-data-jpa
POM provides a quick way to get started.
It provides the following key dependencies:
-
Hibernate: One of the most popular JPA implementations.
-
Spring Data JPA: Helps you to implement JPA-based repositories.
-
Spring ORM: Core ORM support from the Spring Framework.
We do not go into too many details of JPA or Spring Data here. You can follow the “Accessing Data with JPA” guide from spring.io and read the Spring Data JPA and Hibernate reference documentation. |
Entity Classes
Traditionally, JPA “Entity” classes are specified in a persistence.xml
file.
With Spring Boot, this file is not necessary and “Entity Scanning” is used instead.
By default the auto-configuration packages are scanned.
Any classes annotated with @Entity
, @Embeddable
, or @MappedSuperclass
are considered.
A typical entity class resembles the following example:
@Entity
public class City implements Serializable {
@Id
@GeneratedValue
private Long id;
@Column(nullable = false)
private String name;
@Column(nullable = false)
private String state;
// ... additional members, often include @OneToMany mappings
protected City() {
// no-args constructor required by JPA spec
// this one is protected since it should not be used directly
}
public City(String name, String state) {
this.name = name;
this.state = state;
}
public String getName() {
return this.name;
}
public String getState() {
return this.state;
}
// ... etc
}
@Entity
class City : Serializable {
@Id
@GeneratedValue
private val id: Long? = null
@Column(nullable = false)
var name: String? = null
private set
// ... etc
@Column(nullable = false)
var state: String? = null
private set
// ... additional members, often include @OneToMany mappings
protected constructor() {
// no-args constructor required by JPA spec
// this one is protected since it should not be used directly
}
constructor(name: String?, state: String?) {
this.name = name
this.state = state
}
}
You can customize entity scanning locations by using the @EntityScan annotation.
See the “Separate @Entity Definitions from Spring Configuration” how-to.
|
Spring Data JPA Repositories
Spring Data JPA repositories are interfaces that you can define to access data.
JPA queries are created automatically from your method names.
For example, a CityRepository
interface might declare a findAllByState(String state)
method to find all the cities in a given state.
For more complex queries, you can annotate your method with Spring Data’s Query
annotation.
Spring Data repositories usually extend from the Repository
or CrudRepository
interfaces.
If you use auto-configuration, the auto-configuration packages are searched for repositories.
You can customize the locations to look for repositories using @EnableJpaRepositories .
|
The following example shows a typical Spring Data repository interface definition:
public interface CityRepository extends Repository<City, Long> {
Page<City> findAll(Pageable pageable);
City findByNameAndStateAllIgnoringCase(String name, String state);
}
interface CityRepository : Repository<City?, Long?> {
fun findAll(pageable: Pageable?): Page<City?>?
fun findByNameAndStateAllIgnoringCase(name: String?, state: String?): City?
}
Spring Data JPA repositories support three different modes of bootstrapping: default, deferred, and lazy.
To enable deferred or lazy bootstrapping, set the spring.data.jpa.repositories.bootstrap-mode
property to deferred
or lazy
respectively.
When using deferred or lazy bootstrapping, the auto-configured EntityManagerFactoryBuilder
will use the context’s AsyncTaskExecutor
, if any, as the bootstrap executor.
If more than one exists, the one named applicationTaskExecutor
will be used.
When using deferred or lazy bootstrapping, make sure to defer any access to the JPA infrastructure after the application context bootstrap phase.
You can use |
We have barely scratched the surface of Spring Data JPA. For complete details, see the Spring Data JPA reference documentation. |
Spring Data Envers Repositories
If Spring Data Envers is available, JPA repositories are auto-configured to support typical Envers queries.
To use Spring Data Envers, make sure your repository extends from RevisionRepository
as shown in the following example:
public interface CountryRepository extends RevisionRepository<Country, Long, Integer>, Repository<Country, Long> {
Page<Country> findAll(Pageable pageable);
}
interface CountryRepository :
RevisionRepository<Country?, Long?, Int>,
Repository<Country?, Long?> {
fun findAll(pageable: Pageable?): Page<Country?>?
}
For more details, check the Spring Data Envers reference documentation. |
Creating and Dropping JPA Databases
By default, JPA databases are automatically created only if you use an embedded database (H2, HSQL, or Derby).
You can explicitly configure JPA settings by using spring.jpa.*
properties.
For example, to create and drop tables you can add the following line to your application.properties
:
spring.jpa.hibernate.ddl-auto=create-drop
spring:
jpa:
hibernate.ddl-auto: "create-drop"
Hibernate’s own internal property name for this (if you happen to remember it better) is hibernate.hbm2ddl.auto .
You can set it, along with other Hibernate native properties, by using spring.jpa.properties.* (the prefix is stripped before adding them to the entity manager).
The following line shows an example of setting JPA properties for Hibernate:
|
spring.jpa.properties.hibernate[globally_quoted_identifiers]=true
spring:
jpa:
properties:
hibernate:
"globally_quoted_identifiers": "true"
The line in the preceding example passes a value of true
for the hibernate.globally_quoted_identifiers
property to the Hibernate entity manager.
By default, the DDL execution (or validation) is deferred until the ApplicationContext
has started.
There is also a spring.jpa.generate-ddl
flag, but it is not used if Hibernate auto-configuration is active, because the ddl-auto
settings are more fine-grained.
Open EntityManager in View
If you are running a web application, Spring Boot by default registers OpenEntityManagerInViewInterceptor
to apply the “Open EntityManager in View” pattern, to allow for lazy loading in web views.
If you do not want this behavior, you should set spring.jpa.open-in-view
to false
in your application.properties
.
9.1.4. Spring Data JDBC
Spring Data includes repository support for JDBC and will automatically generate SQL for the methods on CrudRepository
.
For more advanced queries, a @Query
annotation is provided.
Spring Boot will auto-configure Spring Data’s JDBC repositories when the necessary dependencies are on the classpath.
They can be added to your project with a single dependency on spring-boot-starter-data-jdbc
.
If necessary, you can take control of Spring Data JDBC’s configuration by adding the @EnableJdbcRepositories
annotation or an AbstractJdbcConfiguration
subclass to your application.
For complete details of Spring Data JDBC, see the reference documentation. |
9.1.5. Using H2’s Web Console
The H2 database provides a browser-based console that Spring Boot can auto-configure for you. The console is auto-configured when the following conditions are met:
-
You are developing a servlet-based web application.
-
com.h2database:h2
is on the classpath. -
You are using Spring Boot’s developer tools.
If you are not using Spring Boot’s developer tools but would still like to make use of H2’s console, you can configure the spring.h2.console.enabled property with a value of true .
|
The H2 console is only intended for use during development, so you should take care to ensure that spring.h2.console.enabled is not set to true in production.
|
Changing the H2 Console’s Path
By default, the console is available at /h2-console
.
You can customize the console’s path by using the spring.h2.console.path
property.
Accessing the H2 Console in a Secured Application
H2 Console uses frames and, as it is intended for development only, does not implement CSRF protection measures. If your application uses Spring Security, you need to configure it to
-
disable CSRF protection for requests against the console,
-
set the header
X-Frame-Options
toSAMEORIGIN
on responses from the console.
More information on CSRF and the header X-Frame-Options can be found in the Spring Security Reference Guide.
In simple setups, a SecurityFilterChain
like the following can be used:
@Profile("dev")
@Configuration(proxyBeanMethods = false)
public class DevProfileSecurityConfiguration {
@Bean
@Order(Ordered.HIGHEST_PRECEDENCE)
SecurityFilterChain h2ConsoleSecurityFilterChain(HttpSecurity http) throws Exception {
http.requestMatcher(PathRequest.toH2Console());
http.authorizeRequests(yourCustomAuthorization());
http.csrf((csrf) -> csrf.disable());
http.headers((headers) -> headers.frameOptions().sameOrigin());
return http.build();
}
}
@Profile("dev")
@Configuration(proxyBeanMethods = false)
class DevProfileSecurityConfiguration {
@Bean
@Order(Ordered.HIGHEST_PRECEDENCE)
fun h2ConsoleSecurityFilterChain(http: HttpSecurity): SecurityFilterChain {
return http.authorizeHttpRequests(yourCustomAuthorization())
.csrf().disable()
.headers().frameOptions().sameOrigin().and()
.build()
}
}
The H2 console is only intended for use during development. In production, disabling CSRF protection or allowing frames for a website may create severe security risks. |
PathRequest.toH2Console() returns the correct request matcher also when the console’s path has been customized.
|
9.1.6. Using jOOQ
jOOQ Object Oriented Querying (jOOQ) is a popular product from Data Geekery which generates Java code from your database and lets you build type-safe SQL queries through its fluent API. Both the commercial and open source editions can be used with Spring Boot.
Code Generation
In order to use jOOQ type-safe queries, you need to generate Java classes from your database schema.
You can follow the instructions in the jOOQ user manual.
If you use the jooq-codegen-maven
plugin and you also use the spring-boot-starter-parent
“parent POM”, you can safely omit the plugin’s <version>
tag.
You can also use Spring Boot-defined version variables (such as h2.version
) to declare the plugin’s database dependency.
The following listing shows an example:
<plugin>
<groupId>org.jooq</groupId>
<artifactId>jooq-codegen-maven</artifactId>
<executions>
...
</executions>
<dependencies>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>${h2.version}</version>
</dependency>
</dependencies>
<configuration>
<jdbc>
<driver>org.h2.Driver</driver>
<url>jdbc:h2:~/yourdatabase</url>
</jdbc>
<generator>
...
</generator>
</configuration>
</plugin>
Using DSLContext
The fluent API offered by jOOQ is initiated through the org.jooq.DSLContext
interface.
Spring Boot auto-configures a DSLContext
as a Spring Bean and connects it to your application DataSource
.
To use the DSLContext
, you can inject it, as shown in the following example:
@Component
public class MyBean {
private final DSLContext create;
public MyBean(DSLContext dslContext) {
this.create = dslContext;
}
}
@Component
class MyBean(private val create: DSLContext) {
}
The jOOQ manual tends to use a variable named create to hold the DSLContext .
|
You can then use the DSLContext
to construct your queries, as shown in the following example:
public List<GregorianCalendar> authorsBornAfter1980() {
return this.create.selectFrom(AUTHOR)
.where(AUTHOR.DATE_OF_BIRTH.greaterThan(new GregorianCalendar(1980, 0, 1)))
.fetch(AUTHOR.DATE_OF_BIRTH);
fun authorsBornAfter1980(): List<GregorianCalendar> {
return create.selectFrom<Tables.TAuthorRecord>(Tables.AUTHOR)
.where(Tables.AUTHOR?.DATE_OF_BIRTH?.greaterThan(GregorianCalendar(1980, 0, 1)))
.fetch(Tables.AUTHOR?.DATE_OF_BIRTH)
}
jOOQ SQL Dialect
Unless the spring.jooq.sql-dialect
property has been configured, Spring Boot determines the SQL dialect to use for your datasource.
If Spring Boot could not detect the dialect, it uses DEFAULT
.
Spring Boot can only auto-configure dialects supported by the open source version of jOOQ. |
Customizing jOOQ
More advanced customizations can be achieved by defining your own DefaultConfigurationCustomizer
bean that will be invoked prior to creating the org.jooq.Configuration
@Bean
.
This takes precedence to anything that is applied by the auto-configuration.
You can also create your own org.jooq.Configuration
@Bean
if you want to take complete control of the jOOQ configuration.
9.1.7. Using R2DBC
The Reactive Relational Database Connectivity (R2DBC) project brings reactive programming APIs to relational databases.
R2DBC’s io.r2dbc.spi.Connection
provides a standard method of working with non-blocking database connections.
Connections are provided by using a ConnectionFactory
, similar to a DataSource
with jdbc.
ConnectionFactory
configuration is controlled by external configuration properties in spring.r2dbc.*
.
For example, you might declare the following section in application.properties
:
spring.r2dbc.url=r2dbc:postgresql://localhost/test
spring.r2dbc.username=dbuser
spring.r2dbc.password=dbpass
spring:
r2dbc:
url: "r2dbc:postgresql://localhost/test"
username: "dbuser"
password: "dbpass"
You do not need to specify a driver class name, since Spring Boot obtains the driver from R2DBC’s Connection Factory discovery. |
At least the url should be provided.
Information specified in the URL takes precedence over individual properties, that is name , username , password and pooling options.
|
The “How-to” section includes a section on how to initialize a database. |
To customize the connections created by a ConnectionFactory
, that is, set specific parameters that you do not want (or cannot) configure in your central database configuration, you can use a ConnectionFactoryOptionsBuilderCustomizer
@Bean
.
The following example shows how to manually override the database port while the rest of the options are taken from the application configuration:
@Configuration(proxyBeanMethods = false)
public class MyR2dbcConfiguration {
@Bean
public ConnectionFactoryOptionsBuilderCustomizer connectionFactoryPortCustomizer() {
return (builder) -> builder.option(ConnectionFactoryOptions.PORT, 5432);
}
}
@Configuration(proxyBeanMethods = false)
class MyR2dbcConfiguration {
@Bean
fun connectionFactoryPortCustomizer(): ConnectionFactoryOptionsBuilderCustomizer {
return ConnectionFactoryOptionsBuilderCustomizer { builder ->
builder.option(ConnectionFactoryOptions.PORT, 5432)
}
}
}
The following examples show how to set some PostgreSQL connection options:
@Configuration(proxyBeanMethods = false)
public class MyPostgresR2dbcConfiguration {
@Bean
public ConnectionFactoryOptionsBuilderCustomizer postgresCustomizer() {
Map<String, String> options = new HashMap<>();
options.put("lock_timeout", "30s");
options.put("statement_timeout", "60s");
return (builder) -> builder.option(PostgresqlConnectionFactoryProvider.OPTIONS, options);
}
}
@Configuration(proxyBeanMethods = false)
class MyPostgresR2dbcConfiguration {
@Bean
fun postgresCustomizer(): ConnectionFactoryOptionsBuilderCustomizer {
val options: MutableMap<String, String> = HashMap()
options["lock_timeout"] = "30s"
options["statement_timeout"] = "60s"
return ConnectionFactoryOptionsBuilderCustomizer { builder ->
builder.option(PostgresqlConnectionFactoryProvider.OPTIONS, options)
}
}
}
When a ConnectionFactory
bean is available, the regular JDBC DataSource
auto-configuration backs off.
If you want to retain the JDBC DataSource
auto-configuration, and are comfortable with the risk of using the blocking JDBC API in a reactive application, add @Import(DataSourceAutoConfiguration.class)
on a @Configuration
class in your application to re-enable it.
Embedded Database Support
Similarly to the JDBC support, Spring Boot can automatically configure an embedded database for reactive usage. You need not provide any connection URLs. You need only include a build dependency to the embedded database that you want to use, as shown in the following example:
<dependency>
<groupId>io.r2dbc</groupId>
<artifactId>r2dbc-h2</artifactId>
<scope>runtime</scope>
</dependency>
If you are using this feature in your tests, you may notice that the same database is reused by your whole test suite regardless of the number of application contexts that you use.
If you want to make sure that each context has a separate embedded database, you should set |
Using DatabaseClient
A DatabaseClient
bean is auto-configured, and you can @Autowire
it directly into your own beans, as shown in the following example:
@Component
public class MyBean {
private final DatabaseClient databaseClient;
public MyBean(DatabaseClient databaseClient) {
this.databaseClient = databaseClient;
}
}
@Component
class MyBean(private val databaseClient: DatabaseClient) {
}
Spring Data R2DBC Repositories
Spring Data R2DBC repositories are interfaces that you can define to access data.
Queries are created automatically from your method names.
For example, a CityRepository
interface might declare a findAllByState(String state)
method to find all the cities in a given state.
For more complex queries, you can annotate your method with Spring Data’s Query
annotation.
Spring Data repositories usually extend from the Repository
or CrudRepository
interfaces.
If you use auto-configuration, the auto-configuration packages are searched for repositories.
The following example shows a typical Spring Data repository interface definition:
public interface CityRepository extends Repository<City, Long> {
Mono<City> findByNameAndStateAllIgnoringCase(String name, String state);
}
interface CityRepository : Repository<City?, Long?> {
fun findByNameAndStateAllIgnoringCase(name: String?, state: String?): Mono<City?>?
}
We have barely scratched the surface of Spring Data R2DBC. For complete details, see the Spring Data R2DBC reference documentation. |
9.2. Working with NoSQL Technologies
Spring Data provides additional projects that help you access a variety of NoSQL technologies, including:
Of these, Spring Boot provides auto-configuration for Cassandra, Couchbase, Elasticsearch, LDAP, MongoDB, Neo4J and Redis. Additionally, Spring Boot for Apache Geode provides auto-configuration for Apache Geode. You can make use of the other projects, but you must configure them yourself. See the appropriate reference documentation at spring.io/projects/spring-data.
Spring Boot also provides auto-configuration for InfluxDB and Solr clients.
9.2.1. Redis
Redis is a cache, message broker, and richly-featured key-value store. Spring Boot offers basic auto-configuration for the Lettuce and Jedis client libraries and the abstractions on top of them provided by Spring Data Redis.
There is a spring-boot-starter-data-redis
“Starter” for collecting the dependencies in a convenient way.
By default, it uses Lettuce.
That starter handles both traditional and reactive applications.
We also provide a spring-boot-starter-data-redis-reactive “Starter” for consistency with the other stores with reactive support.
|
Connecting to Redis
You can inject an auto-configured RedisConnectionFactory
, StringRedisTemplate
, or vanilla RedisTemplate
instance as you would any other Spring Bean.
The following listing shows an example of such a bean:
@Component
public class MyBean {
private final StringRedisTemplate template;
public MyBean(StringRedisTemplate template) {
this.template = template;
}
}
@Component
class MyBean(private val template: StringRedisTemplate) {
}
By default, the instance tries to connect to a Redis server at localhost:6379
.
You can specify custom connection details using spring.redis.*
properties, as shown in the following example:
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.database=0
spring.redis.username=user
spring.redis.password=secret
spring:
redis:
host: "localhost"
port: 6379
database: 0
username: "user"
password: "secret"
You can also register an arbitrary number of beans that implement LettuceClientConfigurationBuilderCustomizer for more advanced customizations.
ClientResources can also be customized using ClientResourcesBuilderCustomizer .
If you use Jedis, JedisClientConfigurationBuilderCustomizer is also available.
Alternatively, you can register a bean of type RedisStandaloneConfiguration , RedisSentinelConfiguration , or RedisClusterConfiguration to take full control over the configuration.
|
If you add your own @Bean
of any of the auto-configured types, it replaces the default (except in the case of RedisTemplate
, when the exclusion is based on the bean name, redisTemplate
, not its type).
By default, a pooled connection factory is auto-configured if commons-pool2
is on the classpath.
9.2.2. MongoDB
MongoDB is an open-source NoSQL document database that uses a JSON-like schema instead of traditional table-based relational data.
Spring Boot offers several conveniences for working with MongoDB, including the spring-boot-starter-data-mongodb
and spring-boot-starter-data-mongodb-reactive
“Starters”.
Connecting to a MongoDB Database
To access MongoDB databases, you can inject an auto-configured org.springframework.data.mongodb.MongoDatabaseFactory
.
By default, the instance tries to connect to a MongoDB server at mongodb://localhost/test
.
The following example shows how to connect to a MongoDB database:
@Component
public class MyBean {
private final MongoDatabaseFactory mongo;
public MyBean(MongoDatabaseFactory mongo) {
this.mongo = mongo;
}
}
@Component
class MyBean(private val mongo: MongoDatabaseFactory) {
}
If you have defined your own MongoClient
, it will be used to auto-configure a suitable MongoDatabaseFactory
.
The auto-configured MongoClient
is created using a MongoClientSettings
bean.
If you have defined your own MongoClientSettings
, it will be used without modification and the spring.data.mongodb
properties will be ignored.
Otherwise a MongoClientSettings
will be auto-configured and will have the spring.data.mongodb
properties applied to it.
In either case, you can declare one or more MongoClientSettingsBuilderCustomizer
beans to fine-tune the MongoClientSettings
configuration.
Each will be called in order with the MongoClientSetti