# 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.html](getting-started.html#getting-started)" and "[using.html](using.html#using)" sections, so that you have a good grounding of the basics.
## 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:
```
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}
```
When your application starts, you should see something similar to the following output:
```
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: v2.6.4
2021-02-03 10:33:25.224 INFO 17321 --- [ main] o.s.b.d.s.s.SpringApplicationExample : Starting SpringApplicationExample using Java 1.8.0_232 on mycomputer with PID 17321 (/apps/myjar.jar started by pwebb)
2021-02-03 10:33:25.226 INFO 17900 --- [ main] o.s.b.d.s.s.SpringApplicationExample : No active profile set, falling back to default profiles: default
2021-02-03 10:33:26.046 INFO 17321 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8080 (http)
2021-02-03 10:33:26.054 INFO 17900 --- [ main] o.apache.catalina.core.StandardService : Starting service [Tomcat]
2021-02-03 10:33:26.055 INFO 17900 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/9.0.41]
2021-02-03 10:33:26.097 INFO 17900 --- [ main] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
2021-02-03 10:33:26.097 INFO 17900 --- [ main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 821 ms
2021-02-03 10:33:26.144 INFO 17900 --- [ main] s.tomcat.SampleTomcatApplication : ServletContext initialized
2021-02-03 10:33:26.376 INFO 17900 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path ''
2021-02-03 10:33:26.384 INFO 17900 --- [ main] o.s.b.d.s.s.SpringApplicationExample : Started SampleTomcatApplication in 1.514 seconds (JVM running for 1.823)
```
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](#features.logging.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`.|
|---|--------------------------------------------------------------------------------------------------------------------------|
### 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](howto.html#howto.application.failure-analyzer).|
|---|-------------------------------------------------------------------------------------------------------------------------------------------|
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](#features.external-config) or [enable `DEBUG` logging](#features.logging.log-levels) 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
```
### 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:
Properties
```
spring.main.lazy-initialization=true
```
Yaml
```
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.|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 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 |
|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `${application.version}` | The version number of your application, as declared in `MANIFEST.MF`.
For example, `Implementation-Version: 1.0` is printed as `1.0`. |
| `${application.formatted-version}` | The version number of your application, as declared in `MANIFEST.MF` and formatted for display (surrounded with brackets and prefixed with `v`).
For example `(v1.0)`. |
| `${spring-boot.version}` | The Spring Boot version that you are using.
For example `2.6.4`. |
| `${spring-boot.formatted-version}` | The Spring Boot version that you are using, formatted for display (surrounded with brackets and prefixed with `v`).
For example `(v2.6.4)`. |
|`${Ansi.NAME}` (or `${AnsiColor.NAME}`, `${AnsiBackground.NAME}`, `${AnsiStyle.NAME}`)|Where `NAME` is the name of an ANSI escape code.
See [`AnsiPropertySource`](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot/src/main/java/org/springframework/boot/ansi/AnsiPropertySource.java) for details.|
| `${application.title}` | The title of your application, as declared in `MANIFEST.MF`.
For example `Implementation-Title: MyApp` is printed as `MyApp`. |
| |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 `${application.version}` and `${application.formatted-version}` properties are only available if you are using Spring Boot launchers.
The values will not be resolved if you are running an unpacked jar and starting it with `java -cp `.
This is why we recommend that you always launch unpacked jars using `java org.springframework.boot.loader.JarLauncher`.
This will initialize the `application.*` banner variables before building the classpath and launching your app.|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 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:
```
import org.springframework.boot.Banner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication application = new SpringApplication(MyApplication.class);
application.setBannerMode(Banner.Mode.OFF);
application.run(args);
}
}
```
| |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](#features.external-config)* for details.
For a complete list of the configuration options, see the [`SpringApplication` Javadoc](https://docs.spring.io/spring-boot/docs/2.6.4/api/org/springframework/boot/SpringApplication.html).
### 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);
```
| |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](https://docs.spring.io/spring-boot/docs/2.6.4/api/org/springframework/boot/builder/SpringApplicationBuilder.html) for full details.|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 1.6. Application Availability
When deployed on platforms, applications can provide information about their availability to the platform using infrastructure such as [Kubernetes Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-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.
#### 1.6.1. 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](actuator.html#actuator.endpoints.health).
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](#features.spring-application.application-events-and-listeners).
#### 1.6.2. 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](#features.spring-application.application-events-and-listeners).
| |Tasks expected to run during startup should be executed by `CommandLineRunner` and `ApplicationRunner` components instead of using Spring component lifecycle callbacks such as `@PostConstruct`.|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 1.6.3. 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:
```
import org.springframework.boot.availability.AvailabilityChangeEvent;
import org.springframework.boot.availability.ReadinessState;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;
@Component
public class MyReadinessStateExporter {
@EventListener
public void onStateChange(AvailabilityChangeEvent event) {
switch (event.getState()) {
case ACCEPTING_TRAFFIC:
// create file /tmp/healthy
break;
case REFUSING_TRAFFIC:
// remove file /tmp/healthy
break;
}
}
}
```
We can also update the state of the application, when the application breaks and cannot recover:
```
import org.springframework.boot.availability.AvailabilityChangeEvent;
import org.springframework.boot.availability.LivenessState;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.stereotype.Component;
@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);
}
}
}
```
Spring Boot provides [Kubernetes HTTP probes for "Liveness" and "Readiness" with Actuator Health Endpoints](actuator.html#actuator.endpoints.kubernetes-probes).
You can get more guidance about [deploying Spring Boot applications on Kubernetes in the dedicated section](deployment.html#deployment.cloud.kubernetes).
### 1.7. Application Events and Listeners
In addition to the usual Spring Framework events, such as [`ContextRefreshedEvent`](https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/context/event/ContextRefreshedEvent.html), a `SpringApplication` sends some additional application events.
| |Some events are actually triggered before the `ApplicationContext` is created, so you cannot register a listener on those as a `@Bean`.
You can register them with the `SpringApplication.addListeners(…)` method or the `SpringApplicationBuilder.listeners(…)` method.
If you want those listeners to be registered automatically, regardless of the way the application is created, you can add a `META-INF/spring.factories` file to your project and reference your listener(s) by using the `org.springframework.context.ApplicationListener` key, as shown in the following example:
```
org.springframework.context.ApplicationListener=com.example.project.MyListener
```|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
Application events are sent in the following order, as your application runs:
1. An `ApplicationStartingEvent` is sent at the start of a run but before any processing, except for the registration of listeners and initializers.
2. An `ApplicationEnvironmentPreparedEvent` is sent when the `Environment` to be used in the context is known but before the context is created.
3. An `ApplicationContextInitializedEvent` is sent when the `ApplicationContext` is prepared and ApplicationContextInitializers have been called but before any bean definitions are loaded.
4. An `ApplicationPreparedEvent` is sent just before the refresh is started but after bean definitions have been loaded.
5. An `ApplicationStartedEvent` is sent after the context has been refreshed but before any application and command-line runners have been called.
6. An `AvailabilityChangeEvent` is sent right after with `LivenessState.CORRECT` to indicate that the application is considered as live.
7. An `ApplicationReadyEvent` is sent after any [application and command-line runners](#features.spring-application.command-line-runner) have been called.
8. An `AvailabilityChangeEvent` is sent right after with `ReadinessState.ACCEPTING_TRAFFIC` to indicate that the application is ready to service requests.
9. 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 the `WebServer` is ready.`ServletWebServerInitializedEvent` and `ReactiveWebServerInitializedEvent` are the servlet and reactive variants respectively.
* A `ContextRefreshedEvent` is sent when an `ApplicationContext` 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](#features.spring-application.command-line-runner) 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`.
### 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 `setApplicationContextClass(…)`.
| |It is often desirable to call `setWebApplicationType(WebApplicationType.NONE)` when using `SpringApplication` within a JUnit test.|
|---|----------------------------------------------------------------------------------------------------------------------------------|
### 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:
```
import java.util.List;
import org.springframework.boot.ApplicationArguments;
import org.springframework.stereotype.Component;
@Component
public class MyBean {
public MyBean(ApplicationArguments args) {
boolean debug = args.containsOption("debug");
List files = args.getNonOptionArgs();
if (debug) {
System.out.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.|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 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:
```
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;
@Component
public class MyCommandLineRunner implements CommandLineRunner {
@Override
public void run(String... args) {
// 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.
### 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:
```
import org.springframework.boot.ExitCodeGenerator;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
@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)));
}
}
```
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.
### 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`](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot/src/main/java/org/springframework/boot/admin/SpringApplicationAdminMXBean.java) 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`.|
|---|----------------------------------------------------------------------------------------------------------------------|
### 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`](https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/core/metrics/ApplicationStartup.html), Spring Framework [allows you to track the application startup sequence with `StartupStep` objects](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/core.html#context-functionality-startup).
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:
```
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.metrics.buffering.BufferingApplicationStartup;
@SpringBootApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication application = new SpringApplication(MyApplication.class);
application.setApplicationStartup(new BufferingApplicationStartup(2048));
application.run(args);
}
}
```
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](https://docs.spring.io/spring-boot/docs/2.6.4/actuator-api/htmlsingle/#startup) that provides this information as a JSON document.
## 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, include 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](#features.external-config.typesafe-configuration-properties) through `@ConfigurationProperties`.
Spring Boot uses a very particular `PropertySource` order that is designed to allow sensible overriding of values.
Properties are considered in the following order (with values from lower items overriding earlier ones):
1. Default properties (specified by setting `SpringApplication.setDefaultProperties`).
2. [`@PropertySource`](https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/context/annotation/PropertySource.html) annotations on your `@Configuration` classes.
Please note that such property sources are not added to the `Environment` until the application context is being refreshed.
This is too late to configure certain properties such as `logging.*` and `spring.main.*` which are read before refresh begins.
3. Config data (such as `application.properties` files).
4. A `RandomValuePropertySource` that has properties only in `random.*`.
5. OS environment variables.
6. Java System properties (`System.getProperties()`).
7. JNDI attributes from `java:comp/env`.
8. `ServletContext` init parameters.
9. `ServletConfig` init parameters.
10. Properties from `SPRING_APPLICATION_JSON` (inline JSON embedded in an environment variable or system property).
11. Command line arguments.
12. `properties` attribute on your tests.
Available on [`@SpringBootTest`](https://docs.spring.io/spring-boot/docs/2.6.4/api/org/springframework/boot/test/context/SpringBootTest.html) and the [test annotations for testing a particular slice of your application](#features.testing.spring-boot-applications.autoconfigured-tests).
13. [`@TestPropertySource`](https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/test/context/TestPropertySource.html) annotations on your tests.
14. [Devtools global settings properties](using.html#using.devtools.globalsettings) in the `$HOME/.config/spring-boot` directory when devtools is active.
Config data files are considered in the following order:
1. [Application properties](#features.external-config.files) packaged inside your jar (`application.properties` and YAML variants).
2. [Profile-specific application properties](#features.external-config.files.profile-specific) packaged inside your jar (`application-{profile}.properties` and YAML variants).
3. [Application properties](#features.external-config.files) outside of your packaged jar (`application.properties` and YAML variants).
4. [Profile-specific application properties](#features.external-config.files.profile-specific) 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 `.yml` format in the same location, `.properties` takes precedence.|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
To provide a concrete example, suppose you develop a `@Component` that uses a `name` property, as shown in the following example:
```
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
@Component
public class MyBean {
@Value("${name}")
private String name;
// ...
}
```
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](actuator.html#actuator.endpoints)" section for details.|
|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 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)`.
### 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.|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 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:
1. From the classpath
1. The classpath root
2. The classpath `/config` package
2. From the current directory
1. The current directory
2. The `/config` subdirectory in the current directory
3. 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 properties 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](#features.external-config.files.optional-prefix) 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](#features.external-config.files.profile-specific).
For example, if you have a `spring.config.location` of `classpath:myconfig.properties`, you will also find appropriate `classpath:myconfig-.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](#features.external-config.files.profile-specific)” 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:
1. `optional:classpath:custom-config/`
2. `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:
1. `optional:classpath:/;optional:classpath:/config/`
2. `optional:file:./;optional:file:./config/;optional:file:./config/*/`
3. `optional:classpath:custom-config/`
4. `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.
| |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](#features.external-config.typesafe-configuration-properties.relaxed-binding.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.|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.3.1. 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`](#features.external-config.files.importing) 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.
#### 2.3.2. 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 `*/` 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.|
|---|-----------------------------------------------------------------------------------------------------------------|
#### 2.3.3. 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.yml` and `application-prod.yml` 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](#features.external-config.files.location-groups) level.
A `spring.config.location` of `classpath:/cfg/,classpath:/ext/` will not have the same override rules as `classpath:/cfg/;classpath:/ext/`.
For example, continuing our `prod,live` example above, we might have the following files:
```
/cfg
application-live.properties
/ext
application-live.properties
application-prod.properties
```
When we have a `spring.config.location` of `classpath:/cfg/,classpath:/ext/` we process all `/cfg` files before all `/ext` files:
1. `/cfg/application-live.properties`
2. `/ext/application-prod.properties`
3. `/ext/application-live.properties`
When we have `classpath:/cfg/;classpath:/ext/` instead (with a `;` delimiter) we process `/cfg` and `/ext` at the same level:
1. `/ext/application-prod.properties`
2. `/cfg/application-live.properties`
3. `/ext/application-live.properties`|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
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](#features.external-config.files.importing) a profile specific property files then it will not be imported a second time.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.3.4. 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:
Properties
```
spring.application.name=myapp
spring.config.import=optional:file:./dev.properties
```
Yaml
```
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:
Properties
```
spring.config.import=my.properties
my.property=value
```
Yaml
```
spring:
config:
import: "my.properties"
my:
property: "value"
```
Properties
```
my.property=value
spring.config.import=my.properties
```
Yaml
```
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](#features.external-config.files.profile-specific) are also considered for import.
The example above would import both `my.properties` as well as any `my-.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](#features.external-config.files.configtree)”.
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 `ConfigDataLocationResolver` and `ConfigDataLoader` classes in the `org.springframework.boot.context.config` package.|
|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.3.5. 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:
Properties
```
spring.config.import=file:/etc/config/myconfig[.yaml]
```
Yaml
```
spring:
config:
import: "file:/etc/config/myconfig[.yaml]"
```
#### 2.3.6. 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`](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#populate-a-volume-with-data-stored-in-a-configmap) and [`Secrets`](https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-files-from-a-pod).
There are two common volume mount patterns that can be used:
1. A single file contains a complete set of properties (usually written as YAML).
2. 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](#features.external-config.files.importing).
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:
Properties
```
spring.config.import=optional:configtree:/etc/config/
```
Yaml
```
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 folders 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.
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:
Properties
```
spring.config.import=optional:configtree:/etc/config/*/
```
Yaml
```
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:
Properties
```
spring.config.import=optional:configtree:/run/secrets/
```
Yaml
```
spring:
config:
import: "optional:configtree:/run/secrets/"
```
#### 2.3.7. Property Placeholders
The values in `application.properties` and `application.yml` are filtered through the existing `Environment` when they are used, so you can refer back to previously defined values (for example, from System properties).
The standard `${name}` property-placeholder syntax can be used anywhere within a value.
For example, the following file will set `app.description` to “MyApp is a Spring Boot application”:
Properties
```
app.name=MyApp
app.description=${app.name} is a Spring Boot application
```
Yaml
```
app:
name: "MyApp"
description: "${app.name} is a Spring Boot application"
```
| |You can also use this technique to create “short” variants of existing Spring Boot properties.
See the *[howto.html](howto.html#howto.properties-and-configuration.short-command-line-arguments)* how-to for details.|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.3.8. 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.yml` 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 `#---` 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 comments.|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| |Multi-document property files are often used in conjunction with activation properties such as `spring.config.activate.on-profile`.
See the [next section](#features.external-config.files.activation-properties) for details.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| |Multi-document property files cannot be loaded by using the `@PropertySource` or `@TestPropertySource` annotations.|
|---|-------------------------------------------------------------------------------------------------------------------|
#### 2.3.9. 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 |
|-------------------|------------------------------------------------------------------------|
| `on-profile` | A profile expression that must match for the document to be active. |
|`on-cloud-platform`|The `CloudPlatform` that must be detected for the document to be active.|
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:
Properties
```
myprop=always-set
#---
spring.config.activate.on-cloud-platform=kubernetes
spring.config.activate.on-profile=prod | staging
myotherprop=sometimes-set
```
Yaml
```
myprop:
"always-set"
---
spring:
config:
activate:
on-cloud-platform: "kubernetes"
on-profile: "prod | staging"
myotherprop: "sometimes-set"
```
### 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 [howto.html](howto.html#howto.application.customize-the-environment-or-application-context) for details.
If you need a secure way to store credentials and passwords, the [Spring Cloud Vault](https://cloud.spring.io/spring-cloud-vault/) project provides support for storing externalized configuration in [HashiCorp Vault](https://www.vaultproject.io/).
### 2.5. Working with YAML
[YAML](https://yaml.org) 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](https://bitbucket.org/asomov/snakeyaml) library on your classpath.
| |If you use “Starters”, SnakeYAML is automatically provided by `spring-boot-starter`.|
|---|------------------------------------------------------------------------------------|
#### 2.5.1. 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](#features.external-config.typesafe-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.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.5.2. 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`.
### 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:
Properties
```
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]}
```
Yaml
```
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).
### 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.
### 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.
| |See also the [differences between `@Value` and type-safe configuration properties](#features.external-config.typesafe-configuration-properties.vs-value-annotation).|
|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.8.1. JavaBean properties binding
It is possible to bind a bean declaring standard JavaBean properties as shown in the following example:
```
import java.net.InetAddress;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties("my.service")
public class MyProperties {
private boolean enabled;
private InetAddress remoteAddress;
private final Security security = new Security();
// getters / setters...
public boolean isEnabled() {
return this.enabled;
}
public void setEnabled(boolean enabled) {
this.enabled = enabled;
}
public InetAddress getRemoteAddress() {
return this.remoteAddress;
}
public void setRemoteAddress(InetAddress remoteAddress) {
this.remoteAddress = remoteAddress;
}
public Security getSecurity() {
return this.security;
}
public static class Security {
private String username;
private String password;
private List roles = new ArrayList<>(Collections.singleton("USER"));
// getters / setters...
public String getUsername() {
return this.username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return this.password;
}
public void setPassword(String password) {
this.password = password;
}
public List getRoles() {
return this.roles;
}
public void setRoles(List roles) {
this.roles = roles;
}
}
}
```
The preceding POJO defines the following properties:
* `my.service.enabled`, with a value of `false` by default.
* `my.service.remote-address`, with a type that can be coerced from `String`.
* `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 been `SecurityProperties`.
* `my.service.security.password`.
* `my.service.security.roles`, with a collection of `String` that defaults to `USER`.
| |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:
* Maps, as long as they are initialized, need a getter but not necessarily a setter, since they can be mutated by the binder.
* Collections and arrays can be accessed either through an index (typically with YAML) or by using a single comma-separated value (properties).
In the latter case, a setter is mandatory.
We recommend to always add a setter for such types.
If you initialize a collection, make sure it is not immutable (as in the preceding example).
* If nested POJO properties are initialized (like the `Security` field in the preceding example), a setter is not required.
If you want the binder to create the instance on the fly by using its default constructor, you need a setter.
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.|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.8.2. Constructor binding
The example in the previous section can be rewritten in an immutable fashion as shown in the following example:
```
import java.net.InetAddress;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.ConstructorBinding;
import org.springframework.boot.context.properties.bind.DefaultValue;
@ConstructorBinding
@ConfigurationProperties("my.service")
public class MyProperties {
// fields...
private final boolean enabled;
private final InetAddress remoteAddress;
private final Security security;
public MyProperties(boolean enabled, InetAddress remoteAddress, Security security) {
this.enabled = enabled;
this.remoteAddress = remoteAddress;
this.security = security;
}
// getters...
public boolean isEnabled() {
return this.enabled;
}
public InetAddress getRemoteAddress() {
return this.remoteAddress;
}
public Security getSecurity() {
return this.security;
}
public static class Security {
// fields...
private final String username;
private final String password;
private final List roles;
public Security(String username, String password, @DefaultValue("USER") List roles) {
this.username = username;
this.password = password;
this.roles = roles;
}
// getters...
public String getUsername() {
return this.username;
}
public String getPassword() {
return this.password;
}
public List getRoles() {
return this.roles;
}
}
}
```
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` and the same conversion service will be applied to coerce the `String` value to the target type of a missing property.
By default, if no properties are bound to `Security`, the `MyProperties` instance will contain a `null` value for `security`.
If you wish you return a non-null instance of `Security` even when no properties are bound to it, you can use an empty `@DefaultValue` annotation to do so:
```
public MyProperties(boolean enabled, InetAddress remoteAddress, @DefaultValue Security security) {
this.enabled = enabled;
this.remoteAddress = remoteAddress;
this.security = security;
}
```
| |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.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.8.3. 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:
```
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(SomeProperties.class)
public class MyConfiguration {
}
```
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:
```
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
@SpringBootApplication
@ConfigurationPropertiesScan({ "com.example.app", "com.example.another" })
public class MyApplication {
}
```
| |When the `@ConfigurationProperties` bean is registered using configuration property scanning or through `@EnableConfigurationProperties`, the bean has a conventional name: `-`, where `` is the environment key prefix specified in the `@ConfigurationProperties` annotation and `` is the fully qualified name of the bean.
If the annotation does not provide any prefix, only the fully qualified name of the bean is used.
The bean name in the example above is `com.example.app-com.example.app.SomeProperties`.|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
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.
#### 2.8.4. 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:
```
import org.springframework.stereotype.Service;
@Service
public class MyService {
private final SomeProperties properties;
public MyService(SomeProperties properties) {
this.properties = properties;
}
public void openConnection() {
Server server = new Server(this.properties.getRemoteAddress());
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](configuration-metadata.html#appendix.configuration-metadata) for details.|
|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.8.5. 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:
```
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
public class ThirdPartyConfiguration {
@Bean
@ConfigurationProperties(prefix = "another")
public AnotherComponent anotherComponent() {
return new AnotherComponent();
}
}
```
Any JavaBean property defined with the `another` prefix is mapped onto that `AnotherComponent` bean in manner similar to the preceding `SomeProperties` example.
#### 2.8.6. 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:
```
import org.springframework.boot.context.properties.ConfigurationProperties;
@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;
}
}
```
With the preceding code, the following properties names can all be used:
| Property | Note |
|-----------------------------------|----------------------------------------------------------------------------------------------|
|`my.main-project.person.first-name`| Kebab case, which is recommended for use in `.properties` and `.yml` files. |
|`my.main-project.person.firstName` | Standard camel case syntax. |
|`my.main-project.person.first_name`|Underscore notation, which is an alternative format for use in `.properties` and `.yml` files.|
| `MY_MAINPROJECT_PERSON_FIRSTNAME` | 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 `[ ]` or comma-separated values |
| 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](#features.external-config.typesafe-configuration-properties.relaxed-binding.environment-variables)).|Numeric values surrounded by underscores (see [Binding from Environment Variables](#features.external-config.typesafe-configuration-properties.relaxed-binding.environment-variables))|
| System properties | Camel case, kebab case, or underscore notation | Standard list syntax using `[ ]` or comma-separated values |
| |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`:
Properties
```
my.map.[/key1]=value1
my.map.[/key2]=value2
my.map./key3=value3
```
Yaml
```
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.
You may also occasionally need to use the bracket notation if your `key` contains a `.` and you are binding to non-scalar value.
For example, binding `a.b=c` to `Map` 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`.
#### 2.8.7. 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`:
```
import java.util.ArrayList;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties("my")
public class MyProperties {
private final List list = new ArrayList<>();
public List getList() {
return this.list;
}
}
```
Consider the following configuration:
Properties
```
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
```
Yaml
```
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:
Properties
```
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
```
Yaml
```
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` from `MyProperties`:
```
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties("my")
public class MyProperties {
private final Map map = new LinkedHashMap<>();
public Map getMap() {
return this.map;
}
}
```
Consider the following configuration:
Properties
```
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
```
Yaml
```
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.|
|---|----------------------------------------------------------------------------------------------|
#### 2.8.8. 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`](https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-)
* A more readable format where the value and the unit are coupled (`10s` means 10 seconds)
Consider the following example:
```
import java.time.Duration;
import java.time.temporal.ChronoUnit;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.convert.DurationUnit;
@ConfigurationProperties("my")
public class MyProperties {
@DurationUnit(ChronoUnit.SECONDS)
private Duration sessionTimeout = Duration.ofSeconds(30);
private Duration readTimeout = Duration.ofMillis(1000);
// getters / setters...
public Duration getSessionTimeout() {
return this.sessionTimeout;
}
public void setSessionTimeout(Duration sessionTimeout) {
this.sessionTimeout = sessionTimeout;
}
public Duration getReadTimeout() {
return this.readTimeout;
}
public void setReadTimeout(Duration readTimeout) {
this.readTimeout = readTimeout;
}
}
```
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:
```
import java.time.Duration;
import java.time.temporal.ChronoUnit;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.ConstructorBinding;
import org.springframework.boot.context.properties.bind.DefaultValue;
import org.springframework.boot.convert.DurationUnit;
@ConfigurationProperties("my")
@ConstructorBinding
public class MyProperties {
// fields...
private final Duration sessionTimeout;
private final Duration readTimeout;
public MyProperties(@DurationUnit(ChronoUnit.SECONDS) @DefaultValue("30s") Duration sessionTimeout,
@DefaultValue("1000ms") Duration readTimeout) {
this.sessionTimeout = sessionTimeout;
this.readTimeout = readTimeout;
}
// getters...
public Duration getSessionTimeout() {
return this.sessionTimeout;
}
public Duration getReadTimeout() {
return this.readTimeout;
}
}
```
| |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`](https://docs.oracle.com/javase/8/docs/api/java/time/Period.html#parse-java.lang.CharSequence-)
* 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:
```
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.convert.DataSizeUnit;
import org.springframework.util.unit.DataSize;
import org.springframework.util.unit.DataUnit;
@ConfigurationProperties("my")
public class MyProperties {
@DataSizeUnit(DataUnit.MEGABYTES)
private DataSize bufferSize = DataSize.ofMegabytes(2);
private DataSize sizeThreshold = DataSize.ofBytes(512);
// getters/setters...
public DataSize getBufferSize() {
return this.bufferSize;
}
public void setBufferSize(DataSize bufferSize) {
this.bufferSize = bufferSize;
}
public DataSize getSizeThreshold() {
return this.sizeThreshold;
}
public void setSizeThreshold(DataSize sizeThreshold) {
this.sizeThreshold = sizeThreshold;
}
}
```
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:
```
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.ConstructorBinding;
import org.springframework.boot.context.properties.bind.DefaultValue;
import org.springframework.boot.convert.DataSizeUnit;
import org.springframework.util.unit.DataSize;
import org.springframework.util.unit.DataUnit;
@ConfigurationProperties("my")
@ConstructorBinding
public class MyProperties {
// fields...
private final DataSize bufferSize;
private final DataSize sizeThreshold;
public MyProperties(@DataSizeUnit(DataUnit.MEGABYTES) @DefaultValue("2MB") DataSize bufferSize,
@DefaultValue("512B") DataSize sizeThreshold) {
this.bufferSize = bufferSize;
this.sizeThreshold = sizeThreshold;
}
// getters...
public DataSize getBufferSize() {
return this.bufferSize;
}
public DataSize getSizeThreshold() {
return this.sizeThreshold;
}
}
```
| |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.|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.8.9. @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:
```
import java.net.InetAddress;
import javax.validation.constraints.NotNull;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
@ConfigurationProperties("my.service")
@Validated
public class MyProperties {
@NotNull
private InetAddress remoteAddress;
// getters/setters...
public InetAddress getRemoteAddress() {
return this.remoteAddress;
}
public void setRemoteAddress(InetAddress remoteAddress) {
this.remoteAddress = remoteAddress;
}
}
```
| |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:
```
import java.net.InetAddress;
import javax.validation.Valid;
import javax.validation.constraints.NotEmpty;
import javax.validation.constraints.NotNull;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
@ConfigurationProperties("my.service")
@Validated
public class MyProperties {
@NotNull
private InetAddress remoteAddress;
@Valid
private final Security security = new Security();
// getters/setters...
public InetAddress getRemoteAddress() {
return this.remoteAddress;
}
public void setRemoteAddress(InetAddress remoteAddress) {
this.remoteAddress = remoteAddress;
}
public Security getSecurity() {
return this.security;
}
public static class Security {
@NotEmpty
private String username;
// getters/setters...
public String getUsername() {
return this.username;
}
public void setUsername(String username) {
this.username = username;
}
}
}
```
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](actuator.html#actuator.endpoints)" section for details.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 2.8.10. @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` |
|----------------------------------------------------------------------------------------------|--------------------------|----------------------------------------------------------------------------------------------------------------|
|[Relaxed binding](#features.external-config.typesafe-configuration-properties.relaxed-binding)| Yes |Limited (see [note below](#features.external-config.typesafe-configuration-properties.vs-value-annotation.note))|
| [Meta-data support](configuration-metadata.html#appendix.configuration-metadata) | Yes | No |
| `SpEL` evaluation | No | Yes |
| |If you do want to use `@Value`, we recommend that you refer to property names 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 `@ConfigurationProperties`.
For example, `@Value("{demo.item-price}")` will pick up `demo.item-price` and `demo.itemPrice` forms from the `application.properties` file, as well as `DEMO_ITEMPRICE` from the system environment.
If you used `@Value("{demo.itemPrice}")` instead, `demo.item-price` and `DEMO_ITEMPRICE` would not be considered.|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
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](#features.external-config.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`.
## 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:
```
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
@Configuration(proxyBeanMethods = false)
@Profile("production")
public 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:
Properties
```
spring.profiles.active=dev,hsqldb
```
Yaml
```
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:
Properties
```
spring.profiles.default=none
```
Yaml
```
spring:
profiles:
default: "none"
```
### 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 `SpringApplication` entry point has a Java API for setting additional profiles (that is, on top of those activated by the `spring.profiles.active` property).
See the `setAdditionalProfiles()` method in [SpringApplication](https://docs.spring.io/spring-boot/docs/2.6.4/api/org/springframework/boot/SpringApplication.html).
Profile groups, which are described in the [next section](#features.profiles.groups) can also be used to add active profiles if a given profile is active.
### 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.
Properties
```
spring.profiles.group.production[0]=proddb
spring.profiles.group.production[1]=prodmq
```
Yaml
```
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.
### 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.
### 3.4. Profile-specific Configuration Files
Profile-specific variants of both `application.properties` (or `application.yml`) and files referenced through `@ConfigurationProperties` are considered as files and loaded.
See "[Profile Specific Files](#features.external-config.files.profile-specific)" for details.
## 4. Logging
Spring Boot uses [Commons Logging](https://commons.apache.org/logging) for all internal logging but leaves the underlying log implementation open.
Default configurations are provided for [Java Util Logging](https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html), [Log4J2](https://logging.apache.org/log4j/2.x/), and [Logback](https://logback.qos.ch/).
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.|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 4.1. Log Format
The default log output from Spring Boot resembles the following example:
```
2019-03-05 10:57:51.112 INFO 45469 --- [ main] org.apache.catalina.core.StandardEngine : Starting Servlet Engine: Apache Tomcat/7.0.52
2019-03-05 10:57:51.253 INFO 45469 --- [ost-startStop-1] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring embedded WebApplicationContext
2019-03-05 10:57:51.253 INFO 45469 --- [ost-startStop-1] o.s.web.context.ContextLoader : Root WebApplicationContext: initialization completed in 1358 ms
2019-03-05 10:57:51.698 INFO 45469 --- [ost-startStop-1] o.s.b.c.e.ServletRegistrationBean : Mapping servlet: 'dispatcherServlet' to [/]
2019-03-05 10:57:51.702 INFO 45469 --- [ost-startStop-1] o.s.b.c.embedded.FilterRegistrationBean : Mapping filter: 'hiddenHttpMethodFilter' to: [/*]
```
The following items are output:
* Date and Time: Millisecond precision and easily sortable.
* Log Level: `ERROR`, `WARN`, `INFO`, `DEBUG`, or `TRACE`.
* 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`.|
|---|-------------------------------------------------------------------|
### 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).
#### 4.2.1. 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](https://docs.spring.io/spring-boot/docs/2.6.4/api/org/springframework/boot/ansi/AnsiOutput.Enabled.html) 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 |
|-------|------|
|`FATAL`| Red |
|`ERROR`| Red |
|`WARN` |Yellow|
|`INFO` |Green |
|`DEBUG`|Green |
|`TRACE`|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`
### 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)* | `my.log` | Writes to the specified log file.
Names can be an exact location or relative to the current directory. |
| *(none)* |Specific directory |`/var/log`|Writes `spring.log` to the specified directory.
Names can be an exact location or relative to the current directory.|
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.|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 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 |
|------------------------------------------------------|----------------------------------------------------------------------|
| `logging.logback.rollingpolicy.file-name-pattern` | The filename pattern used to create log archives. |
|`logging.logback.rollingpolicy.clean-history-on-start`| If log archive cleanup should occur when the application starts. |
| `logging.logback.rollingpolicy.max-file-size` | The maximum size of log file before it is archived. |
| `logging.logback.rollingpolicy.total-size-cap` |The maximum amount of size log archives can take before being deleted.|
| `logging.logback.rollingpolicy.max-history` | The maximum number of archive log files to keep (defaults to 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.=` 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`:
Properties
```
logging.level.root=warn
logging.level.org.springframework.web=debug
logging.level.org.hibernate=error
```
Yaml
```
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`](#features.external-config.application-json) variable.|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 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`:
Properties
```
logging.group.tomcat=org.apache.catalina,org.apache.coyote,org.apache.tomcat
```
Yaml
```
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:
Properties
```
logging.level.tomcat=trace
```
Yaml
```
logging:
level:
tomcat: "trace"
```
Spring Boot includes the following pre-defined logging groups that can be used out-of-the-box:
|Name| Loggers |
|----|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|web |`org.springframework.core.codec`, `org.springframework.http`, `org.springframework.web`, `org.springframework.boot.actuate.endpoint.web`, `org.springframework.boot.web.servlet.ServletContextInitializerBeans`|
|sql | `org.springframework.jdbc.core`, `org.hibernate.SQL`, `org.jooq.tools.LoggerListener` |
### 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](http://logback.qos.ch/manual/loggingSeparation.html) 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:
Properties
```
logging.register-shutdown-hook=false
```
Yaml
```
logging:
register-shutdown-hook: false
```
### 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 |`logback-spring.xml`, `logback-spring.groovy`, `logback.xml`, or `logback.groovy`|
| Log4j2 | `log4j2-spring.xml` or `log4j2.xml` |
|JDK (Java Util Logging)| `logging.properties` |
| |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, as described in the following table:
| Spring Environment | System Property | Comments |
|-----------------------------------|-------------------------------|-----------------------------------------------------------------------------------------------------------|
|`logging.exception-conversion-word`|`LOG_EXCEPTION_CONVERSION_WORD`| The conversion word used when logging exceptions. |
| `logging.file.name` | `LOG_FILE` | If defined, it is used in the default log configuration. |
| `logging.file.path` | `LOG_PATH` | If defined, it is used in the default log configuration. |
| `logging.pattern.console` | `CONSOLE_LOG_PATTERN` | The log pattern to use on the console (stdout). |
| `logging.pattern.dateformat` | `LOG_DATEFORMAT_PATTERN` | Appender pattern for log date format. |
| `logging.charset.console` | `CONSOLE_LOG_CHARSET` | The charset to use for console logging. |
| `logging.pattern.file` | `FILE_LOG_PATTERN` | The log pattern to use in a file (if `LOG_FILE` is enabled). |
| `logging.charset.file` | `FILE_LOG_CHARSET` | The charset to use for file logging (if `LOG_FILE` is enabled). |
| `logging.pattern.level` | `LOG_LEVEL_PATTERN` | The format to use when rendering the log level (default `%5p`). |
| `PID` | `PID` |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 |
|------------------------------------------------------|----------------------------------------------|------------------------------------------------------------------------------------|
| `logging.logback.rollingpolicy.file-name-pattern` | `LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN` |Pattern for rolled-over log file names (default `${LOG_FILE}.%d{yyyy-MM-dd}.%i.gz`).|
|`logging.logback.rollingpolicy.clean-history-on-start`|`LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START`| Whether to clean the archive log files on startup. |
| `logging.logback.rollingpolicy.max-file-size` | `LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE` | Maximum log file size. |
| `logging.logback.rollingpolicy.total-size-cap` | `LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP` | Total size of log backups to be kept. |
| `logging.logback.rollingpolicy.max-history` | `LOGBACK_ROLLINGPOLICY_MAX_HISTORY` | 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:
* [Logback](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot/src/main/resources/org/springframework/boot/logging/logback/defaults.xml)
* [Log4j 2](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot/src/main/resources/org/springframework/boot/logging/log4j2/log4j2.xml)
* [Java Util logging](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot/src/main/resources/org/springframework/boot/logging/java/logging-file.properties)
| |If you want to use a placeholder in a logging property, you should use [Spring Boot’s syntax](#features.external-config.files.property-placeholders) and not the syntax of the underlying framework.
Notably, if you use Logback, you should use `:` as the delimiter between a property name and its default value and not use `:-`.|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| |You can add MDC and other ad-hoc content to log lines by overriding only the `LOG_LEVEL_PATTERN` (or `logging.pattern.level` with Logback).
For example, if you use `logging.pattern.level=user:%X{user} %5p`, then the default log format contains an MDC entry for "user", if it exists, as shown in the following example.
```
2019-08-30 12:30:04.031 user:someone INFO 22174 --- [ nio-8080-exec-0] demo.Controller
Handling authenticated request
```|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 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](https://logback.qos.ch/manual/configuration.html#autoScan).
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 [email protected]:71 - no applicable action for [springProperty], current ElementPath is [[configuration][springProperty]]
ERROR in ch.qos.logback.core.joran.spi.Interpret[email protected]:71 - no applicable action for [springProfile], current ElementPath is [[configuration][springProfile]]
```
#### 4.9.1. Profile-specific Configuration
The `` tag lets you optionally include or exclude sections of configuration based on the active Spring profiles.
Profile sections are supported anywhere within the `` element.
Use the `name` attribute to specify which profile accepts the configuration.
The `` 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](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/core.html#beans-definition-profiles-java) for more details.
The following listing shows three sample profiles:
```
```
#### 4.9.2. Environment Properties
The `` 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 `` 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:
```
${fluentHost}
...
```
| |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.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
## 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:
Properties
```
spring.messages.basename=messages,config.i18n.messages
spring.messages.fallback-to-system-locale=false
```
Yaml
```
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`](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/context/MessageSourceProperties.java) for more supported options.
## 6. JSON
Spring Boot provides integration with three JSON mapping libraries:
* Gson
* Jackson
* JSON-B
Jackson is the preferred and default library.
### 6.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`](howto.html#howto.spring-mvc.customize-jackson-objectmapper).
### 6.2. Gson
Auto-configuration for Gson is provided.
When Gson is on the classpath a `Gson` bean is automatically configured.
Several `spring.gson.*` configuration properties are provided for customizing the configuration.
To take more control, one or more `GsonBuilderCustomizer` beans can be used.
### 6.3. JSON-B
Auto-configuration for JSON-B is provided.
When the JSON-B API and an implementation are on the classpath a `Jsonb` bean will be automatically configured.
The preferred JSON-B implementation is Apache Johnzon for which dependency management is provided.
## 7. 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 `Executor` in the context, regular task execution (that is `@EnableAsync`) will use it transparently but the Spring MVC support will not be configured as it requires an `AsyncTaskExecutor` implementation (named `applicationTaskExecutor`).
Depending on your target arrangement, you could change your `Executor` into a `ThreadPoolTaskExecutor` or define both a `ThreadPoolTaskExecutor` and an `AsyncConfigurer` wrapping your custom `Executor`.
The auto-configured `TaskExecutorBuilder` allows you to easily create instances that reproduce what the auto-configuration does by default.|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
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:
Properties
```
spring.task.execution.pool.max-size=16
spring.task.execution.pool.queue-capacity=100
spring.task.execution.pool.keep-alive=10s
```
Yaml
```
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:
Properties
```
spring.task.scheduling.thread-name-prefix=scheduling-
spring.task.scheduling.pool.size=2
```
Yaml
```
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.
## 8. 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 `junit-vintage-engine`, as shown in the following example:
```
org.junit.vintage
junit-vintage-engine
test
org.hamcrest
hamcrest-core
```|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
`hamcrest-core` is excluded in favor of `org.hamcrest:hamcrest` that is part of `spring-boot-starter-test`.
### 8.1. Test Scope Dependencies
The `spring-boot-starter-test` “Starter” (in the `test` `scope`) contains the following provided libraries:
* [JUnit 5](https://junit.org/junit5/): The de-facto standard for unit testing Java applications.
* [Spring Test](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/testing.html#integration-testing) & Spring Boot Test: Utilities and integration test support for Spring Boot applications.
* [AssertJ](https://assertj.github.io/doc/): A fluent assertion library.
* [Hamcrest](https://github.com/hamcrest/JavaHamcrest): A library of matcher objects (also known as constraints or predicates).
* [Mockito](https://site.mockito.org/): A Java mocking framework.
* [JSONassert](https://github.com/skyscreamer/JSONassert): An assertion library for JSON.
* [JsonPath](https://github.com/jayway/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.
### 8.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](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/testing.html#testing) of the Spring Framework reference documentation.
### 8.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`](#features.testing.spring-boot-applications.detecting-configuration).
In addition to `@SpringBootTest` a number of other annotations are also provided for [testing more specific slices](#features.testing.spring-boot-applications.autoconfigured-tests) 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 web `ApplicationContext` 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-web `ApplicationContext`.
It can be used in conjunction with [`@AutoConfigureMockMvc` or `@AutoConfigureWebTestClient`](#features.testing.spring-boot-applications.with-mock-environment) for mock-based testing of your web application.
* `RANDOM_PORT`: Loads a `WebServerApplicationContext` and provides a real web environment.
Embedded servers are started and listen on a random port.
* `DEFINED_PORT`: Loads a `WebServerApplicationContext` and provides a real web environment.
Embedded servers are started and listen on a defined port (from your `application.properties`) or on the default port of `8080`.
* `NONE`: Loads an `ApplicationContext` by using `SpringApplication` 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.|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.1. 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:
```
import org.springframework.boot.test.context.SpringBootTest;
@SpringBootTest(properties = "spring.main.web-application-type=reactive")
class MyWebFluxTests {
// ...
}
```
#### 8.3.2. 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](using.html#using.structuring-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](#features.testing.spring-boot-applications.autoconfigured-tests), you should avoid adding configuration settings that are specific to a particular area on the [main method’s application class](#features.testing.spring-boot-applications.user-configuration-and-slicing).
The underlying component scan configuration of `@SpringBootApplication` defines exclude filters that are used to make sure slicing works as expected.
If you are using an explicit `@ComponentScan` directive on your `@SpringBootApplication`-annotated class, be aware that those filters will be disabled.
If you are using slicing, you should define them again.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
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.|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.3. 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](#features.testing.spring-boot-applications.detecting-configuration), `@TestConfiguration` can be used on an inner class of a test to customize the primary configuration.
When placed on a top-level class, `@TestConfiguration` indicates that classes in `src/test/java` should not be picked up by scanning.
You can then import that class explicitly where it is required, as shown in the following example:
```
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.annotation.Import;
@SpringBootTest
@Import(MyTestsConfiguration.class)
class MyTests {
@Test
void exampleTest() {
// ...
}
}
```
| |If you directly use `@ComponentScan` (that is, not through `@SpringBootApplication`) you need to register the `TypeExcludeFilter` with it.
See [the Javadoc](https://docs.spring.io/spring-boot/docs/2.6.4/api/org/springframework/boot/context/TypeExcludeFilter.html) for details.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.4. Using Application Arguments
If your application expects [arguments](#features.spring-application.application-arguments), you can
have `@SpringBootTest` inject them using the `args` attribute.
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.test.context.SpringBootTest;
import static org.assertj.core.api.Assertions.assertThat;
@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");
}
}
```
#### 8.3.5. 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`](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/testing.html#spring-mvc-test-framework) or `WebTestClient`, as shown in the following example:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.reactive.server.WebTestClient;
import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@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");
}
}
```
| |If you want to focus only on the web layer and not start a complete `ApplicationContext`, consider [using `@WebMvcTest` instead](#features.testing.spring-boot-applications.spring-mvc-tests).|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
With Spring WebFlux endpoints, you can use [`WebTestClient`](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/testing.html#webtestclient-tests) as shown in the following example:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.AutoConfigureWebTestClient;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.reactive.server.WebTestClient;
@SpringBootTest
@AutoConfigureWebTestClient
class MyMockWebTestClientTests {
@Test
void exampleTest(@Autowired WebTestClient webClient) {
webClient
.get().uri("/")
.exchange()
.expectStatus().isOk()
.expectBody(String.class).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](web.html#web.servlet.spring-mvc.error-handling.error-pages) is rendered.
If you need to test these lower-level concerns, you can start a fully running server as described in the next section.|
|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.6. 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](howto.html#howto.webserver.discover-port) into your test.
For convenience, tests that need to make REST calls to the started server can additionally `@Autowire` a [`WebTestClient`](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/testing.html#webtestclient-tests), which resolves relative links to the running server and comes with a dedicated API for verifying responses, as shown in the following example:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.test.web.reactive.server.WebTestClient;
@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");
}
}
```
| |`WebTestClient` can be used against both live servers and [mock environments](#features.testing.spring-boot-applications.with-mock-environment).|
|---|------------------------------------------------------------------------------------------------------------------------------------------------|
This setup requires `spring-webflux` on the classpath.
If you can not or will not add webflux, Spring Boot also provides a `TestRestTemplate` facility:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.boot.test.web.client.TestRestTemplate;
import static org.assertj.core.api.Assertions.assertThat;
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyRandomPortTestRestTemplateTests {
@Test
void exampleTest(@Autowired TestRestTemplate restTemplate) {
String body = restTemplate.getForObject("/", String.class);
assertThat(body).isEqualTo("Hello World");
}
}
```
#### 8.3.7. 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`.
#### 8.3.8. 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:
```
import javax.management.MBeanServer;
import javax.management.MalformedObjectNameException;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.annotation.DirtiesContext;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import static org.assertj.core.api.Assertions.assertThat;
@ExtendWith(SpringExtension.class)
@SpringBootTest(properties = "spring.jmx.enabled=true")
@DirtiesContext
class MyJmxTests {
@Autowired
private MBeanServer mBeanServer;
@Test
void exampleTest() throws MalformedObjectNameException {
assertThat(this.mBeanServer.getDomains()).contains("java.lang");
// ...
}
}
```
#### 8.3.9. 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`.
#### 8.3.10. 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 `@SpringBootTest`), this feature is automatically enabled.
To use this feature with a different arrangement, listeners must be explicitly added, as shown in the following example:
```
import org.springframework.boot.test.mock.mockito.MockitoTestExecutionListener;
import org.springframework.boot.test.mock.mockito.ResetMocksTestExecutionListener;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.TestExecutionListeners;
@ContextConfiguration(classes = MyConfig.class)
@TestExecutionListeners({ MockitoTestExecutionListener.class, ResetMocksTestExecutionListener.class })
class MyTests {
// ...
}
```|
|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
The following example replaces an existing `RemoteService` bean with a mock implementation:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.BDDMockito.given;
@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");
}
}
```
| |`@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](https://docs.spring.io/spring-boot/docs/2.6.4/api/org/springframework/boot/test/mock/mockito/SpyBean.html) 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.|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.11. 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.|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.12. 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 Jackson `Module`s
* `Gson`
* `Jsonb`
| |A list of the auto-configurations that are enabled by `@JsonTest` can be [found in the appendix](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
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:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.json.JsonTest;
import org.springframework.boot.test.json.JacksonTester;
import static org.assertj.core.api.Assertions.assertThat;
@JsonTest
class MyJsonTests {
@Autowired
private JacksonTester 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");
}
}
```
| |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)));
}
```
#### 8.3.13. 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](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| |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`:|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import static org.mockito.BDDMockito.given;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@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"));
}
}
```
| |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:
```
import com.gargoylesoftware.htmlunit.WebClient;
import com.gargoylesoftware.htmlunit.html.HtmlPage;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.BDDMockito.given;
@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");
}
}
```
| |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 *[howto.html](howto.html#howto.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](#features.testing.spring-boot-applications.with-running-server).|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.14. Auto-configured Spring WebFlux Tests
To test that [Spring WebFlux](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/web-reactive.html) 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](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| |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`](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/testing.html#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`:|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.web.reactive.server.WebTestClient;
import static org.mockito.BDDMockito.given;
@WebFluxTest(UserVehicleController.class)
class MyControllerTests {
@Autowired
private WebTestClient webClient;
@MockBean
private UserVehicleService userVehicleService;
@Test
void testExample() throws Exception {
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");
}
}
```
| |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](#features.testing.spring-boot-applications.with-running-server).|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.15. 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 "[data.html](data.html#data.nosql.cassandra)", earlier in this chapter.)
| |A list of the auto-configuration settings that are enabled by `@DataCassandraTest` can be [found in the appendix](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
The following example shows a typical setup for using Cassandra tests in Spring Boot:
```
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.cassandra.DataCassandraTest;
@DataCassandraTest
class MyDataCassandraTests {
@Autowired
private SomeRepository repository;
}
```
#### 8.3.16. 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](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
By default, data JPA tests are transactional and roll back at the end of each test.
See the [relevant section](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/testing.html#testcontext-tx-enabling-transactions) 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:
```
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;
@DataJpaTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyNonTransactionalTests {
// ...
}
```
Data JPA tests may also inject a [`TestEntityManager`](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/orm/jpa/TestEntityManager.java) 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:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.boot.test.autoconfigure.orm.jpa.TestEntityManager;
import static org.assertj.core.api.Assertions.assertThat;
@DataJpaTest
class MyRepositoryTests {
@Autowired
private TestEntityManager entityManager;
@Autowired
private UserRepository repository;
@Test
void testExample() throws Exception {
this.entityManager.persist(new User("sboot", "1234"));
User user = this.repository.findByUsername("sboot");
assertThat(user.getUsername()).isEqualTo("sboot");
assertThat(user.getEmployeeNumber()).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:
```
import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase;
import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase.Replace;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
@DataJpaTest
@AutoConfigureTestDatabase(replace = Replace.NONE)
class MyRepositoryTests {
// ...
}
```
#### 8.3.17. 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](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
By default, JDBC tests are transactional and roll back at the end of each test.
See the [relevant section](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/testing.html#testcontext-tx-enabling-transactions) 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:
```
import org.springframework.boot.test.autoconfigure.jdbc.JdbcTest;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;
@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](#features.testing.spring-boot-applications.autoconfigured-spring-data-jpa)".)
#### 8.3.18. 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.
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataJdbcTest` annotation is used.`@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](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
By default, Data JDBC tests are transactional and roll back at the end of each test.
See the [relevant section](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/testing.html#testcontext-tx-enabling-transactions) 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](#features.testing.spring-boot-applications.autoconfigured-jdbc).
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](#features.testing.spring-boot-applications.autoconfigured-spring-data-jpa)".)
#### 8.3.19. 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 "[data.html](data.html#data.sql.jooq)", earlier in this chapter.)
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](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
`@JooqTest` configures a `DSLContext`.
The following example shows the `@JooqTest` annotation in use:
```
import org.jooq.DSLContext;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.jooq.JooqTest;
@JooqTest
class MyJooqTests {
@Autowired
private 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](#features.testing.spring-boot-applications.autoconfigured-jdbc).
#### 8.3.20. 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 "[data.html](data.html#data.nosql.mongodb)", earlier in this chapter.)
| |A list of the auto-configuration settings that are enabled by `@DataMongoTest` can be [found in the appendix](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
The following class shows the `@DataMongoTest` annotation in use:
```
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.mongo.DataMongoTest;
import org.springframework.data.mongodb.core.MongoTemplate;
@DataMongoTest
class MyDataMongoDbTests {
@Autowired
private 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:
```
import org.springframework.boot.autoconfigure.mongo.embedded.EmbeddedMongoAutoConfiguration;
import org.springframework.boot.test.autoconfigure.data.mongo.DataMongoTest;
@DataMongoTest(excludeAutoConfiguration = EmbeddedMongoAutoConfiguration.class)
class MyDataMongoDbTests {
// ...
}
```
#### 8.3.21. 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 "[data.html](data.html#data.nosql.neo4j)", earlier in this chapter.)
| |A list of the auto-configuration settings that are enabled by `@DataNeo4jTest` can be [found in the appendix](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
The following example shows a typical setup for using Neo4J tests in Spring Boot:
```
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.neo4j.DataNeo4jTest;
@DataNeo4jTest
class MyDataNeo4jTests {
@Autowired
private SomeRepository repository;
// ...
}
```
By default, Data Neo4j tests are transactional and roll back at the end of each test.
See the [relevant section](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/testing.html#testcontext-tx-enabling-transactions) 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:
```
import org.springframework.boot.test.autoconfigure.data.neo4j.DataNeo4jTest;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;
@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.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.22. 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 "[data.html](data.html#data.nosql.redis)", earlier in this chapter.)
| |A list of the auto-configuration settings that are enabled by `@DataRedisTest` can be [found in the appendix](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
The following example shows the `@DataRedisTest` annotation in use:
```
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.redis.DataRedisTest;
@DataRedisTest
class MyDataRedisTests {
@Autowired
private SomeRepository repository;
// ...
}
```
#### 8.3.23. 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 "[data.html](data.html#data.nosql.ldap)", earlier in this chapter.)
| |A list of the auto-configuration settings that are enabled by `@DataLdapTest` can be [found in the appendix](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
The following example shows the `@DataLdapTest` annotation in use:
```
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.ldap.DataLdapTest;
import org.springframework.ldap.core.LdapTemplate;
@DataLdapTest
class MyDataLdapTests {
@Autowired
private 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:
```
import org.springframework.boot.autoconfigure.ldap.embedded.EmbeddedLdapAutoConfiguration;
import org.springframework.boot.test.autoconfigure.data.ldap.DataLdapTest;
@DataLdapTest(excludeAutoConfiguration = EmbeddedLdapAutoConfiguration.class)
class MyDataLdapTests {
// ...
}
```
#### 8.3.24. 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](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
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:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.client.RestClientTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.client.MockRestServiceServer;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.client.match.MockRestRequestMatchers.requestTo;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withSuccess;
@RestClientTest(RemoteVehicleDetailsService.class)
class MyRestClientTests {
@Autowired
private RemoteVehicleDetailsService service;
@Autowired
private MockRestServiceServer server;
@Test
void getVehicleDetailsWhenResultIsSuccessShouldReturnDetails() throws Exception {
this.server.expect(requestTo("/greet/details")).andRespond(withSuccess("hello", MediaType.TEXT_PLAIN));
String greeting = this.service.callRestService();
assertThat(greeting).isEqualTo("hello");
}
}
```
#### 8.3.25. Auto-configured Spring REST Docs Tests
You can use the `@AutoConfigureRestDocs` annotation to use [Spring REST Docs](https://spring.io/projects/spring-restdocs) 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:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@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"));
}
}
```
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:
```
import org.springframework.boot.test.autoconfigure.restdocs.RestDocsMockMvcConfigurationCustomizer;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentationConfigurer;
import org.springframework.restdocs.templates.TemplateFormats;
@TestConfiguration(proxyBeanMethods = false)
public class MyRestDocsConfiguration implements RestDocsMockMvcConfigurationCustomizer {
@Override
public void customize(MockMvcRestDocumentationConfigurer configurer) {
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:
```
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;
import org.springframework.restdocs.mockmvc.RestDocumentationResultHandler;
@TestConfiguration(proxyBeanMethods = false)
public class MyResultHandlerConfiguration {
@Bean
public RestDocumentationResultHandler restDocumentation() {
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:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.test.web.reactive.server.WebTestClient;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;
@WebFluxTest
@AutoConfigureRestDocs
class MyUsersDocumentationTests {
@Autowired
private WebTestClient webTestClient;
@Test
void listUsers() {
this.webTestClient
.get().uri("/")
.exchange()
.expectStatus()
.isOk()
.expectBody()
.consumeWith(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:
```
import org.springframework.boot.test.autoconfigure.restdocs.RestDocsWebTestClientConfigurationCustomizer;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.restdocs.webtestclient.WebTestClientRestDocumentationConfigurer;
@TestConfiguration(proxyBeanMethods = false)
public class MyRestDocsConfiguration implements RestDocsWebTestClientConfigurationCustomizer {
@Override
public void customize(WebTestClientRestDocumentationConfigurer configurer) {
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:
```
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.test.web.reactive.server.WebTestClientBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;
@TestConfiguration(proxyBeanMethods = false)
public class MyWebTestClientBuilderCustomizerConfiguration {
@Bean
public WebTestClientBuilderCustomizer restDocumentation() {
return (builder) -> builder.entityExchangeResultConsumer(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:
```
import io.restassured.specification.RequestSpecification;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.boot.web.server.LocalServerPort;
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.is;
import static org.springframework.restdocs.restassured3.RestAssuredRestDocumentation.document;
@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));
}
}
```
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:
```
import org.springframework.boot.test.autoconfigure.restdocs.RestDocsRestAssuredConfigurationCustomizer;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.restdocs.restassured3.RestAssuredRestDocumentationConfigurer;
import org.springframework.restdocs.templates.TemplateFormats;
@TestConfiguration(proxyBeanMethods = false)
public class MyRestDocsConfiguration implements RestDocsRestAssuredConfigurationCustomizer {
@Override
public void customize(RestAssuredRestDocumentationConfigurer configurer) {
configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
}
}
```
#### 8.3.26. 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 "[io.html](io.html#io.webservices)", earlier in this chapter.)
| |A list of the auto-configuration settings that are enabled by `@WebServiceClientTest` can be [found in the appendix](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
The following example shows the `@WebServiceClientTest` annotation in use:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.webservices.client.WebServiceClientTest;
import org.springframework.ws.test.client.MockWebServiceServer;
import org.springframework.xml.transform.StringSource;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.ws.test.client.RequestMatchers.payload;
import static org.springframework.ws.test.client.ResponseCreators.withPayload;
@WebServiceClientTest(SomeWebService.class)
class MyWebServiceClientTests {
@Autowired
private MockWebServiceServer server;
@Autowired
private SomeWebService someWebService;
@Test
void mockServerCall() {
this.server
.expect(payload(new StringSource("")))
.andRespond(withPayload(new StringSource("200")));
assertThat(this.someWebService.test())
.extracting(Response::getStatus)
.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 "[io.html](io.html#io.webservices)", earlier in this chapter.)
| |A list of the auto-configuration settings that are enabled by `@WebServiceServerTest` can be [found in the appendix](test-auto-configuration.html#appendix.test-auto-configuration).|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
The following example shows the `@WebServiceServerTest` annotation in use:
```
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.webservices.server.WebServiceServerTest;
import org.springframework.ws.test.server.MockWebServiceClient;
import org.springframework.ws.test.server.RequestCreators;
import org.springframework.ws.test.server.ResponseMatchers;
import org.springframework.xml.transform.StringSource;
@WebServiceServerTest(ExampleEndpoint.class)
class MyWebServiceServerTests {
@Autowired
private MockWebServiceClient client;
@Test
void mockServerCall() {
this.client
.sendRequest(RequestCreators.withPayload(new StringSource("")))
.andExpect(ResponseMatchers.payload(new StringSource("42")));
}
}
```
#### 8.3.27. 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:
```
import org.springframework.boot.autoconfigure.ImportAutoConfiguration;
import org.springframework.boot.autoconfigure.integration.IntegrationAutoConfiguration;
import org.springframework.boot.test.autoconfigure.jdbc.JdbcTest;
@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 `META-INF/spring.factories` as shown in the following example:
```
org.springframework.boot.test.autoconfigure.jdbc.JdbcTest=com.example.IntegrationAutoConfiguration
```
| |A slice or `@AutoConfigure…` annotation can be customized this way as long as it is meta-annotated with `@ImportAutoConfiguration`.|
|---|------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.28. User Configuration and Slicing
If you [structure your code](using.html#using.structuring-your-code) in a sensible way, your `@SpringBootApplication` class is [used by default](#features.testing.spring-boot-applications.detecting-configuration) 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:
```
import org.springframework.batch.core.configuration.annotation.EnableBatchProcessing;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
@EnableBatchProcessing
public 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:
```
import org.springframework.batch.core.configuration.annotation.EnableBatchProcessing;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
@EnableBatchProcessing
public 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.|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
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:
```
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration(proxyBeanMethods = false)
public class MyWebConfiguration {
@Bean
public WebMvcConfigurer testConfigurer() {
return new WebMvcConfigurer() {
// ...
};
}
}
```
The configuration below will, however, cause the custom `WebMvcConfigurer` to be loaded by the test slice.
```
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Component
public class MyWebMvcConfigurer implements 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:
```
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
@SpringBootApplication
@ComponentScan({ "com.example.app", "com.example.another" })
public 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.|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.3.29. 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](https://spockframework.org/spock/docs/2.0/modules.html#_spring_module) for further details.
### 8.4. Test Utilities
A few test utility classes that are generally useful when testing your application are packaged as part of `spring-boot`.
#### 8.4.1. 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:
```
import org.springframework.boot.test.context.ConfigDataApplicationContextInitializer;
import org.springframework.test.context.ContextConfiguration;
@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.|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 8.4.2. TestPropertyValues
`TestPropertyValues` lets you quickly add properties to a `ConfigurableEnvironment` or `ConfigurableApplicationContext`.
You can call it with `key=value` strings, as follows:
```
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.util.TestPropertyValues;
import org.springframework.mock.env.MockEnvironment;
import static org.assertj.core.api.Assertions.assertThat;
class MyEnvironmentTests {
@Test
void testPropertySources() {
MockEnvironment environment = new MockEnvironment();
TestPropertyValues.of("org=Spring", "name=Boot").applyTo(environment);
assertThat(environment.getProperty("name")).isEqualTo("Boot");
}
}
```
#### 8.4.3. 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:
```
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.boot.test.system.CapturedOutput;
import org.springframework.boot.test.system.OutputCaptureExtension;
import static org.assertj.core.api.Assertions.assertThat;
@ExtendWith(OutputCaptureExtension.class)
class MyOutputCaptureTests {
@Test
void testName(CapturedOutput output) {
System.out.println("Hello World!");
assertThat(output).contains("World");
}
}
```
#### 8.4.4. 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](#features.testing.spring-boot-applications.spring-webflux-tests) and both [WebFlux and MVC end-to-end testing](#features.testing.spring-boot-applications.with-running-server).
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:
```
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.http.ResponseEntity;
import static org.assertj.core.api.Assertions.assertThat;
class MyTests {
private TestRestTemplate template = new TestRestTemplate();
@Test
void testRequest() throws Exception {
ResponseEntity headers = this.template.getForEntity("https://myhost.example.com/example", String.class);
assertThat(headers.getHeaders().getLocation()).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:
```
import java.time.Duration;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.http.HttpHeaders;
import static org.assertj.core.api.Assertions.assertThat;
@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));
}
}
}
```
## 9. 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](#features.developing-auto-configuration.custom-starter).
| |A [demo project](https://github.com/snicoll-demos/spring-boot-master-auto-configuration) is available to showcase how you can create a starter step-by-step.|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 9.1. Understanding Auto-configured Beans
Under the hood, auto-configuration is implemented with 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`](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure) to see the `@Configuration` classes that Spring provides (see the [`META-INF/spring.factories`](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot-autoconfigure/src/main/resources/META-INF/spring.factories) file).
### 9.2. Locating Auto-configuration Candidates
Spring Boot checks for the presence of a `META-INF/spring.factories` file within your published jar.
The file should list your configuration classes under the `EnableAutoConfiguration` key, as shown in the following example:
```
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.mycorp.libx.autoconfigure.LibXAutoConfiguration,\
com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration
```
| |Auto-configurations must be loaded that way *only*.
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.|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
You can use the [`@AutoConfigureAfter`](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureAfter.java) or [`@AutoConfigureBefore`](https://github.com/spring-projects/spring-boot/tree/v2.6.4/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureBefore.java) annotations if your configuration needs to be applied in a specific order.
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.
### 9.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](#features.developing-auto-configuration.condition-annotations.class-conditions)
* [Bean Conditions](#features.developing-auto-configuration.condition-annotations.bean-conditions)
* [Property Conditions](#features.developing-auto-configuration.condition-annotations.property-conditions)
* [Resource Conditions](#features.developing-auto-configuration.condition-annotations.resource-conditions)
* [Web Application Conditions](#features.developing-auto-configuration.condition-annotations.web-application-conditions)
* [SpEL Expression Conditions](#features.developing-auto-configuration.condition-annotations.spel-conditions)
#### 9.3.1. 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](https://asm.ow2.io/), 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:
```
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
// 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();
}
}
}
```
| |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.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 9.3.2. 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:
```
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
public class MyAutoConfiguration {
@Bean
@ConditionalOnMissingBean
public SomeService someService() {
return new 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.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
#### 9.3.3. 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.
#### 9.3.4. 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`.
#### 9.3.5. 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` annotation lets configuration be included depending on whether the application is a traditional WAR application that is deployed to a container.
This condition will not match for applications that are run with an embedded server.
#### 9.3.6. SpEL Expression Conditions
The `@ConditionalOnExpression` annotation lets configuration be included based on the result of a [SpEL expression](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/core.html#expressions).
| |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.|
|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 9.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));
```
| |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");
}
}
```
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");
});
}
```
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.
```
import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener;
import org.springframework.boot.logging.LogLevel;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
class MyConditionEvaluationReportingTests {
@Test
void autoConfigTest() {
new ApplicationContextRunner()
.withInitializer(new ConditionEvaluationReportLoggingListener(LogLevel.INFO))
.run((context) -> {
// Test something...
});
}
}
```
#### 9.4.1. 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.
#### 9.4.2. 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"));
}
```
### 9.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 the `autoconfigure` 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.
#### 9.5.1. 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`.
#### 9.5.2. 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:
```
import java.time.Duration;
import org.springframework.boot.context.properties.ConfigurationProperties;
@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);
// getters/setters ...
public boolean isCheckLocation() {
return this.checkLocation;
}
public void setCheckLocation(boolean checkLocation) {
this.checkLocation = checkLocation;
}
public Duration getLoginTimeout() {
return this.loginTimeout;
}
public void setLoginTimeout(Duration loginTimeout) {
this.loginTimeout = loginTimeout;
}
}
```
| |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 than `long` 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](configuration-metadata.html#appendix.configuration-metadata.annotation-processor) 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.
#### 9.5.3. 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.
It is recommended to add the following dependency in a module that contains auto-configurations:
```
org.springframework.boot
spring-boot-autoconfigure-processor
true
```
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:
```
org.springframework.boot
spring-boot-maven-plugin
org.springframework.boot
spring-boot-autoconfigure-processor
```
With Gradle 4.5 and earlier, the dependency should be declared in the `compileOnly` configuration, as shown in the following example:
```
dependencies {
compileOnly "org.springframework.boot:spring-boot-autoconfigure-processor"
}
```
With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example:
```
dependencies {
annotationProcessor "org.springframework.boot:spring-boot-autoconfigure-processor"
}
```
#### 9.5.4. 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.|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
## 10. Kotlin support
[Kotlin](https://kotlinlang.org) is a statically-typed language targeting the JVM (and other platforms) which allows writing concise and elegant code while providing [interoperability](https://kotlinlang.org/docs/reference/java-interop.html) 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](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/languages.html#kotlin) for more information.
The easiest way to start with Spring Boot and Kotlin is to follow [this comprehensive tutorial](https://spring.io/guides/tutorials/spring-boot-kotlin/).
You can create new Kotlin projects by using [start.spring.io](https://start.spring.io/#!language=kotlin).
Feel free to join the #spring channel of [Kotlin Slack](https://slack.kotlinlang.org/) or ask a question with the `spring` and `kotlin` tags on [Stack Overflow](https://stackoverflow.com/questions/tagged/spring+kotlin) if you need support.
### 10.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](https://discuss.kotlinlang.org/t/classes-final-by-default/166), you are likely to want to configure [kotlin-spring](https://kotlinlang.org/docs/reference/compiler-plugins.html#spring-support) plugin in order to automatically open Spring-annotated classes so that they can be proxied.
[Jackson’s Kotlin module](https://github.com/FasterXML/jackson-module-kotlin) 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](https://start.spring.io/#!language=kotlin).|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------|
### 10.2. Null-safety
One of Kotlin’s key features is [null-safety](https://kotlinlang.org/docs/reference/null-safety.html).
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](https://www.baeldung.com/kotlin-null-safety).
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](https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types) for which null-checks are relaxed.[Kotlin’s support for JSR 305 annotations](https://kotlinlang.org/docs/reference/java-interop.html#jsr-305-support) 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](https://jira.spring.io/browse/SPR-15942) for up-to-date information.
Also be aware that Spring Boot’s own API is [not yet annotated](https://github.com/spring-projects/spring-boot/issues/10712).|
|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 10.3. Kotlin API
#### 10.3.1. runApplication
Spring Boot provides an idiomatic way to run an application with `runApplication(*args)` as shown in the following example:
```
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
@SpringBootApplication
class MyApplication
fun main(args: Array) {
runApplication(*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(*args) {
setBannerMode(OFF)
}
```
#### 10.3.2. Extensions
Kotlin [extensions](https://kotlinlang.org/docs/reference/extensions.html) 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.
### 10.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](https://start.spring.io/#!language=kotlin).|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 10.5. @ConfigurationProperties
`@ConfigurationProperties` when used in combination with [`@ConstructorBinding`](#features.external-config.typesafe-configuration-properties.constructor-binding) 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](configuration-metadata.html#appendix.configuration-metadata.annotation-processor) using the annotation processor, [`kapt` should be configured](https://kotlinlang.org/docs/reference/kapt.html) 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.|
|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### 10.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](https://mockk.io/) is recommended.
If you need the `Mockk` equivalent of the Mockito specific [`@MockBean` and `@SpyBean` annotations](#features.testing.spring-boot-applications.mocking-beans), you can use [SpringMockK](https://github.com/Ninja-Squad/springmockk) which provides similar `@MockkBean` and `@SpykBean` annotations.
### 10.7. Resources
#### 10.7.1. Further reading
* [Kotlin language reference](https://kotlinlang.org/docs/reference/)
* [Kotlin Slack](https://kotlinlang.slack.com/) (with a dedicated #spring channel)
* [Stackoverflow with `spring` and `kotlin` tags](https://stackoverflow.com/questions/tagged/spring+kotlin)
* [Try Kotlin in your browser](https://try.kotlinlang.org/)
* [Kotlin blog](https://blog.jetbrains.com/kotlin/)
* [Awesome Kotlin](https://kotlin.link/)
* [Tutorial: building web applications with Spring Boot and Kotlin](https://spring.io/guides/tutorials/spring-boot-kotlin/)
* [Developing Spring Boot applications with Kotlin](https://spring.io/blog/2016/02/15/developing-spring-boot-applications-with-kotlin)
* [A Geospatial Messenger with Kotlin, Spring Boot and PostgreSQL](https://spring.io/blog/2016/03/20/a-geospatial-messenger-with-kotlin-spring-boot-and-postgresql)
* [Introducing Kotlin support in Spring Framework 5.0](https://spring.io/blog/2017/01/04/introducing-kotlin-support-in-spring-framework-5-0)
* [Spring Framework 5 Kotlin APIs, the functional way](https://spring.io/blog/2017/08/01/spring-framework-5-kotlin-apis-the-functional-way)
#### 10.7.2. Examples
* [spring-boot-kotlin-demo](https://github.com/sdeleuze/spring-boot-kotlin-demo): regular Spring Boot + Spring Data JPA project
* [mixit](https://github.com/mixitconf/mixit): Spring Boot 2 + WebFlux + Reactive Spring Data MongoDB
* [spring-kotlin-fullstack](https://github.com/sdeleuze/spring-kotlin-fullstack): WebFlux Kotlin fullstack example with Kotlin2js for frontend instead of JavaScript or TypeScript
* [spring-petclinic-kotlin](https://github.com/spring-petclinic/spring-petclinic-kotlin): Kotlin version of the Spring PetClinic Sample Application
* [spring-kotlin-deepdive](https://github.com/sdeleuze/spring-kotlin-deepdive): a step by step migration for Boot 1.0 + Java to Boot 2.0 + Kotlin
* [spring-boot-coroutines-demo](https://github.com/sdeleuze/spring-boot-coroutines-demo): Coroutines sample project
## 11. 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](https://docs.spring.io/spring-boot/docs/2.6.4/api/) or you can browse the [source code directly](https://github.com/spring-projects/spring-boot/tree/v2.6.4).
If you have specific questions, see the [how-to](howto.html#howto) section.
If you are comfortable with Spring Boot’s core features, you can continue on and read about [production-ready features](actuator.html#actuator).