@ -442,11 +442,11 @@ For example, you might declare the following section in `application.properties`
TIP: You do not need to specify a driver class name, since Spring Boot obtains the driver from R2DBC's Connection Factory discovery.
TIP: You do not need to specify a driver class name, since Spring Boot obtains the driver from R2DBC's Connection Factory discovery.
NOTE: At least the url should be provided.
NOTE: At least the url should be provided.
Information specified in the URL takes precedence over individual properties, i.e. `name`, `username`, `password` and pooling options.
Information specified in the URL takes precedence over individual properties, that is `name`, `username`, `password` and pooling options.
TIP: The "`How-to`" section includes a <<howto#howto.data-initialization.using-basic-sql-scripts, section on how to initialize a database>>.
TIP: The "`How-to`" section includes a <<howto#howto.data-initialization.using-basic-sql-scripts, section on how to initialize a database>>.
To customize the connections created by a `ConnectionFactory`, i.e., set specific parameters that you do not want (or cannot) configure in your central database configuration, you can use a `ConnectionFactoryOptionsBuilderCustomizer` `@Bean`.
To customize the connections created by a `ConnectionFactory`, that is, set specific parameters that you do not want (or cannot) configure in your central database configuration, you can use a `ConnectionFactoryOptionsBuilderCustomizer` `@Bean`.
The following example shows how to manually override the database port while the rest of the options is taken from the application configuration:
The following example shows how to manually override the database port while the rest of the options is taken from the application configuration:
@ -245,7 +245,7 @@ If you only have one module that combines the two, name it `acme-spring-boot-sta
If your starter provides configuration keys, use a unique namespace for them.
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).
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.
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 (e.g. `acme`).
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:
Make sure that configuration keys are documented by adding field javadoc for each property, as shown in the following example:
@ -261,7 +261,7 @@ Here are some rules we follow internally to make sure descriptions are consisten
* Do not start the description by "The" or "A".
* Do not start the description by "The" or "A".
* For `boolean` types, start the description with "Whether" or "Enable".
* For `boolean` types, start the description with "Whether" or "Enable".
* For collection-based types, start the description with "Comma-separated list"
* 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, e.g. "If a duration suffix is not specified, seconds will be used".
* Use `java.time.Duration` rather than `long` and describe the default unit if it differs from milliseconds, for example "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.
* Do not provide the default value in the description unless it has to be determined at runtime.
Make sure to <<configuration-metadata#configuration-metadata.annotation-processor,trigger meta-data generation>> so that IDE assistance is available for your keys as well.
Make sure to <<configuration-metadata#configuration-metadata.annotation-processor,trigger meta-data generation>> so that IDE assistance is available for your keys as well.
@ -346,5 +346,5 @@ If the library you are auto-configuring typically requires other starters, menti
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.
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.
In other words, you should not include optional dependencies.
NOTE: Either way, your starter must reference the core Spring Boot starter (`spring-boot-starter`) directly or indirectly (i.e. no need to add it if your starter relies on another starter).
NOTE: 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.
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.
NOTE: To use constructor binding the class must be enabled using `@EnableConfigurationProperties` or configuration property scanning.
NOTE: 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 (e.g. `@Component` beans, beans created via `@Bean` methods or beans loaded using `@Import`)
You cannot use constructor binding with beans that are created by the regular Spring mechanisms (for example `@Component` beans, beans created via `@Bean` methods or beans loaded using `@Import`)
TIP: If you have more than one constructor for your class you can also use `@ConstructorBinding` directly on the constructor that should be bound.
TIP: If you have more than one constructor for your class you can also use `@ConstructorBinding` directly on the constructor that should be bound.
@ -1048,7 +1048,7 @@ If you expose a `java.time.Duration` property, the following formats in applicat
* A regular `long` representation (using milliseconds as the default unit unless a `@DurationUnit` has been specified)
* A regular `long` representation (using milliseconds as the default unit unless a `@DurationUnit` has been specified)
* The standard ISO-8601 format {java-api}/java/time/Duration.html#parse-java.lang.CharSequence-[used by `java.time.Duration`]
* The standard ISO-8601 format {java-api}/java/time/Duration.html#parse-java.lang.CharSequence-[used by `java.time.Duration`]
* A more readable format where the value and the unit are coupled (e.g. `10s` means 10 seconds)
* A more readable format where the value and the unit are coupled (for example `10s` means 10 seconds)
Consider the following example:
Consider the following example:
@ -1093,7 +1093,7 @@ 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)
* An regular `int` representation (using days as the default unit unless a `@PeriodUnit` has been specified)
* The standard ISO-8601 format {java-api}/java/time/Period.html#parse-java.lang.CharSequence-[used by `java.time.Period`]
* The standard ISO-8601 format {java-api}/java/time/Period.html#parse-java.lang.CharSequence-[used by `java.time.Period`]
* A simpler format where the value and the unit pairs are coupled (e.g. `1y3d` means 1 year and 3 days)
* A simpler format where the value and the unit pairs are coupled (for example `1y3d` means 1 year and 3 days)
The following units are supported with the simple format:
The following units are supported with the simple format:
@ -1112,7 +1112,7 @@ 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:
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 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 (e.g. `10MB` means 10 megabytes)
* A more readable format where the value and the unit are coupled (for example `10MB` means 10 megabytes)
Spring Boot supports localized messages so that your application can cater to users of different language preferences.
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.
By default, Spring Boot looks for the presence of a `messages` resource bundle at the root of the classpath.
NOTE: The auto-configuration applies when the default properties file for the configured resource bundle is available (i.e. `messages.properties` by default).
NOTE: The auto-configuration applies when the default properties file for the configured resource bundle is available (that is `messages.properties` by default).
If your resource bundle contains only language-specific properties files, you are required to add the 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`.
If no properties file is found that matches any of the configured base names, there will be no auto-configured `MessageSource`.
@ -4,7 +4,7 @@ In the absence of an `Executor` bean in the context, Spring Boot auto-configures
[TIP]
[TIP]
====
====
If you have defined a custom `Executor` in the context, regular task execution (i.e. `@EnableAsync`) will use it transparently but the Spring MVC support will not be configured as it requires an `AsyncTaskExecutor` implementation (named `applicationTaskExecutor`).
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`.
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 auto-configured `TaskExecutorBuilder` allows you to easily create instances that reproduce what the auto-configuration does by default.
@ -27,7 +27,7 @@ Those default settings can be fine-tuned using the `spring.task.execution` names
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.
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).
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 (e.g. `@EnableScheduling`).
A `ThreadPoolTaskScheduler` can also be auto-configured if need to be associated to scheduled task execution (for example `@EnableScheduling`).
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:
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:
@ -36,8 +36,8 @@ See also the section on "`<<web#web.servlet.spring-mvc.error-handling, Error Han
[[howto.actuator.sanitize-sensitive-values]]
[[howto.actuator.sanitize-sensitive-values]]
=== Sanitize Sensitive Values
=== Sanitize Sensitive Values
Information returned by the `env` and `configprops` endpoints can be somewhat sensitive so keys matching certain patterns are sanitized by default (i.e. their values are replaced by `+******+`). Spring Boot uses sensible defaults for such keys: any key ending with the word "password", "secret", "key", "token", "vcap_services", "sun.java.command" is entirely sanitized.
Information returned by the `env` and `configprops` endpoints can be somewhat sensitive so keys matching certain patterns are sanitized by default (that is their values are replaced by `+******+`). Spring Boot uses sensible defaults for such keys: any key ending with the word "password", "secret", "key", "token", "vcap_services", "sun.java.command" is entirely sanitized.
Additionally, any key that holds the word `credentials` (configured as a regular expression, i.e. `+*credentials.*+`) as part of the key is also entirely sanitized.
Additionally, any key that holds the word `credentials` (configured as a regular expression, that is `+*credentials.*+`) as part of the key is also entirely sanitized.
Furthermore, Spring Boot sanitizes the sensitive portion of URI-like values for keys with one of the following endings:
Furthermore, Spring Boot sanitizes the sensitive portion of URI-like values for keys with one of the following endings:
@ -106,6 +106,6 @@ See "`<<features#features.spring-application.fluent-builder-api>>`" in the '`Spr
Not all Spring applications have to be web applications (or web services).
Not all Spring applications have to be web applications (or web services).
If you want to execute some code in a `main` method but also bootstrap a Spring application to set up the infrastructure to use, you can use the `SpringApplication` features of Spring Boot.
If you want to execute some code in a `main` method but also bootstrap a Spring application to set up the infrastructure to use, you can use the `SpringApplication` features of Spring Boot.
A `SpringApplication` changes its `ApplicationContext` class, depending on whether it thinks it needs a web application or not.
A `SpringApplication` changes its `ApplicationContext` class, depending on whether it thinks it needs a web application or not.
The first thing you can do to help it is to leave server-related dependencies (e.g. servlet API) off the classpath.
The first thing you can do to help it is to leave server-related dependencies (for example servlet API) off the classpath.
If you cannot do that (for example, you run two applications from the same code base) then you can explicitly call `setWebApplicationType(WebApplicationType.NONE)` on your `SpringApplication` instance or set the `applicationContextClass` property (through the Java API or with external properties).
If you cannot do that (for example, you run two applications from the same code base) then you can explicitly call `setWebApplicationType(WebApplicationType.NONE)` on your `SpringApplication` instance or set the `applicationContextClass` property (through the Java API or with external properties).
Application code that you want to run as your business logic can be implemented as a `CommandLineRunner` and dropped into the context as a `@Bean` definition.
Application code that you want to run as your business logic can be implemented as a `CommandLineRunner` and dropped into the context as a `@Bean` definition.
@ -33,7 +33,7 @@ See {spring-boot-autoconfigure-module-code}/batch/BatchAutoConfiguration.java[Ba
=== Running from the Command Line
=== Running from the Command Line
Spring Boot converts any command line argument starting with `--` to a property to add to the `Environment`, see <<features#features.external-config.command-line-args,accessing command line properties>>.
Spring Boot converts any command line argument starting with `--` to a property to add to the `Environment`, see <<features#features.external-config.command-line-args,accessing command line properties>>.
This should not be used to pass arguments to batch jobs.
This should not be used to pass arguments to batch jobs.
To specify batch arguments on the command line, use the regular format (i.e. without `--`), as shown in the following example:
To specify batch arguments on the command line, use the regular format (that is without `--`), as shown in the following example:
@ -162,7 +162,7 @@ To automatically run Liquibase database migrations on startup, add the `org.liqu
====
====
When you add the `org.liquibase:liquibase-core` to your classpath, database migrations run by default for both during application startup and before your tests run.
When you add the `org.liquibase:liquibase-core` to your classpath, database migrations run by default for both during application startup and before your tests run.
This behavior can be customized by using the configprop:spring.liquibase.enabled[] property, setting different values in the `main` and `test` configurations.
This behavior can be customized by using the configprop:spring.liquibase.enabled[] property, setting different values in the `main` and `test` configurations.
It is not possible to use two different ways to initialize the database (e.g. Liquibase for application startup, JPA for test runs).
It is not possible to use two different ways to initialize the database (for example Liquibase for application startup, JPA for test runs).
====
====
By default, the master change log is read from `db/changelog/db.changelog-master.yaml`, but you can change the location by setting `spring.liquibase.change-log`.
By default, the master change log is read from `db/changelog/db.changelog-master.yaml`, but you can change the location by setting `spring.liquibase.change-log`.
@ -284,7 +284,7 @@ When you do so, auto-configured customizers are still applied on your custom fac
[[howto.webserver.add-servlet-filter-listener]]
[[howto.webserver.add-servlet-filter-listener]]
=== Add a Servlet, Filter, or Listener to an Application
=== Add a Servlet, Filter, or Listener to an Application
In a servlet stack application, i.e. with the `spring-boot-starter-web`, there are two ways to add `Servlet`, `Filter`, `ServletContextListener`, and the other listeners supported by the Servlet API to your application:
In a servlet stack application, that is with the `spring-boot-starter-web`, there are two ways to add `Servlet`, `Filter`, `ServletContextListener`, and the other listeners supported by the Servlet API to your application:
@ -33,7 +33,7 @@ The required dependencies are provided by the `spring-boot-starter-rsocket`.
Spring Boot allows exposing RSocket over WebSocket from a WebFlux server, or standing up an independent RSocket server.
Spring Boot allows exposing RSocket over WebSocket from a WebFlux server, or standing up an independent RSocket server.
This depends on the type of application and its configuration.
This depends on the type of application and its configuration.
For WebFlux application (i.e. of type `WebApplicationType.REACTIVE`), the RSocket server will be plugged into the Web Server only if the following properties match:
For WebFlux application (that is of type `WebApplicationType.REACTIVE`), the RSocket server will be plugged into the Web Server only if the following properties match:
TIP: While the buildpack runs from an <<packaging,executable archive>>, it is not necessary to execute the `repackage` goal first as the executable archive is created automatically if necessary.
TIP: While the buildpack runs from an <<packaging,executable archive>>, it is not necessary to execute the `repackage` goal first as the executable archive is created automatically if necessary.
When the `build-image` repackages the application, it applies the same settings as the `repackage` goal would, i.e. dependencies can be excluded using one of the exclude options, and Devtools is automatically excluded by default (you can control that using the `excludeDevtools` property).
When the `build-image` repackages the application, it applies the same settings as the `repackage` goal would, that is dependencies can be excluded using one of the exclude options, and Devtools is automatically excluded by default (you can control that using the `excludeDevtools` property).
@ -32,7 +32,7 @@ The following table shows the environment variables and their values:
| Environment variable | Description
| Environment variable | Description
| DOCKER_HOST
| DOCKER_HOST
| URL containing the host and port for the Docker daemon - e.g. `tcp://192.168.99.100:2376`
| URL containing the host and port for the Docker daemon - for example `tcp://192.168.99.100:2376`
| DOCKER_TLS_VERIFY
| DOCKER_TLS_VERIFY
| Enable secure HTTPS protocol when set to `1` (optional)
| Enable secure HTTPS protocol when set to `1` (optional)
@ -50,7 +50,7 @@ The following table summarizes the available parameters:
| Parameter | Description
| Parameter | Description
| `host`
| `host`
| URL containing the host and port for the Docker daemon - e.g. `tcp://192.168.99.100:2376`
| URL containing the host and port for the Docker daemon - for example `tcp://192.168.99.100:2376`
| `tlsVerify`
| `tlsVerify`
| Enable secure HTTPS protocol when set to `true` (optional)
| Enable secure HTTPS protocol when set to `true` (optional)
@ -14,7 +14,7 @@ TIP: If you are using `spring-boot-starter-parent`, such execution is already pr
The example above repackages a `jar` or `war` archive that is built during the package phase of the Maven lifecycle, including any `provided` dependencies that are defined in the project.
The example above repackages a `jar` or `war` archive that is built during the package phase of the Maven lifecycle, including any `provided` dependencies that are defined in the project.
If some of these dependencies need to be excluded, you can use one of the `exclude` options; see the <<packaging.examples.exclude-dependency,dependency exclusion>> for more details.
If some of these dependencies need to be excluded, you can use one of the `exclude` options; see the <<packaging.examples.exclude-dependency,dependency exclusion>> for more details.
The original (i.e. non-executable) artifact is renamed to `.original` by default but it is also possible to keep the original artifact using a custom classifier.
The original (that is non-executable) artifact is renamed to `.original` by default but it is also possible to keep the original artifact using a custom classifier.
NOTE: The `outputFileNameMapping` feature of the `maven-war-plugin` is currently not supported.
NOTE: The `outputFileNameMapping` feature of the `maven-war-plugin` is currently not supported.
@ -10,7 +10,7 @@ The plugin includes a run goal which can be used to launch your application from
Application arguments can be specified using the `arguments` parameter, see <<run.examples.using-application-arguments,using application arguments>> for more details.
Application arguments can be specified using the `arguments` parameter, see <<run.examples.using-application-arguments,using application arguments>> for more details.
By default the application is executed in a forked process and setting properties on the command-line will not affect the application.
By default the application is executed in a forked process and setting properties on the command-line will not affect the application.
If you need to specify some JVM arguments (i.e. for debugging purposes), you can use the `jvmArguments` parameter, see <<run.examples.debug,Debug the application>> for more details.
If you need to specify some JVM arguments (that is for debugging purposes), you can use the `jvmArguments` parameter, see <<run.examples.debug,Debug the application>> for more details.
There is also explicit support for <<run.examples.system-properties,system properties>> and <<run.examples.environment-variables,environment variables>>.
There is also explicit support for <<run.examples.system-properties,system properties>> and <<run.examples.environment-variables,environment variables>>.
As enabling a profile is quite common, there is dedicated `profiles` property that offers a shortcut for `-Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev"`, see <<run.examples.specify-active-profiles,Specify active profiles>>.
As enabling a profile is quite common, there is dedicated `profiles` property that offers a shortcut for `-Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev"`, see <<run.examples.specify-active-profiles,Specify active profiles>>.
@ -101,11 +101,11 @@ The following example sets `property1` to `test` and `property2` to 42:
If the value is empty or not defined (i.e. `<my-property/`>), the system property is set with an empty String as the value.
If the value is empty or not defined (that is `<my-property/`>), the system property is set with an empty String as the value.
Maven trims values specified in the pom so it is not possible to specify a System property which needs to start or end with a space via this mechanism: consider using `jvmArguments` instead.
Maven trims values specified in the pom so it is not possible to specify a System property which needs to start or end with a space via this mechanism: consider using `jvmArguments` instead.
Any String typed Maven variable can be passed as system properties.
Any String typed Maven variable can be passed as system properties.
Any attempt to pass any other Maven variable type (e.g. a `List` or a `URL` variable) will cause the variable expression to be passed literally (unevaluated).
Any attempt to pass any other Maven variable type (for example a `List` or a `URL` variable) will cause the variable expression to be passed literally (unevaluated).
The `jvmArguments` parameter takes precedence over system properties defined with the mechanism above.
The `jvmArguments` parameter takes precedence over system properties defined with the mechanism above.
In the following example, the value for `property1` is `overridden`:
In the following example, the value for `property1` is `overridden`:
@ -127,11 +127,11 @@ The following example sets the 'ENV1', 'ENV2', 'ENV3', 'ENV4' env variables:
If the value is empty or not defined (i.e. `<MY_ENV/`>), the env variable is set with an empty String as the value.
If the value is empty or not defined (that is `<MY_ENV/`>), the env variable is set with an empty String as the value.
Maven trims values specified in the pom so it is not possible to specify an env variable which needs to start or end with a space.
Maven trims values specified in the pom so it is not possible to specify an env variable which needs to start or end with a space.
Any String typed Maven variable can be passed as system properties.
Any String typed Maven variable can be passed as system properties.
Any attempt to pass any other Maven variable type (e.g. a `List` or a `URL` variable) will cause the variable expression to be passed literally (unevaluated).
Any attempt to pass any other Maven variable type (for example a `List` or a `URL` variable) will cause the variable expression to be passed literally (unevaluated).
Environment variables defined this way take precedence over existing values.
Environment variables defined this way take precedence over existing values.
Vincent Ricard
3 years ago
committed by
Stephane Nicoll