Skip to content

S
spring-boot
Commit 25952584 authored by Phillip Webb's avatar Phillip Webb
Browse files
Options

Provide both properties and YAML examples in docs 

Update all configuration examples in the docs to YAML and make use of
the new `configblocks` spring-asciidoctor-extensions feature to
automatically create both "Properties" and "Yaml" versions.

Closes gh-23515
parent 68d65376
Show whitespace changes
Inline Side-by-side
Showing with 1288 additions and 656 deletions
spring-boot-project/spring-boot-docs/build.gradle
View file @ 25952584
...@@ -46,6 +46,7 @@ plugins.withType(EclipsePlugin) { ...@@ -46,6 +46,7 @@ plugins.withType(EclipsePlugin) {
dependencies { dependencies {
actuatorApiDocumentation(project(path: ":spring-boot-project:spring-boot-actuator-autoconfigure", configuration: "documentation")) actuatorApiDocumentation(project(path: ":spring-boot-project:spring-boot-actuator-autoconfigure", configuration: "documentation"))
asciidoctorExtensions("io.spring.asciidoctor:spring-asciidoctor-extensions-block-switch")
asciidoctorExtensions("io.spring.asciidoctor:spring-asciidoctor-extensions-spring-boot") asciidoctorExtensions("io.spring.asciidoctor:spring-asciidoctor-extensions-spring-boot")
asciidoctorExtensions(project(path: ":spring-boot-project:spring-boot-actuator-autoconfigure")) asciidoctorExtensions(project(path: ":spring-boot-project:spring-boot-actuator-autoconfigure"))
asciidoctorExtensions(project(path: ":spring-boot-project:spring-boot-autoconfigure")) asciidoctorExtensions(project(path: ":spring-boot-project:spring-boot-autoconfigure"))
......
spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc
View file @ 25952584
...@@ -85,7 +85,7 @@ See "`<<spring-boot-features.adoc#boot-features-application-events-and-listeners ...@@ -85,7 +85,7 @@ See "`<<spring-boot-features.adoc#boot-features-application-events-and-listeners
It is also possible to customize the `Environment` before the application context is refreshed by using `EnvironmentPostProcessor`. It is also possible to customize the `Environment` before the application context is refreshed by using `EnvironmentPostProcessor`.
Each implementation should be registered in `META-INF/spring.factories`, as shown in the following example: Each implementation should be registered in `META-INF/spring.factories`, as shown in the following example:
[source,properties,indent=0] [indent=0]
---- ----
org.springframework.boot.env.EnvironmentPostProcessor=com.example.YourEnvironmentPostProcessor org.springframework.boot.env.EnvironmentPostProcessor=com.example.YourEnvironmentPostProcessor
---- ----
...@@ -145,10 +145,12 @@ This is possible in both Maven and Gradle. ...@@ -145,10 +145,12 @@ This is possible in both Maven and Gradle.
You can automatically expand properties from the Maven project by using resource filtering. You can automatically expand properties from the Maven project by using resource filtering.
If you use the `spring-boot-starter-parent`, you can then refer to your Maven '`project properties`' with `@..@` placeholders, as shown in the following example: If you use the `spring-boot-starter-parent`, you can then refer to your Maven '`project properties`' with `@..@` placeholders, as shown in the following example:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
app.encoding=@project.build.sourceEncoding@ app:
app.java.version=@java.version@ encoding: "@project.build.sourceEncoding@"
java:
version: "@java.version@"
---- ----
NOTE: Only production configuration is filtered that way (in other words, no filtering is applied on `src/test/resources`). NOTE: Only production configuration is filtered that way (in other words, no filtering is applied on `src/test/resources`).
...@@ -205,10 +207,11 @@ You can automatically expand properties from the Gradle project by configuring t ...@@ -205,10 +207,11 @@ You can automatically expand properties from the Gradle project by configuring t
You can then refer to your Gradle project's properties by using placeholders, as shown in the following example: You can then refer to your Gradle project's properties by using placeholders, as shown in the following example:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
app.name=${name} app:
app.description=${description} name: "${name}"
description: "${description}"
---- ----
NOTE: Gradle's `expand` method uses Groovy's `SimpleTemplateEngine`, which transforms `${..}` tokens. NOTE: Gradle's `expand` method uses Groovy's `SimpleTemplateEngine`, which transforms `${..}` tokens.
...@@ -223,10 +226,12 @@ A `SpringApplication` has bean properties (mainly setters), so you can use its J ...@@ -223,10 +226,12 @@ A `SpringApplication` has bean properties (mainly setters), so you can use its J
Alternatively, you can externalize the configuration by setting properties in `+spring.main.*+`. Alternatively, you can externalize the configuration by setting properties in `+spring.main.*+`.
For example, in `application.properties`, you might have the following settings: For example, in `application.properties`, you might have the following settings:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.main.web-application-type=none spring:
spring.main.banner-mode=off main:
web-application-type: "none"
banner-mode: "off"
---- ----
Then the Spring Boot banner is not printed on startup, and the application is not starting an embedded web server. Then the Spring Boot banner is not printed on startup, and the application is not starting an embedded web server.
...@@ -244,10 +249,12 @@ Consider the following application: ...@@ -244,10 +249,12 @@ Consider the following application:
Now consider the following configuration: Now consider the following configuration:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.main.sources=com.acme.Config,com.acme.ExtraConfig spring:
spring.main.banner-mode=console main:
sources: "com.acme.Config,com.acme.ExtraConfig"
banner-mode: "console"
---- ----
The actual application _now_ shows the banner (as overridden by configuration) and uses three sources for the `ApplicationContext` (in the following order): `demo.MyApp`, `com.acme.Config`, and `com.acme.ExtraConfig`. The actual application _now_ shows the banner (as overridden by configuration) and uses three sources for the `ApplicationContext` (in the following order): `demo.MyApp`, `com.acme.Config`, and `com.acme.ExtraConfig`.
...@@ -278,9 +285,10 @@ See {spring-boot-module-code}/context/config/ConfigFileApplicationListener.java[ ...@@ -278,9 +285,10 @@ See {spring-boot-module-code}/context/config/ConfigFileApplicationListener.java[
Some people like to use (for example) `--port=9000` instead of `--server.port=9000` to set configuration properties on the command line. Some people like to use (for example) `--port=9000` instead of `--server.port=9000` to set configuration properties on the command line.
You can enable this behavior by using placeholders in `application.properties`, as shown in the following example: You can enable this behavior by using placeholders in `application.properties`, as shown in the following example:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
server.port=${port:8080} server:
port: "${port:8080}"
---- ----
TIP: If you inherit from the `spring-boot-starter-parent` POM, the default filter token of the `maven-resources-plugins` has been changed from `+${*}+` to `@` (that is, `@maven.token@` instead of `${maven.token}`) to prevent conflicts with Spring-style placeholders. TIP: If you inherit from the `spring-boot-starter-parent` POM, the default filter token of the `maven-resources-plugins` has been changed from `+${*}+` to `@` (that is, `@maven.token@` instead of `${maven.token}`) to prevent conflicts with Spring-style placeholders.
...@@ -299,10 +307,10 @@ YAML is a superset of JSON and, as such, is a convenient syntax for storing exte ...@@ -299,10 +307,10 @@ YAML is a superset of JSON and, as such, is a convenient syntax for storing exte
---- ----
spring: spring:
application: application:
name: cruncher name: "cruncher"
datasource: datasource:
driverClassName: com.mysql.jdbc.Driver driver-class-name: "com.mysql.jdbc.Driver"
url: jdbc:mysql://localhost/test url: "jdbc:mysql://localhost/test"
server: server:
port: 9000 port: 9000
---- ----
...@@ -337,9 +345,11 @@ Also, you can launch your application with a `-D` argument (remember to put it b ...@@ -337,9 +345,11 @@ Also, you can launch your application with a `-D` argument (remember to put it b
In Spring Boot, you can also set the active profile in `application.properties`, as shown in the following example: In Spring Boot, you can also set the active profile in `application.properties`, as shown in the following example:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.profiles.active=production spring:
profiles:
active: "production"
---- ----
A value set this way is replaced by the System property or environment variable setting but not by the `SpringApplicationBuilder.profiles()` method. A value set this way is replaced by the System property or environment variable setting but not by the `SpringApplicationBuilder.profiles()` method.
...@@ -356,15 +366,24 @@ Spring Boot supports multi-document YAML and Properties files (see <<spring-boot ...@@ -356,15 +366,24 @@ Spring Boot supports multi-document YAML and Properties files (see <<spring-boot
If a document contains a `spring.config.activate.on-profile` key, then the profiles value (a comma-separated list of profiles or a profile expression) is fed into the Spring `Environment.acceptsProfiles()` method. If a document contains a `spring.config.activate.on-profile` key, then the profiles value (a comma-separated list of profiles or a profile expression) is fed into the Spring `Environment.acceptsProfiles()` method.
If the profile expression matches then that document is included in the final merge (otherwise, it is not), as shown in the following example: If the profile expression matches then that document is included in the final merge (otherwise, it is not), as shown in the following example:
[source,yaml,indent=0,subs="verbatim,quotes,attributes"] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
server.port: 9000 server:
port: 9000
--- ---
spring.config.activate.on-profile: development spring:
server.port: 9001 config:
activate:
on-profile: "development"
server:
port: 9001
--- ---
spring.config.activate.on-profile: production spring:
server.port: 0 config:
activate:
on-profile: "production"
server:
port: 0
---- ----
In the preceding example, the default port is 9000. In the preceding example, the default port is 9000.
...@@ -461,9 +480,11 @@ NOTE: `spring-boot-starter-reactor-netty` is required to use the `WebClient` cla ...@@ -461,9 +480,11 @@ NOTE: `spring-boot-starter-reactor-netty` is required to use the `WebClient` cla
If your classpath contains the necessary bits to start a web server, Spring Boot will automatically start it. If your classpath contains the necessary bits to start a web server, Spring Boot will automatically start it.
To disable this behavior configure the `WebApplicationType` in your `application.properties`, as shown in the following example: To disable this behavior configure the `WebApplicationType` in your `application.properties`, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.main.web-application-type=none spring:
main:
web-application-type: "none"
---- ----
...@@ -520,9 +541,11 @@ Contrary to a test, application code callbacks are processed early (before the v ...@@ -520,9 +541,11 @@ Contrary to a test, application code callbacks are processed early (before the v
HTTP response compression is supported by Jetty, Tomcat, and Undertow. HTTP response compression is supported by Jetty, Tomcat, and Undertow.
It can be enabled in `application.properties`, as follows: It can be enabled in `application.properties`, as follows:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
server.compression.enabled=true server:
compression:
enabled: true
---- ----
By default, responses must be at least 2048 bytes in length for compression to be performed. By default, responses must be at least 2048 bytes in length for compression to be performed.
...@@ -548,12 +571,14 @@ You can configure this behavior by setting the configprop:server.compression.mim ...@@ -548,12 +571,14 @@ You can configure this behavior by setting the configprop:server.compression.mim
SSL can be configured declaratively by setting the various `+server.ssl.*+` properties, typically in `application.properties` or `application.yml`. SSL can be configured declaratively by setting the various `+server.ssl.*+` properties, typically in `application.properties` or `application.yml`.
The following example shows setting SSL properties in `application.properties`: The following example shows setting SSL properties in `application.properties`:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
server.port=8443 server:
server.ssl.key-store=classpath:keystore.jks port: 8443
server.ssl.key-store-password=secret ssl:
server.ssl.key-password=another-secret key-store: "classpath:keystore.jks"
key-store-password: "secret"
key-password: "another-secret"
---- ----
See {spring-boot-module-code}/web/server/Ssl.java[`Ssl`] for details of all of the supported properties. See {spring-boot-module-code}/web/server/Ssl.java[`Ssl`] for details of all of the supported properties.
...@@ -742,11 +767,14 @@ Access logs can be configured for Tomcat, Undertow, and Jetty through their resp ...@@ -742,11 +767,14 @@ Access logs can be configured for Tomcat, Undertow, and Jetty through their resp
For instance, the following settings log access on Tomcat with a {tomcat-docs}/config/valve.html#Access_Logging[custom pattern]. For instance, the following settings log access on Tomcat with a {tomcat-docs}/config/valve.html#Access_Logging[custom pattern].
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
server.tomcat.basedir=my-tomcat server:
server.tomcat.accesslog.enabled=true tomcat:
server.tomcat.accesslog.pattern=%t %a "%r" %s (%D ms) basedir: "my-tomcat"
accesslog:
enabled: true
pattern: "%t %a %r %s (%D ms)"
---- ----
NOTE: The default location for logs is a `logs` directory relative to the Tomcat base directory. NOTE: The default location for logs is a `logs` directory relative to the Tomcat base directory.
...@@ -755,10 +783,13 @@ In the preceding example, the logs are available in `my-tomcat/logs` relative to ...@@ -755,10 +783,13 @@ In the preceding example, the logs are available in `my-tomcat/logs` relative to
Access logging for Undertow can be configured in a similar fashion, as shown in the following example: Access logging for Undertow can be configured in a similar fashion, as shown in the following example:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
server.undertow.accesslog.enabled=true server:
server.undertow.accesslog.pattern=%t %a "%r" %s (%D ms) undertow:
accesslog:
enabled: true
pattern: "%t %a %r %s (%D ms)"
---- ----
Logs are stored in a `logs` directory relative to the working directory of the application. Logs are stored in a `logs` directory relative to the working directory of the application.
...@@ -766,10 +797,13 @@ You can customize this location by setting the configprop:server.undertow.access ...@@ -766,10 +797,13 @@ You can customize this location by setting the configprop:server.undertow.access
Finally, access logging for Jetty can also be configured as follows: Finally, access logging for Jetty can also be configured as follows:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
server.jetty.accesslog.enabled=true server:
server.jetty.accesslog.filename=/var/log/jetty-access.log jetty:
accesslog:
enabled: true
filename: "/var/log/jetty-access.log"
---- ----
By default, logs are redirected to `System.err`. By default, logs are redirected to `System.err`.
...@@ -801,24 +835,27 @@ In all other instances, it defaults to `NONE`. ...@@ -801,24 +835,27 @@ In all other instances, it defaults to `NONE`.
==== Customize Tomcat's Proxy Configuration ==== Customize Tomcat's Proxy Configuration
If you use Tomcat, you can additionally configure the names of the headers used to carry "`forwarded`" information, as shown in the following example: If you use Tomcat, you can additionally configure the names of the headers used to carry "`forwarded`" information, as shown in the following example:
[indent=0] [source,yaml,indent=0,configprops,configblocks]
---- ----
server.tomcat.remoteip.remote-ip-header=x-your-remote-ip-header server:
server.tomcat.remoteip.protocol-header=x-your-protocol-header tomcat:
remoteip:
remote-ip-header: "x-your-remote-ip-header"
protocol-header: "x-your-protocol-header"
---- ----
Tomcat is also configured with a default regular expression that matches internal proxies that are to be trusted. Tomcat is also configured with a default regular expression that matches internal proxies that are to be trusted.
By default, IP addresses in `10/8`, `192.168/16`, `169.254/16` and `127/8` are trusted. By default, IP addresses in `10/8`, `192.168/16`, `169.254/16` and `127/8` are trusted.
You can customize the valve's configuration by adding an entry to `application.properties`, as shown in the following example: You can customize the valve's configuration by adding an entry to `application.properties`, as shown in the following example:
[indent=0] [source,yaml,indent=0,configprops,configblocks]
---- ----
server.tomcat.remoteip.internal-proxies=192\\.168\\.\\d{1,3}\\.\\d{1,3} server:
tomcat:
remoteip:
internal-proxies: "192\\.168\\.\\d{1,3}\\.\\d{1,3}"
---- ----
NOTE: The double backslashes are required only when you use a properties file for configuration.
If you use YAML, single backslashes are sufficient, and a value equivalent to that shown in the preceding example would be `192\.168\.\d{1,3}\.\d{1,3}`.
NOTE: You can trust all proxies by setting the `internal-proxies` to empty (but do not do so in production). NOTE: You can trust all proxies by setting the `internal-proxies` to empty (but do not do so in production).
You can take complete control of the configuration of Tomcat's `RemoteIpValve` by switching the automatic one off (to do so, set `server.forward-headers-strategy=NONE`) and adding a new valve instance in a `TomcatServletWebServerFactory` bean. You can take complete control of the configuration of Tomcat's `RemoteIpValve` by switching the automatic one off (to do so, set `server.forward-headers-strategy=NONE`) and adding a new valve instance in a `TomcatServletWebServerFactory` bean.
...@@ -890,9 +927,12 @@ Embedded Tomcat's MBean registry is disabled by default. ...@@ -890,9 +927,12 @@ Embedded Tomcat's MBean registry is disabled by default.
This minimizes Tomcat's memory footprint. This minimizes Tomcat's memory footprint.
If you want to use Tomcat's MBeans, for example so that they can be used to expose metrics via Micrometer, you must use the configprop:server.tomcat.mbeanregistry.enabled[] property to do so, as shown in the following example: If you want to use Tomcat's MBeans, for example so that they can be used to expose metrics via Micrometer, you must use the configprop:server.tomcat.mbeanregistry.enabled[] property to do so, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
server.tomcat.mbeanregistry.enabled=true server:
tomcat:
mbeanregistry:
enabled: true
---- ----
...@@ -1110,9 +1150,12 @@ NOTE: It is recommended to use the container's built-in support for multipart up ...@@ -1110,9 +1150,12 @@ NOTE: It is recommended to use the container's built-in support for multipart up
By default, all content is served from the root of your application (`/`). By default, all content is served from the root of your application (`/`).
If you would rather map to a different path, you can configure one as follows: If you would rather map to a different path, you can configure one as follows:
[source,properties,indent=0,subs="verbatim",configprops] [source,yaml,indent=0,subs="verbatim",configprops,configblocks]
---- ----
spring.mvc.servlet.path=/acme spring:
mvc:
servlet:
path: "/acme"
---- ----
If you have additional servlets you can declare a `@Bean` of type `Servlet` or `ServletRegistrationBean` for each and Spring Boot will register them transparently to the container. If you have additional servlets you can declare a `@Bean` of type `Servlet` or `ServletRegistrationBean` for each and Spring Boot will register them transparently to the container.
...@@ -1299,13 +1342,15 @@ If Logback is available, it is the first choice. ...@@ -1299,13 +1342,15 @@ If Logback is available, it is the first choice.
If the only change you need to make to logging is to set the levels of various loggers, you can do so in `application.properties` by using the "logging.level" prefix, as shown in the following example: If the only change you need to make to logging is to set the levels of various loggers, you can do so in `application.properties` by using the "logging.level" prefix, as shown in the following example:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
logging.level.org.springframework.web=DEBUG logging:
logging.level.org.hibernate=ERROR level:
org.springframework.web: "debug"
org.hibernate: "error"
---- ----
You can also set the location of a file to which to write the log (in addition to the console) by using "logging.file.name". You can also set the location of a file to which to write the log (in addition to the console) by using `logging.file.name`.
To configure the more fine-grained settings of a logging system, you need to use the native configuration format supported by the `LoggingSystem` in question. To configure the more fine-grained settings of a logging system, you need to use the native configuration format supported by the `LoggingSystem` in question.
By default, Spring Boot picks up the native configuration from its default location for the system (such as `classpath:logback.xml` for Logback), but you can set the location of the config file by using the configprop:logging.config[] property. By default, Spring Boot picks up the native configuration from its default location for the system (such as `classpath:logback.xml` for Logback), but you can set the location of the config file by using the configprop:logging.config[] property.
...@@ -1382,11 +1427,13 @@ If you want to disable console logging and write output only to a file, you need ...@@ -1382,11 +1427,13 @@ If you want to disable console logging and write output only to a file, you need
</configuration> </configuration>
---- ----
You also need to add `logging.file.name` to your `application.properties`, as shown in the following example: You also need to add `logging.file.name` to your `application.properties` or `application.yaml`, as shown in the following example:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
logging.file.name=myapplication.log logging:
file:
name: "myapplication.log"
---- ----
...@@ -1492,11 +1539,13 @@ The following example shows how to define a data source in a bean: ...@@ -1492,11 +1539,13 @@ The following example shows how to define a data source in a bean:
The following example shows how to define a data source by setting properties: The following example shows how to define a data source by setting properties:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
app.datasource.url=jdbc:h2:mem:mydb app:
app.datasource.username=sa datasource:
app.datasource.pool-size=30 url: "jdbc:h2:mem:mydb"
username: "sa"
pool-size: 30
---- ----
Assuming that your `FancyDataSource` has regular JavaBean properties for the URL, the username, and the pool size, these settings are bound automatically before the `DataSource` is made available to other components. Assuming that your `FancyDataSource` has regular JavaBean properties for the URL, the username, and the pool size, these settings are bound automatically before the `DataSource` is made available to other components.
...@@ -1519,12 +1568,14 @@ Check the implementation that is going to be used at runtime for more details. ...@@ -1519,12 +1568,14 @@ Check the implementation that is going to be used at runtime for more details.
The following example shows how to define a JDBC data source by setting properties: The following example shows how to define a JDBC data source by setting properties:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
app.datasource.url=jdbc:mysql://localhost/test app:
app.datasource.username=dbuser datasource:
app.datasource.password=dbpass url: "jdbc:mysql://localhost/test"
app.datasource.pool-size=30 username: "dbuser"
password: "dbpass"
pool-size: 30
---- ----
However, there is a catch. However, there is a catch.
...@@ -1532,12 +1583,14 @@ Because the actual type of the connection pool is not exposed, no keys are gener ...@@ -1532,12 +1583,14 @@ Because the actual type of the connection pool is not exposed, no keys are gener
Also, if you happen to have Hikari on the classpath, this basic setup does not work, because Hikari has no `url` property (but does have a `jdbcUrl` property). Also, if you happen to have Hikari on the classpath, this basic setup does not work, because Hikari has no `url` property (but does have a `jdbcUrl` property).
In that case, you must rewrite your configuration as follows: In that case, you must rewrite your configuration as follows:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
app.datasource.jdbc-url=jdbc:mysql://localhost/test app:
app.datasource.username=dbuser datasource:
app.datasource.password=dbpass jdbc-url: "jdbc:mysql://localhost/test"
app.datasource.maximum-pool-size=30 username: "dbuser"
password: "dbpass"
pool-size: 30
---- ----
You can fix that by forcing the connection pool to use and return a dedicated implementation rather than `DataSource`. You can fix that by forcing the connection pool to use and return a dedicated implementation rather than `DataSource`.
...@@ -1563,12 +1616,15 @@ include::{code-examples}/jdbc/ConfigurableDataSourceExample.java[tag=configurati ...@@ -1563,12 +1616,15 @@ include::{code-examples}/jdbc/ConfigurableDataSourceExample.java[tag=configurati
This setup puts you _in sync_ with what Spring Boot does for you by default, except that a dedicated connection pool is chosen (in code) and its settings are exposed in the `app.datasource.configuration` sub namespace. This setup puts you _in sync_ with what Spring Boot does for you by default, except that a dedicated connection pool is chosen (in code) and its settings are exposed in the `app.datasource.configuration` sub namespace.
Because `DataSourceProperties` is taking care of the `url`/`jdbcUrl` translation for you, you can configure it as follows: Because `DataSourceProperties` is taking care of the `url`/`jdbcUrl` translation for you, you can configure it as follows:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
app.datasource.url=jdbc:mysql://localhost/test app:
app.datasource.username=dbuser datasource:
app.datasource.password=dbpass url: "jdbc:mysql://localhost/test"
app.datasource.configuration.maximum-pool-size=30 username: "dbuser"
password: "dbpass"
configuration:
maximum-pool-size: 30
---- ----
TIP: Spring Boot will expose Hikari-specific settings to `spring.datasource.hikari`. TIP: Spring Boot will expose Hikari-specific settings to `spring.datasource.hikari`.
...@@ -1599,17 +1655,22 @@ TIP: `firstDataSourceProperties` has to be flagged as `@Primary` so that the dat ...@@ -1599,17 +1655,22 @@ TIP: `firstDataSourceProperties` has to be flagged as `@Primary` so that the dat
Both data sources are also bound for advanced customizations. Both data sources are also bound for advanced customizations.
For instance, you could configure them as follows: For instance, you could configure them as follows:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
app.datasource.first.url=jdbc:mysql://localhost/first app:
app.datasource.first.username=dbuser datasource:
app.datasource.first.password=dbpass first:
app.datasource.first.configuration.maximum-pool-size=30 url: "jdbc:mysql://localhost/first"
username: "dbuser"
password: "dbpass"
configuration:
maximum-pool-size: 30
app.datasource.second.url=jdbc:mysql://localhost/second second:
app.datasource.second.username=dbuser url: "jdbc:mysql://localhost/second"
app.datasource.second.password=dbpass username: "dbuser"
app.datasource.second.max-total=30 password: "dbpass"
max-total: 30
---- ----
You can apply the same concept to the secondary `DataSource` as well, as shown in the following example: You can apply the same concept to the secondary `DataSource` as well, as shown in the following example:
...@@ -1673,10 +1734,14 @@ If you prefer to set the dialect yourself, set the configprop:spring.jpa.databas ...@@ -1673,10 +1734,14 @@ If you prefer to set the dialect yourself, set the configprop:spring.jpa.databas
The most common options to set are shown in the following example: The most common options to set are shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.jpa.hibernate.naming.physical-strategy=com.example.MyPhysicalNamingStrategy spring:
spring.jpa.show-sql=true jpa:
hibernate:
naming:
physical-strategy: "com.example.MyPhysicalNamingStrategy"
show-sql: true
---- ----
In addition, all properties in `+spring.jpa.properties.*+` are passed through as normal JPA properties (with the prefix stripped) when the local `EntityManagerFactory` is created. In addition, all properties in `+spring.jpa.properties.*+` are passed through as normal JPA properties (with the prefix stripped) when the local `EntityManagerFactory` is created.
...@@ -1993,12 +2058,14 @@ Spring Boot can detect your database type and execute those scripts on startup. ...@@ -1993,12 +2058,14 @@ Spring Boot can detect your database type and execute those scripts on startup.
If you use an embedded database, this happens by default. If you use an embedded database, this happens by default.
You can also enable it for any database type, as shown in the following example: You can also enable it for any database type, as shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.batch.initialize-schema=always spring:
batch:
initialize-schema: "always"
---- ----
You can also switch off the initialization explicitly by setting `spring.batch.initialize-schema=never`. You can also switch off the initialization explicitly by setting `spring.batch.initialize-schema` to `never`.
...@@ -2017,17 +2084,21 @@ By default, they are in a directory called `classpath:db/migration`, but you can ...@@ -2017,17 +2084,21 @@ By default, they are in a directory called `classpath:db/migration`, but you can
This is a comma-separated list of one or more `classpath:` or `filesystem:` locations. This is a comma-separated list of one or more `classpath:` or `filesystem:` locations.
For example, the following configuration would search for scripts in both the default classpath location and the `/opt/migration` directory: For example, the following configuration would search for scripts in both the default classpath location and the `/opt/migration` directory:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.flyway.locations=classpath:db/migration,filesystem:/opt/migration spring:
flyway:
locations: "classpath:db/migration,filesystem:/opt/migration"
---- ----
You can also add a special `\{vendor}` placeholder to use vendor-specific scripts. You can also add a special `\{vendor}` placeholder to use vendor-specific scripts.
Assume the following: Assume the following:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.flyway.locations=classpath:db/migration/{vendor} spring:
flyway:
locations: "classpath:db/migration/{vendor}"
---- ----
Rather than using `db/migration`, the preceding configuration sets the directory to use according to the type of the database (such as `db/migration/mysql` for MySQL). Rather than using `db/migration`, the preceding configuration sets the directory to use according to the type of the database (such as `db/migration/mysql` for MySQL).
...@@ -2061,9 +2132,11 @@ For example, you can place test-specific migrations in `src/test/resources` and ...@@ -2061,9 +2132,11 @@ For example, you can place test-specific migrations in `src/test/resources` and
Also, you can use profile-specific configuration to customize `spring.flyway.locations` so that certain migrations run only when a particular profile is active. Also, you can use profile-specific configuration to customize `spring.flyway.locations` so that certain migrations run only when a particular profile is active.
For example, in `application-dev.properties`, you might specify the following setting: For example, in `application-dev.properties`, you might specify the following setting:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.flyway.locations=classpath:/db/migration,classpath:/dev/db/migration spring:
flyway:
locations: "classpath:/db/migration,classpath:/dev/db/migration"
---- ----
With that setup, migrations in `dev/db/migration` run only when the `dev` profile is active. With that setup, migrations in `dev/db/migration` run only when the `dev` profile is active.
...@@ -2287,10 +2360,13 @@ If you use Tomcat as a servlet container, then Spring Boot adds Tomcat's own `Re ...@@ -2287,10 +2360,13 @@ If you use Tomcat as a servlet container, then Spring Boot adds Tomcat's own `Re
The standard behavior is determined by the presence or absence of certain request headers (`x-forwarded-for` and `x-forwarded-proto`), whose names are conventional, so it should work with most front-end proxies. The standard behavior is determined by the presence or absence of certain request headers (`x-forwarded-for` and `x-forwarded-proto`), whose names are conventional, so it should work with most front-end proxies.
You can switch on the valve by adding some entries to `application.properties`, as shown in the following example: You can switch on the valve by adding some entries to `application.properties`, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
server.tomcat.remoteip.remote-ip-header=x-forwarded-for server:
server.tomcat.remoteip.protocol-header=x-forwarded-proto tomcat:
remoteip:
remote-ip-header: "x-forwarded-for"
protocol-header: "x-forwarded-proto"
---- ----
(The presence of either of those properties switches on the valve. (The presence of either of those properties switches on the valve.
......
spring-boot-project/spring-boot-docs/src/docs/asciidoc/production-ready-features.adoc
View file @ 25952584
...@@ -161,18 +161,25 @@ By default, all endpoints except for `shutdown` are enabled. ...@@ -161,18 +161,25 @@ By default, all endpoints except for `shutdown` are enabled.
To configure the enablement of an endpoint, use its `management.endpoint.<id>.enabled` property. To configure the enablement of an endpoint, use its `management.endpoint.<id>.enabled` property.
The following example enables the `shutdown` endpoint: The following example enables the `shutdown` endpoint:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoint.shutdown.enabled=true management:
endpoint:
shutdown:
enabled: true
---- ----
If you prefer endpoint enablement to be opt-in rather than opt-out, set the configprop:management.endpoints.enabled-by-default[] property to `false` and use individual endpoint `enabled` properties to opt back in. If you prefer endpoint enablement to be opt-in rather than opt-out, set the configprop:management.endpoints.enabled-by-default[] property to `false` and use individual endpoint `enabled` properties to opt back in.
The following example enables the `info` endpoint and disables all other endpoints: The following example enables the `info` endpoint and disables all other endpoints:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoints.enabled-by-default=false management:
management.endpoint.info.enabled=true endpoints:
enabled-by-default: false
endpoint:
info:
enabled: true
---- ----
NOTE: Disabled endpoints are removed entirely from the application context. NOTE: Disabled endpoints are removed entirely from the application context.
...@@ -312,33 +319,29 @@ Both `include` and `exclude` properties can be configured with a list of endpoin ...@@ -312,33 +319,29 @@ Both `include` and `exclude` properties can be configured with a list of endpoin
For example, to stop exposing all endpoints over JMX and only expose the `health` and `info` endpoints, use the following property: For example, to stop exposing all endpoints over JMX and only expose the `health` and `info` endpoints, use the following property:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoints.jmx.exposure.include=health,info management:
endpoints:
jmx:
exposure:
include: "health,info"
---- ----
`*` can be used to select all endpoints. `*` can be used to select all endpoints.
For example, to expose everything over HTTP except the `env` and `beans` endpoints, use the following properties: For example, to expose everything over HTTP except the `env` and `beans` endpoints, use the following properties:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
----
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans
----
[NOTE]
====
`*` has a special meaning in YAML, so be sure to add quotes if you want to include (or exclude) all endpoints, as shown in the following example:
[source,yaml,indent=0]
---- ----
management: management:
endpoints: endpoints:
web: web:
exposure: exposure:
include: "*" include: "*"
exclude: "env,beans"
---- ----
====
NOTE: `*` has a special meaning in YAML, so be sure to add quotes if you want to include (or exclude) all endpoints.
NOTE: If your application is exposed publicly, we strongly recommend that you also <<production-ready-endpoints-security, secure your endpoints>>. NOTE: If your application is exposed publicly, we strongly recommend that you also <<production-ready-endpoints-security, secure your endpoints>>.
...@@ -377,9 +380,13 @@ If you deploy applications behind a firewall, you may prefer that all your actua ...@@ -377,9 +380,13 @@ If you deploy applications behind a firewall, you may prefer that all your actua
You can do so by changing the configprop:management.endpoints.web.exposure.include[] property, as follows: You can do so by changing the configprop:management.endpoints.web.exposure.include[] property, as follows:
.application.properties .application.properties
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoints.web.exposure.include=* management:
endpoints:
web:
exposure:
include: "*"
---- ----
Additionally, if Spring Security is present, you would need to add custom security configuration that allows unauthenticated access to the endpoints as shown in the following example: Additionally, if Spring Security is present, you would need to add custom security configuration that allows unauthenticated access to the endpoints as shown in the following example:
...@@ -407,9 +414,13 @@ To configure the amount of time for which an endpoint will cache a response, use ...@@ -407,9 +414,13 @@ To configure the amount of time for which an endpoint will cache a response, use
The following example sets the time-to-live of the `beans` endpoint's cache to 10 seconds: The following example sets the time-to-live of the `beans` endpoint's cache to 10 seconds:
.application.properties .application.properties
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoint.beans.cache.time-to-live=10s management:
endpoint:
beans:
cache:
time-to-live: "10s"
---- ----
NOTE: The prefix `management.endpoint.<name>` is used to uniquely identify the endpoint that is being configured. NOTE: The prefix `management.endpoint.<name>` is used to uniquely identify the endpoint that is being configured.
...@@ -435,10 +446,14 @@ If you use Spring MVC or Spring WebFlux, Actuator's web endpoints can be configu ...@@ -435,10 +446,14 @@ If you use Spring MVC or Spring WebFlux, Actuator's web endpoints can be configu
CORS support is disabled by default and is only enabled once the configprop:management.endpoints.web.cors.allowed-origins[] property has been set. CORS support is disabled by default and is only enabled once the configprop:management.endpoints.web.cors.allowed-origins[] property has been set.
The following configuration permits `GET` and `POST` calls from the `example.com` domain: The following configuration permits `GET` and `POST` calls from the `example.com` domain:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoints.web.cors.allowed-origins=https://example.com management:
management.endpoints.web.cors.allowed-methods=GET,POST endpoints:
web:
cors:
allowed-origins: "https://example.com"
allowed-methods: "GET,POST"
---- ----
TIP: See {spring-boot-actuator-autoconfigure-module-code}/endpoint/web/CorsEndpointProperties.java[CorsEndpointProperties] for a complete list of options. TIP: See {spring-boot-actuator-autoconfigure-module-code}/endpoint/web/CorsEndpointProperties.java[CorsEndpointProperties] for a complete list of options.
...@@ -798,9 +813,13 @@ In such cases, a custom implementation of the {spring-boot-actuator-module-code} ...@@ -798,9 +813,13 @@ In such cases, a custom implementation of the {spring-boot-actuator-module-code}
For example, assume a new `Status` with code `FATAL` is being used in one of your `HealthIndicator` implementations. For example, assume a new `Status` with code `FATAL` is being used in one of your `HealthIndicator` implementations.
To configure the severity order, add the following property to your application properties: To configure the severity order, add the following property to your application properties:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up management:
endpoint:
health:
status:
order: "fatal,down,out-of-service,unknown,up"
---- ----
The HTTP status code in the response reflects the overall health status. The HTTP status code in the response reflects the overall health status.
...@@ -811,11 +830,16 @@ Configuring a custom mapping disables the defaults mappings for `DOWN` and `OUT_ ...@@ -811,11 +830,16 @@ Configuring a custom mapping disables the defaults mappings for `DOWN` and `OUT_
If you want to retain the default mappings they must be configured explicitly alongside any custom mappings. If you want to retain the default mappings they must be configured explicitly alongside any custom mappings.
For example, the following property maps `FATAL` to 503 (service unavailable) and retains the default mappings for `DOWN` and `OUT_OF_SERVICE`: For example, the following property maps `FATAL` to 503 (service unavailable) and retains the default mappings for `DOWN` and `OUT_OF_SERVICE`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoint.health.status.http-mapping.down=503 management:
management.endpoint.health.status.http-mapping.fatal=503 endpoint:
management.endpoint.health.status.http-mapping.out-of-service=503 health:
status:
http-mapping:
down: 503
fatal: 503
out-of-service: 503
---- ----
TIP: If you need more control, you can define your own `HttpCodeStatusMapper` bean. TIP: If you need more control, you can define your own `HttpCodeStatusMapper` bean.
...@@ -908,30 +932,47 @@ It's sometimes useful to organize health indicators into groups that can be used ...@@ -908,30 +932,47 @@ It's sometimes useful to organize health indicators into groups that can be used
To create a health indicator group you can use the `management.endpoint.health.group.<name>` property and specify a list of health indicator IDs to `include` or `exclude`. To create a health indicator group you can use the `management.endpoint.health.group.<name>` property and specify a list of health indicator IDs to `include` or `exclude`.
For example, to create a group that includes only database indicators you can define the following: For example, to create a group that includes only database indicators you can define the following:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoint.health.group.custom.include=db management:
endpoint:
health:
group:
custom:
include: "db"
---- ----
You can then check the result by hitting `http://localhost:8080/actuator/health/custom`. You can then check the result by hitting `http://localhost:8080/actuator/health/custom`.
Similarly, to create a group that excludes the database indicators from the group and includes all the other indicators, you can define the following: Similarly, to create a group that excludes the database indicators from the group and includes all the other indicators, you can define the following:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoint.health.group.custom.exclude=db management:
endpoint:
health:
group:
custom:
exclude: "db"
---- ----
By default groups will inherit the same `StatusAggregator` and `HttpCodeStatusMapper` settings as the system health, however, these can also be defined on a per-group basis. By default groups will inherit the same `StatusAggregator` and `HttpCodeStatusMapper` settings as the system health, however, these can also be defined on a per-group basis.
It's also possible to override the `show-details` and `roles` properties if required: It's also possible to override the `show-details` and `roles` properties if required:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoint.health.group.custom.show-details=when-authorized management:
management.endpoint.health.group.custom.roles=admin endpoint:
management.endpoint.health.group.custom.status.order=fatal,up health:
management.endpoint.health.group.custom.status.http-mapping.fatal=500 group:
management.endpoint.health.group.custom.status.http-mapping.out-of-service=500 custom:
show-details: "when-authorized"
roles: "admin"
status:
order: "fatal,up"
http-mapping:
fatal: 500
out-of-service: 500
---- ----
TIP: You can use `@Qualifier("groupname")` if you need to register custom `StatusAggregator` or `HttpCodeStatusMapper` beans for use with the group. TIP: You can use `@Qualifier("groupname")` if you need to register custom `StatusAggregator` or `HttpCodeStatusMapper` beans for use with the group.
...@@ -986,9 +1027,14 @@ In this case, a probe check could be successful even if the main application doe ...@@ -986,9 +1027,14 @@ In this case, a probe check could be successful even if the main application doe
Actuator configures the "liveness" and "readiness" probes as Health Groups; this means that all the <<production-ready-health-groups, Health Groups features>> are available for them. Actuator configures the "liveness" and "readiness" probes as Health Groups; this means that all the <<production-ready-health-groups, Health Groups features>> are available for them.
You can, for example, configure additional Health Indicators: You can, for example, configure additional Health Indicators:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoint.health.group.readiness.include=readinessState,customCheck management:
endpoint:
health:
group:
readiness:
include: "readinessState,customCheck"
---- ----
By default, Spring Boot does not add other Health Indicators to these groups. By default, Spring Boot does not add other Health Indicators to these groups.
...@@ -1101,11 +1147,14 @@ You can customize the data exposed by the `info` endpoint by setting `+info.*+` ...@@ -1101,11 +1147,14 @@ You can customize the data exposed by the `info` endpoint by setting `+info.*+`
All `Environment` properties under the `info` key are automatically exposed. All `Environment` properties under the `info` key are automatically exposed.
For example, you could add the following settings to your `application.properties` file: For example, you could add the following settings to your `application.properties` file:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
info.app.encoding=UTF-8 info:
info.app.java.source=1.8 app:
info.app.java.target=1.8 encoding: "UTF-8"
java:
source: "11"
target: "11"
---- ----
[TIP] [TIP]
...@@ -1114,11 +1163,14 @@ Rather than hardcoding those values, you could also <<howto.adoc#howto-automatic ...@@ -1114,11 +1163,14 @@ Rather than hardcoding those values, you could also <<howto.adoc#howto-automatic
Assuming you use Maven, you could rewrite the preceding example as follows: Assuming you use Maven, you could rewrite the preceding example as follows:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
info.app.encoding=@project.build.sourceEncoding@ info:
info.app.java.source=@java.version@ app:
info.app.java.target=@java.version@ encoding: "@project.build.sourceEncoding@"
java:
source: "@java.version@"
target: "@java.version@"
---- ----
==== ====
...@@ -1134,9 +1186,12 @@ See "<<howto.adoc#howto-git-info,Generate git information>>" for more details. ...@@ -1134,9 +1186,12 @@ See "<<howto.adoc#howto-git-info,Generate git information>>" for more details.
If you want to display the full git information (that is, the full content of `git.properties`), use the configprop:management.info.git.mode[] property, as follows: If you want to display the full git information (that is, the full content of `git.properties`), use the configprop:management.info.git.mode[] property, as follows:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.info.git.mode=full management:
info:
git:
mode: "full"
---- ----
...@@ -1209,9 +1264,12 @@ Sometimes, it is useful to customize the prefix for the management endpoints. ...@@ -1209,9 +1264,12 @@ Sometimes, it is useful to customize the prefix for the management endpoints.
For example, your application might already use `/actuator` for another purpose. For example, your application might already use `/actuator` for another purpose.
You can use the configprop:management.endpoints.web.base-path[] property to change the prefix for your management endpoint, as shown in the following example: You can use the configprop:management.endpoints.web.base-path[] property to change the prefix for your management endpoint, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoints.web.base-path=/manage management:
endpoints:
web:
base-path: "/manage"
---- ----
The preceding `application.properties` example changes the endpoint from `/actuator/\{id}` to `/manage/\{id}` (for example, `/manage/info`). The preceding `application.properties` example changes the endpoint from `/actuator/\{id}` to `/manage/\{id}` (for example, `/manage/info`).
...@@ -1224,10 +1282,14 @@ If you want to map endpoints to a different path, you can use the configprop:man ...@@ -1224,10 +1282,14 @@ If you want to map endpoints to a different path, you can use the configprop:man
The following example remaps `/actuator/health` to `/healthcheck`: The following example remaps `/actuator/health` to `/healthcheck`:
.application.properties .application.properties
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoints.web.base-path=/ management:
management.endpoints.web.path-mapping.health=healthcheck endpoints:
web:
base-path: "/"
path-mapping:
health: "healthcheck"
---- ----
...@@ -1239,9 +1301,11 @@ If, however, your application runs inside your own data center, you may prefer t ...@@ -1239,9 +1301,11 @@ If, however, your application runs inside your own data center, you may prefer t
You can set the configprop:management.server.port[] property to change the HTTP port, as shown in the following example: You can set the configprop:management.server.port[] property to change the HTTP port, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.server.port=8081 management:
server:
port: 8081
---- ----
NOTE: On Cloud Foundry, applications only receive requests on port 8080 for both HTTP and TCP routing, by default. NOTE: On Cloud Foundry, applications only receive requests on port 8080 for both HTTP and TCP routing, by default.
...@@ -1254,28 +1318,38 @@ If you want to use a custom management port on Cloud Foundry, you will need to e ...@@ -1254,28 +1318,38 @@ If you want to use a custom management port on Cloud Foundry, you will need to e
When configured to use a custom port, the management server can also be configured with its own SSL by using the various `management.server.ssl.*` properties. When configured to use a custom port, the management server can also be configured with its own SSL by using the various `management.server.ssl.*` properties.
For example, doing so lets a management server be available over HTTP while the main application uses HTTPS, as shown in the following property settings: For example, doing so lets a management server be available over HTTP while the main application uses HTTPS, as shown in the following property settings:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
server.port=8443 server:
server.ssl.enabled=true port: 8443
server.ssl.key-store=classpath:store.jks ssl:
server.ssl.key-password=secret enabled: true
management.server.port=8080 key-store: "classpath:store.jks"
management.server.ssl.enabled=false key-password: secret
management:
server:
port: 8080
ssl:
enabled: false
---- ----
Alternatively, both the main server and the management server can use SSL but with different key stores, as follows: Alternatively, both the main server and the management server can use SSL but with different key stores, as follows:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
server.port=8443 server:
server.ssl.enabled=true port: 8443
server.ssl.key-store=classpath:main.jks ssl:
server.ssl.key-password=secret enabled: true
management.server.port=8080 key-store: "classpath:main.jks"
management.server.ssl.enabled=true key-password: "secret"
management.server.ssl.key-store=classpath:management.jks management:
management.server.ssl.key-password=secret server:
port: 8080
ssl:
enabled: true
key-store: "classpath:management.jks"
key-password: "secret"
---- ----
...@@ -1289,10 +1363,12 @@ NOTE: You can listen on a different address only when the port differs from the ...@@ -1289,10 +1363,12 @@ NOTE: You can listen on a different address only when the port differs from the
The following example `application.properties` does not allow remote management connections: The following example `application.properties` does not allow remote management connections:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.server.port=8081 management:
management.server.address=127.0.0.1 server:
port: 8081
address: "127.0.0.1"
---- ----
...@@ -1301,16 +1377,22 @@ The following example `application.properties` does not allow remote management ...@@ -1301,16 +1377,22 @@ The following example `application.properties` does not allow remote management
=== Disabling HTTP Endpoints === Disabling HTTP Endpoints
If you do not want to expose endpoints over HTTP, you can set the management port to `-1`, as shown in the following example: If you do not want to expose endpoints over HTTP, you can set the management port to `-1`, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.server.port=-1 management:
server:
port: -1
---- ----
This can be achieved using the configprop:management.endpoints.web.exposure.exclude[] property as well, as shown in the following example: This can be achieved using the configprop:management.endpoints.web.exposure.exclude[] property as well, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoints.web.exposure.exclude=* management:
endpoints:
web:
exposure:
exclude: "*"
---- ----
...@@ -1334,10 +1416,15 @@ To solve this problem, you can set the configprop:spring.jmx.unique-names[] prop ...@@ -1334,10 +1416,15 @@ To solve this problem, you can set the configprop:spring.jmx.unique-names[] prop
You can also customize the JMX domain under which endpoints are exposed. You can also customize the JMX domain under which endpoints are exposed.
The following settings show an example of doing so in `application.properties`: The following settings show an example of doing so in `application.properties`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.jmx.unique-names=true spring:
management.endpoints.jmx.domain=com.example.myapp jmx:
unique-names: true
management:
endpoints:
jmx:
domain: "com.example.myapp"
---- ----
...@@ -1346,9 +1433,13 @@ The following settings show an example of doing so in `application.properties`: ...@@ -1346,9 +1433,13 @@ The following settings show an example of doing so in `application.properties`:
=== Disabling JMX Endpoints === Disabling JMX Endpoints
If you do not want to expose endpoints over JMX, you can set the configprop:management.endpoints.jmx.exposure.exclude[] property to `*`, as shown in the following example: If you do not want to expose endpoints over JMX, you can set the configprop:management.endpoints.jmx.exposure.exclude[] property to `*`, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoints.jmx.exposure.exclude=* management:
endpoints:
jmx:
exposure:
exclude: "*"
---- ----
...@@ -1382,9 +1473,13 @@ Jolokia has a number of settings that you would traditionally configure by setti ...@@ -1382,9 +1473,13 @@ Jolokia has a number of settings that you would traditionally configure by setti
With Spring Boot, you can use your `application.properties` file. With Spring Boot, you can use your `application.properties` file.
To do so, prefix the parameter with `management.endpoint.jolokia.config.`, as shown in the following example: To do so, prefix the parameter with `management.endpoint.jolokia.config.`, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoint.jolokia.config.debug=true management:
endpoint:
jolokia:
config:
debug: true
---- ----
...@@ -1393,9 +1488,12 @@ To do so, prefix the parameter with `management.endpoint.jolokia.config.`, as sh ...@@ -1393,9 +1488,12 @@ To do so, prefix the parameter with `management.endpoint.jolokia.config.`, as sh
==== Disabling Jolokia ==== Disabling Jolokia
If you use Jolokia but do not want Spring Boot to configure it, set the configprop:management.endpoint.jolokia.enabled[] property to `false`, as follows: If you use Jolokia but do not want Spring Boot to configure it, set the configprop:management.endpoint.jolokia.enabled[] property to `false`, as follows:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.endpoint.jolokia.enabled=false management:
endpoint:
jolokia:
enabled: false
---- ----
...@@ -1470,23 +1568,33 @@ Most registries share common features. ...@@ -1470,23 +1568,33 @@ Most registries share common features.
For instance, you can disable a particular registry even if the Micrometer registry implementation is on the classpath. For instance, you can disable a particular registry even if the Micrometer registry implementation is on the classpath.
For example, to disable Datadog: For example, to disable Datadog:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.datadog.enabled=false management:
metrics:
export:
datadog:
enabled: false
---- ----
You can also disable all registries unless stated otherwise by the registry-specific property, as shown in the following example: You can also disable all registries unless stated otherwise by the registry-specific property, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.defaults.enabled=false management:
metrics:
export:
defaults:
enabled: false
---- ----
Spring Boot will also add any auto-configured registries to the global static composite registry on the `Metrics` class unless you explicitly tell it not to: Spring Boot will also add any auto-configured registries to the global static composite registry on the `Metrics` class unless you explicitly tell it not to:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.use-global-registry=false management:
metrics:
use-global-registry: false
---- ----
You can register any number of `MeterRegistryCustomizer` beans to further configure the registry, such as applying common tags, before any meters are registered with the registry: You can register any number of `MeterRegistryCustomizer` beans to further configure the registry, such as applying common tags, before any meters are registered with the registry:
...@@ -1523,9 +1631,13 @@ Spring Boot also <<production-ready-metrics-meter,configures built-in instrument ...@@ -1523,9 +1631,13 @@ Spring Boot also <<production-ready-metrics-meter,configures built-in instrument
By default, the AppOptics registry pushes metrics to `https://api.appoptics.com/v1/measurements` periodically. By default, the AppOptics registry pushes metrics to `https://api.appoptics.com/v1/measurements` periodically.
To export metrics to SaaS {micrometer-registry-docs}/appOptics[AppOptics], your API token must be provided: To export metrics to SaaS {micrometer-registry-docs}/appOptics[AppOptics], your API token must be provided:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.appoptics.api-token=YOUR_TOKEN management:
metrics:
export:
appoptics:
api-token: "YOUR_TOKEN"
---- ----
...@@ -1535,9 +1647,13 @@ To export metrics to SaaS {micrometer-registry-docs}/appOptics[AppOptics], your ...@@ -1535,9 +1647,13 @@ To export metrics to SaaS {micrometer-registry-docs}/appOptics[AppOptics], your
By default, metrics are exported to {micrometer-registry-docs}/atlas[Atlas] running on your local machine. By default, metrics are exported to {micrometer-registry-docs}/atlas[Atlas] running on your local machine.
The location of the https://github.com/Netflix/atlas[Atlas server] to use can be provided using: The location of the https://github.com/Netflix/atlas[Atlas server] to use can be provided using:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.atlas.uri=https://atlas.example.com:7101/api/v1/publish management:
metrics:
export:
atlas:
uri: "https://atlas.example.com:7101/api/v1/publish"
---- ----
...@@ -1547,16 +1663,24 @@ The location of the https://github.com/Netflix/atlas[Atlas server] to use can be ...@@ -1547,16 +1663,24 @@ The location of the https://github.com/Netflix/atlas[Atlas server] to use can be
Datadog registry pushes metrics to https://www.datadoghq.com[datadoghq] periodically. Datadog registry pushes metrics to https://www.datadoghq.com[datadoghq] periodically.
To export metrics to {micrometer-registry-docs}/datadog[Datadog], your API key must be provided: To export metrics to {micrometer-registry-docs}/datadog[Datadog], your API key must be provided:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.datadog.api-key=YOUR_KEY management:
metrics:
export:
datadog:
api-key: "YOUR_KEY"
---- ----
You can also change the interval at which metrics are sent to Datadog: You can also change the interval at which metrics are sent to Datadog:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.datadog.step=30s management:
metrics:
export:
datadog:
step: "30s"
---- ----
...@@ -1566,18 +1690,26 @@ You can also change the interval at which metrics are sent to Datadog: ...@@ -1566,18 +1690,26 @@ You can also change the interval at which metrics are sent to Datadog:
Dynatrace registry pushes metrics to the configured URI periodically. Dynatrace registry pushes metrics to the configured URI periodically.
To export metrics to {micrometer-registry-docs}/dynatrace[Dynatrace], your API token, device ID, and URI must be provided: To export metrics to {micrometer-registry-docs}/dynatrace[Dynatrace], your API token, device ID, and URI must be provided:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.dynatrace.api-token=YOUR_TOKEN management:
management.metrics.export.dynatrace.device-id=YOUR_DEVICE_ID metrics:
management.metrics.export.dynatrace.uri=YOUR_URI export:
dynatrace:
api-token: "YOUR_TOKEN"
device-id: "YOUR_DEVICE_ID"
uri: "YOUR_URI"
---- ----
You can also change the interval at which metrics are sent to Dynatrace: You can also change the interval at which metrics are sent to Dynatrace:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.dynatrace.step=30s management:
metrics:
export:
dynatrace:
step: "30s"
---- ----
...@@ -1587,9 +1719,13 @@ You can also change the interval at which metrics are sent to Dynatrace: ...@@ -1587,9 +1719,13 @@ You can also change the interval at which metrics are sent to Dynatrace:
By default, metrics are exported to {micrometer-registry-docs}/elastic[Elastic] running on your local machine. By default, metrics are exported to {micrometer-registry-docs}/elastic[Elastic] running on your local machine.
The location of the Elastic server to use can be provided using the following property: The location of the Elastic server to use can be provided using the following property:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.elastic.host=https://elastic.example.com:8086 management:
metrics:
export:
elastic:
host: "https://elastic.example.com:8086"
---- ----
...@@ -1599,10 +1735,14 @@ The location of the Elastic server to use can be provided using the following pr ...@@ -1599,10 +1735,14 @@ The location of the Elastic server to use can be provided using the following pr
By default, metrics are exported to {micrometer-registry-docs}/ganglia[Ganglia] running on your local machine. By default, metrics are exported to {micrometer-registry-docs}/ganglia[Ganglia] running on your local machine.
The http://ganglia.sourceforge.net[Ganglia server] host and port to use can be provided using: The http://ganglia.sourceforge.net[Ganglia server] host and port to use can be provided using:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.ganglia.host=ganglia.example.com management:
management.metrics.export.ganglia.port=9649 metrics:
export:
ganglia:
host: "ganglia.example.com"
port: 9649
---- ----
...@@ -1612,10 +1752,14 @@ The http://ganglia.sourceforge.net[Ganglia server] host and port to use can be p ...@@ -1612,10 +1752,14 @@ The http://ganglia.sourceforge.net[Ganglia server] host and port to use can be p
By default, metrics are exported to {micrometer-registry-docs}/graphite[Graphite] running on your local machine. By default, metrics are exported to {micrometer-registry-docs}/graphite[Graphite] running on your local machine.
The https://graphiteapp.org[Graphite server] host and port to use can be provided using: The https://graphiteapp.org[Graphite server] host and port to use can be provided using:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.graphite.host=graphite.example.com management:
management.metrics.export.graphite.port=9004 metrics:
export:
graphite:
host: "graphite.example.com"
port: 9004
---- ----
Micrometer provides a default `HierarchicalNameMapper` that governs how a dimensional meter id is {micrometer-registry-docs}/graphite#_hierarchical_name_mapping[mapped to flat hierarchical names]. Micrometer provides a default `HierarchicalNameMapper` that governs how a dimensional meter id is {micrometer-registry-docs}/graphite#_hierarchical_name_mapping[mapped to flat hierarchical names].
...@@ -1638,17 +1782,26 @@ public GraphiteMeterRegistry graphiteMeterRegistry(GraphiteConfig config, Clock ...@@ -1638,17 +1782,26 @@ public GraphiteMeterRegistry graphiteMeterRegistry(GraphiteConfig config, Clock
By default, the Humio registry pushes metrics to https://cloud.humio.com periodically. By default, the Humio registry pushes metrics to https://cloud.humio.com periodically.
To export metrics to SaaS {micrometer-registry-docs}/humio[Humio], your API token must be provided: To export metrics to SaaS {micrometer-registry-docs}/humio[Humio], your API token must be provided:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.humio.api-token=YOUR_TOKEN management:
metrics:
export:
humio:
api-token: "YOUR_TOKEN"
---- ----
You should also configure one or more tags to identify the data source to which metrics will be pushed: You should also configure one or more tags to identify the data source to which metrics will be pushed:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.humio.tags.alpha=a management:
management.metrics.export.humio.tags.bravo=b metrics:
export:
humio:
tags:
alpha: "a"
bravo: "b"
---- ----
...@@ -1658,9 +1811,13 @@ You should also configure one or more tags to identify the data source to which ...@@ -1658,9 +1811,13 @@ You should also configure one or more tags to identify the data source to which
By default, metrics are exported to {micrometer-registry-docs}/influx[Influx] running on your local machine. By default, metrics are exported to {micrometer-registry-docs}/influx[Influx] running on your local machine.
The location of the https://www.influxdata.com[Influx server] to use can be provided using: The location of the https://www.influxdata.com[Influx server] to use can be provided using:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.influx.uri=https://influx.example.com:8086 management:
metrics:
export:
influx:
uri: "https://influx.example.com:8086"
---- ----
...@@ -1671,9 +1828,13 @@ Micrometer provides a hierarchical mapping to {micrometer-registry-docs}/jmx[JMX ...@@ -1671,9 +1828,13 @@ Micrometer provides a hierarchical mapping to {micrometer-registry-docs}/jmx[JMX
By default, metrics are exported to the `metrics` JMX domain. By default, metrics are exported to the `metrics` JMX domain.
The domain to use can be provided using: The domain to use can be provided using:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.jmx.domain=com.example.app.metrics management:
metrics:
export:
jmx:
domain: "com.example.app.metrics"
---- ----
Micrometer provides a default `HierarchicalNameMapper` that governs how a dimensional meter id is {micrometer-registry-docs}/jmx#_hierarchical_name_mapping[mapped to flat hierarchical names]. Micrometer provides a default `HierarchicalNameMapper` that governs how a dimensional meter id is {micrometer-registry-docs}/jmx#_hierarchical_name_mapping[mapped to flat hierarchical names].
...@@ -1696,9 +1857,13 @@ public JmxMeterRegistry jmxMeterRegistry(JmxConfig config, Clock clock) { ...@@ -1696,9 +1857,13 @@ public JmxMeterRegistry jmxMeterRegistry(JmxConfig config, Clock clock) {
By default, metrics are exported to {micrometer-registry-docs}/kairos[KairosDB] running on your local machine. By default, metrics are exported to {micrometer-registry-docs}/kairos[KairosDB] running on your local machine.
The location of the https://kairosdb.github.io/[KairosDB server] to use can be provided using: The location of the https://kairosdb.github.io/[KairosDB server] to use can be provided using:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.kairos.uri=https://kairosdb.example.com:8080/api/v1/datapoints management:
metrics:
export:
kairos:
uri: "https://kairosdb.example.com:8080/api/v1/datapoints"
---- ----
...@@ -1708,24 +1873,36 @@ The location of the https://kairosdb.github.io/[KairosDB server] to use can be p ...@@ -1708,24 +1873,36 @@ The location of the https://kairosdb.github.io/[KairosDB server] to use can be p
New Relic registry pushes metrics to {micrometer-registry-docs}/new-relic[New Relic] periodically. New Relic registry pushes metrics to {micrometer-registry-docs}/new-relic[New Relic] periodically.
To export metrics to https://newrelic.com[New Relic], your API key and account id must be provided: To export metrics to https://newrelic.com[New Relic], your API key and account id must be provided:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.newrelic.api-key=YOUR_KEY management:
management.metrics.export.newrelic.account-id=YOUR_ACCOUNT_ID metrics:
export:
newrelic:
api-key: "YOUR_KEY"
account-id: "YOUR_ACCOUNT_ID"
---- ----
You can also change the interval at which metrics are sent to New Relic: You can also change the interval at which metrics are sent to New Relic:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.newrelic.step=30s management:
metrics:
export:
newrelic:
step: "30s"
---- ----
By default, metrics are published via REST calls but it is also possible to use the Java Agent API if you have it on the classpath: By default, metrics are published via REST calls but it is also possible to use the Java Agent API if you have it on the classpath:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.newrelic.client-provider-type=insights-agent management:
metrics:
export:
newrelic:
client-provider-type: "insights-agent"
---- ----
Finally, you can take full control by defining your own `NewRelicClientProvider` bean. Finally, you can take full control by defining your own `NewRelicClientProvider` bean.
...@@ -1774,16 +1951,24 @@ For advanced configuration, you can also provide your own `PrometheusPushGateway ...@@ -1774,16 +1951,24 @@ For advanced configuration, you can also provide your own `PrometheusPushGateway
SignalFx registry pushes metrics to {micrometer-registry-docs}/signalFx[SignalFx] periodically. SignalFx registry pushes metrics to {micrometer-registry-docs}/signalFx[SignalFx] periodically.
To export metrics to https://www.signalfx.com[SignalFx], your access token must be provided: To export metrics to https://www.signalfx.com[SignalFx], your access token must be provided:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.signalfx.access-token=YOUR_ACCESS_TOKEN management:
metrics:
export:
signalfx:
access-token: "YOUR_ACCESS_TOKEN"
---- ----
You can also change the interval at which metrics are sent to SignalFx: You can also change the interval at which metrics are sent to SignalFx:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.signalfx.step=30s management:
metrics:
export:
signalfx:
step: "30s"
---- ----
...@@ -1796,9 +1981,13 @@ This allows you to see what metrics are collected in the <<production-ready-metr ...@@ -1796,9 +1981,13 @@ This allows you to see what metrics are collected in the <<production-ready-metr
The in-memory backend disables itself as soon as you're using any of the other available backend. The in-memory backend disables itself as soon as you're using any of the other available backend.
You can also disable it explicitly: You can also disable it explicitly:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.simple.enabled=false management:
metrics:
export:
simple:
enabled: false
---- ----
...@@ -1808,16 +1997,24 @@ You can also disable it explicitly: ...@@ -1808,16 +1997,24 @@ You can also disable it explicitly:
Stackdriver registry pushes metrics to https://cloud.google.com/stackdriver/[Stackdriver] periodically. Stackdriver registry pushes metrics to https://cloud.google.com/stackdriver/[Stackdriver] periodically.
To export metrics to SaaS {micrometer-registry-docs}/stackdriver[Stackdriver], your Google Cloud project id must be provided: To export metrics to SaaS {micrometer-registry-docs}/stackdriver[Stackdriver], your Google Cloud project id must be provided:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.stackdriver.project-id=my-project management:
metrics:
export:
stackdriver:
project-id: "my-project"
---- ----
You can also change the interval at which metrics are sent to Stackdriver: You can also change the interval at which metrics are sent to Stackdriver:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.stackdriver.step=30s management:
metrics:
export:
stackdriver:
step: "30s"
---- ----
...@@ -1828,18 +2025,26 @@ The StatsD registry pushes metrics over UDP to a StatsD agent eagerly. ...@@ -1828,18 +2025,26 @@ The StatsD registry pushes metrics over UDP to a StatsD agent eagerly.
By default, metrics are exported to a {micrometer-registry-docs}/statsD[StatsD] agent running on your local machine. By default, metrics are exported to a {micrometer-registry-docs}/statsD[StatsD] agent running on your local machine.
The StatsD agent host, port, and protocol to use can be provided using: The StatsD agent host, port, and protocol to use can be provided using:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.statsd.host=statsd.example.com management:
management.metrics.export.statsd.port=9125 metrics:
management.metrics.export.statsd.protocol=udp export:
statsd:
host: "statsd.example.com"
port: 9125
protocol: "udp"
---- ----
You can also change the StatsD line protocol to use (default to Datadog): You can also change the StatsD line protocol to use (default to Datadog):
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.statsd.flavor=etsy management:
metrics:
export:
statsd:
flavor: "etsy"
---- ----
...@@ -1849,25 +2054,37 @@ You can also change the StatsD line protocol to use (default to Datadog): ...@@ -1849,25 +2054,37 @@ You can also change the StatsD line protocol to use (default to Datadog):
Wavefront registry pushes metrics to {micrometer-registry-docs}/wavefront[Wavefront] periodically. Wavefront registry pushes metrics to {micrometer-registry-docs}/wavefront[Wavefront] periodically.
If you are exporting metrics to https://www.wavefront.com/[Wavefront] directly, your API token must be provided: If you are exporting metrics to https://www.wavefront.com/[Wavefront] directly, your API token must be provided:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.wavefront.api-token=YOUR_API_TOKEN management:
metrics:
export:
wavefront:
api-token: "YOUR_API_TOKEN"
---- ----
Alternatively, you may use a Wavefront sidecar or an internal proxy set up in your environment that forwards metrics data to the Wavefront API host: Alternatively, you may use a Wavefront sidecar or an internal proxy set up in your environment that forwards metrics data to the Wavefront API host:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.wavefront.uri=proxy://localhost:2878 management:
metrics:
export:
wavefront:
uri: "proxy://localhost:2878"
---- ----
TIP: If publishing metrics to a Wavefront proxy (as described in https://docs.wavefront.com/proxies_installing.html[the documentation]), the host must be in the `proxy://HOST:PORT` format. TIP: If publishing metrics to a Wavefront proxy (as described in https://docs.wavefront.com/proxies_installing.html[the documentation]), the host must be in the `proxy://HOST:PORT` format.
You can also change the interval at which metrics are sent to Wavefront: You can also change the interval at which metrics are sent to Wavefront:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.export.wavefront.step=30s management:
metrics:
export:
wavefront:
step: "30s"
---- ----
...@@ -2119,9 +2336,12 @@ Metrics are also tagged by the name of the `EntityManagerFactory` that is derive ...@@ -2119,9 +2336,12 @@ Metrics are also tagged by the name of the `EntityManagerFactory` that is derive
To enable statistics, the standard JPA property `hibernate.generate_statistics` must be set to `true`. To enable statistics, the standard JPA property `hibernate.generate_statistics` must be set to `true`.
You can enable that on the auto-configured `EntityManagerFactory` as shown in the following example: You can enable that on the auto-configured `EntityManagerFactory` as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.jpa.properties.hibernate.generate_statistics=true spring:
jpa:
properties:
"[hibernate.generate_statistics]": true
---- ----
...@@ -2180,10 +2400,13 @@ include::{code-examples}/actuate/metrics/MetricsFilterBeanExample.java[tag=confi ...@@ -2180,10 +2400,13 @@ include::{code-examples}/actuate/metrics/MetricsFilterBeanExample.java[tag=confi
Common tags are generally used for dimensional drill-down on the operating environment like host, instance, region, stack, etc. Common tags are generally used for dimensional drill-down on the operating environment like host, instance, region, stack, etc.
Commons tags are applied to all meters and can be configured as shown in the following example: Commons tags are applied to all meters and can be configured as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.tags.region=us-east-1 management:
management.metrics.tags.stack=prod metrics:
tags:
region: "us-east-1"
stack: "prod"
---- ----
The example above adds `region` and `stack` tags to all meters with a value of `us-east-1` and `prod` respectively. The example above adds `region` and `stack` tags to all meters with a value of `us-east-1` and `prod` respectively.
...@@ -2198,9 +2421,13 @@ In addition to `MeterFilter` beans, it's also possible to apply a limited set of ...@@ -2198,9 +2421,13 @@ In addition to `MeterFilter` beans, it's also possible to apply a limited set of
Per-meter customizations apply to any all meter IDs that start with the given name. Per-meter customizations apply to any all meter IDs that start with the given name.
For example, the following will disable any meters that have an ID starting with `example.remote` For example, the following will disable any meters that have an ID starting with `example.remote`
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.metrics.enable.example.remote=false management:
metrics:
enable:
example:
remote: false
---- ----
The following properties allow per-meter customization: The following properties allow per-meter customization:
...@@ -2347,9 +2574,11 @@ If you want to fully disable the `/cloudfoundryapplication` endpoints, you can a ...@@ -2347,9 +2574,11 @@ If you want to fully disable the `/cloudfoundryapplication` endpoints, you can a
.application.properties .application.properties
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.cloudfoundry.enabled=false management:
cloudfoundry:
enabled: false
---- ----
...@@ -2360,9 +2589,11 @@ By default, the security verification for `/cloudfoundryapplication` endpoints m ...@@ -2360,9 +2589,11 @@ By default, the security verification for `/cloudfoundryapplication` endpoints m
If your Cloud Foundry UAA or Cloud Controller services use self-signed certificates, you need to set the following property: If your Cloud Foundry UAA or Cloud Controller services use self-signed certificates, you need to set the following property:
.application.properties .application.properties
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
management.cloudfoundry.skip-ssl-validation=true management:
cloudfoundry:
skip-ssl-validation: true
---- ----
......
spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc
View file @ 25952584
...@@ -96,9 +96,11 @@ For these reasons, lazy initialization is not enabled by default and it is recom ...@@ -96,9 +96,11 @@ For these reasons, lazy initialization is not enabled by default and it is recom
Lazy initialization can be enabled programmatically using the `lazyInitialization` method on `SpringApplicationBuilder` or the `setLazyInitialization` method on `SpringApplication`. 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 configprop:spring.main.lazy-initialization[] property as shown in the following example: Alternatively, it can be enabled using the configprop:spring.main.lazy-initialization[] property as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.main.lazy-initialization=true spring:
main:
lazy-initialization: true
---- ----
TIP: 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. TIP: 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.
...@@ -713,10 +715,13 @@ Imports are processed as they are discovered, and are treated as an additional d ...@@ -713,10 +715,13 @@ Imports are processed as they are discovered, and are treated as an additional d
For example, you might have the following in your classpath `application.properties` file: For example, you might have the following in your classpath `application.properties` file:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
spring.application.name=myapp spring:
spring.config.import=optional:file:./dev.properties 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). This will trigger the import of a `dev.properties` file in current directory (if such a file exists).
...@@ -747,9 +752,11 @@ You can do this by putting an extension hint in square brackets. ...@@ -747,9 +752,11 @@ 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. 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: You can import it from your `application.properties` using the following:
[source,properties,indent=0] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.config.import=file:/etc/config/myconfig[.yaml] spring:
config:
import: "file:/etc/config/myconfig[.yaml]"
---- ----
...@@ -783,11 +790,13 @@ As an example, let's imagine that Kubernetes has mounted the following volume: ...@@ -783,11 +790,13 @@ As an example, let's imagine that Kubernetes has mounted the following volume:
The contents of the `username` file would be a config value, and the contents of `password` would be a secret. 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` file: To import these properties, you can add the following to your `application.properties` or `application.yaml` file:
[source,properties,indent=0] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.config.import=optional:configtree:/etc/config spring:
config:
import: "optional:configtree:/etc/config"
---- ----
You can then access or inject `myapp.username` and `myapp.password` properties from the `Environment` in the usual way. You can then access or inject `myapp.username` and `myapp.password` properties from the `Environment` in the usual way.
...@@ -801,12 +810,13 @@ TIP: Configuration tree values can be bound to both string `String` and `byte[]` ...@@ -801,12 +810,13 @@ TIP: Configuration tree values can be bound to both string `String` and `byte[]`
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 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. The standard `$\{name}` property-placeholder syntax can be used anywhere within a value.
For example, the following `application.properties` file will set `app.description` to "`MyApp is a Spring Boot application`": For example, the following file will set `app.description` to "`MyApp is a Spring Boot application`":
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
app.name=MyApp app:
app.description=${app.name} is a Spring Boot application name: "MyApp"
description: "${app.name} is a Spring Boot application"
---- ----
TIP: You can also use this technique to create "`short`" variants of existing Spring Boot properties. TIP: You can also use this technique to create "`short`" variants of existing Spring Boot properties.
...@@ -873,13 +883,17 @@ The following activation properties are available: ...@@ -873,13 +883,17 @@ The following activation properties are available:
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: 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:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
myprop=always-set myprop:
#--- always-set
spring.config.activate.on-cloud-platform=kubernetes ---
spring.config.activate.on-profile=prod | staging spring:
myotherprop=sometimes-set config:
activate:
on-cloud-platform: "kubernetes"
on-profile: "prod | staging"
myotherprop: sometimes-set
---- ----
...@@ -995,14 +1009,15 @@ Stick to using only one of them. ...@@ -995,14 +1009,15 @@ Stick to using only one of them.
The `RandomValuePropertySource` is useful for injecting random values (for example, into secrets or test cases). 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: It can produce integers, longs, uuids, or strings, as shown in the following example:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
my.secret=${random.value} my:
my.number=${random.int} secret: "${random.value}"
my.bignumber=${random.long} number: "${random.int}"
my.uuid=${random.uuid} bignumber: "${random.long}"
my.number.less.than.ten=${random.int(10)} uuid: "${random.uuid}"
my.number.in.range=${random.int[1024,65536]} 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. The `+random.int*+` syntax is `OPEN value (,max) CLOSE` where the `OPEN,CLOSE` are any character and `value,max` are integers.
...@@ -1271,8 +1286,6 @@ This style of configuration works particularly well with the `SpringApplication` ...@@ -1271,8 +1286,6 @@ This style of configuration works particularly well with the `SpringApplication`
[source,yaml,indent=0] [source,yaml,indent=0]
---- ----
# application.yml
acme: acme:
remote-address: 192.168.1.1 remote-address: 192.168.1.1
security: security:
...@@ -1280,8 +1293,6 @@ This style of configuration works particularly well with the `SpringApplication` ...@@ -1280,8 +1293,6 @@ This style of configuration works particularly well with the `SpringApplication`
roles: roles:
- USER - USER
- ADMIN - ADMIN
# additional configuration as required
---- ----
To work with `@ConfigurationProperties` beans, you can inject them in the same way as any other bean, as shown in the following example: To work with `@ConfigurationProperties` beans, you can inject them in the same way as any other bean, as shown in the following example:
...@@ -1427,14 +1438,23 @@ When binding to `Map` properties, if the `key` contains anything other than lowe ...@@ -1427,14 +1438,23 @@ When binding to `Map` properties, if the `key` contains anything other than lowe
If the key is not surrounded by `[]`, any characters that are not alpha-numeric or `-` are removed. 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`: For example, consider binding the following properties to a `Map`:
[source,yaml,indent=0]
[source,properties,indent=0,role="primary"]
.Properties
----
acme.map.[/key1]=value1
acme.map.[/key2]=value2
acme.map./key3=value3
----
[source,yaml,indent=0,role="secondary"]
.Yaml
---- ----
acme: acme:
map: map:
"[/key1]": value1 "[/key1]": value1
"[/key2]": value2 "[/key2]": value2
/key3: value3 "/key3": value3
---- ----
The properties above will bind to a `Map` with `/key1`, `/key2` and `key3` as the keys in the map. The properties above will bind to a `Map` with `/key1`, `/key2` and `key3` as the keys in the map.
...@@ -1442,6 +1462,7 @@ The properties above will bind to a `Map` with `/key1`, `/key2` and `key3` as th ...@@ -1442,6 +1462,7 @@ The properties above will bind to a `Map` with `/key1`, `/key2` and `key3` as th
NOTE: For YAML files, the brackets need to be surrounded by quotes for the keys to be parsed properly. NOTE: For YAML files, the brackets need to be surrounded by quotes for the keys to be parsed properly.
[[boot-features-external-config-relaxed-binding-from-environment-variables]] [[boot-features-external-config-relaxed-binding-from-environment-variables]]
===== Binding from Environment Variables ===== Binding from Environment Variables
Most operating systems impose strict rules around the names that can be used for environment variables. Most operating systems impose strict rules around the names that can be used for environment variables.
...@@ -1491,18 +1512,20 @@ The following example exposes a list of `MyPojo` objects from `AcmeProperties`: ...@@ -1491,18 +1512,20 @@ The following example exposes a list of `MyPojo` objects from `AcmeProperties`:
Consider the following configuration: Consider the following configuration:
[source,yaml,indent=0] [source,yaml,indent=0,configblocks]
---- ----
acme: acme:
list: list:
- name: my name - name: "my name"
description: my description description: "my description"
--- ---
spring: spring:
profiles: dev config:
activate:
on-profile: "dev"
acme: acme:
list: list:
- name: my another name - name: "my another name"
---- ----
If the `dev` profile is not active, `AcmeProperties.list` contains one `MyPojo` entry, as previously defined. If the `dev` profile is not active, `AcmeProperties.list` contains one `MyPojo` entry, as previously defined.
...@@ -1512,20 +1535,22 @@ This configuration _does not_ add a second `MyPojo` instance to the list, and it ...@@ -1512,20 +1535,22 @@ This configuration _does not_ add a second `MyPojo` instance to the list, and it
When a `List` is specified in multiple profiles, the one with the highest priority (and only that one) is used. When a `List` is specified in multiple profiles, the one with the highest priority (and only that one) is used.
Consider the following example: Consider the following example:
[source,yaml,indent=0] [source,yaml,indent=0,configblocks]
---- ----
acme: acme:
list: list:
- name: my name - name: "my name"
description: my description description: "my description"
- name: another name - name: "another name"
description: another description description: "another description"
--- ---
spring: spring:
profiles: dev config:
activate:
on-profile: "dev"
acme: acme:
list: list:
- name: my another name - name: "my another name"
---- ----
In the preceding example, if the `dev` profile is active, `AcmeProperties.list` contains _one_ `MyPojo` entry (with a name of `my another name` and a description of `null`). In the preceding example, if the `dev` profile is active, `AcmeProperties.list` contains _one_ `MyPojo` entry (with a name of `my another name` and a description of `null`).
...@@ -1551,29 +1576,31 @@ The following example exposes a `Map<String, MyPojo>` from `AcmeProperties`: ...@@ -1551,29 +1576,31 @@ The following example exposes a `Map<String, MyPojo>` from `AcmeProperties`:
Consider the following configuration: Consider the following configuration:
[source,yaml,indent=0] [source,yaml,indent=0,configblocks]
---- ----
acme: acme:
map: map:
key1: key1:
name: my name 1 name: "my name 1"
description: my description 1 description: "my description 1"
--- ---
spring: spring:
profiles: dev config:
activate:
on-profile: "dev"
acme: acme:
map: map:
key1: key1:
name: dev name 1 name: "dev name 1"
key2: key2:
name: dev name 2 name: "dev name 2"
description: dev description 2 description: "dev description 2"
---- ----
If the `dev` profile is not active, `AcmeProperties.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 not active, `AcmeProperties.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`). 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`).
NOTE: The preceding merging rules apply to properties from all property sources and not just YAML files. NOTE: The preceding merging rules apply to properties from all property sources, and not just files.
...@@ -1813,9 +1840,11 @@ You can use a configprop:spring.profiles.active[] `Environment` property to spec ...@@ -1813,9 +1840,11 @@ You can use a configprop:spring.profiles.active[] `Environment` property to spec
You can specify the property in any of the ways described earlier in this chapter. 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: For example, you could include it in your `application.properties`, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.profiles.active=dev,hsqldb spring:
profiles:
active: "dev,hsqldb"
---- ----
You could also specify it on the command line by using the following switch: `--spring.profiles.active=dev,hsqldb`. You could also specify it on the command line by using the following switch: `--spring.profiles.active=dev,hsqldb`.
...@@ -1843,11 +1872,14 @@ A profile group allows you to define a logical name for a related group of profi ...@@ -1843,11 +1872,14 @@ A profile group allows you to define a logical name for a related group of profi
For example, we can create a `production` group that consists of our `proddb` and `prodmq` profiles. For example, we can create a `production` group that consists of our `proddb` and `prodmq` profiles.
[source,yaml,indent=0] [source,yaml,indent=0,configblocks]
---- ----
spring.profiles.group.production: spring:
- proddb profiles:
- prodmq 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. Our application can now be started using `--spring.profiles.active=production` to active the `production`, `proddb` and `prodmq` profiles in one hit.
...@@ -2040,13 +2072,24 @@ The `root` logger can be configured by using `logging.level.root`. ...@@ -2040,13 +2072,24 @@ The `root` logger can be configured by using `logging.level.root`.
The following example shows potential logging settings in `application.properties`: The following example shows potential logging settings in `application.properties`:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,properties,indent=0,subs="verbatim,quotes,attributes",configprops,role="primary"]
.Properties
---- ----
logging.level.root=warn logging.level.root=warn
logging.level.org.springframework.web=debug logging.level.org.springframework.web=debug
logging.level.org.hibernate=error logging.level.org.hibernate=error
---- ----
[source,properties,indent=0,subs="verbatim,quotes,attributes",role="secondary"]
.Yaml
----
logging:
level:
root: "warn"
org.springframework.web: "debug"
org.hibernate: "error"
----
It's also possible to set logging levels using environment variables. It's also possible to set logging levels using environment variables.
For example, `LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG` will set `org.springframework.web` to `DEBUG`. For example, `LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG` will set `org.springframework.web` to `DEBUG`.
...@@ -2064,16 +2107,20 @@ For example, you might commonly change the logging levels for _all_ Tomcat relat ...@@ -2064,16 +2107,20 @@ For example, you might commonly change the logging levels for _all_ Tomcat relat
To help with this, Spring Boot allows you to define logging groups in your Spring `Environment`. To help with this, Spring Boot allows you to define logging groups in your Spring `Environment`.
For example, here's how you could define a "`tomcat`" group by adding it to your `application.properties`: For example, here's how you could define a "`tomcat`" group by adding it to your `application.properties`:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
logging.group.tomcat=org.apache.catalina, org.apache.coyote, org.apache.tomcat logging:
group:
tomcat: "org.apache.catalina,org.apache.coyote,org.apache.tomcat"
---- ----
Once defined, you can change the level for all the loggers in the group with a single line: Once defined, you can change the level for all the loggers in the group with a single line:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
logging.level.tomcat=TRACE logging:
level:
tomcat: "trace"
---- ----
Spring Boot includes the following pre-defined logging groups that can be used out-of-the-box: Spring Boot includes the following pre-defined logging groups that can be used out-of-the-box:
...@@ -2297,10 +2344,12 @@ If no properties file is found that matches any of the configured base names, th ...@@ -2297,10 +2344,12 @@ If no properties file is found that matches any of the configured base names, th
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: 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:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.messages.basename=messages,config.i18n.messages spring:
spring.messages.fallback-to-system-locale=false messages:
basename: "messages,config.i18n.messages"
fallback-to-system-locale: false
---- ----
TIP: `spring.messages.basename` supports comma-separated list of locations, either a package qualifier or a resource resolved from the classpath root. TIP: `spring.messages.basename` supports comma-separated list of locations, either a package qualifier or a resource resolved from the classpath root.
...@@ -2504,9 +2553,11 @@ Most of the time, this does not happen (unless you modify the default MVC config ...@@ -2504,9 +2553,11 @@ Most of the time, this does not happen (unless you modify the default MVC config
By default, resources are mapped on `+/**+`, but you can tune that with the configprop:spring.mvc.static-path-pattern[] property. By default, resources are mapped on `+/**+`, but you can tune that with the configprop:spring.mvc.static-path-pattern[] property.
For instance, relocating all resources to `/resources/**` can be achieved as follows: For instance, relocating all resources to `/resources/**` can be achieved as follows:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.mvc.static-path-pattern=/resources/** spring:
mvc:
static-path-pattern: "/resources/**"
---- ----
You can also customize the static resource locations by using the configprop:spring.resources.static-locations[] property (replacing the default values with a list of directory locations). You can also customize the static resource locations by using the configprop:spring.resources.static-locations[] property (replacing the default values with a list of directory locations).
...@@ -2529,10 +2580,15 @@ Otherwise, all Webjars resolve as a `404`. ...@@ -2529,10 +2580,15 @@ Otherwise, all Webjars resolve as a `404`.
To use cache busting, the following configuration configures a cache busting solution for all static resources, effectively adding a content hash, such as `<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>`, in URLs: To use cache busting, the following configuration configures a cache busting solution for all static resources, effectively adding a content hash, such as `<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>`, in URLs:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.resources.chain.strategy.content.enabled=true spring:
spring.resources.chain.strategy.content.paths=/** resources:
chain:
strategy:
content:
enabled: true
paths: "/**"
---- ----
NOTE: Links to resources are rewritten in templates at runtime, thanks to a `ResourceUrlEncodingFilter` that is auto-configured for Thymeleaf and FreeMarker. NOTE: Links to resources are rewritten in templates at runtime, thanks to a `ResourceUrlEncodingFilter` that is auto-configured for Thymeleaf and FreeMarker.
...@@ -2543,13 +2599,19 @@ When loading resources dynamically with, for example, a JavaScript module loader ...@@ -2543,13 +2599,19 @@ When loading resources dynamically with, for example, a JavaScript module loader
That is why other strategies are also supported and can be combined. That is why other strategies are also supported and can be combined.
A "fixed" strategy adds a static version string in the URL without changing the file name, as shown in the following example: A "fixed" strategy adds a static version string in the URL without changing the file name, as shown in the following example:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.resources.chain.strategy.content.enabled=true spring:
spring.resources.chain.strategy.content.paths=/** resources:
spring.resources.chain.strategy.fixed.enabled=true chain:
spring.resources.chain.strategy.fixed.paths=/js/lib/ strategy:
spring.resources.chain.strategy.fixed.version=v12 content:
enabled: true
paths: "/**"
fixed:
enabled: true
paths: "/js/lib/"
version: "v12"
---- ----
With this configuration, JavaScript modules located under `"/js/lib/"` use a fixed versioning strategy (`"/v12/js/lib/mymodule.js"`), while other resources still use the content one (`<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>`). With this configuration, JavaScript modules located under `"/js/lib/"` use a fixed versioning strategy (`"/v12/js/lib/mymodule.js"`), while other resources still use the content one (`<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>`).
...@@ -2589,16 +2651,37 @@ Nowadays, Content Negotiation is much more reliable. ...@@ -2589,16 +2651,37 @@ Nowadays, Content Negotiation is much more reliable.
There are other ways to deal with HTTP clients that don't consistently send proper "Accept" request headers. There are other ways to deal with HTTP clients that don't consistently send proper "Accept" request headers.
Instead of using suffix matching, we can use a query parameter to ensure that requests like `"GET /projects/spring-boot?format=json"` will be mapped to `@GetMapping("/projects/spring-boot")`: Instead of using suffix matching, we can use a query parameter to ensure that requests like `"GET /projects/spring-boot?format=json"` will be mapped to `@GetMapping("/projects/spring-boot")`:
[source,yaml,indent=0,subs="verbatim,quotes,attributes",configblocks]
----
spring:
mvc:
contentnegotiation:
favor-parameter: true
----
Or if you prefer to use a different parameter name:
[source,properties,indent=0,subs="verbatim,quotes,attributes"] [source,properties,indent=0,subs="verbatim,quotes,attributes"]
---- ----
spring.mvc.contentnegotiation.favor-parameter=true spring:
mvc:
contentnegotiation:
favor-parameter: true
parameter-name: "myparam"
----
# We can change the parameter name, which is "format" by default: Most standard media types are supported out-of-the-box, but you can also define new ones:
# spring.mvc.contentnegotiation.parameter-name=myparam
# We can also register additional file extensions/media types with: [source,yaml,indent=0,subs="verbatim,quotes,attributes",configblocks]
spring.mvc.contentnegotiation.media-types.markdown=text/markdown
---- ----
spring:
mvc:
contentnegotiation:
media-types:
markdown: "text/markdown"
----
Suffix pattern matching is deprecated and will be removed in a future release. Suffix pattern matching is deprecated and will be removed in a future release.
If you understand the caveats and would still like your application to use suffix pattern matching, the following configuration is required: If you understand the caveats and would still like your application to use suffix pattern matching, the following configuration is required:
...@@ -2611,22 +2694,26 @@ If you understand the caveats and would still like your application to use suffi ...@@ -2611,22 +2694,26 @@ If you understand the caveats and would still like your application to use suffi
Alternatively, rather than open all suffix patterns, it's more secure to only support registered suffix patterns: Alternatively, rather than open all suffix patterns, it's more secure to only support registered suffix patterns:
[source,properties,indent=0,subs="verbatim,quotes,attributes"] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.mvc.contentnegotiation.favor-path-extension=true spring:
spring.mvc.pathmatch.use-registered-suffix-pattern=true mvc:
contentnegotiation:
# You can also register additional file extensions/media types with: favor-path-extension: true
# spring.mvc.contentnegotiation.media-types.adoc=text/asciidoc pathmatch:
use-registered-suffix-pattern: true
---- ----
As of Spring Framework 5.3, Spring MVC supports several implementation strategies for matching request paths to Controller handlers. As of Spring Framework 5.3, Spring MVC supports several implementation strategies for matching request paths to Controller handlers.
It was previously only supporting the `AntPathMatcher` strategy, but it now also offers `PathPatternParser`. It was previously only supporting the `AntPathMatcher` strategy, but it now also offers `PathPatternParser`.
Spring Boot now provides a configuration property to choose and opt in the new strategy: Spring Boot now provides a configuration property to choose and opt in the new strategy:
[source,properties,indent=0,subs="verbatim,quotes,attributes"] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.mvc.pathmatch.matching-strategy=path_pattern_parser spring:
mvc:
pathmatch:
matching-strategy: "path-pattern-parser"
---- ----
For more details on why you should consider this new implementation, please check out the For more details on why you should consider this new implementation, please check out the
...@@ -2999,9 +3086,11 @@ It uses the `ResourceWebHandler` from Spring WebFlux so that you can modify that ...@@ -2999,9 +3086,11 @@ It uses the `ResourceWebHandler` from Spring WebFlux so that you can modify that
By default, resources are mapped on `+/**+`, but you can tune that by setting the configprop:spring.webflux.static-path-pattern[] property. By default, resources are mapped on `+/**+`, but you can tune that by setting the configprop:spring.webflux.static-path-pattern[] property.
For instance, relocating all resources to `/resources/**` can be achieved as follows: For instance, relocating all resources to `/resources/**` can be achieved as follows:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.webflux.static-path-pattern=/resources/** spring:
webflux:
static-path-pattern: "/resources/**"
---- ----
You can also customize the static resource locations by using `spring.resources.static-locations`. You can also customize the static resource locations by using `spring.resources.static-locations`.
...@@ -3264,7 +3353,7 @@ Most applications are auto-configured, and the appropriate `ApplicationContext` ...@@ -3264,7 +3353,7 @@ Most applications are auto-configured, and the appropriate `ApplicationContext`
[[boot-features-customizing-embedded-containers]] [[boot-features-customizing-embedded-containers]]
==== Customizing Embedded Servlet Containers ==== Customizing Embedded Servlet Containers
Common servlet container settings can be configured by using Spring `Environment` properties. Common servlet container settings can be configured by using Spring `Environment` properties.
Usually, you would define the properties in your `application.properties` file. Usually, you would define the properties in your `application.properties` or `application.yaml` file.
Common server settings include: Common server settings include:
...@@ -3382,16 +3471,19 @@ NOTE: Graceful shutdown with Tomcat requires Tomcat 9.0.33 or later. ...@@ -3382,16 +3471,19 @@ NOTE: Graceful shutdown with Tomcat requires Tomcat 9.0.33 or later.
To enable graceful shutdown, configure the configprop:server.shutdown[] property, as shown in the following example: To enable graceful shutdown, configure the configprop:server.shutdown[] property, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
server.shutdown=graceful server:
shutdown: "graceful"
---- ----
To configure the timeout period, configure the configprop:spring.lifecycle.timeout-per-shutdown-phase[] property, as shown in the following example: To configure the timeout period, configure the configprop:spring.lifecycle.timeout-per-shutdown-phase[] property, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.lifecycle.timeout-per-shutdown-phase=20s spring:
lifecycle:
timeout-per-shutdown-phase: "20s"
---- ----
IMPORTANT: Using graceful shutdown with your IDE may not work properly if it does not send a proper `SIGTERM` signal. IMPORTANT: Using graceful shutdown with your IDE may not work properly if it does not send a proper `SIGTERM` signal.
...@@ -3434,11 +3526,13 @@ This depends on the type of application and its configuration. ...@@ -3434,11 +3526,13 @@ 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 (i.e. of type `WebApplicationType.REACTIVE`), the RSocket server will be plugged into the Web Server only if the following properties match:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.rsocket.server.mapping-path=/rsocket # a mapping path is defined spring:
spring.rsocket.server.transport=websocket # websocket is chosen as a transport rsocket:
#spring.rsocket.server.port= # no port is defined server:
mapping-path: "/rsocket"
transport: "websocket"
---- ----
WARNING: Plugging RSocket into a web server is only supported with Reactor Netty, as RSocket itself is built with that library. WARNING: Plugging RSocket into a web server is only supported with Reactor Netty, as RSocket itself is built with that library.
...@@ -3446,10 +3540,12 @@ WARNING: Plugging RSocket into a web server is only supported with Reactor Netty ...@@ -3446,10 +3540,12 @@ WARNING: Plugging RSocket into a web server is only supported with Reactor Netty
Alternatively, an RSocket TCP or websocket server is started as an independent, embedded server. Alternatively, an RSocket TCP or websocket server is started as an independent, embedded server.
Besides the dependency requirements, the only required configuration is to define a port for that server: Besides the dependency requirements, the only required configuration is to define a port for that server:
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops] [source,yaml,indent=0,subs="verbatim,quotes,attributes",configprops,configblocks]
---- ----
spring.rsocket.server.port=9898 # the only required configuration spring:
spring.rsocket.server.transport=tcp # you're free to configure other properties rsocket:
server:
port: 9898
---- ----
...@@ -3580,32 +3676,41 @@ The same properties are applicable to both servlet and reactive applications. ...@@ -3580,32 +3676,41 @@ The same properties are applicable to both servlet and reactive applications.
You can register multiple OAuth2 clients and providers under the `spring.security.oauth2.client` prefix, as shown in the following example: You can register multiple OAuth2 clients and providers under the `spring.security.oauth2.client` prefix, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.security.oauth2.client.registration.my-client-1.client-id=abcd spring:
spring.security.oauth2.client.registration.my-client-1.client-secret=password security:
spring.security.oauth2.client.registration.my-client-1.client-name=Client for user scope oauth2:
spring.security.oauth2.client.registration.my-client-1.provider=my-oauth-provider client:
spring.security.oauth2.client.registration.my-client-1.scope=user registration:
spring.security.oauth2.client.registration.my-client-1.redirect-uri=https://my-redirect-uri.com my-client-1:
spring.security.oauth2.client.registration.my-client-1.client-authentication-method=basic client-id: "abcd"
spring.security.oauth2.client.registration.my-client-1.authorization-grant-type=authorization_code client-secret: "password"
client-name: "Client for user scope"
spring.security.oauth2.client.registration.my-client-2.client-id=abcd provider: "my-oauth-provider"
spring.security.oauth2.client.registration.my-client-2.client-secret=password scope: "user"
spring.security.oauth2.client.registration.my-client-2.client-name=Client for email scope redirect-uri: "https://my-redirect-uri.com"
spring.security.oauth2.client.registration.my-client-2.provider=my-oauth-provider client-authentication-method: "basic"
spring.security.oauth2.client.registration.my-client-2.scope=email authorization-grant-type: "authorization-code"
spring.security.oauth2.client.registration.my-client-2.redirect-uri=https://my-redirect-uri.com
spring.security.oauth2.client.registration.my-client-2.client-authentication-method=basic my-client-2:
spring.security.oauth2.client.registration.my-client-2.authorization-grant-type=authorization_code client-id: "abcd"
client-secret: "password"
spring.security.oauth2.client.provider.my-oauth-provider.authorization-uri=https://my-auth-server/oauth/authorize client-name: "Client for email scope"
spring.security.oauth2.client.provider.my-oauth-provider.token-uri=https://my-auth-server/oauth/token provider: "my-oauth-provider"
spring.security.oauth2.client.provider.my-oauth-provider.user-info-uri=https://my-auth-server/userinfo scope: "email"
spring.security.oauth2.client.provider.my-oauth-provider.user-info-authentication-method=header redirect-uri: "https://my-redirect-uri.com"
spring.security.oauth2.client.provider.my-oauth-provider.jwk-set-uri=https://my-auth-server/token_keys client-authentication-method: "basic"
spring.security.oauth2.client.provider.my-oauth-provider.user-name-attribute=name authorization-grant-type: "authorization_code"
provider:
my-oauth-provider:
authorization-uri: "https://my-auth-server/oauth/authorize"
token-uri: "https://my-auth-server/oauth/token"
user-info-uri: "https://my-auth-server/userinfo"
user-info-authentication-method: "header"
jwk-set-uri: "https://my-auth-server/token_keys"
user-name-attribute: "name"
---- ----
For OpenID Connect providers that support https://openid.net/specs/openid-connect-discovery-1_0.html[OpenID Connect discovery], the configuration can be further simplified. For OpenID Connect providers that support https://openid.net/specs/openid-connect-discovery-1_0.html[OpenID Connect discovery], the configuration can be further simplified.
...@@ -3614,9 +3719,15 @@ For example, if the `issuer-uri` provided is "https://example.com", then an `Ope ...@@ -3614,9 +3719,15 @@ For example, if the `issuer-uri` provided is "https://example.com", then an `Ope
The result is expected to be an `OpenID Provider Configuration Response`. The result is expected to be an `OpenID Provider Configuration Response`.
The following example shows how an OpenID Connect Provider can be configured with the `issuer-uri`: The following example shows how an OpenID Connect Provider can be configured with the `issuer-uri`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.security.oauth2.client.provider.oidc-provider.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/ spring:
security:
oauth2:
client:
provider:
oidc-provider:
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
---- ----
By default, Spring Security's `OAuth2LoginAuthenticationFilter` only processes URLs matching `/login/oauth2/code/*`. By default, Spring Security's `OAuth2LoginAuthenticationFilter` only processes URLs matching `/login/oauth2/code/*`.
...@@ -3651,14 +3762,20 @@ Also, if the key for the client registration matches a default supported provide ...@@ -3651,14 +3762,20 @@ Also, if the key for the client registration matches a default supported provide
In other words, the two configurations in the following example use the Google provider: In other words, the two configurations in the following example use the Google provider:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.security.oauth2.client.registration.my-client.client-id=abcd spring:
spring.security.oauth2.client.registration.my-client.client-secret=password security:
spring.security.oauth2.client.registration.my-client.provider=google oauth2:
client:
spring.security.oauth2.client.registration.google.client-id=abcd registration:
spring.security.oauth2.client.registration.google.client-secret=password my-client:
client-id: "abcd"
client-secret: "password"
provider: "google"
google:
client-id: "abcd"
client-secret: "password"
---- ----
...@@ -3668,14 +3785,24 @@ In other words, the two configurations in the following example use the Google p ...@@ -3668,14 +3785,24 @@ In other words, the two configurations in the following example use the Google p
If you have `spring-security-oauth2-resource-server` on your classpath, Spring Boot can set up an OAuth2 Resource Server. If you have `spring-security-oauth2-resource-server` on your classpath, Spring Boot can set up an OAuth2 Resource Server.
For JWT configuration, a JWK Set URI or OIDC Issuer URI needs to be specified, as shown in the following examples: For JWT configuration, a JWK Set URI or OIDC Issuer URI needs to be specified, as shown in the following examples:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.security.oauth2.resourceserver.jwt.jwk-set-uri=https://example.com/oauth2/default/v1/keys spring:
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: "https://example.com/oauth2/default/v1/keys"
---- ----
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/ spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
---- ----
NOTE: If the authorization server does not support a JWK Set URI, you can configure the resource server with the Public Key used for verifying the signature of the JWT. NOTE: If the authorization server does not support a JWK Set URI, you can configure the resource server with the Public Key used for verifying the signature of the JWT.
...@@ -3687,11 +3814,16 @@ Alternatively, you can define your own `JwtDecoder` bean for servlet application ...@@ -3687,11 +3814,16 @@ Alternatively, you can define your own `JwtDecoder` bean for servlet application
In cases where opaque tokens are used instead of JWTs, you can configure the following properties to validate tokens via introspection: In cases where opaque tokens are used instead of JWTs, you can configure the following properties to validate tokens via introspection:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.security.oauth2.resourceserver.opaquetoken.introspection-uri=https://example.com/check-token spring:
spring.security.oauth2.resourceserver.opaquetoken.client-id=my-client-id security:
spring.security.oauth2.resourceserver.opaquetoken.client-secret=my-client-secret oauth2:
resourceserver:
opaquetoken:
introspection-uri: "https://example.com/check-token"
client-id: "my-client-id"
client-secret: "my-client-secret"
---- ----
Again, the same properties are applicable for both servlet and reactive applications. Again, the same properties are applicable for both servlet and reactive applications.
...@@ -3719,19 +3851,35 @@ This configuration makes use of the properties under `Saml2RelyingPartyPropertie ...@@ -3719,19 +3851,35 @@ This configuration makes use of the properties under `Saml2RelyingPartyPropertie
A relying party registration represents a paired configuration between an Identity Provider, IDP, and a Service Provider, SP. A relying party registration represents a paired configuration between an Identity Provider, IDP, and a Service Provider, SP.
You can register multiple relying parties under the `spring.security.saml2.relyingparty` prefix, as shown in the following example: You can register multiple relying parties under the `spring.security.saml2.relyingparty` prefix, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.security.saml2.relyingparty.registration.my-relying-party1.signing.credentials[0].private-key-location=path-to-private-key spring:
spring.security.saml2.relyingparty.registration.my-relying-party1.signing.credentials[0].certificate-location=path-to-certificate security:
spring.security.saml2.relyingparty.registration.my-relying-party1.identityprovider.verification.credentials[0].certificate-location=path-to-verification-cert saml2:
spring.security.saml2.relyingparty.registration.my-relying-party1.identityprovider.entity-id=remote-idp-entity-id1 relyingparty:
spring.security.saml2.relyingparty.registration.my-relying-party1.identityprovider.sso-url=https://remoteidp1.sso.url registration:
my-relying-party1:
spring.security.saml2.relyingparty.registration.my-relying-party2.signing.credentials[0].private-key-location=path-to-private-key signing.credentials:
spring.security.saml2.relyingparty.registration.my-relying-party2.signing.credentials[0].certificate-location=path-to-certificate - private-key-location: "path-to-private-key"
spring.security.saml2.relyingparty.registration.my-relying-party2.identityprovider.verification.credentials[0].certificate-location=path-to-other-verification-cert certificate-location: "path-to-certificate"
spring.security.saml2.relyingparty.registration.my-relying-party2.identityprovider.entity-id=remote-idp-entity-id2 identityprovider:
spring.security.saml2.relyingparty.registration.my-relying-party2.identityprovider.sso-url=https://remoteidp2.sso.url verification:
credentials:
- certificate-location: "path-to-verification-cert"
entity-id: "remote-idp-entity-id1"
sso-url: "https://remoteidp1.sso.url"
my-relying-party2:
signing:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
identityprovider:
verification:
credentials:
- certificate-location: "path-to-other-verification-cert"
entity-id: "remote-idp-entity-id2"
sso-url: "https://remoteidp2.sso.url"
---- ----
...@@ -3840,18 +3988,21 @@ If you define your own `DataSource` bean, auto-configuration does not occur. ...@@ -3840,18 +3988,21 @@ If you define your own `DataSource` bean, auto-configuration does not occur.
DataSource configuration is controlled by external configuration properties in `+spring.datasource.*+`. DataSource configuration is controlled by external configuration properties in `+spring.datasource.*+`.
For example, you might declare the following section in `application.properties`: For example, you might declare the following section in `application.properties`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.datasource.url=jdbc:mysql://localhost/test spring:
spring.datasource.username=dbuser datasource:
spring.datasource.password=dbpass url: "jdbc:mysql://localhost/test"
spring.datasource.driver-class-name=com.mysql.jdbc.Driver username: "dbuser"
password: "dbpass"
---- ----
NOTE: You should at least specify the URL by setting the configprop:spring.datasource.url[] property. NOTE: You should at least specify the URL by setting the configprop:spring.datasource.url[] property.
Otherwise, Spring Boot tries to auto-configure an embedded database. Otherwise, Spring Boot tries to auto-configure an embedded database.
TIP: You often do not need to specify the `driver-class-name`, since Spring Boot can deduce it for most databases from the `url`. TIP: Spring Boot can deduce the JDBC driver class for most databases from the URL.
If you need to specify a specific class, you can use the configprop:spring.datasource.driver-class-name[] property.
NOTE: For a pooling `DataSource` to be created, we need to be able to verify that a valid `Driver` class is available, so we check for that before doing anything. NOTE: For a pooling `DataSource` to be created, we need to be able to verify that a valid `Driver` class is available, so we check for that before doing anything.
In other words, if you set `spring.datasource.driver-class-name=com.mysql.jdbc.Driver`, then that class has to be loadable. In other words, if you set `spring.datasource.driver-class-name=com.mysql.jdbc.Driver`, then that class has to be loadable.
...@@ -3863,18 +4014,18 @@ Refer to the documentation of the connection pool implementation you are using f ...@@ -3863,18 +4014,18 @@ Refer to the documentation of the connection pool implementation you are using f
For instance, if you use the {tomcat-docs}/jdbc-pool.html#Common_Attributes[Tomcat connection pool], you could customize many additional settings, as shown in the following example: For instance, if you use the {tomcat-docs}/jdbc-pool.html#Common_Attributes[Tomcat connection pool], you could customize many additional settings, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
# Number of ms to wait before throwing an exception if no connection is available. spring:
spring.datasource.tomcat.max-wait=10000 datasource:
tomcat:
# Maximum number of active connections that can be allocated from this pool at the same time. max-wait: 10000
spring.datasource.tomcat.max-active=50 max-active: 50
test-on-borrow: true
# Validate the connection before borrowing it from the pool.
spring.datasource.tomcat.test-on-borrow=true
---- ----
This will set the pool to wait 10000 ms before throwing an exception if no connection is available, limit the maximum number of connections to 50 and validate the connection before borrowing it from the pool.
[[boot-features-connecting-to-a-jndi-datasource]] [[boot-features-connecting-to-a-jndi-datasource]]
...@@ -3884,9 +4035,11 @@ If you deploy your Spring Boot application to an Application Server, you might w ...@@ -3884,9 +4035,11 @@ If you deploy your Spring Boot application to an Application Server, you might w
The configprop:spring.datasource.jndi-name[] property can be used as an alternative to the configprop:spring.datasource.url[], configprop:spring.datasource.username[], and configprop:spring.datasource.password[] properties to access the `DataSource` from a specific JNDI location. The configprop:spring.datasource.jndi-name[] property can be used as an alternative to the configprop:spring.datasource.url[], configprop:spring.datasource.username[], and configprop:spring.datasource.password[] properties to access the `DataSource` from a specific JNDI location.
For example, the following section in `application.properties` shows how you can access a JBoss AS defined `DataSource`: For example, the following section in `application.properties` shows how you can access a JBoss AS defined `DataSource`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.datasource.jndi-name=java:jboss/datasources/customers spring:
datasource:
jndi-name: "java:jboss/datasources/customers"
---- ----
...@@ -3918,9 +4071,12 @@ Spring's `JdbcTemplate` and `NamedParameterJdbcTemplate` classes are auto-config ...@@ -3918,9 +4071,12 @@ Spring's `JdbcTemplate` and `NamedParameterJdbcTemplate` classes are auto-config
You can customize some properties of the template by using the `spring.jdbc.template.*` properties, as shown in the following example: You can customize some properties of the template by using the `spring.jdbc.template.*` properties, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.jdbc.template.max-rows=500 spring:
jdbc:
template:
max-rows: 500
---- ----
NOTE: The `NamedParameterJdbcTemplate` reuses the same `JdbcTemplate` instance behind the scenes. NOTE: The `NamedParameterJdbcTemplate` reuses the same `JdbcTemplate` instance behind the scenes.
...@@ -4224,11 +4380,13 @@ Connections are provided via a `ConnectionFactory`, similar to a `DataSource` wi ...@@ -4224,11 +4380,13 @@ Connections are provided via a `ConnectionFactory`, similar to a `DataSource` wi
`ConnectionFactory` configuration is controlled by external configuration properties in `+spring.r2dbc.*+`. `ConnectionFactory` configuration is controlled by external configuration properties in `+spring.r2dbc.*+`.
For example, you might declare the following section in `application.properties`: For example, you might declare the following section in `application.properties`:
[source,properties,indent=0] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.r2dbc.url=r2dbc:postgresql://localhost/test spring:
spring.r2dbc.username=dbuser r2dbc:
spring.r2dbc.password=dbpass url: "r2dbc:postgresql://localhost/test"
username: "dbuser"
password: "dbpass"
---- ----
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.
...@@ -4469,13 +4627,16 @@ You can set the configprop:spring.data.mongodb.uri[] property to change the URL ...@@ -4469,13 +4627,16 @@ You can set the configprop:spring.data.mongodb.uri[] property to change the URL
Alternatively, you can specify connection details using discrete properties. Alternatively, you can specify connection details using discrete properties.
For example, you might declare the following settings in your `application.properties`: For example, you might declare the following settings in your `application.properties`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.data.mongodb.host=mongoserver.example.com spring:
spring.data.mongodb.port=27017 data:
spring.data.mongodb.database=test mongodb:
spring.data.mongodb.username=user host: "mongoserver.example.com"
spring.data.mongodb.password=secret port: 27017
database: "test"
username: "user"
password: "secret"
---- ----
TIP: If `spring.data.mongodb.port` is not specified, the default of `27017` is used. TIP: If `spring.data.mongodb.port` is not specified, the default of `27017` is used.
...@@ -4599,11 +4760,14 @@ The following example shows how to inject a Neo4j `Driver` that gives you access ...@@ -4599,11 +4760,14 @@ The following example shows how to inject a Neo4j `Driver` that gives you access
You can configure various aspects of the driver using `spring.neo4j.*` properties. You can configure various aspects of the driver using `spring.neo4j.*` properties.
The following example shows how to configure the uri and credentials to use: The following example shows how to configure the uri and credentials to use:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.neo4j.uri=bolt://my-server:7687 spring:
spring.neo4j.authentication.username=neo4j neo4j:
spring.neo4j.authentication.password=secret uri: "bolt://my-server:7687"
authentication:
username: "neo4j"
password: "secret"
---- ----
The auto-configured `Driver` is created using `ConfigBuilder`. The auto-configured `Driver` is created using `ConfigBuilder`.
...@@ -4703,6 +4867,7 @@ Spring Boot supports several clients: ...@@ -4703,6 +4867,7 @@ Spring Boot supports several clients:
Spring Boot provides a dedicated "`Starter`", `spring-boot-starter-data-elasticsearch`. Spring Boot provides a dedicated "`Starter`", `spring-boot-starter-data-elasticsearch`.
[[boot-features-connecting-to-elasticsearch-rest]] [[boot-features-connecting-to-elasticsearch-rest]]
==== Connecting to Elasticsearch using REST clients ==== Connecting to Elasticsearch using REST clients
Elasticsearch ships https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/index.html[two different REST clients] that you can use to query a cluster: the "Low Level" client and the "High Level" client. Elasticsearch ships https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/index.html[two different REST clients] that you can use to query a cluster: the "Low Level" client and the "High Level" client.
...@@ -4711,12 +4876,15 @@ Spring Boot provides support for the "High Level" client, which ships with `org. ...@@ -4711,12 +4876,15 @@ Spring Boot provides support for the "High Level" client, which ships with `org.
If you have this dependency on the classpath, Spring Boot will auto-configure and register a `RestHighLevelClient` bean that by default targets `http://localhost:9200`. If you have this dependency on the classpath, Spring Boot will auto-configure and register a `RestHighLevelClient` bean that by default targets `http://localhost:9200`.
You can further tune how `RestHighLevelClient` is configured, as shown in the following example: You can further tune how `RestHighLevelClient` is configured, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.elasticsearch.rest.uris=https://search.example.com:9200 spring:
spring.elasticsearch.rest.read-timeout=10s elasticsearch:
spring.elasticsearch.rest.username=user rest:
spring.elasticsearch.rest.password=secret uris: "https://search.example.com:9200"
read-timeout: "10s"
username: "user"
password: "secret"
---- ----
You can also register an arbitrary number of beans that implement `RestClientBuilderCustomizer` for more advanced customizations. You can also register an arbitrary number of beans that implement `RestClientBuilderCustomizer` for more advanced customizations.
...@@ -4724,6 +4892,8 @@ To take full control over the registration, define a `RestClientBuilder` bean. ...@@ -4724,6 +4892,8 @@ To take full control over the registration, define a `RestClientBuilder` bean.
TIP: If your application needs access to a "Low Level" `RestClient`, you can get it by calling `client.getLowLevelClient()` on the auto-configured `RestHighLevelClient`. TIP: If your application needs access to a "Low Level" `RestClient`, you can get it by calling `client.getLowLevelClient()` on the auto-configured `RestHighLevelClient`.
[[boot-features-connecting-to-elasticsearch-reactive-rest]] [[boot-features-connecting-to-elasticsearch-reactive-rest]]
==== Connecting to Elasticsearch using Reactive REST clients ==== Connecting to Elasticsearch using Reactive REST clients
{spring-data-elasticsearch}[Spring Data Elasticsearch] ships `ReactiveElasticsearchClient` for querying Elasticsearch instances in a reactive fashion. {spring-data-elasticsearch}[Spring Data Elasticsearch] ships `ReactiveElasticsearchClient` for querying Elasticsearch instances in a reactive fashion.
...@@ -4733,18 +4903,25 @@ By default, Spring Boot will auto-configure and register a `ReactiveElasticsearc ...@@ -4733,18 +4903,25 @@ By default, Spring Boot will auto-configure and register a `ReactiveElasticsearc
bean that targets `http://localhost:9200`. bean that targets `http://localhost:9200`.
You can further tune how it is configured, as shown in the following example: You can further tune how it is configured, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.data.elasticsearch.client.reactive.endpoints=search.example.com:9200 spring:
spring.data.elasticsearch.client.reactive.use-ssl=true data:
spring.data.elasticsearch.client.reactive.socket-timeout=10s elasticsearch:
spring.data.elasticsearch.client.reactive.username=user client:
spring.data.elasticsearch.client.reactive.password=secret reactive:
endpoints: "search.example.com:9200"
use-ssl: true
socket-timeout: "10s"
username: "user"
password: "secret"
---- ----
If the configuration properties are not enough and you'd like to fully control the client If the configuration properties are not enough and you'd like to fully control the client
configuration, you can register a custom `ClientConfiguration` bean. configuration, you can register a custom `ClientConfiguration` bean.
[[boot-features-connecting-to-elasticsearch-spring-data]] [[boot-features-connecting-to-elasticsearch-spring-data]]
==== Connecting to Elasticsearch by Using Spring Data ==== Connecting to Elasticsearch by Using Spring Data
To connect to Elasticsearch, a `RestHighLevelClient` bean must be defined, To connect to Elasticsearch, a `RestHighLevelClient` bean must be defined,
...@@ -4792,9 +4969,13 @@ Same applies to `ReactiveElasticsearchTemplate` and `ReactiveElasticsearchOperat ...@@ -4792,9 +4969,13 @@ Same applies to `ReactiveElasticsearchTemplate` and `ReactiveElasticsearchOperat
You can choose to disable the repositories support with the following property: You can choose to disable the repositories support with the following property:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.data.elasticsearch.repositories.enabled=false spring:
data:
elasticsearch:
repositories:
enabled: false
---- ----
...@@ -4812,20 +4993,26 @@ You can inject an auto-configured `CassandraTemplate` or a Cassandra `CqlSession ...@@ -4812,20 +4993,26 @@ You can inject an auto-configured `CassandraTemplate` or a Cassandra `CqlSession
The `spring.data.cassandra.*` properties can be used to customize the connection. The `spring.data.cassandra.*` properties can be used to customize the connection.
Generally, you provide `keyspace-name` and `contact-points` as well the local datacenter name, as shown in the following example: Generally, you provide `keyspace-name` and `contact-points` as well the local datacenter name, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.data.cassandra.keyspace-name=mykeyspace spring:
spring.data.cassandra.contact-points=cassandrahost1:9042,cassandrahost2:9042 data:
spring.data.cassandra.local-datacenter=datacenter1 cassandra:
keyspace-name: "mykeyspace"
contact-points: "cassandrahost1:9042,cassandrahost2:9042"
local-datacenter: "datacenter1"
---- ----
If the port is the same for all your contact points you can use a shortcut and only specify the host names, as shown in the following example: If the port is the same for all your contact points you can use a shortcut and only specify the host names, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.data.cassandra.keyspace-name=mykeyspace spring:
spring.data.cassandra.contact-points=cassandrahost1,cassandrahost2 data:
spring.data.cassandra.local-datacenter=datacenter1 cassandra:
keyspace-name: "mykeyspace"
contact-points: "cassandrahost1,cassandrahost2"
local-datacenter: "datacenter1"
---- ----
TIP: Those two examples are identical as the port default to `9042`. TIP: Those two examples are identical as the port default to `9042`.
...@@ -4887,21 +5074,28 @@ You can get a `Cluster` by adding the Couchbase SDK and some configuration. ...@@ -4887,21 +5074,28 @@ You can get a `Cluster` by adding the Couchbase SDK and some configuration.
The `spring.couchbase.*` properties can be used to customize the connection. The `spring.couchbase.*` properties can be used to customize the connection.
Generally, you provide the https://github.com/couchbaselabs/sdk-rfcs/blob/master/rfc/0011-connection-string.md[connection string], username, and password, as shown in the following example: Generally, you provide the https://github.com/couchbaselabs/sdk-rfcs/blob/master/rfc/0011-connection-string.md[connection string], username, and password, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.couchbase.connection-string=couchbase://192.168.1.123 spring:
spring.couchbase.username=user couchbase:
spring.couchbase.password=secret connection-string: "couchbase://192.168.1.123"
username: "user"
password: "secret"
---- ----
It is also possible to customize some of the `ClusterEnvironment` settings. It is also possible to customize some of the `ClusterEnvironment` settings.
For instance, the following configuration changes the timeout to use to open a new `Bucket` and enables SSL support: For instance, the following configuration changes the timeout to use to open a new `Bucket` and enables SSL support:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.couchbase.env.timeouts.connect=3000 spring:
spring.couchbase.env.ssl.key-store=/location/of/keystore.jks couchbase:
spring.couchbase.env.ssl.key-store-password=secret env:
timeouts:
connect: "3s"
ssl:
key-store: "/location/of/keystore.jks"
key-store-password: "secret"
---- ----
TIP: Check the `spring.couchbase.env.*` properties for more details. TIP: Check the `spring.couchbase.env.*` properties for more details.
...@@ -4917,9 +5111,12 @@ For complete details of Spring Data Couchbase, refer to the {spring-data-couchba ...@@ -4917,9 +5111,12 @@ For complete details of Spring Data Couchbase, refer to the {spring-data-couchba
You can inject an auto-configured `CouchbaseTemplate` instance as you would with any other Spring Bean, provided a `CouchbaseClientFactory` bean is available. You can inject an auto-configured `CouchbaseTemplate` instance as you would with any other Spring Bean, provided a `CouchbaseClientFactory` bean is available.
This happens when a `Cluster` is available, as described above, and a bucket name has been specified: This happens when a `Cluster` is available, as described above, and a bucket name has been specified:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.data.couchbase.bucket-name=my-bucket spring:
data:
couchbase:
bucket-name: "my-bucket"
---- ----
The following examples shows how to inject a `CouchbaseTemplate` bean: The following examples shows how to inject a `CouchbaseTemplate` bean:
...@@ -4981,11 +5178,13 @@ There is a `spring-boot-starter-data-ldap` "`Starter`" for collecting the depend ...@@ -4981,11 +5178,13 @@ There is a `spring-boot-starter-data-ldap` "`Starter`" for collecting the depend
==== Connecting to an LDAP Server ==== Connecting to an LDAP Server
To connect to an LDAP server, make sure you declare a dependency on the `spring-boot-starter-data-ldap` "`Starter`" or `spring-ldap-core` and then declare the URLs of your server in your application.properties, as shown in the following example: To connect to an LDAP server, make sure you declare a dependency on the `spring-boot-starter-data-ldap` "`Starter`" or `spring-ldap-core` and then declare the URLs of your server in your application.properties, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.ldap.urls=ldap://myserver:1235 spring:
spring.ldap.username=admin ldap:
spring.ldap.password=secret urls: "ldap://myserver:1235"
username: "admin"
password: "secret"
---- ----
If you need to customize connection settings, you can use the `spring.ldap.base` and `spring.ldap.base-environment` properties. If you need to customize connection settings, you can use the `spring.ldap.base` and `spring.ldap.base-environment` properties.
...@@ -5029,32 +5228,26 @@ You can also inject an auto-configured `LdapTemplate` instance as you would with ...@@ -5029,32 +5228,26 @@ You can also inject an auto-configured `LdapTemplate` instance as you would with
For testing purposes, Spring Boot supports auto-configuration of an in-memory LDAP server from https://ldap.com/unboundid-ldap-sdk-for-java/[UnboundID]. For testing purposes, Spring Boot supports auto-configuration of an in-memory LDAP server from https://ldap.com/unboundid-ldap-sdk-for-java/[UnboundID].
To configure the server, add a dependency to `com.unboundid:unboundid-ldapsdk` and declare a configprop:spring.ldap.embedded.base-dn[] property, as follows: To configure the server, add a dependency to `com.unboundid:unboundid-ldapsdk` and declare a configprop:spring.ldap.embedded.base-dn[] property, as follows:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.ldap.embedded.base-dn=dc=spring,dc=io spring:
ldap:
embedded:
base-dn: "dc=spring,dc=io"
---- ----
[NOTE] [NOTE]
==== ====
It is possible to define multiple base-dn values, however, since distinguished names usually contain commas, they must be defined using the correct notation. It is possible to define multiple base-dn values, however, since distinguished names usually contain commas, they must be defined using the correct notation.
In yaml files, you can use the yaml list notation: In yaml files, you can use the yaml list notation. In properties files, you must include the index as part of the property name:
[source,yaml,indent=0] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.ldap.embedded.base-dn: spring.ldap.embedded.base-dn:
- dc=spring,dc=io - dc=spring,dc=io
- dc=pivotal,dc=io - dc=pivotal,dc=io
---- ----
In properties files, you must include the index as part of the property name:
[source,properties,indent=0,configprops]
----
spring.ldap.embedded.base-dn[0]=dc=spring,dc=io
spring.ldap.embedded.base-dn[1]=dc=pivotal,dc=io
----
==== ====
By default, the server starts on a random port and triggers the regular LDAP support. By default, the server starts on a random port and triggers the regular LDAP support.
...@@ -5079,9 +5272,11 @@ https://www.influxdata.com/[InfluxDB] is an open-source time series database opt ...@@ -5079,9 +5272,11 @@ https://www.influxdata.com/[InfluxDB] is an open-source time series database opt
==== Connecting to InfluxDB ==== Connecting to InfluxDB
Spring Boot auto-configures an `InfluxDB` instance, provided the `influxdb-java` client is on the classpath and the URL of the database is set, as shown in the following example: Spring Boot auto-configures an `InfluxDB` instance, provided the `influxdb-java` client is on the classpath and the URL of the database is set, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.influx.url=https://172.0.0.1:8086 spring:
influx:
url: "https://172.0.0.1:8086"
---- ----
If the connection to InfluxDB requires a user and password, you can set the `spring.influx.user` and `spring.influx.password` properties accordingly. If the connection to InfluxDB requires a user and password, you can set the `spring.influx.user` and `spring.influx.password` properties accordingly.
...@@ -5168,10 +5363,12 @@ The following example sets a flag to say that `null` values should be passed dow ...@@ -5168,10 +5363,12 @@ The following example sets a flag to say that `null` values should be passed dow
@Bean @Bean
public CacheManagerCustomizer<ConcurrentMapCacheManager> cacheManagerCustomizer() { public CacheManagerCustomizer<ConcurrentMapCacheManager> cacheManagerCustomizer() {
return new CacheManagerCustomizer<ConcurrentMapCacheManager>() { return new CacheManagerCustomizer<ConcurrentMapCacheManager>() {
@Override @Override
public void customize(ConcurrentMapCacheManager cacheManager) { public void customize(ConcurrentMapCacheManager cacheManager) {
cacheManager.setAllowNullValues(false); cacheManager.setAllowNullValues(false);
} }
}; };
} }
---- ----
...@@ -5198,11 +5395,14 @@ Any other compliant library can be added as well. ...@@ -5198,11 +5395,14 @@ Any other compliant library can be added as well.
It might happen that more than one provider is present, in which case the provider must be explicitly specified. It might happen that more than one provider is present, in which case the provider must be explicitly specified.
Even if the JSR-107 standard does not enforce a standardized way to define the location of the configuration file, Spring Boot does its best to accommodate setting a cache with implementation details, as shown in the following example: Even if the JSR-107 standard does not enforce a standardized way to define the location of the configuration file, Spring Boot does its best to accommodate setting a cache with implementation details, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
# Only necessary if more than one provider is present # Only necessary if more than one provider is present
spring.cache.jcache.provider=com.acme.MyCachingProvider spring:
spring.cache.jcache.config=classpath:acme.xml cache:
jcache:
provider: "com.acme.MyCachingProvider"
config: "classpath:acme.xml"
---- ----
NOTE: When a cache library offers both a native implementation and JSR-107 support, Spring Boot prefers the JSR-107 support, so that the same features are available if you switch to a different JSR-107 implementation. NOTE: When a cache library offers both a native implementation and JSR-107 support, Spring Boot prefers the JSR-107 support, so that the same features are available if you switch to a different JSR-107 implementation.
...@@ -5227,9 +5427,12 @@ https://www.ehcache.org/[EhCache] 2.x is used if a file named `ehcache.xml` can ...@@ -5227,9 +5427,12 @@ https://www.ehcache.org/[EhCache] 2.x is used if a file named `ehcache.xml` can
If EhCache 2.x is found, the `EhCacheCacheManager` provided by the `spring-boot-starter-cache` "`Starter`" is used to bootstrap the cache manager. If EhCache 2.x is found, the `EhCacheCacheManager` provided by the `spring-boot-starter-cache` "`Starter`" is used to bootstrap the cache manager.
An alternate configuration file can be provided as well, as shown in the following example: An alternate configuration file can be provided as well, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.cache.ehcache.config=classpath:config/another-config.xml spring:
cache:
ehcache:
config: "classpath:config/another-config.xml"
---- ----
...@@ -5246,9 +5449,12 @@ If a `HazelcastInstance` has been auto-configured, it is automatically wrapped i ...@@ -5246,9 +5449,12 @@ If a `HazelcastInstance` has been auto-configured, it is automatically wrapped i
https://infinispan.org/[Infinispan] has no default configuration file location, so it must be specified explicitly. https://infinispan.org/[Infinispan] has no default configuration file location, so it must be specified explicitly.
Otherwise, the default bootstrap is used. Otherwise, the default bootstrap is used.
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.cache.infinispan.config=infinispan.xml spring:
cache:
infinispan:
config: "infinispan.xml"
---- ----
Caches can be created on startup by setting the configprop:spring.cache.cache-names[] property. Caches can be created on startup by setting the configprop:spring.cache.cache-names[] property.
...@@ -5266,10 +5472,13 @@ If Spring Data Couchbase is available and Couchbase is <<boot-features-couchbase ...@@ -5266,10 +5472,13 @@ If Spring Data Couchbase is available and Couchbase is <<boot-features-couchbase
It is possible to create additional caches on startup by setting the configprop:spring.cache.cache-names[] property and cache defaults can be configured by using `spring.cache.couchbase.*` properties. It is possible to create additional caches on startup by setting the configprop:spring.cache.cache-names[] property and cache defaults can be configured by using `spring.cache.couchbase.*` properties.
For instance, the following configuration creates `cache1` and `cache2` caches with an entry _expiration_ of 10 minutes: For instance, the following configuration creates `cache1` and `cache2` caches with an entry _expiration_ of 10 minutes:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.cache.cache-names=cache1,cache2 spring:
spring.cache.couchbase.expiration=10m cache:
cache-names: "cache1,cache2"
couchbase:
expiration: "10m"
---- ----
If you need more control over the configuration, consider registering a `CouchbaseCacheManagerBuilderCustomizer` bean. If you need more control over the configuration, consider registering a `CouchbaseCacheManagerBuilderCustomizer` bean.
...@@ -5288,10 +5497,13 @@ If https://redis.io/[Redis] is available and configured, a `RedisCacheManager` i ...@@ -5288,10 +5497,13 @@ If https://redis.io/[Redis] is available and configured, a `RedisCacheManager` i
It is possible to create additional caches on startup by setting the configprop:spring.cache.cache-names[] property and cache defaults can be configured by using `spring.cache.redis.*` properties. It is possible to create additional caches on startup by setting the configprop:spring.cache.cache-names[] property and cache defaults can be configured by using `spring.cache.redis.*` properties.
For instance, the following configuration creates `cache1` and `cache2` caches with a _time to live_ of 10 minutes: For instance, the following configuration creates `cache1` and `cache2` caches with a _time to live_ of 10 minutes:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.cache.cache-names=cache1,cache2 spring:
spring.cache.redis.time-to-live=600000 cache:
cache-names: "cache1,cache2"
redis:
time-to-live: "10m"
---- ----
NOTE: By default, a key prefix is added so that, if two separate caches use the same key, Redis does not have overlapping keys and cannot return invalid values. NOTE: By default, a key prefix is added so that, if two separate caches use the same key, Redis does not have overlapping keys and cannot return invalid values.
...@@ -5323,10 +5535,13 @@ Caches can be created on startup by setting the configprop:spring.cache.cache-na ...@@ -5323,10 +5535,13 @@ Caches can be created on startup by setting the configprop:spring.cache.cache-na
For instance, the following configuration creates `cache1` and `cache2` caches with a maximum size of 500 and a _time to live_ of 10 minutes For instance, the following configuration creates `cache1` and `cache2` caches with a maximum size of 500 and a _time to live_ of 10 minutes
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.cache.cache-names=cache1,cache2 spring:
spring.cache.caffeine.spec=maximumSize=500,expireAfterAccess=600s cache:
cache-names: "cache1,cache2"
caffeine:
spec: "maximumSize=500,expireAfterAccess=600s"
---- ----
If a `com.github.benmanes.caffeine.cache.CacheLoader` bean is defined, it is automatically associated to the `CaffeineCacheManager`. If a `com.github.benmanes.caffeine.cache.CacheLoader` bean is defined, it is automatically associated to the `CaffeineCacheManager`.
...@@ -5342,9 +5557,11 @@ This is the default if no caching library is present in your application. ...@@ -5342,9 +5557,11 @@ This is the default if no caching library is present in your application.
By default, caches are created as needed, but you can restrict the list of available caches by setting the `cache-names` property. By default, caches are created as needed, but you can restrict the list of available caches by setting the `cache-names` property.
For instance, if you want only `cache1` and `cache2` caches, set the `cache-names` property as follows: For instance, if you want only `cache1` and `cache2` caches, set the `cache-names` property as follows:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.cache.cache-names=cache1,cache2 spring:
cache:
cache-names: "cache1,cache2"
---- ----
If you do so and your application uses a cache not listed, then it fails at runtime when the cache is needed, but not on startup. If you do so and your application uses a cache not listed, then it fails at runtime when the cache is needed, but not on startup.
...@@ -5357,9 +5574,11 @@ This is similar to the way the "real" cache providers behave if you use an undec ...@@ -5357,9 +5574,11 @@ This is similar to the way the "real" cache providers behave if you use an undec
When `@EnableCaching` is present in your configuration, a suitable cache configuration is expected as well. When `@EnableCaching` is present in your configuration, a suitable cache configuration is expected as well.
If you need to disable caching altogether in certain environments, force the cache type to `none` to use a no-op implementation, as shown in the following example: If you need to disable caching altogether in certain environments, force the cache type to `none` to use a no-op implementation, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.cache.type=none spring:
cache:
type: "none"
---- ----
...@@ -5393,26 +5612,34 @@ NOTE: If you use `spring-boot-starter-activemq`, the necessary dependencies to c ...@@ -5393,26 +5612,34 @@ NOTE: If you use `spring-boot-starter-activemq`, the necessary dependencies to c
ActiveMQ configuration is controlled by external configuration properties in `+spring.activemq.*+`. ActiveMQ configuration is controlled by external configuration properties in `+spring.activemq.*+`.
For example, you might declare the following section in `application.properties`: For example, you might declare the following section in `application.properties`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.activemq.broker-url=tcp://192.168.1.210:9876 spring:
spring.activemq.user=admin activemq:
spring.activemq.password=secret broker-url: "tcp://192.168.1.210:9876"
user: "admin"
password: "secret"
---- ----
By default, a `CachingConnectionFactory` wraps the native `ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`: By default, a `CachingConnectionFactory` wraps the native `ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.jms.cache.session-cache-size=5 spring:
jms:
cache:
session-cache-size: 5
---- ----
If you'd rather use native pooling, you can do so by adding a dependency to `org.messaginghub:pooled-jms` and configuring the `JmsPoolConnectionFactory` accordingly, as shown in the following example: If you'd rather use native pooling, you can do so by adding a dependency to `org.messaginghub:pooled-jms` and configuring the `JmsPoolConnectionFactory` accordingly, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.activemq.pool.enabled=true spring:
spring.activemq.pool.max-connections=50 activemq:
pool:
enabled: true
max-connections: 50
---- ----
TIP: See {spring-boot-autoconfigure-module-code}/jms/activemq/ActiveMQProperties.java[`ActiveMQProperties`] for more of the supported options. TIP: See {spring-boot-autoconfigure-module-code}/jms/activemq/ActiveMQProperties.java[`ActiveMQProperties`] for more of the supported options.
...@@ -5435,13 +5662,15 @@ Adding `org.apache.activemq:artemis-jms-server` to your application lets you use ...@@ -5435,13 +5662,15 @@ Adding `org.apache.activemq:artemis-jms-server` to your application lets you use
Artemis configuration is controlled by external configuration properties in `+spring.artemis.*+`. Artemis configuration is controlled by external configuration properties in `+spring.artemis.*+`.
For example, you might declare the following section in `application.properties`: For example, you might declare the following section in `application.properties`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.artemis.mode=native spring:
spring.artemis.host=192.168.1.210 artemis:
spring.artemis.port=9876 mode: native
spring.artemis.user=admin host: "192.168.1.210"
spring.artemis.password=secret port: 9876
user: "admin"
password: "secret"
---- ----
When embedding the broker, you can choose if you want to enable persistence and list the destinations that should be made available. When embedding the broker, you can choose if you want to enable persistence and list the destinations that should be made available.
...@@ -5449,17 +5678,23 @@ These can be specified as a comma-separated list to create them with the default ...@@ -5449,17 +5678,23 @@ These can be specified as a comma-separated list to create them with the default
By default, a `CachingConnectionFactory` wraps the native `ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`: By default, a `CachingConnectionFactory` wraps the native `ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.jms.cache.session-cache-size=5 spring:
jms:
cache:
session-cache-size: 5
---- ----
If you'd rather use native pooling, you can do so by adding a dependency to `org.messaginghub:pooled-jms` and configuring the `JmsPoolConnectionFactory` accordingly, as shown in the following example: If you'd rather use native pooling, you can do so by adding a dependency to `org.messaginghub:pooled-jms` and configuring the `JmsPoolConnectionFactory` accordingly, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.artemis.pool.enabled=true spring:
spring.artemis.pool.max-connections=50 artemis:
pool:
enabled: true
max-connections: 50
---- ----
See {spring-boot-autoconfigure-module-code}/jms/artemis/ArtemisProperties.java[`ArtemisProperties`] for more supported options. See {spring-boot-autoconfigure-module-code}/jms/artemis/ArtemisProperties.java[`ArtemisProperties`] for more supported options.
...@@ -5474,9 +5709,11 @@ If you are running your application in an application server, Spring Boot tries ...@@ -5474,9 +5709,11 @@ If you are running your application in an application server, Spring Boot tries
By default, the `java:/JmsXA` and `java:/XAConnectionFactory` location are checked. By default, the `java:/JmsXA` and `java:/XAConnectionFactory` location are checked.
You can use the configprop:spring.jms.jndi-name[] property if you need to specify an alternative location, as shown in the following example: You can use the configprop:spring.jms.jndi-name[] property if you need to specify an alternative location, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.jms.jndi-name=java:/MyConnectionFactory spring:
jms:
jndi-name: "java:/MyConnectionFactory"
---- ----
...@@ -5597,19 +5834,23 @@ Spring uses `RabbitMQ` to communicate through the AMQP protocol. ...@@ -5597,19 +5834,23 @@ Spring uses `RabbitMQ` to communicate through the AMQP protocol.
RabbitMQ configuration is controlled by external configuration properties in `+spring.rabbitmq.*+`. RabbitMQ configuration is controlled by external configuration properties in `+spring.rabbitmq.*+`.
For example, you might declare the following section in `application.properties`: For example, you might declare the following section in `application.properties`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.rabbitmq.host=localhost spring:
spring.rabbitmq.port=5672 rabbitmq:
spring.rabbitmq.username=admin host: "localhost"
spring.rabbitmq.password=secret port: 5672
username: "admin"
password: "secret"
---- ----
Alternatively, you could configure the same connection using the `addresses` attribute: Alternatively, you could configure the same connection using the `addresses` attribute:
[source,properties,indent=0] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.rabbitmq.addresses=amqp://admin:secret@localhost spring:
rabbitmq:
addresses: "amqp://admin:secret@localhost"
---- ----
NOTE: When specifying addresses that way, the `host` and `port` properties are ignored. NOTE: When specifying addresses that way, the `host` and `port` properties are ignored.
...@@ -5657,10 +5898,14 @@ If necessary, any `org.springframework.amqp.core.Queue` that is defined as a bea ...@@ -5657,10 +5898,14 @@ If necessary, any `org.springframework.amqp.core.Queue` that is defined as a bea
To retry operations, you can enable retries on the `AmqpTemplate` (for example, in the event that the broker connection is lost): To retry operations, you can enable retries on the `AmqpTemplate` (for example, in the event that the broker connection is lost):
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.rabbitmq.template.retry.enabled=true spring:
spring.rabbitmq.template.retry.initial-interval=2s rabbitmq:
template:
retry:
enabled: true
initial-interval: "2s"
---- ----
Retries are disabled by default. Retries are disabled by default.
...@@ -5753,10 +5998,13 @@ https://kafka.apache.org/[Apache Kafka] is supported by providing auto-configura ...@@ -5753,10 +5998,13 @@ https://kafka.apache.org/[Apache Kafka] is supported by providing auto-configura
Kafka configuration is controlled by external configuration properties in `spring.kafka.*`. Kafka configuration is controlled by external configuration properties in `spring.kafka.*`.
For example, you might declare the following section in `application.properties`: For example, you might declare the following section in `application.properties`:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.kafka.bootstrap-servers=localhost:9092 spring:
spring.kafka.consumer.group-id=myGroup kafka:
bootstrap-servers: "localhost:9092"
consumer:
group-id: "myGroup"
---- ----
TIP: To create a topic on startup, add a bean of type `NewTopic`. TIP: To create a topic on startup, add a bean of type `NewTopic`.
...@@ -5859,32 +6107,51 @@ Spring Boot auto-configuration supports all HIGH importance properties, some sel ...@@ -5859,32 +6107,51 @@ Spring Boot auto-configuration supports all HIGH importance properties, some sel
Only a subset of the properties supported by Kafka are available directly through the `KafkaProperties` class. Only a subset of the properties supported by Kafka are available directly through the `KafkaProperties` class.
If you wish to configure the producer or consumer with additional properties that are not directly supported, use the following properties: If you wish to configure the producer or consumer with additional properties that are not directly supported, use the following properties:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.kafka.properties.prop.one=first spring:
spring.kafka.admin.properties.prop.two=second kafka:
spring.kafka.consumer.properties.prop.three=third properties:
spring.kafka.producer.properties.prop.four=fourth "[prop.one]": "first"
spring.kafka.streams.properties.prop.five=fifth admin:
properties:
"[prop.two]": "second"
consumer:
properties:
"[prop.three]": "third"
producer:
properties:
"[prop.four]": "fourth"
streams:
properties:
"[prop.five]": "fifth"
---- ----
This sets the common `prop.one` Kafka property to `first` (applies to producers, consumers and admins), the `prop.two` admin property to `second`, the `prop.three` consumer property to `third`, the `prop.four` producer property to `fourth` and the `prop.five` streams property to `fifth`. This sets the common `prop.one` Kafka property to `first` (applies to producers, consumers and admins), the `prop.two` admin property to `second`, the `prop.three` consumer property to `third`, the `prop.four` producer property to `fourth` and the `prop.five` streams property to `fifth`.
You can also configure the Spring Kafka `JsonDeserializer` as follows: You can also configure the Spring Kafka `JsonDeserializer` as follows:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.kafka.consumer.value-deserializer=org.springframework.kafka.support.serializer.JsonDeserializer spring:
spring.kafka.consumer.properties.spring.json.value.default.type=com.example.Invoice kafka:
spring.kafka.consumer.properties.spring.json.trusted.packages=com.example,org.acme consumer:
value-deserializer: "org.springframework.kafka.support.serializer.JsonDeserializer"
properties:
"[spring.json.value.default.type]": "com.example.Invoice"
"[spring.json.trusted.packages]": "com.example,org.acme"
---- ----
Similarly, you can disable the `JsonSerializer` default behavior of sending type information in headers: Similarly, you can disable the `JsonSerializer` default behavior of sending type information in headers:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.kafka.producer.value-serializer=org.springframework.kafka.support.serializer.JsonSerializer spring:
spring.kafka.producer.properties.spring.json.add.type.headers=false kafka:
producer:
value-serializer: "org.springframework.kafka.support.serializer.JsonSerializer"
properties:
"[spring.json.add.type.headers]": false
---- ----
IMPORTANT: Properties set in this way override any configuration item that Spring Boot explicitly supports. IMPORTANT: Properties set in this way override any configuration item that Spring Boot explicitly supports.
...@@ -5904,24 +6171,26 @@ There are several ways to do that: ...@@ -5904,24 +6171,26 @@ There are several ways to do that:
[source,java,indent=0] [source,java,indent=0]
---- ----
static { static {
System.setProperty(EmbeddedKafkaBroker.BROKER_LIST_PROPERTY, "spring.kafka.bootstrap-servers"); System.setProperty(EmbeddedKafkaBroker.BROKER_LIST_PROPERTY, "spring.kafka.bootstrap-servers");
} }
---- ----
* Configure a property name on the `@EmbeddedKafka` annotation: * Configure a property name on the `@EmbeddedKafka` annotation:
[source,java,indent=0] [source,java,indent=0]
---- ----
@EmbeddedKafka(topics = "someTopic", @EmbeddedKafka(topics = "someTopic",
bootstrapServersProperty = "spring.kafka.bootstrap-servers") bootstrapServersProperty = "spring.kafka.bootstrap-servers")
---- ----
* Use a placeholder in configuration properties: * Use a placeholder in configuration properties:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.kafka.bootstrap-servers=${spring.embedded.kafka.brokers} spring:
kafka:
bootstrap-servers: "${spring.embedded.kafka.brokers}"
---- ----
...@@ -6089,18 +6358,23 @@ See {spring-boot-autoconfigure-module-code}/mail/MailProperties.java[`MailProper ...@@ -6089,18 +6358,23 @@ See {spring-boot-autoconfigure-module-code}/mail/MailProperties.java[`MailProper
In particular, certain default timeout values are infinite, and you may want to change that to avoid having a thread blocked by an unresponsive mail server, as shown in the following example: In particular, certain default timeout values are infinite, and you may want to change that to avoid having a thread blocked by an unresponsive mail server, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.mail.properties.mail.smtp.connectiontimeout=5000 spring:
spring.mail.properties.mail.smtp.timeout=3000 mail:
spring.mail.properties.mail.smtp.writetimeout=5000 properties:
"[mail.smtp.connectiontimeout]": 5000
"[mail.smtp.timeout]": 3000
"[mail.smtp.writetimeout]": 5000
---- ----
It is also possible to configure a `JavaMailSender` with an existing `Session` from JNDI: It is also possible to configure a `JavaMailSender` with an existing `Session` from JNDI:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.mail.jndi-name=mail/Session spring:
mail:
jndi-name: "mail/Session"
---- ----
When a `jndi-name` is set, it takes precedence over all other Session-related settings. When a `jndi-name` is set, it takes precedence over all other Session-related settings.
...@@ -6225,9 +6499,11 @@ If your configuration defines an instance name, Spring Boot tries to locate an e ...@@ -6225,9 +6499,11 @@ If your configuration defines an instance name, Spring Boot tries to locate an e
You could also specify the Hazelcast configuration file to use through configuration, as shown in the following example: You could also specify the Hazelcast configuration file to use through configuration, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.hazelcast.config=classpath:config/my-hazelcast.xml spring:
hazelcast:
config: "classpath:config/my-hazelcast.xml"
---- ----
Otherwise, Spring Boot tries to find the Hazelcast configuration from the default locations: `hazelcast.xml` in the working directory or at the root of the classpath, or a `.yaml` counterpart in the same locations. Otherwise, Spring Boot tries to find the Hazelcast configuration from the default locations: `hazelcast.xml` in the working directory or at the root of the classpath, or a `.yaml` counterpart in the same locations.
...@@ -6254,16 +6530,21 @@ Beans of the following types are automatically picked up and associated with the ...@@ -6254,16 +6530,21 @@ Beans of the following types are automatically picked up and associated with the
By default, an in-memory `JobStore` is used. By default, an in-memory `JobStore` is used.
However, it is possible to configure a JDBC-based store if a `DataSource` bean is available in your application and if the configprop:spring.quartz.job-store-type[] property is configured accordingly, as shown in the following example: However, it is possible to configure a JDBC-based store if a `DataSource` bean is available in your application and if the configprop:spring.quartz.job-store-type[] property is configured accordingly, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.quartz.job-store-type=jdbc spring:
quartz:
job-store-type: "jdbc"
---- ----
When the JDBC store is used, the schema can be initialized on startup, as shown in the following example: When the JDBC store is used, the schema can be initialized on startup, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.quartz.jdbc.initialize-schema=always spring:
quartz:
jdbc:
initialize-schema: "always"
---- ----
WARNING: By default, the database is detected and initialized by using the standard scripts provided with the Quartz library. WARNING: By default, the database is detected and initialized by using the standard scripts provided with the Quartz library.
...@@ -6325,11 +6606,15 @@ The auto-configured `TaskExecutorBuilder` allows you to easily create instances ...@@ -6325,11 +6606,15 @@ The auto-configured `TaskExecutorBuilder` allows you to easily create instances
The thread pool uses 8 core threads that can grow and shrink according to the load. 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: Those default settings can be fine-tuned using the `spring.task.execution` namespace as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.task.execution.pool.max-size=16 spring:
spring.task.execution.pool.queue-capacity=100 task:
spring.task.execution.pool.keep-alive=10s 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. 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.
...@@ -6352,9 +6637,12 @@ Spring Boot also configures some features that are triggered by the presence of ...@@ -6352,9 +6637,12 @@ Spring Boot also configures some features that are triggered by the presence of
If `spring-integration-jmx` is also on the classpath, message processing statistics are published over JMX. If `spring-integration-jmx` is also on the classpath, message processing statistics are published over JMX.
If `spring-integration-jdbc` is available, the default database schema can be created on startup, as shown in the following line: If `spring-integration-jdbc` is available, the default database schema can be created on startup, as shown in the following line:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.integration.jdbc.initialize-schema=always spring:
integration:
jdbc:
initialize-schema: "always"
---- ----
If `spring-integration-rsocket` is available, developers can configure an RSocket server using `"spring.rsocket.server.*"` properties and let it use `IntegrationRSocketEndpoint` or `RSocketOutboundGateway` components to handle incoming RSocket messages. If `spring-integration-rsocket` is available, developers can configure an RSocket server using `"spring.rsocket.server.*"` properties and let it use `IntegrationRSocketEndpoint` or `RSocketOutboundGateway` components to handle incoming RSocket messages.
...@@ -6362,14 +6650,25 @@ This infrastructure can handle Spring Integration RSocket channel adapters and ` ...@@ -6362,14 +6650,25 @@ This infrastructure can handle Spring Integration RSocket channel adapters and `
Spring Boot can also auto-configure an `ClientRSocketConnector` using configuration properties: Spring Boot can also auto-configure an `ClientRSocketConnector` using configuration properties:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
# Connecting to a RSocket server over TCP # Connecting to a RSocket server over TCP
spring.integration.rsocket.client.host=example.org spring:
spring.integration.rsocket.client.port=9898 integration:
rsocket:
client:
host: "example.org"
port: 9898
----
[source,yaml,indent=0,configprops,configblocks]
----
# Connecting to a RSocket Server over WebSocket # Connecting to a RSocket Server over WebSocket
spring.integration.rsocket.client.uri=ws://example.org spring:
integration:
rsocket:
client:
uri: "ws://example.org"
---- ----
See the {spring-boot-autoconfigure-module-code}/integration/IntegrationAutoConfiguration.java[`IntegrationAutoConfiguration`] and {spring-boot-autoconfigure-module-code}/integration/IntegrationProperties.java[`IntegrationProperties`] classes for more details. See the {spring-boot-autoconfigure-module-code}/integration/IntegrationAutoConfiguration.java[`IntegrationAutoConfiguration`] and {spring-boot-autoconfigure-module-code}/integration/IntegrationProperties.java[`IntegrationProperties`] classes for more details.
...@@ -6398,9 +6697,11 @@ If a single Spring Session module is present on the classpath, Spring Boot uses ...@@ -6398,9 +6697,11 @@ If a single Spring Session module is present on the classpath, Spring Boot uses
If you have more than one implementation, you must choose the {spring-boot-autoconfigure-module-code}/session/StoreType.java[`StoreType`] that you wish to use to store the sessions. If you have more than one implementation, you must choose the {spring-boot-autoconfigure-module-code}/session/StoreType.java[`StoreType`] that you wish to use to store the sessions.
For instance, to use JDBC as the back-end store, you can configure your application as follows: For instance, to use JDBC as the back-end store, you can configure your application as follows:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.session.store-type=jdbc spring:
session:
store-type: "jdbc"
---- ----
TIP: You can disable Spring Session by setting the `store-type` to `none`. TIP: You can disable Spring Session by setting the `store-type` to `none`.
...@@ -6408,15 +6709,19 @@ TIP: You can disable Spring Session by setting the `store-type` to `none`. ...@@ -6408,15 +6709,19 @@ TIP: You can disable Spring Session by setting the `store-type` to `none`.
Each store has specific additional settings. Each store has specific additional settings.
For instance, it is possible to customize the name of the table for the JDBC store, as shown in the following example: For instance, it is possible to customize the name of the table for the JDBC store, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.session.jdbc.table-name=SESSIONS spring:
session:
jdbc:
table-name: "SESSIONS"
---- ----
For setting the timeout of the session you can use the configprop:spring.session.timeout[] property. For setting the timeout of the session you can use the configprop:spring.session.timeout[] property.
If that property is not set, the auto-configuration falls back to the value of configprop:server.servlet.session.timeout[]. If that property is not set, the auto-configuration falls back to the value of configprop:server.servlet.session.timeout[].
[[boot-features-jmx]] [[boot-features-jmx]]
== Monitoring and Management over JMX == Monitoring and Management over JMX
Java Management Extensions (JMX) provide a standard mechanism to monitor and manage applications. Java Management Extensions (JMX) provide a standard mechanism to monitor and manage applications.
...@@ -7798,9 +8103,11 @@ The {spring-webservices-docs}[Spring Web Services features] can be easily access ...@@ -7798,9 +8103,11 @@ The {spring-webservices-docs}[Spring Web Services features] can be easily access
To do so, configure their location, as shown in the following example: To do so, configure their location, as shown in the following example:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.webservices.wsdl-locations=classpath:/wsdl spring:
webservices:
wsdl-locations: "classpath:/wsdl"
---- ----
...@@ -8443,17 +8750,17 @@ Out-of-the-box, the following layers are supported: ...@@ -8443,17 +8750,17 @@ Out-of-the-box, the following layers are supported:
The following shows an example of a `layers.idx` file: The following shows an example of a `layers.idx` file:
[source] [source,yaml,indent=0]
---- ----
- "dependencies": - "dependencies":
- BOOT-INF/lib/library1.jar - BOOT-INF/lib/library1.jar
- BOOT-INF/lib/library2.jar - BOOT-INF/lib/library2.jar
- "spring-boot-loader": - "spring-boot-loader":
- org/springframework/boot/loader/JarLauncher.class - org/springframework/boot/loader/JarLauncher.class
- org/springframework/boot/loader/jar/JarEntry.class - org/springframework/boot/loader/jar/JarEntry.class
- "snapshot-dependencies": - "snapshot-dependencies":
- BOOT-INF/lib/library3-SNAPSHOT.jar - BOOT-INF/lib/library3-SNAPSHOT.jar
- "application": - "application":
- META-INF/MANIFEST.MF - META-INF/MANIFEST.MF
- BOOT-INF/classes/a/b/C.class - BOOT-INF/classes/a/b/C.class
---- ----
......
spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc
View file @ 25952584
...@@ -630,9 +630,12 @@ The report shows the changes to your application's auto-configuration as you mak ...@@ -630,9 +630,12 @@ The report shows the changes to your application's auto-configuration as you mak
To disable the logging of the report, set the following property: To disable the logging of the report, set the following property:
[indent=0] [source,yaml,indent=0,configblocks]
---- ----
spring.devtools.restart.log-condition-evaluation-delta=false spring:
devtools:
restart:
log-condition-evaluation-delta: false
---- ----
...@@ -644,9 +647,12 @@ By default, changing resources in `/META-INF/maven`, `/META-INF/resources`, `/re ...@@ -644,9 +647,12 @@ By default, changing resources in `/META-INF/maven`, `/META-INF/resources`, `/re
If you want to customize these exclusions, you can use the configprop:spring.devtools.restart.exclude[] property. If you want to customize these exclusions, you can use the configprop:spring.devtools.restart.exclude[] property.
For example, to exclude only `/static` and `/public` you would set the following property: For example, to exclude only `/static` and `/public` you would set the following property:
[indent=0] [source,yaml,indent=0,configblocks]
---- ----
spring.devtools.restart.exclude=static/**,public/** spring:
devtools:
restart:
exclude: "static/**,public/**"
---- ----
TIP: If you want to keep those defaults and _add_ additional exclusions, use the configprop:spring.devtools.restart.additional-exclude[] property instead. TIP: If you want to keep those defaults and _add_ additional exclusions, use the configprop:spring.devtools.restart.additional-exclude[] property instead.
...@@ -700,9 +706,12 @@ For example, if you have a project with the following structure: ...@@ -700,9 +706,12 @@ For example, if you have a project with the following structure:
Then your `trigger-file` property would be: Then your `trigger-file` property would be:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.devtools.restart.trigger-file=.reloadtrigger spring:
devtools:
restart:
trigger-file: ".reloadtrigger"
---- ----
Restarts will now only happen when the `src/main/resources/.reloadtrigger` is updated. Restarts will now only happen when the `src/main/resources/.reloadtrigger` is updated.
...@@ -730,10 +739,13 @@ The `spring-devtools.properties` file can contain properties prefixed with `rest ...@@ -730,10 +739,13 @@ The `spring-devtools.properties` file can contain properties prefixed with `rest
The `include` elements are items that should be pulled up into the "`restart`" classloader, and the `exclude` elements are items that should be pushed down into the "`base`" classloader. The `include` elements are items that should be pulled up into the "`restart`" classloader, and the `exclude` elements are items that should be pushed down into the "`base`" classloader.
The value of the property is a regex pattern that is applied to the classpath, as shown in the following example: The value of the property is a regex pattern that is applied to the classpath, as shown in the following example:
[source,properties,indent=0] [source,yaml,indent=0,configblocks]
---- ----
restart.exclude.companycommonlibs=/mycorp-common-[\\w\\d-\.]+\.jar restart:
restart.include.projectcommon=/mycorp-myproj-[\\w\\d-\.]+\.jar exclude:
companycommonlibs: "/mycorp-common-[\\w\\d-\\.]+\\.jar"
include:
projectcommon: "/mycorp-myproj-[\\w\\d-\\.]+\\.jar"
---- ----
NOTE: All property keys must be unique. NOTE: All property keys must be unique.
...@@ -776,12 +788,14 @@ You can configure global devtools settings by adding any of the following files ...@@ -776,12 +788,14 @@ You can configure global devtools settings by adding any of the following files
. `spring-boot-devtools.yml` . `spring-boot-devtools.yml`
Any properties added to these file apply to _all_ Spring Boot applications on your machine that use devtools. Any properties added to these file apply to _all_ Spring Boot applications on your machine that use devtools.
For example, to configure restart to always use a <<using-boot-devtools-restart-triggerfile, trigger file>>, you would add the following property: For example, to configure restart to always use a <<using-boot-devtools-restart-triggerfile, trigger file>>, you would add the following property to your `spring-boot-devtools` file:
.~/.config/spring-boot/spring-boot-devtools.properties [source,yaml,indent=0,configprops,configblocks]
[source,properties,indent=0,configprops]
---- ----
spring.devtools.restart.trigger-file=.reloadtrigger spring:
devtools:
restart:
trigger-file: ".reloadtrigger"
---- ----
NOTE: If devtools configuration files are not found in `$HOME/.config/spring-boot`, the root of the `$HOME` directory is searched for the presence of a `.spring-boot-devtools.properties` file. NOTE: If devtools configuration files are not found in `$HOME/.config/spring-boot`, the root of the `$HOME` directory is searched for the presence of a `.spring-boot-devtools.properties` file.
...@@ -803,10 +817,13 @@ Profile specific filenames (of the form `spring-boot-devtools-<profile>.properti ...@@ -803,10 +817,13 @@ Profile specific filenames (of the form `spring-boot-devtools-<profile>.properti
Since Spring Boot relies entirely on the IDE to compile and copy files into the location from where Spring Boot can read them, you might find that there are times when certain changes are not reflected when devtools restarts the application. Since Spring Boot relies entirely on the IDE to compile and copy files into the location from where Spring Boot can read them, you might find that there are times when certain changes are not reflected when devtools restarts the application.
If you observe such problems constantly, try increasing the `spring.devtools.restart.poll-interval` and `spring.devtools.restart.quiet-period` parameters to the values that fit your development environment: If you observe such problems constantly, try increasing the `spring.devtools.restart.poll-interval` and `spring.devtools.restart.quiet-period` parameters to the values that fit your development environment:
[source,properties,indent=0,configprops] [source,yaml,indent=0,configprops,configblocks]
---- ----
spring.devtools.restart.poll-interval=2s spring:
spring.devtools.restart.quiet-period=1s devtools:
restart:
poll-interval: "2s"
quiet-period: "1s"
---- ----
The monitored classpath directories are now polled every 2 seconds for changes, and a 1 second quiet period is maintained to make sure there are no additional class changes. The monitored classpath directories are now polled every 2 seconds for changes, and a 1 second quiet period is maintained to make sure there are no additional class changes.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment