Spring/spring-boot
Spring/spring-boot
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-boot.git synced 2024-07-15 01:07:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

Use Asciidoctor extension to verify documented configuration properties

Browse Source 
Closes gh-18451
This commit is contained in:
Andy Wilkinson 2019-09-26 20:20:33 +01:00
parent a36d2cd159
commit a6f1619971
8 changed files with 351 additions and 321 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
spring-boot-project/spring-boot-docs/pom.xml
View File

@ -1522,8 +1522,31 @@
<spring-framework-version>${spring-framework.version}</spring-framework-version>
<spring-integration-version>${spring-integration.version}</spring-integration-version>
<spring-security-version>${spring-security.version}</spring-security-version>
<spring-webservices-version>${spring-ws.version}</spring-webservices-version> </attributes>
<spring-webservices-version>${spring-ws.version}</spring-webservices-version>
</attributes>
</configuration>
<dependencies>
<dependency>
<groupId>io.spring.asciidoctor</groupId>
<artifactId>spring-asciidoctor-extensions-spring-boot</artifactId>
<version>${spring-asciidoctor-extensions.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-actuator-autoconfigure</artifactId>
<version>${revision}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-autoconfigure</artifactId>
<version>${revision}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<version>${revision}</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>generate-html-documentation</id>
@ -1551,9 +1574,9 @@
<attribute-missing>warn</attribute-missing>
</attributes>
<logHandler>
<outputToConsole>true</outputToConsole>
<outputToConsole>false</outputToConsole>
<failIf>
<severity>DEBUG</severity>
<severity>INFO</severity>
</failIf>
</logHandler>
</configuration>
@ -1581,6 +1604,12 @@
<stylesdir>css/</stylesdir>
<stylesheet>spring.css</stylesheet>
</attributes>
<logHandler>
<outputToConsole>false</outputToConsole>
<failIf>
<severity>INFO</severity>
</failIf>
</logHandler>
</configuration>
</execution>
<execution>

4
spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-configuration-metadata.adoc
View File

@ -81,7 +81,7 @@ They use a simple JSON format with items categorized under either "`groups`" or
Each "`property`" is a configuration item that the user specifies with a given value.
For example, `server.port` and `server.address` might be specified in `application.properties`, as follows:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
server.port=9090
server.address=127.0.0.1
@ -94,7 +94,7 @@ NOTE: It is not required that every "`property`" has a "`group`".
Some properties might exist in their own right.
Finally, "`hints`" are additional information used to assist the user in configuring a given property.
For example, when a developer is configuring the `spring.jpa.hibernate.ddl-auto` property, a tool can use the hints to offer some auto-completion help for the `none`, `validate`, `update`, `create`, and `create-drop` values.
For example, when a developer is configuring the configprop:spring.jpa.hibernate.ddl-auto[] property, a tool can use the hints to offer some auto-completion help for the `none`, `validate`, `update`, `create`, and `create-drop` values.

74
spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc
View File

@ -222,7 +222,7 @@ 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.*+`.
For example, in `application.properties`, you might have the following settings:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.main.web-application-type=none
spring.main.banner-mode=off
@ -243,7 +243,7 @@ Consider the following application:
Now consider the following configuration:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.main.sources=com.acme.Config,com.acme.ExtraConfig
spring.main.banner-mode=console
@ -264,8 +264,8 @@ Properties added in this way have lower priority than any added by using the def
You can also provide the following System properties (or environment variables) to change the behavior:
* `spring.config.name` (`SPRING_CONFIG_NAME`): Defaults to `application` as the root of the file name.
* `spring.config.location` (`SPRING_CONFIG_LOCATION`): The file to load (such as a classpath resource or a URL).
* configprop:spring.config.name[] (configprop:spring.config.name[format=envvar]): Defaults to `application` as the root of the file name.
* configprop:spring.config.location[] (configprop:spring.config.location[format=envvar]): The file to load (such as a classpath resource or a URL).
A separate `Environment` property source is set up for this document and it can be overridden by system properties, environment variables, or the command line.
No matter what you set in the environment, Spring Boot always loads `application.properties` as described above.
@ -282,7 +282,7 @@ 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.
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"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
server.port=${port:8080}
----
@ -317,10 +317,10 @@ A YAML file is parsed to a Java `Map<String,Object>` (like a JSON object), and S
The preceding example YAML corresponds to the following `application.properties` file:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.application.name=cruncher
spring.datasource.driverClassName=com.mysql.jdbc.Driver
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://localhost/test
server.port=9000
----
@ -331,7 +331,7 @@ See "`<<spring-boot-features.adoc#boot-features-external-config-yaml>>`" in the
[[howto-set-active-spring-profiles]]
=== Set the Active Spring Profiles
The Spring `Environment` has an API for this, but you would normally set a System property (`spring.profiles.active`) or an OS environment variable (`SPRING_PROFILES_ACTIVE`).
The Spring `Environment` has an API for this, but you would normally set a System property (configprop:spring.profiles.active[]) or an OS environment variable (configprop:spring.profiles.active[format=envvar]).
Also, you can launch your application with a `-D` argument (remember to put it before the main class or jar archive), as follows:
[indent=0,subs="verbatim,quotes,attributes"]
@ -341,7 +341,7 @@ 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:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.profiles.active=production
----
@ -474,7 +474,7 @@ 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.
To disable this behavior configure the `WebApplicationType` in your `application.properties`, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.main.web-application-type=none
----
@ -483,8 +483,8 @@ To disable this behavior configure the `WebApplicationType` in your `application
[[howto-change-the-http-port]]
=== Change the HTTP Port
In a standalone application, the main HTTP port defaults to `8080` but can be set with `server.port` (for example, in `application.properties` or as a System property).
Thanks to relaxed binding of `Environment` values, you can also use `SERVER_PORT` (for example, as an OS environment variable).
In a standalone application, the main HTTP port defaults to `8080` but can be set with configprop:server.port[] (for example, in `application.properties` or as a System property).
Thanks to relaxed binding of `Environment` values, you can also use configprop:server.port[format=envvar] (for example, as an OS environment variable).
To switch off the HTTP endpoints completely but still create a `WebApplicationContext`, use `server.port=-1` (doing so is sometimes useful for testing).
@ -536,13 +536,13 @@ Contrary to a test, application code callbacks are processed early (before the v
HTTP response compression is supported by Jetty, Tomcat, and Undertow.
It can be enabled in `application.properties`, as follows:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
server.compression.enabled=true
----
By default, responses must be at least 2048 bytes in length for compression to be performed.
You can configure this behavior by setting the `server.compression.min-response-size` property.
You can configure this behavior by setting the configprop:server.compression.min-response-size[] property.
By default, responses are compressed only if their content type is one of the following:
@ -555,7 +555,7 @@ By default, responses are compressed only if their content type is one of the fo
* `application/json`
* `application/xml`
You can configure this behavior by setting the `server.compression.mime-types` property.
You can configure this behavior by setting the configprop:server.compression.mime-types[] property.
@ -564,7 +564,7 @@ You can configure this behavior by setting the `server.compression.mime-types` p
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`:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
server.port=8443
server.ssl.key-store=classpath:keystore.jks
@ -583,7 +583,7 @@ We recommend using `application.properties` to configure HTTPS, as the HTTP conn
[[howto-configure-http2]]
=== Configure HTTP/2
You can enable HTTP/2 support in your Spring Boot application with the `+server.http2.enabled+` configuration property.
You can enable HTTP/2 support in your Spring Boot application with the configprop:server.http2.enabled[] configuration property.
This support depends on the chosen web server and the application environment, since that protocol is not supported out-of-the-box by JDK8.
[NOTE]
@ -754,7 +754,7 @@ 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].
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
server.tomcat.basedir=my-tomcat
server.tomcat.accesslog.enabled=true
@ -767,18 +767,18 @@ 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:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
server.undertow.accesslog.enabled=true
server.undertow.accesslog.pattern=%t %a "%r" %s (%D ms)
----
Logs are stored in a `logs` directory relative to the working directory of the application.
You can customize this location by setting the `server.undertow.accesslog.dir` property.
You can customize this location by setting the configprop:server.undertow.accesslog.dir[] property.
Finally, access logging for Jetty can also be configured as follows:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
server.jetty.accesslog.enabled=true
server.jetty.accesslog.filename=/var/log/jetty-access.log
@ -798,7 +798,7 @@ Typically, such situations are handled through a contract with the proxy, which
If the proxy adds conventional `X-Forwarded-For` and `X-Forwarded-Proto` headers (most proxy servers do so), the absolute links should be rendered correctly, provided `server.forward-headers-strategy` is set to `NATIVE` or `FRAMEWORK` in your `application.properties`.
NOTE: If your application runs in Cloud Foundry or Heroku, the `server.forward-headers-strategy` property defaults to `NATIVE`.
NOTE: If your application runs in Cloud Foundry or Heroku, the configprop:server.forward-headers-strategy[] property defaults to `NATIVE`.
In all other instances, it defaults to `NONE`.
@ -894,9 +894,9 @@ include::{code-examples}/context/embedded/TomcatLegacyCookieProcessorExample.jav
=== Enable Tomcat's MBean Registry
Embedded Tomcat's MBean registry is disabled by default.
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 `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]
[source,properties,indent=0,configprops]
----
server.tomcat.mbeanregistry.enabled=true
----
@ -1054,7 +1054,7 @@ These features are described in six enums (in Jackson) that map onto properties
| `true`, `false`
| `com.fasterxml.jackson.annotation.JsonInclude.Include`
| `spring.jackson.default-property-inclusion`
| configprop:spring.jackson.default-property-inclusion[]
| `always`, `non_null`, `non_absent`, `non_default`, `non_empty`
|===
@ -1101,7 +1101,7 @@ See the {spring-boot-autoconfigure-module-code}/web/servlet/WebMvcAutoConfigurat
Spring Boot embraces the Servlet 3 `javax.servlet.http.Part` API to support uploading files.
By default, Spring Boot configures Spring MVC with a maximum size of 1MB per file and a maximum of 10MB of file data in a single request.
You may override these values, the location to which intermediate data is stored (for example, to the `/tmp` directory), and the threshold past which data is flushed to disk by using the properties exposed in the `MultipartProperties` class.
For example, if you want to specify that files be unlimited, set the `spring.servlet.multipart.max-file-size` property to `-1`.
For example, if you want to specify that files be unlimited, set the configprop:spring.servlet.multipart.max-file-size[] property to `-1`.
The multipart support is helpful when you want to receive multipart encoded file data as a `@RequestParam`-annotated parameter of type `MultipartFile` in a Spring MVC controller handler method.
@ -1116,7 +1116,7 @@ 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 (`/`).
If you would rather map to a different path, you can configure one as follows:
[source,properties,indent=0,subs="verbatim"]
[source,properties,indent=0,subs="verbatim",configprops]
----
spring.mvc.servlet.path=/acme
----
@ -1284,7 +1284,7 @@ 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:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
logging.level.org.springframework.web=DEBUG
logging.level.org.hibernate=ERROR
@ -1293,7 +1293,7 @@ If the only change you need to make to logging is to set the levels of various l
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.
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 "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.
@ -1369,7 +1369,7 @@ If you want to disable console logging and write output only to a file, you need
You also need to add `logging.file.name` to your `application.properties`, as shown in the following example:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
logging.file.name=myapplication.log
----
@ -1652,7 +1652,7 @@ If an embedded database is used and no schema manager (such as Liquibase or Flyw
In all other cases, it defaults to `none`.
The dialect to use is detected by the JPA provider.
If you prefer to set the dialect yourself, set the `spring.jpa.database-platform` property.
If you prefer to set the dialect yourself, set the configprop:spring.jpa.database-platform[] property.
The most common options to set are shown in the following example:
@ -1922,7 +1922,7 @@ For example, you might choose to set it to the vendor name of the database (`hsq
[NOTE]
====
Spring Boot automatically creates the schema of an embedded `DataSource`.
This behavior can be customized by using the `spring.datasource.initialization-mode` property.
This behavior can be customized by using the configprop:spring.datasource.initialization-mode[] property.
For instance, if you want to always initialize the `DataSource` regardless of its type:
[indent=0,subs="verbatim,quotes,attributes"]
@ -1971,7 +1971,7 @@ By default, they are in a folder called `classpath:db/migration`, but you can mo
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.flyway.locations=classpath:db/migration,filesystem:/opt/migration
----
@ -1979,7 +1979,7 @@ For example, the following configuration would search for scripts in both the de
You can also add a special `\{vendor}` placeholder to use vendor-specific scripts.
Assume the following:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.flyway.locations=classpath:db/migration/{vendor}
----
@ -2015,7 +2015,7 @@ 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.
For example, in `application-dev.properties`, you might specify the following setting:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.flyway.locations=classpath:/db/migration,classpath:/dev/db/migration
----
@ -2119,7 +2119,7 @@ This section answers questions that often arise from its use.
[[howto-change-the-http-port-or-address-of-the-actuator-endpoints]]
=== Change the HTTP Port or Address of the Actuator Endpoints
In a standalone application, the Actuator HTTP port defaults to the same as the main HTTP port.
To make the application listen on a different port, set the external property: `management.server.port`.
To make the application listen on a different port, set the external property: configprop:management.server.port[].
To listen on a completely different network address (such as when you have an internal network for management and an external one for user applications), you can also set `management.server.address` to a valid IP address to which the server is able to bind.
For more detail, see the {spring-boot-actuator-autoconfigure-module-code}/web/server/ManagementServerProperties.java[`ManagementServerProperties`] source code and "`<<production-ready-features.adoc#production-ready-customizing-management-server-port>>`" in the "`Production-ready features`" section.
@ -2185,7 +2185,7 @@ 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.
You can switch on the valve by adding some entries to `application.properties`, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
server.tomcat.remote-ip-header=x-forwarded-for
server.tomcat.protocol-header=x-forwarded-proto

180
spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc
View File

@ -172,15 +172,15 @@ By default, all endpoints except for `shutdown` are enabled.
To configure the enablement of an endpoint, use its `management.endpoint.<id>.enabled` property.
The following example enables the `shutdown` endpoint:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoint.shutdown.enabled=true
----
If you prefer endpoint enablement to be opt-in rather than opt-out, set the `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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true
@ -299,16 +299,16 @@ To change which endpoints are exposed, use the following technology-specific `in
|===
| Property | Default
| `management.endpoints.jmx.exposure.exclude`
| configprop:management.endpoints.jmx.exposure.exclude[]
|
| `management.endpoints.jmx.exposure.include`
| configprop:management.endpoints.jmx.exposure.include[]
| `*`
| `management.endpoints.web.exposure.exclude`
| configprop:management.endpoints.web.exposure.exclude[]
|
|`management.endpoints.web.exposure.include`
| configprop:management.endpoints.web.exposure.include[]
| `info, health`
|===
@ -319,7 +319,7 @@ 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoints.jmx.exposure.include=health,info
----
@ -327,7 +327,7 @@ For example, to stop exposing all endpoints over JMX and only expose the `health
`*` can be used to select all endpoints.
For example, to expose everything over HTTP except the `env` and `beans` endpoints, use the following properties:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans
@ -381,10 +381,10 @@ Several other matcher methods are also available on `EndpointRequest`.
See the API documentation ({spring-boot-actuator-restapi}/html[HTML] or {spring-boot-actuator-restapi}/pdf/spring-boot-actuator-web-api.pdf[PDF]) for details.
If you deploy applications behind a firewall, you may prefer that all your actuator endpoints can be accessed without requiring authentication.
You can do so by changing the `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
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoints.web.exposure.include=*
----
@ -414,7 +414,7 @@ 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:
.application.properties
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoint.beans.cache.time-to-live=10s
----
@ -441,10 +441,10 @@ When the management context path is set to `/`, the discovery page is disabled t
https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing] (CORS) is a https://www.w3.org/TR/cors/[W3C specification] that lets you specify in a flexible way what kind of cross-domain requests are authorized.
If you use Spring MVC or Spring WebFlux, Actuator's web endpoints can be configured to support such scenarios.
CORS support is disabled by default and is only enabled once the `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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POST
@ -623,7 +623,7 @@ The `@Endpoint` and `@WebEndpoint` annotations should be preferred whenever poss
=== Health Information
You can use health information to check the status of your running application.
It is often used by monitoring software to alert someone when a production system goes down.
The information exposed by the `health` endpoint depends on the `management.endpoint.health.show-details` and `management.endpoint.health.show-components` properties which can be configured with one of the following values:
The information exposed by the `health` endpoint depends on the configprop:management.endpoint.health.show-details[] and configprop:management.endpoint.health.show-components[] properties which can be configured with one of the following values:
[cols="1, 3"]
|===
@ -643,7 +643,7 @@ The information exposed by the `health` endpoint depends on the `management.endp
The default value is `never`.
A user is considered to be authorized when they are in one or more of the endpoint's roles.
If the endpoint has no configured roles (the default) all authenticated users are considered to be authorized.
The roles can be configured using the `management.endpoint.health.roles` property.
The roles can be configured using the configprop:management.endpoint.health.roles[] property.
NOTE: If you have secured your application and wish to use `always`, your security configuration must permit access to the health endpoint for both authenticated and unauthenticated users.
@ -713,7 +713,7 @@ The following `HealthIndicators` are auto-configured by Spring Boot when appropr
| Checks that a Solr server is up.
|===
TIP: You can disable them all by setting the `management.health.defaults.enabled` property.
TIP: You can disable them all by setting the configprop:management.health.defaults.enabled[] property.
@ -748,12 +748,12 @@ NOTE: The identifier for a given `HealthIndicator` is the name of the bean witho
In the preceding example, the health information is available in an entry named `my`.
In addition to Spring Boot's predefined {spring-boot-actuator-module-code}/health/Status.java[`Status`] types, it is also possible for `Health` to return a custom `Status` that represents a new system state.
In such cases, a custom implementation of the {spring-boot-actuator-module-code}/health/StatusAggregator.java[`StatusAggregator`] interface also needs to be provided, or the default implementation has to be configured by using the `management.endpoint.health.status.order` configuration property.
In such cases, a custom implementation of the {spring-boot-actuator-module-code}/health/StatusAggregator.java[`StatusAggregator`] interface also needs to be provided, or the default implementation has to be configured by using the configprop:management.endpoint.health.status.order[] configuration property.
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up
----
@ -762,7 +762,7 @@ The HTTP status code in the response reflects the overall health status (for exa
You might also want to register custom status mappings if you access the health endpoint over HTTP.
For example, the following property maps `FATAL` to 503 (service unavailable):
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoint.health.status.http-mapping.fatal=503
----
@ -851,7 +851,7 @@ For example, if you deploy your application to Kubernetes, you may want one diff
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoint.health.group.custom.include=db
----
@ -861,7 +861,7 @@ You can then check the result by hitting `http://localhost:8080/actuator/health/
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoint.health.group.custom.show-details=when-authorized
management.endpoint.health.group.custom.roles=admin
@ -899,7 +899,7 @@ The following `InfoContributor` beans are auto-configured by Spring Boot, when a
| Exposes build information if a `META-INF/build-info.properties` file is available.
|===
TIP: It is possible to disable them all by setting the `management.info.defaults.enabled` property.
TIP: It is possible to disable them all by setting the configprop:management.info.defaults.enabled[] property.
@ -909,7 +909,7 @@ You can customize the data exposed by the `info` endpoint by setting `+info.*+`
All `Environment` properties under the `info` key are automatically exposed.
For example, you could add the following settings to your `application.properties` file:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
info.app.encoding=UTF-8
info.app.java.source=1.8
@ -922,7 +922,7 @@ Rather than hardcoding those values, you could also <<howto.adoc#howto-automatic
Assuming you use Maven, you could rewrite the preceding example as follows:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
info.app.encoding=@project.build.sourceEncoding@
info.app.java.source=@java.version@
@ -940,9 +940,9 @@ If a `GitProperties` bean is available, the `git.branch`, `git.commit.id`, and `
TIP: A `GitProperties` bean is auto-configured if a `git.properties` file is available at the root of the classpath.
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 `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]
[source,properties,indent=0,configprops]
----
management.info.git.mode=full
----
@ -1012,9 +1012,9 @@ TIP: Actuator is supported natively with Spring MVC, Spring WebFlux, and Jersey.
=== Customizing the Management Endpoint Paths
Sometimes, it is useful to customize the prefix for the management endpoints.
For example, your application might already use `/actuator` for another purpose.
You can use the `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]
[source,properties,indent=0,configprops]
----
management.endpoints.web.base-path=/manage
----
@ -1024,12 +1024,12 @@ The preceding `application.properties` example changes the endpoint from `/actua
NOTE: Unless the management port has been configured to <<production-ready-customizing-management-server-port,expose endpoints by using a different HTTP port>>, `management.endpoints.web.base-path` is relative to `server.servlet.context-path`.
If `management.server.port` is configured, `management.endpoints.web.base-path` is relative to `management.server.servlet.context-path`.
If you want to map endpoints to a different path, you can use the `management.endpoints.web.path-mapping` property.
If you want to map endpoints to a different path, you can use the configprop:management.endpoints.web.path-mapping[] property.
The following example remaps `/actuator/health` to `/healthcheck`:
.application.properties
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoints.web.base-path=/
management.endpoints.web.path-mapping.health=healthcheck
@ -1042,9 +1042,9 @@ The following example remaps `/actuator/health` to `/healthcheck`:
Exposing management endpoints by using the default HTTP port is a sensible choice for cloud-based deployments.
If, however, your application runs inside your own data center, you may prefer to expose endpoints by using a different HTTP port.
You can set the `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]
[source,properties,indent=0,configprops]
----
management.server.port=8081
----
@ -1059,7 +1059,7 @@ 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.
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]
[source,properties,indent=0,configprops]
----
server.port=8443
server.ssl.enabled=true
@ -1071,7 +1071,7 @@ For example, doing so lets a management server be available over HTTP while the
Alternatively, both the main server and the management server can use SSL but with different key stores, as follows:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
server.port=8443
server.ssl.enabled=true
@ -1087,14 +1087,14 @@ Alternatively, both the main server and the management server can use SSL but wi
[[production-ready-customizing-management-server-address]]
=== Customizing the Management Server Address
You can customize the address that the management endpoints are available on by setting the `management.server.address` property.
You can customize the address that the management endpoints are available on by setting the configprop:management.server.address[] property.
Doing so can be useful if you want to listen only on an internal or ops-facing network or to listen only for connections from `localhost`.
NOTE: You can listen on a different address only when the port differs from the main server port.
The following example `application.properties` does not allow remote management connections:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.server.port=8081
management.server.address=127.0.0.1
@ -1106,14 +1106,14 @@ The following example `application.properties` does not allow remote management
=== 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.server.port=-1
----
This can be achieved using the `management.endpoints.web.exposure.exclude` property as well, as shown in following example:
This can be achieved using the configprop:management.endpoints.web.exposure.exclude[] property as well, as shown in following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoints.web.exposure.exclude=*
----
@ -1123,7 +1123,7 @@ This can be achieved using the `management.endpoints.web.exposure.exclude` prope
[[production-ready-jmx]]
== Monitoring and Management over JMX
Java Management Extensions (JMX) provide a standard mechanism to monitor and manage applications.
By default, this feature is not enabled and can be turned on with the configuration property `spring.jmx.enabled=true`.
By default, this feature is not enabled and can be turned on by setting the configuration property configprop:spring.jmx.enabled[] to `true`.
Spring Boot exposes management endpoints as JMX MBeans under the `org.springframework.boot` domain by default.
@ -1134,12 +1134,12 @@ The name of the MBean is usually generated from the `id` of the endpoint.
For example, the `health` endpoint is exposed as `org.springframework.boot:type=Endpoint,name=Health`.
If your application contains more than one Spring `ApplicationContext`, you may find that names clash.
To solve this problem, you can set the `spring.jmx.unique-names` property to `true` so that MBean names are always unique.
To solve this problem, you can set the configprop:spring.jmx.unique-names[] property to `true` so that MBean names are always unique.
You can also customize the JMX domain under which endpoints are exposed.
The following settings show an example of doing so in `application.properties`:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.jmx.unique-names=true
management.endpoints.jmx.domain=com.example.myapp
@ -1149,9 +1149,9 @@ The following settings show an example of doing so in `application.properties`:
[[production-ready-disable-jmx-endpoints]]
=== Disabling JMX Endpoints
If you do not want to expose endpoints over JMX, you can set the `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]
[source,properties,indent=0,configprops]
----
management.endpoints.jmx.exposure.exclude=*
----
@ -1172,7 +1172,7 @@ For example, with Maven, you would add the following dependency:
</dependency>
----
The Jolokia endpoint can then be exposed by adding `jolokia` or `*` to the `management.endpoints.web.exposure.include` property.
The Jolokia endpoint can then be exposed by adding `jolokia` or `*` to the configprop:management.endpoints.web.exposure.include[] property.
You can then access it by using `/actuator/jolokia` on your management HTTP server.
@ -1183,7 +1183,7 @@ Jolokia has a number of settings that you would traditionally configure by setti
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.endpoint.jolokia.config.debug=true
----
@ -1192,9 +1192,9 @@ To do so, prefix the parameter with `management.endpoint.jolokia.config.`, as sh
[[production-ready-disabling-jolokia]]
==== Disabling Jolokia
If you use Jolokia but do not want Spring Boot to configure it, set the `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]
[source,properties,indent=0,configprops]
----
management.endpoint.jolokia.enabled=false
----
@ -1270,14 +1270,14 @@ Most registries share common features.
For instance, you can disable a particular registry even if the Micrometer registry implementation is on the classpath.
For example, to disable Datadog:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.datadog.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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.use-global-registry=false
----
@ -1323,7 +1323,7 @@ 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.
To export metrics to SaaS {micrometer-registry-docs}/appoptics[AppOptics], your API token must be provided:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.appoptics.api-token=YOUR_TOKEN
----
@ -1335,7 +1335,7 @@ 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.
The location of the https://github.com/Netflix/atlas[Atlas server] to use can be provided using:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.atlas.uri=https://atlas.example.com:7101/api/v1/publish
----
@ -1347,14 +1347,14 @@ 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.
To export metrics to {micrometer-registry-docs}/datadog[Datadog], your API key must be provided:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.datadog.api-key=YOUR_KEY
----
You can also change the interval at which metrics are sent to Datadog:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.datadog.step=30s
----
@ -1366,7 +1366,7 @@ You can also change the interval at which metrics are sent to Datadog:
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.dynatrace.api-token=YOUR_TOKEN
management.metrics.export.dynatrace.device-id=YOUR_DEVICE_ID
@ -1375,7 +1375,7 @@ To export metrics to {micrometer-registry-docs}/dynatrace[Dynatrace], your API t
You can also change the interval at which metrics are sent to Dynatrace:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.dynatrace.step=30s
----
@ -1387,7 +1387,7 @@ 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.
The location of the Elastic server to use can be provided using the following property:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.elastic.host=https://elastic.example.com:8086
----
@ -1399,7 +1399,7 @@ 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.
The http://ganglia.sourceforge.net[Ganglia server] host and port to use can be provided using:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.ganglia.host=ganglia.example.com
management.metrics.export.ganglia.port=9649
@ -1412,7 +1412,7 @@ 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.
The https://graphiteapp.org[Graphite server] host and port to use can be provided using:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.graphite.host=graphite.example.com
management.metrics.export.graphite.port=9004
@ -1438,14 +1438,14 @@ public GraphiteMeterRegistry graphiteMeterRegistry(GraphiteConfig config, Clock
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.humio.tags.alpha=a
management.metrics.export.humio.tags.bravo=b
@ -1458,7 +1458,7 @@ 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.
The location of the https://www.influxdata.com[Influx server] to use can be provided using:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.influx.uri=https://influx.example.com:8086
----
@ -1471,7 +1471,7 @@ Micrometer provides a hierarchical mapping to {micrometer-registry-docs}/jmx[JMX
By default, metrics are exported to the `metrics` JMX domain.
The domain to use can be provided using:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.jmx.domain=com.example.app.metrics
----
@ -1496,7 +1496,7 @@ public JmxMeterRegistry jmxMeterRegistry(JmxConfig config, Clock clock) {
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.kairos.uri=https://kairosdb.example.com:8080/api/v1/datapoints
----
@ -1508,7 +1508,7 @@ 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.
To export metrics to https://newrelic.com[New Relic], your API key and account id must be provided:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.newrelic.api-key=YOUR_KEY
management.metrics.export.newrelic.account-id=YOUR_ACCOUNT_ID
@ -1516,7 +1516,7 @@ To export metrics to https://newrelic.com[New Relic], your API key and account i
You can also change the interval at which metrics are sent to New Relic:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.newrelic.step=30s
----
@ -1564,14 +1564,14 @@ For advanced configuration, you can also provide your own `PrometheusPushGateway
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.signalfx.access-token=YOUR_ACCESS_TOKEN
----
You can also change the interval at which metrics are sent to SignalFx:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.signalfx.step=30s
----
@ -1586,7 +1586,7 @@ 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.
You can also disable it explicitly:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.simple.enabled=false
----
@ -1599,7 +1599,7 @@ 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.
The StatsD agent host and port to use can be provided using:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.statsd.host=statsd.example.com
management.metrics.export.statsd.port=9125
@ -1607,7 +1607,7 @@ The StatsD agent host and port to use can be provided using:
You can also change the StatsD line protocol to use (default to Datadog):
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.statsd.flavor=etsy
----
@ -1619,14 +1619,14 @@ You can also change the StatsD line protocol to use (default to Datadog):
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.wavefront.uri=proxy://localhost:2878
----
@ -1635,7 +1635,7 @@ TIP: If publishing metrics to a Wavefront proxy (as described in https://docs.wa
You can also change the interval at which metrics are sent to Wavefront:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.export.wavefront.step=30s
----
@ -1688,7 +1688,7 @@ Alternatively, when set to `false`, you can enable instrumentation by adding `@T
Long task timers require a separate metric name, and can be stacked with a short task timer.
By default, metrics are generated with the name, `http.server.requests`.
The name can be customized by setting the `management.metrics.web.server.requests-metric-name` property.
The name can be customized by setting the configprop:management.metrics.web.server.request.metric-name[] property.
By default, Spring MVC-related metrics are tagged with the following information:
@ -1721,7 +1721,7 @@ To customize the tags, provide a `@Bean` that implements `WebMvcTagsProvider`.
Auto-configuration enables the instrumentation of all requests handled by WebFlux controllers and functional handlers.
By default, metrics are generated with the name `http.server.requests`.
You can customize the name by setting the `management.metrics.web.server.requests-metric-name` property.
You can customize the name by setting the configprop:management.metrics.web.server.request.metric-name[] property.
By default, WebFlux-related metrics are tagged with the following information:
@ -1774,7 +1774,7 @@ Alternatively, when set to `false`, you can enable instrumentation by adding `@T
Long task timers require a separate metric name, and can be stacked with a short task timer.
By default, metrics are generated with the name, `http.server.requests`.
The name can be customized by setting the `management.metrics.web.server.requests-metric-name` property.
The name can be customized by setting the configprop:management.metrics.web.server.request.metric-name[] property.
By default, Jersey server metrics are tagged with the following information:
@ -1813,7 +1813,7 @@ For that, you have to get injected with an auto-configured builder and use it to
It is also possible to apply manually the customizers responsible for this instrumentation, namely `MetricsRestTemplateCustomizer` and `MetricsWebClientCustomizer`.
By default, metrics are generated with the name, `http.client.requests`.
The name can be customized by setting the `management.metrics.web.client.requests-metric-name` property.
The name can be customized by setting the configprop:management.metrics.web.client.request.metric-name[] property.
By default, metrics generated by an instrumented client are tagged with the following information:
@ -1887,7 +1887,7 @@ 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`.
You can enable that on the auto-configured `EntityManagerFactory` as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.jpa.properties.hibernate.generate_statistics=true
----
@ -1933,7 +1933,7 @@ 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.
Commons tags are applied to all meters and can be configured as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.tags.region=us-east-1
management.metrics.tags.stack=prod
@ -1951,7 +1951,7 @@ 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.
For example, the following will disable any meters that have an ID starting with `example.remote`
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.metrics.enable.example.remote=false
----
@ -1962,19 +1962,19 @@ The following properties allow per-meter customization:
|===
| Property | Description
| `management.metrics.enable`
| configprop:management.metrics.enable[]
| Whether to deny meters from emitting any metrics.
| `management.metrics.distribution.percentiles-histogram`
| configprop:management.metrics.distribution.percentiles-histogram[]
| Whether to publish a histogram suitable for computing aggregable (across dimension) percentile approximations.
| `management.metrics.distribution.minimum-expected-value`, `management.metrics.distribution.maximum-expected-value`
| configprop:management.metrics.distribution.minimum-expected-value[], configprop:management.metrics.distribution.maximum-expected-value[]
| Publish less histogram buckets by clamping the range of expected values.
| `management.metrics.distribution.percentiles`
| configprop:management.metrics.distribution.percentiles[]
| Publish percentile values computed in your application
| `management.metrics.distribution.sla`
| configprop:management.metrics.distribution.sla[]
| Publish a cumulative histogram with buckets defined by your SLAs.
|===
@ -2042,7 +2042,7 @@ The `httptrace` endpoint can be used to obtain information about the request-res
[[production-ready-http-tracing-custom]]
=== Custom HTTP tracing
To customize the items that are included in each trace, use the `management.trace.http.include` configuration property.
To customize the items that are included in each trace, use the configprop:management.trace.http.include[] configuration property.
For advanced customization, consider registering your own `HttpExchangeTracer` implementation.
@ -2100,7 +2100,7 @@ If you want to fully disable the `/cloudfoundryapplication` endpoints, you can a
.application.properties
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.cloudfoundry.enabled=false
----
@ -2113,7 +2113,7 @@ 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:
.application.properties
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
management.cloudfoundry.skip-ssl-validation=true
----

332
spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
View File

@ -90,9 +90,9 @@ Care must also be taken to ensure that the JVM has sufficient memory to accommod
For these reasons, lazy initialization is not enabled by default and it is recommended that fine-tuning of the JVM's heap size is done before enabling lazy initialization.
Lazy initialization can be enabled programatically using the `lazyInitialization` method on `SpringApplicationBuilder` or the `setLazyInitialization` method on `SpringApplication`.
Alternatively, it can be enabled using the `spring.main.lazy-initialization` property as shown in the following example:
Alternatively, it can be enabled using the configprop:spring.main.lazy-initialization[] property as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.main.lazy-initialization=true
----
@ -103,9 +103,9 @@ TIP: If you want to disable lazy initialization for certain beans while using la
[[boot-features-banner]]
=== Customizing the Banner
The banner that is printed on start up can be changed by adding a `banner.txt` file to your classpath or by setting the `spring.banner.location` property to the location of such a file.
The banner that is printed on start up can be changed by adding a `banner.txt` file to your classpath or by setting the configprop:spring.banner.location[] property to the location of such a file.
If the file has an encoding other than UTF-8, you can set `spring.banner.charset`.
In addition to a text file, you can also add a `banner.gif`, `banner.jpg`, or `banner.png` image file to your classpath or set the `spring.banner.image.location` property.
In addition to a text file, you can also add a `banner.gif`, `banner.jpg`, or `banner.png` image file to your classpath or set the configprop:spring.banner.image.location[] property.
Images are converted into an ASCII art representation and printed above any text banner.
Inside your `banner.txt` file, you can use any of the following placeholders:
@ -142,7 +142,7 @@ Inside your `banner.txt` file, you can use any of the following placeholders:
TIP: The `SpringApplication.setBanner(...)` method can be used if you want to generate a banner programmatically.
Use the `org.springframework.boot.Banner` interface and implement your own `printBanner()` method.
You can also use the `spring.main.banner-mode` property to determine if the banner has to be printed on `System.out` (`console`), sent to the configured logger (`log`), or not produced at all (`off`).
You can also use the configprop:spring.main.banner-mode[] property to determine if the banner has to be printed on `System.out` (`console`), sent to the configured logger (`log`), or not produced at all (`off`).
The printed banner is registered as a singleton bean under the following name: `springBootBanner`.
@ -331,7 +331,7 @@ When such an exception is encountered, Spring Boot returns the exit code provide
[[boot-features-application-admin]]
=== Admin Features
It is possible to enable admin-related features for the application by specifying the `spring.application.admin.enabled` property.
It is possible to enable admin-related features for the application by specifying the configprop:spring.application.admin.enabled[] property.
This exposes the {spring-boot-module-code}/admin/SpringApplicationAdminMXBean.java[`SpringApplicationAdminMXBean`] on the platform `MBeanServer`.
You could use this feature to administer your Spring Boot application remotely.
This feature could also be useful for any service wrapper implementation.
@ -463,7 +463,7 @@ The list is ordered by precedence (properties defined in locations higher in the
NOTE: You can also <<boot-features-external-config-yaml, use YAML ('.yml') files>> as an alternative to '.properties'.
If you do not like `application.properties` as the configuration file name, you can switch to another file name by specifying a `spring.config.name` environment property.
If you do not like `application.properties` as the configuration file name, you can switch to another file name by specifying a configprop:spring.config.name[] environment property.
You can also refer to an explicit location by using the `spring.config.location` environment property (which is a comma-separated list of directory locations or file paths).
The following example shows how to specify a different file name:
@ -515,7 +515,7 @@ This search ordering lets you specify default values in one configuration file a
You can provide default values for your application in `application.properties` (or whatever other basename you choose with `spring.config.name`) in one of the default locations.
These default values can then be overridden at runtime with a different file located in one of the custom locations.
NOTE: If you use environment variables rather than system properties, most operating systems disallow period-separated key names, but you can use underscores instead (for example, `SPRING_CONFIG_NAME` instead of `spring.config.name`).
NOTE: If you use environment variables rather than system properties, most operating systems disallow period-separated key names, but you can use underscores instead (for example, configprop:spring.config.name[format=envvar] instead of configprop:spring.config.name[]).
NOTE: If your application runs in a container, then JNDI properties (in `java:comp/env`) or servlet context initialization parameters can be used instead of, or as well as, environment variables or system properties.
@ -530,10 +530,10 @@ In other words, if no profiles are explicitly activated, then properties from `a
Profile-specific properties are loaded from the same locations as standard `application.properties`, with profile-specific files always overriding the non-specific ones, whether or not the profile-specific files are inside or outside your packaged jar.
If several profiles are specified, a last-wins strategy applies.
For example, profiles specified by the `spring.profiles.active` property are added after those configured through the `SpringApplication` API and therefore take precedence.
For example, profiles specified by the configprop:spring.profiles.active[] property are added after those configured through the `SpringApplication` API and therefore take precedence.
NOTE: If you have specified any files in `spring.config.location`, profile-specific variants of those files are not considered.
Use directories in `spring.config.location` if you want to also use profile-specific properties.
NOTE: If you have specified any files in configprop:spring.config.location[], profile-specific variants of those files are not considered.
Use directories in configprop:spring.config.location[] if you want to also use profile-specific properties.
@ -663,8 +663,8 @@ You can specify multiple profile-specific YAML documents in a single file by usi
address: 192.168.1.120
----
In the preceding example, if the `development` profile is active, the `server.address` property is `127.0.0.1`.
Similarly, if the `production` *and* `eu-central` profiles are active, the `server.address` property is `192.168.1.120`.
In the preceding example, if the `development` profile is active, the configprop:server.address[] property is `127.0.0.1`.
Similarly, if the `production` *and* `eu-central` profiles are active, the configprop:server.address[] property is `192.168.1.120`.
If the `development`, `production` and `eu-central` profiles are *not* enabled, then the value for the property is `192.168.1.100`.
[NOTE]
@ -1407,11 +1407,11 @@ Any `@Component`, `@Configuration` or `@ConfigurationProperties` can be marked w
NOTE: If `@ConfigurationProperties` beans are registered via `@EnableConfigurationProperties` instead of automatic scanning, the `@Profile` annotation needs to be specified on the `@Configuration` class that has the `@EnableConfigurationProperties` annotation.
In the case where `@ConfigurationProperties` are scanned, `@Profile` can be specified on the `@ConfigurationProperties` class itself.
You can use a `spring.profiles.active` `Environment` property to specify which profiles are active.
You can use a configprop:spring.profiles.active[] `Environment` property to specify which profiles are active.
You can specify the property in any of the ways described earlier in this chapter.
For example, you could include it in your `application.properties`, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.profiles.active=dev,hsqldb
----
@ -1422,12 +1422,12 @@ You could also specify it on the command line by using the following switch: `--
[[boot-features-adding-active-profiles]]
=== Adding Active Profiles
The `spring.profiles.active` property follows the same ordering rules as other properties: The highest `PropertySource` wins.
The configprop:spring.profiles.active[] property follows the same ordering rules as other properties: The highest `PropertySource` wins.
This means that you can specify active profiles in `application.properties` and then *replace* them by using the command line switch.
Sometimes, it is useful to have profile-specific properties that *add* to the active profiles rather than replace them.
The `spring.profiles.include` property can be used to unconditionally add active profiles.
The `SpringApplication` entry point also has a Java API for setting additional profiles (that is, on top of those activated by the `spring.profiles.active` property).
Sometimes, it is useful to have profil-specific properties that *add* to the active profiles rather than replace them.
The configprop:spring.profiles.include[] property can be used to unconditionally add active profiles.
The `SpringApplication` entry point also has a Java API for setting additional profiles (that is, on top of those activated by the configprop:spring.profiles.active[] property).
See the `setAdditionalProfiles()` method in {spring-boot-module-api}/SpringApplication.html[SpringApplication].
For example, when an application with the following properties is run by using the switch, `--spring.profiles.active=prod`, the `proddb` and `prodmq` profiles are also activated:
@ -1586,14 +1586,14 @@ The following colors and styles are supported:
[[boot-features-logging-file-output]]
=== File Output
By default, Spring Boot logs only to the console and does not write log files.
If you want to write log files in addition to the console output, you need to set a `logging.file.name` or `logging.file.path` property (for example, in your `application.properties`).
If you want to write log files in addition to the console output, you need to set a configprop:logging.file.name[] or configprop:logging.file.path[] property (for example, in your `application.properties`).
The following table shows how the `logging.*` properties can be used together:
.Logging properties
[cols="1,1,1,4"]
|===
| `logging.file.name` | `logging.file.path` | Example | Description
| configprop:logging.file.name[] | configprop:logging.file.path[] | Example | Description
| _(none)_
| _(none)_
@ -1614,11 +1614,11 @@ The following table shows how the `logging.*` properties can be used together:
|===
Log files rotate when they reach 10 MB and, as with console output, `ERROR`-level, `WARN`-level, and `INFO`-level messages are logged by default.
Size limits can be changed using the `logging.file.max-size` property.
Previously rotated files are archived indefinitely unless the `logging.file.max-history` property has been set.
The total size of log archives can be capped using `logging.file.total-size-cap`.
Size limits can be changed using the configprop:logging.file.max-size[] property.
Previously rotated files are archived indefinitely unless the configprop:logging.file.max-history[] property has been set.
The total size of log archives can be capped using configprop:logging.file.total-size-cap[].
When the total size of log archives exceeds that threshold, backups will be deleted.
To force log archive cleanup on application startup, use the `logging.file.clean-history-on-start` property.
To force log archive cleanup on application startup, use the configprop:logging.file.clean-history-on-start[] property.
TIP: Logging properties are independent of the actual logging infrastructure.
As a result, specific configuration keys (such as `logback.configurationFile` for Logback) are not managed by spring Boot.
@ -1632,7 +1632,7 @@ The `root` logger can be configured by using `logging.level.root`.
The following example shows potential logging settings in `application.properties`:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
logging.level.root=warn
logging.level.org.springframework.web=debug
@ -1644,7 +1644,7 @@ For example, `LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG` will set `org.springf
NOTE: The above approach will only work for package level logging.
Since relaxed binding always converts environment variables to lowercase, it's not possible to configure logging for an individual class in this way.
If you need to configure logging for a class, you can use <<boot-features-external-config-application-json, the SPRING_APPLICATION_JSON>> variable.
If you need to configure logging for a class, you can use <<boot-features-external-config-application-json, the `SPRING_APPLICATION_JSON`>> variable.
@ -1656,14 +1656,14 @@ 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`.
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"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
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:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
logging.level.tomcat=TRACE
----
@ -1685,7 +1685,7 @@ Spring Boot includes the following pre-defined logging groups that can be used o
[[boot-features-custom-log-configuration]]
=== Custom Log Configuration
The various logging systems can be activated by including the appropriate libraries on the classpath and can be further customized by providing a suitable configuration file in the root of the classpath or in a location specified by the following Spring `Environment` property: `logging.config`.
The various logging systems can be activated by including the appropriate libraries on the classpath and can be further customized by providing a suitable configuration file in the root of the classpath or in a location specified by the following Spring `Environment` property: configprop:logging.config[].
You can force Spring Boot to use a particular logging system by using the `org.springframework.boot.logging.LoggingSystem` system property.
The value should be the fully qualified class name of a `LoggingSystem` implementation.
@ -1720,59 +1720,59 @@ To help with the customization, some other properties are transferred from the S
|===
| Spring Environment | System Property | Comments
| `logging.exception-conversion-word`
| configprop:logging.exception-conversion-word[]
| `LOG_EXCEPTION_CONVERSION_WORD`
| The conversion word used when logging exceptions.
| `logging.file.clean-history-on-start`
| configprop:logging.file.clean-history-on-start[]
| `LOG_FILE_CLEAN_HISTORY_ON_START`
| Whether to clean the archive log files on startup (if LOG_FILE enabled).
(Only supported with the default Logback setup.)
| `logging.file.name`
| configprop:logging.file.name[]
| `LOG_FILE`
| If defined, it is used in the default log configuration.
| `logging.file.max-size`
| configprop:logging.file.max-size[]
| `LOG_FILE_MAX_SIZE`
| Maximum log file size (if LOG_FILE enabled).
(Only supported with the default Logback setup.)
| `logging.file.max-history`
| configprop:logging.file.max-history[]
| `LOG_FILE_MAX_HISTORY`
| Maximum number of archive log files to keep (if LOG_FILE enabled).
(Only supported with the default Logback setup.)
| `logging.file.path`
| configprop:logging.file.path[]
| `LOG_PATH`
| If defined, it is used in the default log configuration.
| `logging.file.total-size-cap`
| configprop:logging.file.total-size-cap[]
| `LOG_FILE_TOTAL_SIZE_CAP`
| Total size of log backups to be kept (if LOG_FILE enabled).
(Only supported with the default Logback setup.)
| `logging.pattern.console`
| configprop:logging.pattern.console[]
| `CONSOLE_LOG_PATTERN`
| The log pattern to use on the console (stdout).
(Only supported with the default Logback setup.)
| `logging.pattern.dateformat`
| configprop:logging.pattern.dateformat[]
| `LOG_DATEFORMAT_PATTERN`
| Appender pattern for log date format.
(Only supported with the default Logback setup.)
| `logging.pattern.file`
| configprop:logging.pattern.file[]
| `FILE_LOG_PATTERN`
| The log pattern to use in a file (if `LOG_FILE` is enabled).
(Only supported with the default Logback setup.)
| `logging.pattern.level`
| configprop:logging.pattern.level[]
| `LOG_LEVEL_PATTERN`
| The format to use when rendering the log level (default `%5p`).
(Only supported with the default Logback setup.)
| `logging.pattern.rolling-file-name`
| configprop:logging.pattern.rolling-file-name[]
| `ROLLING_FILE_NAME_PATTERN`
| Pattern for rolled-over log file names (default `$\{LOG_FILE}.%d\{yyyy-MM-dd}.%i.gz`).
(Only supported with the default Logback setup.)
@ -1815,7 +1815,7 @@ Spring Boot includes a number of extensions to Logback that can help with advanc
You can use these extensions in your `logback-spring.xml` configuration file.
NOTE: Because the standard `logback.xml` configuration file is loaded too early, you cannot use extensions in it.
You need to either use `logback-spring.xml` or define a `logging.config` property.
You need to either use `logback-spring.xml` or define a configprop:logging.config[] property.
WARNING: The extensions cannot be used with Logback's https://logback.qos.ch/manual/configuration.html#autoScan[configuration scanning].
If you attempt to do so, making changes to the configuration file results in an error similar to one of the following being logged:
@ -1889,7 +1889,7 @@ 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.messages.basename=messages,config.i18n.messages
spring.messages.fallback-to-system-locale=false
@ -2080,7 +2080,7 @@ See {spring-boot-module-api}/jackson/JsonObjectSerializer.html[`JsonObjectSerial
[[boot-features-spring-message-codes]]
==== MessageCodesResolver
Spring MVC has a strategy for generating error codes for rendering error messages from binding errors: `MessageCodesResolver`.
If you set the `spring.mvc.message-codes-resolver.format` property `PREFIX_ERROR_CODE` or `POSTFIX_ERROR_CODE`, Spring Boot creates one for you (see the enumeration in {spring-framework-api}/validation/DefaultMessageCodesResolver.Format.html[`DefaultMessageCodesResolver.Format`]).
If you set the configprop:spring.mvc.message-codes-resolver-format[] property `PREFIX_ERROR_CODE` or `POSTFIX_ERROR_CODE`, Spring Boot creates one for you (see the enumeration in {spring-framework-api}/validation/DefaultMessageCodesResolver.Format.html[`DefaultMessageCodesResolver.Format`]).
@ -2092,15 +2092,15 @@ It uses the `ResourceHttpRequestHandler` from Spring MVC so that you can modify
In a stand-alone web application, the default servlet from the container is also enabled and acts as a fallback, serving content from the root of the `ServletContext` if Spring decides not to handle it.
Most of the time, this does not happen (unless you modify the default MVC configuration), because Spring can always handle requests through the `DispatcherServlet`.
By default, resources are mapped on `+/**+`, but you can tune that with the `spring.mvc.static-path-pattern` property.
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:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.mvc.static-path-pattern=/resources/**
----
You can also customize the static resource locations by using the `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).
The root Servlet context path, `"/"`, is automatically added as a location as well.
In addition to the "`standard`" static resource locations mentioned earlier, a special case is made for https://www.webjars.org/[Webjars content].
@ -2120,7 +2120,7 @@ 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:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.resources.chain.strategy.content.enabled=true
spring.resources.chain.strategy.content.paths=/**
@ -2134,7 +2134,7 @@ When loading resources dynamically with, for example, a JavaScript module loader
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:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.resources.chain.strategy.content.enabled=true
spring.resources.chain.strategy.content.paths=/**
@ -2180,7 +2180,7 @@ 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.
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,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.mvc.contentnegotiation.favor-parameter=true
@ -2193,7 +2193,7 @@ Instead of using suffix matching, we can use a query parameter to ensure that re
If you understand the caveats and would still like your application to use suffix pattern matching, the following configuration is required:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.mvc.contentnegotiation.favor-path-extension=true
spring.mvc.pathmatch.use-suffix-pattern=true
@ -2201,7 +2201,7 @@ 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 just support registered suffix patterns:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.mvc.contentnegotiation.favor-path-extension=true
spring.mvc.pathmatch.use-registered-suffix-pattern=true
@ -2560,10 +2560,10 @@ You can also leverage <<boot-features-json-components,Boot's custom JSON seriali
By default, Spring Boot serves static content from a directory called `/static` (or `/public` or `/resources` or `/META-INF/resources`) in the classpath.
It uses the `ResourceWebHandler` from Spring WebFlux so that you can modify that behavior by adding your own `WebFluxConfigurer` and overriding the `addResourceHandlers` method.
By default, resources are mapped on `+/**+`, but you can tune that by setting the `spring.webflux.static-path-pattern` property.
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:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.webflux.static-path-pattern=/resources/**
----
@ -2960,7 +2960,7 @@ 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:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.rsocket.server.mapping-path=/rsocket # a mapping path is defined
spring.rsocket.server.transport=websocket # websocket is chosen as a transport
@ -2972,7 +2972,7 @@ 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.
Besides the dependency requirements, the only required configuration is to define a port for that server:
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
[source,properties,indent=0,subs="verbatim,quotes,attributes",configprops]
----
spring.rsocket.server.port=9898 # the only required configuration
spring.rsocket.server.transport=tcp # you're free to configure other properties
@ -3062,7 +3062,7 @@ To also switch off the `UserDetailsService` configuration, you can add a bean of
Access rules can be overridden by adding a custom `WebSecurityConfigurerAdapter`.
Spring Boot provides convenience methods that can be used to override access rules for actuator endpoints and static resources.
`EndpointRequest` can be used to create a `RequestMatcher` that is based on the `management.endpoints.web.base-path` property.
`EndpointRequest` can be used to create a `RequestMatcher` that is based on the configprop:management.endpoints.web.base-path[] property.
`PathRequest` can be used to create a `RequestMatcher` for resources in commonly used locations.
@ -3078,7 +3078,7 @@ To also switch off the `UserDetailsService` configuration, you can add a bean of
Access rules can be configured by adding a custom `SecurityWebFilterChain`.
Spring Boot provides convenience methods that can be used to override access rules for actuator endpoints and static resources.
`EndpointRequest` can be used to create a `ServerWebExchangeMatcher` that is based on the `management.endpoints.web.base-path` property.
`EndpointRequest` can be used to create a `ServerWebExchangeMatcher` that is based on the configprop:management.endpoints.web.base-path[] property.
`PathRequest` can be used to create a `ServerWebExchangeMatcher` for resources in commonly used locations.
@ -3105,7 +3105,7 @@ 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.security.oauth2.client.registration.my-client-1.client-id=abcd
spring.security.oauth2.client.registration.my-client-1.client-secret=password
@ -3139,7 +3139,7 @@ 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 following example shows how an OpenID Connect Provider can be configured with the `issuer-uri`:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.security.oauth2.client.provider.oidc-provider.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/
----
@ -3176,7 +3176,7 @@ 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.security.oauth2.client.registration.my-client.client-id=abcd
spring.security.oauth2.client.registration.my-client.client-secret=password
@ -3193,18 +3193,18 @@ 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.
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]
[source,properties,indent=0,configprops]
----
spring.security.oauth2.resourceserver.jwt.jwk-set-uri=https://example.com/oauth2/default/v1/keys
----
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
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.
This can be done using the `spring.security.oauth2.resourceserver.jwt.public-key-location` property, where the value needs to point to a file containing the public key in the PEM-encoded x509 format.
This can be done using the configprop:spring.security.oauth2.resourceserver.jwt.public-key-location[] property, where the value needs to point to a file containing the public key in the PEM-encoded x509 format.
The same properties are applicable for both servlet and reactive applications.
@ -3212,11 +3212,11 @@ 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.security.oauth2.resourceserver.opaquetoken.introspection-uri=https://example.com/check-token
spring.security.oauth2.resourceserver.opaquetoken.client-id=my-client-id
spring.security.oauth2.resourceserver.opaquetoken.client-secret-my-client-secret
spring.security.oauth2.resourceserver.opaquetoken.client-secret=my-client-secret
----
Again, the same properties are applicable for both servlet and reactive applications.
@ -3235,7 +3235,7 @@ Until then, you can use the `spring-security-oauth2-autoconfigure` module to eas
[[boot-features-security-actuator]]
=== Actuator Security
For security purposes, all actuators other than `/health` and `/info` are disabled by default.
The `management.endpoints.web.exposure.include` property can be used to enable the actuators.
The configprop:management.endpoints.web.exposure.include[] property can be used to enable the actuators.
If Spring Security is on the classpath and no other WebSecurityConfigurerAdapter is present, all actuators other than `/health` and `/info` are secured by Spring Boot auto-configuration.
If you define a custom `WebSecurityConfigurerAdapter`, Spring Boot auto-configuration will back off and you will be in full control of actuator access rules.
@ -3326,7 +3326,7 @@ Spring Boot uses the following algorithm for choosing a specific implementation:
If you use the `spring-boot-starter-jdbc` or `spring-boot-starter-data-jpa` "`starters`", you automatically get a dependency to `HikariCP`.
NOTE: You can bypass that algorithm completely and specify the connection pool to use by setting the `spring.datasource.type` property.
NOTE: You can bypass that algorithm completely and specify the connection pool to use by setting the configprop:spring.datasource.type[] property.
This is especially important if you run your application in a Tomcat container, as `tomcat-jdbc` is provided by default.
TIP: Additional connection pools can always be configured manually.
@ -3335,7 +3335,7 @@ If you define your own `DataSource` bean, auto-configuration does not occur.
DataSource configuration is controlled by external configuration properties in `+spring.datasource.*+`.
For example, you might declare the following section in `application.properties`:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.datasource.url=jdbc:mysql://localhost/test
spring.datasource.username=dbuser
@ -3343,7 +3343,7 @@ For example, you might declare the following section in `application.properties`
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
----
NOTE: You should at least specify the URL by setting the `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.
TIP: You often do not need to specify the `driver-class-name`, since Spring Boot can deduce it for most databases from the `url`.
@ -3358,7 +3358,7 @@ Refer to the documentation of the connection pool implementation you are using f
For instance, if you use the https://tomcat.apache.org/tomcat-8.0-doc/jdbc-pool.html#Common_Attributes[Tomcat connection pool], you could customize many additional settings, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
# Number of ms to wait before throwing an exception if no connection is available.
spring.datasource.tomcat.max-wait=10000
@ -3376,10 +3376,10 @@ For instance, if you use the https://tomcat.apache.org/tomcat-8.0-doc/jdbc-pool.
==== Connection to a JNDI DataSource
If you deploy your Spring Boot application to an Application Server, you might want to configure and manage your DataSource by using your Application Server's built-in features and access it by using JNDI.
The `spring.datasource.jndi-name` property can be used as an alternative to the `spring.datasource.url`, `spring.datasource.username`, and `spring.datasource.password` properties to access the `DataSource` from a specific JNDI location.
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`:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.datasource.jndi-name=java:jboss/datasources/customers
----
@ -3413,7 +3413,7 @@ 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.jdbc.template.max-rows=500
----
@ -3527,7 +3527,7 @@ The following example shows a typical Spring Data repository interface definitio
----
Spring Data JPA repositories support three different modes of bootstrapping: default, deferred, and lazy.
To enable deferred or lazy bootstrapping, set the `spring.data.jpa.repositories.bootstrap-mode` to `deferred` or `lazy` respectively.
To enable deferred or lazy bootstrapping, set the configprop:spring.data.jpa.repositories.bootstrap-mode[] property to `deferred` or `lazy` respectively.
When using deferred or lazy bootstrapping, the auto-configured `EntityManagerFactoryBuilder` will use the context's `AsyncTaskExecutor`, if any, as the bootstrap executor.
If more than one exists, the one named `applicationTaskExecutor` will be used.
@ -3592,7 +3592,7 @@ The console is auto-configured when the following conditions are met:
* `com.h2database:h2` is on the classpath.
* You are using <<using-spring-boot.adoc#using-boot-devtools,Spring Boot's developer tools>>.
TIP: If you are not using Spring Boot's developer tools but would still like to make use of H2's console, you can configure the `spring.h2.console.enabled` property with a value of `true`.
TIP: If you are not using Spring Boot's developer tools but would still like to make use of H2's console, you can configure the configprop:spring.h2.console.enabled[] property with a value of `true`.
NOTE: The H2 console is only intended for use during development, so you should take care to ensure that `spring.h2.console.enabled` is not set to `true` in production.
@ -3601,7 +3601,7 @@ NOTE: The H2 console is only intended for use during development, so you should
[[boot-features-sql-h2-console-custom-path]]
==== Changing the H2 Console's Path
By default, the console is available at `/h2-console`.
You can customize the console's path by using the `spring.h2.console.path` property.
You can customize the console's path by using the configprop:spring.h2.console.path[] property.
@ -3684,7 +3684,7 @@ You can then use the `DSLContext` to construct your queries, as shown in the fol
==== jOOQ SQL Dialect
Unless the `spring.jooq.sql-dialect` property has been configured, Spring Boot determines the SQL dialect to use for your datasource.
Unless the configprop:spring.jooq.sql-dialect[] property has been configured, Spring Boot determines the SQL dialect to use for your datasource.
If Spring Boot could not detect the dialect, it uses `DEFAULT`.
NOTE: Spring Boot can only auto-configure dialects supported by the open source version of jOOQ.
@ -3811,9 +3811,9 @@ The following example shows how to connect to a MongoDB database:
}
----
You can set the `spring.data.mongodb.uri` property to change the URL and configure additional settings such as the _replica set_, as shown in the following example:
You can set the configprop:spring.data.mongodb.uri[] property to change the URL and configure additional settings such as the _replica set_, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.data.mongodb.uri=mongodb://user:secret@mongo1.example.com:12345,mongo2.example.com:23456/test
----
@ -3821,7 +3821,7 @@ You can set the `spring.data.mongodb.uri` property to change the URL and configu
Alternatively, as long as you use Mongo 2.x, you can specify a `host`/`port`.
For example, you might declare the following settings in your `application.properties`:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.data.mongodb.host=mongoserver
spring.data.mongodb.port=27017
@ -3910,7 +3910,7 @@ TIP: For complete details of Spring Data MongoDB, including its rich object mapp
Spring Boot offers auto-configuration for https://github.com/flapdoodle-oss/de.flapdoodle.embed.mongo[Embedded Mongo].
To use it in your Spring Boot application, add a dependency on `de.flapdoodle.embed:de.flapdoodle.embed.mongo`.
The port that Mongo listens on can be configured by setting the `spring.data.mongodb.port` property.
The port that Mongo listens on can be configured by setting the configprop:spring.data.mongodb.port[] property.
To use a randomly allocated free port, use a value of 0.
The `MongoClient` created by `MongoAutoConfiguration` is automatically configured to use the randomly allocated port.
@ -3955,7 +3955,7 @@ The following example shows how to inject a Neo4j `Session`:
You can configure the uri and credentials to use by setting the `spring.data.neo4j.*` properties, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.data.neo4j.uri=bolt://my-server:7687
spring.data.neo4j.username=neo4j
@ -3986,9 +3986,9 @@ NOTE: You can enable persistence for the embedded mode by providing a path to a
==== Using Native Types
Neo4j-OGM can map some types, like those in `java.time.*`, to `String`-based properties or to one of the native types that Neo4j provides.
For backwards compatibility reasons the default for Neo4j-OGM is to use a `String`-based representation.
To use native types, add a dependency on either `org.neo4j:neo4j-ogm-bolt-native-types` or `org.neo4j:neo4j-ogm-embedded-native-types`, and configure the `spring.data.neo4j.use-native-types` property as shown in the following example:
To use native types, add a dependency on either `org.neo4j:neo4j-ogm-bolt-native-types` or `org.neo4j:neo4j-ogm-embedded-native-types`, and configure the configprop:spring.data.neo4j.use-native-types[] property as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.data.neo4j.use-native-types=true
----
@ -4000,7 +4000,7 @@ To use native types, add a dependency on either `org.neo4j:neo4j-ogm-bolt-native
By default, if you are running a web application, the session is bound to the thread for the entire processing of the request (that is, it uses the "Open Session in View" pattern).
If you do not want this behavior, add the following line to your `application.properties` file:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.data.neo4j.open-in-view=false
----
@ -4108,7 +4108,7 @@ Elasticsearch ships https://www.elastic.co/guide/en/elasticsearch/client/java-re
If you have the `org.elasticsearch.client:elasticsearch-rest-client` dependency on the classpath, Spring Boot will auto-configure and register a `RestClient` bean that by default targets `http://localhost:9200`.
You can further tune how `RestClient` is configured, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.elasticsearch.rest.uris=https://search.example.com:9200
spring.elasticsearch.rest.read-timeout=10s
@ -4131,13 +4131,13 @@ By default, Spring Boot will auto-configure and register a `ReactiveElasticsearc
bean that targets `http://localhost:9200`.
You can further tune how it is configured, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.elasticsearch.reactive.endpoints=search.example.com:9200
spring.elasticsearch.reactive.use-ssl=true
spring.elasticsearch.reactive.socket-timeout=10s
spring.elasticsearch.reactive.username=user
spring.elasticsearch.reactive.password=secret
spring.data.elasticsearch.client.reactive.endpoints=search.example.com:9200
spring.data.elasticsearch.client.reactive.use-ssl=true
spring.data.elasticsearch.client.reactive.socket-timeout=10s
spring.data.elasticsearch.client.reactive.username=user
spring.data.elasticsearch.client.reactive.password=secret
----
If the configuration properties are not enough and you'd like to fully control the client
@ -4150,7 +4150,7 @@ Now that Spring Boot supports the official `RestHighLevelClient`, Jest support i
If you have `Jest` on the classpath, you can inject an auto-configured `JestClient` that by default targets `http://localhost:9200`.
You can further tune how the client is configured, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.elasticsearch.jest.uris=https://search.example.com:9200
spring.elasticsearch.jest.read-timeout=10000
@ -4217,7 +4217,7 @@ Same applies to `ReactiveElasticsearchTemplate` and `ReactiveElasticsearchOperat
You can choose to disable the repositories support with the following property:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.data.elasticsearch.repositories.enabled=false
----
@ -4237,7 +4237,7 @@ You can inject an auto-configured `CassandraTemplate` or a Cassandra `Session` i
The `spring.data.cassandra.*` properties can be used to customize the connection.
Generally, you provide `keyspace-name` and `contact-points` properties, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.data.cassandra.keyspace-name=mykeyspace
spring.data.cassandra.contact-points=cassandrahost1,cassandrahost2
@ -4291,7 +4291,7 @@ You can get a `Bucket` and `Cluster` by adding the Couchbase SDK and some config
The `spring.couchbase.*` properties can be used to customize the connection.
Generally, you provide the bootstrap hosts, bucket name, and password, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.couchbase.bootstrap-hosts=my-host-1,192.168.1.123
spring.couchbase.bucket.name=my-bucket
@ -4304,7 +4304,7 @@ Alternatively, you can define your own `org.springframework.data.couchbase.confi
It is also possible to customize some of the `CouchbaseEnvironment` settings.
For instance, the following configuration changes the timeout to use to open a new `Bucket` and enables SSL support:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.couchbase.env.timeouts.connect=3000
spring.couchbase.env.ssl.key-store=/location/of/keystore.jks
@ -4383,7 +4383,7 @@ There is a `spring-boot-starter-data-ldap` "`Starter`" for collecting the depend
==== 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.ldap.urls=ldap://myserver:1235
spring.ldap.username=admin
@ -4428,9 +4428,9 @@ You can also inject an auto-configured `LdapTemplate` instance as you would with
[[boot-features-ldap-embedded]]
==== Embedded In-memory LDAP Server
For testing purposes, Spring Boot supports auto-configuration of an in-memory LDAP server from https://www.ldap.com/unboundid-ldap-sdk-for-java[UnboundID].
To configure the server, add a dependency to `com.unboundid:unboundid-ldapsdk` and declare a `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]
[source,properties,indent=0,configprops]
----
spring.ldap.embedded.base-dn=dc=spring,dc=io
----
@ -4450,7 +4450,7 @@ 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,properties,indent=0]
[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
@ -4459,14 +4459,14 @@ In properties files, you must include the index as part of the property name:
====
By default, the server starts on a random port and triggers the regular LDAP support.
There is no need to specify a `spring.ldap.urls` property.
There is no need to specify a configprop:spring.ldap.urls[] property.
If there is a `schema.ldif` file on your classpath, it is used to initialize the server.
If you want to load the initialization script from a different resource, you can also use the `spring.ldap.embedded.ldif` property.
If you want to load the initialization script from a different resource, you can also use the configprop:spring.ldap.embedded.ldif[] property.
By default, a standard schema is used to validate `LDIF` files.
You can turn off validation altogether by setting the `spring.ldap.embedded.validation.enabled` property.
If you have custom attributes, you can use `spring.ldap.embedded.validation.schema` to define your custom attribute types or object classes.
You can turn off validation altogether by setting the configprop:spring.ldap.embedded.validation.enabled[] property.
If you have custom attributes, you can use configprop:spring.ldap.embedded.validation.schema[] to define your custom attribute types or object classes.
@ -4480,7 +4480,7 @@ https://www.influxdata.com/[InfluxDB] is an open-source time series database opt
==== 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.influx.url=https://172.0.0.1:8086
----
@ -4532,7 +4532,7 @@ When a cache is required (such as `piDecimals` in the preceding example), this p
The simple provider is not really recommended for production usage, but it is great for getting started and making sure that you understand the features.
When you have made up your mind about the cache provider to use, please make sure to read its documentation to figure out how to configure the caches that your application uses.
Nearly all providers require you to explicitly configure every cache that you use in the application.
Some offer a way to customize the default caches defined by the `spring.cache.cache-names` property.
Some offer a way to customize the default caches defined by the configprop:spring.cache.cache-names[] property.
TIP: It is also possible to transparently {spring-framework-docs}integration.html#cache-annotations-put[update] or {spring-framework-docs}integration.html#cache-annotations-evict[evict] data from the cache.
@ -4554,7 +4554,7 @@ If you have not defined a bean of type `CacheManager` or a `CacheResolver` named
. <<boot-features-caching-provider-caffeine,Caffeine>>
. <<boot-features-caching-provider-simple,Simple>>
TIP: It is also possible to _force_ a particular cache provider by setting the `spring.cache.type` property.
TIP: It is also possible to _force_ a particular cache provider by setting the configprop:spring.cache.type[] property.
Use this property if you need to <<boot-features-caching-provider-none,disable caching altogether>> in certain environment (such as tests).
TIP: Use the `spring-boot-starter-cache` "`Starter`" to quickly add basic caching dependencies.
@ -4599,7 +4599,7 @@ 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.
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]
[source,properties,indent=0,configprops]
----
# Only necessary if more than one provider is present
spring.cache.jcache.provider=com.acme.MyCachingProvider
@ -4609,11 +4609,11 @@ Even if the JSR-107 standard does not enforce a standardized way to define the l
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.
TIP: Spring Boot has <<boot-features-hazelcast,general support for Hazelcast>>.
If a single `HazelcastInstance` is available, it is automatically reused for the `CacheManager` as well, unless the `spring.cache.jcache.config` property is specified.
If a single `HazelcastInstance` is available, it is automatically reused for the `CacheManager` as well, unless the configprop:spring.cache.jcache.config[] property is specified.
There are two ways to customize the underlying `javax.cache.cacheManager`:
* Caches can be created on startup by setting the `spring.cache.cache-names` property.
* Caches can be created on startup by setting the configprop:spring.cache.cache-names[] property.
If a custom `javax.cache.configuration.Configuration` bean is defined, it is used to customize them.
* `org.springframework.boot.autoconfigure.cache.JCacheManagerCustomizer` beans are invoked with the reference of the `CacheManager` for full customization.
@ -4628,7 +4628,7 @@ 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.
An alternate configuration file can be provided as well, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.cache.ehcache.config=classpath:config/another-config.xml
----
@ -4647,12 +4647,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.
Otherwise, the default bootstrap is used.
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.cache.infinispan.config=infinispan.xml
----
Caches can be created on startup by setting the `spring.cache.cache-names` property.
Caches can be created on startup by setting the configprop:spring.cache.cache-names[] property.
If a custom `ConfigurationBuilder` bean is defined, it is used to customize the caches.
NOTE: The support of Infinispan in Spring Boot is restricted to the embedded mode and is quite basic.
@ -4664,13 +4664,13 @@ See https://github.com/infinispan/infinispan-spring-boot[Infinispan's documentat
[[boot-features-caching-provider-couchbase]]
==== Couchbase
If the https://www.couchbase.com/[Couchbase] Java client and the `couchbase-spring-cache` implementation are available and Couchbase is <<boot-features-couchbase,configured>>, a `CouchbaseCacheManager` is auto-configured.
It is also possible to create additional caches on startup by setting the `spring.cache.cache-names` property.
It is also possible to create additional caches on startup by setting the configprop:spring.cache.cache-names[] property.
These caches operate on the `Bucket` that was auto-configured.
You can _also_ create additional caches on another `Bucket` by using the customizer.
Assume you need two caches (`cache1` and `cache2`) on the "main" `Bucket` and one (`cache3`) cache with a custom time to live of 2 seconds on the "`another`" `Bucket`.
You can create the first two caches through configuration, as follows:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.cache.cache-names=cache1,cache2
----
@ -4711,10 +4711,10 @@ This sample configuration reuses the `Cluster` that was created through auto-con
[[boot-features-caching-provider-redis]]
==== Redis
If https://redis.io/[Redis] is available and configured, a `RedisCacheManager` is auto-configured.
It is possible to create additional caches on startup by setting the `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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.cache.cache-names=cache1,cache2
spring.cache.redis.time-to-live=600000
@ -4732,7 +4732,7 @@ This can be useful if you're looking for customizing the serialization strategy.
==== Caffeine
https://github.com/ben-manes/caffeine[Caffeine] is a Java 8 rewrite of Guava's cache that supersedes support for Guava.
If Caffeine is present, a `CaffeineCacheManager` (provided by the `spring-boot-starter-cache` "`Starter`") is auto-configured.
Caches can be created on startup by setting the `spring.cache.cache-names` property and can be customized by one of the following (in the indicated order):
Caches can be created on startup by setting the configprop:spring.cache.cache-names[] property and can be customized by one of the following (in the indicated order):
. A cache spec defined by `spring.cache.caffeine.spec`
. A `com.github.benmanes.caffeine.cache.CaffeineSpec` bean is defined
@ -4740,7 +4740,7 @@ Caches can be created on startup by setting the `spring.cache.cache-names` prope
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]
[source,properties,indent=0,configprops]
----
spring.cache.cache-names=cache1,cache2
spring.cache.caffeine.spec=maximumSize=500,expireAfterAccess=600s
@ -4759,7 +4759,7 @@ 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.
For instance, if you want only `cache1` and `cache2` caches, set the `cache-names` property as follows:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.cache.cache-names=cache1,cache2
----
@ -4774,7 +4774,7 @@ 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.
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]
[source,properties,indent=0,configprops]
----
spring.cache.type=none
----
@ -4810,7 +4810,7 @@ NOTE: If you use `spring-boot-starter-activemq`, the necessary dependencies to c
ActiveMQ configuration is controlled by external configuration properties in `+spring.activemq.*+`.
For example, you might declare the following section in `application.properties`:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.activemq.broker-url=tcp://192.168.1.210:9876
spring.activemq.user=admin
@ -4819,14 +4819,14 @@ For example, you might declare the following section in `application.properties`
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]
[source,properties,indent=0,configprops]
----
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.activemq.pool.enabled=true
spring.activemq.pool.max-connections=50
@ -4852,7 +4852,7 @@ Adding `org.apache.activemq:artemis-jms-server` to your application lets you use
Artemis configuration is controlled by external configuration properties in `+spring.artemis.*+`.
For example, you might declare the following section in `application.properties`:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.artemis.mode=native
spring.artemis.host=192.168.1.210
@ -4866,14 +4866,14 @@ 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.*+`:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.artemis.pool.enabled=true
spring.artemis.pool.max-connections=50
@ -4889,9 +4889,9 @@ No JNDI lookup is involved, and destinations are resolved against their names, u
==== Using a JNDI ConnectionFactory
If you are running your application in an application server, Spring Boot tries to locate a JMS `ConnectionFactory` by using JNDI.
By default, the `java:/JmsXA` and `java:/XAConnectionFactory` location are checked.
You can use the `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]
[source,properties,indent=0,configprops]
----
spring.jms.jndi-name=java:/MyConnectionFactory
----
@ -5014,7 +5014,7 @@ Spring uses `RabbitMQ` to communicate through the AMQP protocol.
RabbitMQ configuration is controlled by external configuration properties in `+spring.rabbitmq.*+`.
For example, you might declare the following section in `application.properties`:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.rabbitmq.host=localhost
spring.rabbitmq.port=5672
@ -5064,7 +5064,7 @@ 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):
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.rabbitmq.template.retry.enabled=true
spring.rabbitmq.template.retry.initial-interval=2s
@ -5078,7 +5078,7 @@ You can also customize the `RetryTemplate` programmatically by declaring a `Rabb
[[boot-features-using-amqp-receiving]]
==== Receiving a Message
When the Rabbit infrastructure is present, any bean can be annotated with `@RabbitListener` to create a listener endpoint.
If no `RabbitListenerContainerFactory` has been defined, a default `SimpleRabbitListenerContainerFactory` is automatically configured and you can switch to a direct container using the `spring.rabbitmq.listener.type` property.
If no `RabbitListenerContainerFactory` has been defined, a default `SimpleRabbitListenerContainerFactory` is automatically configured and you can switch to a direct container using the configprop:spring.rabbitmq.listener.type[] property.
If a `MessageConverter` or a `MessageRecoverer` bean is defined, it is automatically associated with the default factory.
The following sample component creates a listener endpoint on the `someQueue` queue:
@ -5158,7 +5158,7 @@ https://kafka.apache.org/[Apache Kafka] is supported by providing auto-configura
Kafka configuration is controlled by external configuration properties in `spring.kafka.*`.
For example, you might declare the following section in `application.properties`:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.kafka.bootstrap-servers=localhost:9092
spring.kafka.consumer.group-id=myGroup
@ -5192,7 +5192,7 @@ public class MyBean {
}
----
NOTE: If the property `spring.kafka.producer.transaction-id-prefix` is defined, a `KafkaTransactionManager` is automatically configured.
NOTE: If the property configprop:spring.kafka.producer.transaction-id-prefix[] is defined, a `KafkaTransactionManager` is automatically configured.
Also, if a `RecordMessageConverter` bean is defined, it is automatically associated to the auto-configured `KafkaTemplate`.
@ -5247,7 +5247,7 @@ include::{code-examples}/kafka/KafkaStreamsBeanExample.java[tag=configuration]
----
By default, the streams managed by the `StreamBuilder` object it creates are started automatically.
You can customize this behaviour using the `spring.kafka.streams.auto-startup` property.
You can customize this behaviour using the configprop:spring.kafka.streams.auto-startup[] property.
@ -5264,7 +5264,7 @@ 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.
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]
[source,properties,indent=0,configprops]
----
spring.kafka.properties.prop.one=first
spring.kafka.admin.properties.prop.two=second
@ -5277,7 +5277,7 @@ This sets the common `prop.one` Kafka property to `first` (applies to producers,
You can also configure the Spring Kafka `JsonDeserializer` as follows:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.kafka.consumer.value-deserializer=org.springframework.kafka.support.serializer.JsonDeserializer
spring.kafka.consumer.properties.spring.json.value.default.type=com.example.Invoice
@ -5286,7 +5286,7 @@ You can also configure the Spring Kafka `JsonDeserializer` as follows:
Similarly, you can disable the `JsonSerializer` default behavior of sending type information in headers:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.kafka.producer.value-serializer=org.springframework.kafka.support.serializer.JsonSerializer
spring.kafka.producer.properties.spring.json.add.type.headers=false
@ -5305,7 +5305,7 @@ For more information, please see the Spring for Apache Kafka https://docs.spring
To make Spring Boot auto-configuration work with the aforementioned embedded Apache Kafka broker, you need to remap a system property for embedded broker addresses (populated by the `EmbeddedKafkaBroker`) into the Spring Boot configuration property for Apache Kafka.
There are several ways to do that:
* Provide a system property to map embedded broker addresses into `spring.kafka.bootstrap-servers` in the test class:
* Provide a system property to map embedded broker addresses into configprop:spring.kafka.bootstrap-servers[] in the test class:
[source,java,indent=0]
----
@ -5324,7 +5324,7 @@ static {
* Use a placeholder in configuration properties:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.kafka.bootstrap-servers=${spring.embedded.kafka.brokers}
----
@ -5485,7 +5485,7 @@ 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.mail.properties.mail.smtp.connectiontimeout=5000
spring.mail.properties.mail.smtp.timeout=3000
@ -5494,7 +5494,7 @@ In particular, certain default timeout values are infinite, and you may want to
It is also possible to configure a `JavaMailSender` with an existing `Session` from JNDI:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.mail.jndi-name=mail/Session
----
@ -5511,7 +5511,7 @@ JTA transactions are also supported when deploying to a suitable Java EE Applica
When a JTA environment is detected, Spring's `JtaTransactionManager` is used to manage transactions.
Auto-configured JMS, DataSource, and JPA beans are upgraded to support XA transactions.
You can use standard Spring idioms, such as `@Transactional`, to participate in a distributed transaction.
If you are within a JTA environment and still want to use local transactions, you can set the `spring.jta.enabled` property to `false` to disable the JTA auto-configuration.
If you are within a JTA environment and still want to use local transactions, you can set the configprop:spring.jta.enabled[] property to `false` to disable the JTA auto-configuration.
@ -5522,13 +5522,13 @@ You can use the `spring-boot-starter-jta-atomikos` starter to pull in the approp
Spring Boot auto-configures Atomikos and ensures that appropriate `depends-on` settings are applied to your Spring beans for correct startup and shutdown ordering.
By default, Atomikos transaction logs are written to a `transaction-logs` directory in your application's home directory (the directory in which your application jar file resides).
You can customize the location of this directory by setting a `spring.jta.log-dir` property in your `application.properties` file.
You can customize the location of this directory by setting a configprop:spring.jta.log-dir[] property in your `application.properties` file.
Properties starting with `spring.jta.atomikos.properties` can also be used to customize the Atomikos `UserTransactionServiceImp`.
See the {spring-boot-module-api}/jta/atomikos/AtomikosProperties.html[`AtomikosProperties` Javadoc] for complete details.
NOTE: To ensure that multiple transaction managers can safely coordinate the same resource managers, each Atomikos instance must be configured with a unique ID.
By default, this ID is the IP address of the machine on which Atomikos is running.
To ensure uniqueness in production, you should configure the `spring.jta.transaction-manager-id` property with a different value for each instance of your application.
To ensure uniqueness in production, you should configure the configprop:spring.jta.transaction-manager-id[] property with a different value for each instance of your application.
@ -5539,13 +5539,13 @@ You can use the `spring-boot-starter-jta-bitronix` starter to add the appropriat
As with Atomikos, Spring Boot automatically configures Bitronix and post-processes your beans to ensure that startup and shutdown ordering is correct.
By default, Bitronix transaction log files (`part1.btm` and `part2.btm`) are written to a `transaction-logs` directory in your application home directory.
You can customize the location of this directory by setting the `spring.jta.log-dir` property.
You can customize the location of this directory by setting the configprop:spring.jta.log-dir[] property.
Properties starting with `spring.jta.bitronix.properties` are also bound to the `bitronix.tm.Configuration` bean, allowing for complete customization.
See the https://github.com/bitronix/btm/wiki/Transaction-manager-configuration[Bitronix documentation] for details.
NOTE: To ensure that multiple transaction managers can safely coordinate the same resource managers, each Bitronix instance must be configured with a unique ID.
By default, this ID is the IP address of the machine on which Bitronix is running.
To ensure uniqueness in production, you should configure the `spring.jta.transaction-manager-id` property with a different value for each instance of your application.
To ensure uniqueness in production, you should configure the configprop:spring.jta.transaction-manager-id[] property with a different value for each instance of your application.
@ -5554,7 +5554,7 @@ To ensure uniqueness in production, you should configure the `spring.jta.transac
If you package your Spring Boot application as a `war` or `ear` file and deploy it to a Java EE application server, you can use your application server's built-in transaction manager.
Spring Boot tries to auto-configure a transaction manager by looking at common JNDI locations (`java:comp/UserTransaction`, `java:comp/TransactionManager`, and so on).
If you use a transaction service provided by your application server, you generally also want to ensure that all resources are managed by the server and exposed over JNDI.
Spring Boot tries to auto-configure JMS by looking for a `ConnectionFactory` at the JNDI path (`java:/JmsXA` or `java:/XAConnectionFactory`), and you can use the <<boot-features-connecting-to-a-jndi-datasource, `spring.datasource.jndi-name` property>> to configure your `DataSource`.
Spring Boot tries to auto-configure JMS by looking for a `ConnectionFactory` at the JNDI path (`java:/JmsXA` or `java:/XAConnectionFactory`), and you can use the <<boot-features-connecting-to-a-jndi-datasource, configprop:spring.datasource.jndi-name[] property>> to configure your `DataSource`.
@ -5610,7 +5610,7 @@ 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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.hazelcast.config=classpath:config/my-hazelcast.xml
----
@ -5622,7 +5622,7 @@ See the https://docs.hazelcast.org/docs/latest/manual/html-single/[Hazelcast doc
If `hazelcast-client` is present on the classpath, Spring Boot first attempts to create a client by checking the following configuration options:
* The presence of a `com.hazelcast.client.config.ClientConfig` bean.
* A configuration file defined by the `spring.hazelcast.config` property.
* A configuration file defined by the configprop:spring.hazelcast.config[] property.
* The presence of the `hazelcast.client.config` system property.
* A `hazelcast-client.xml` in the working directory or at the root of the classpath.
* A `hazelcast-client.yaml` in the working directory or at the root of the classpath.
@ -5645,29 +5645,29 @@ Beans of the following types are automatically picked up and associated with the
* `Trigger`: defines when a particular job is triggered.
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 `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]
[source,properties,indent=0,configprops]
----
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:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
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.
These scripts drop existing tables, deleting all triggers on every restart.
It is also possible to provide a custom script by setting the `spring.quartz.jdbc.schema` property.
It is also possible to provide a custom script by setting the configprop:spring.quartz.jdbc.schema[] property.
To have Quartz use a `DataSource` other than the application's main `DataSource`, declare a `DataSource` bean, annotating its `@Bean` method with `@QuartzDataSource`.
Doing so ensures that the Quartz-specific `DataSource` is used by both the `SchedulerFactoryBean` and for schema initialization.
By default, jobs created by configuration will not overwrite already registered jobs that have been read from a persistent job store.
To enable overwriting existing job definitions set the `spring.quartz.overwrite-existing-jobs` property.
To enable overwriting existing job definitions set the configprop:spring.quartz.overwrite-existing-jobs[] property.
Quartz Scheduler configuration can be customized using `spring.quartz` properties and `SchedulerFactoryBeanCustomizer` beans, which allow programmatic `SchedulerFactoryBean` customization.
Advanced Quartz configuration properties can be customized using `spring.quartz.properties.*`.
@ -5718,7 +5718,7 @@ 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.
Those default settings can be fine-tuned using the `spring.task.execution` namespace as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.task.execution.pool.max-size=16
spring.task.execution.pool.queue-capacity=100
@ -5745,7 +5745,7 @@ 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-jdbc` is available, the default database schema can be created on startup, as shown in the following line:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.integration.jdbc.initialize-schema=always
----
@ -5776,7 +5776,7 @@ 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.
For instance, to use JDBC as the back-end store, you can configure your application as follows:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.session.store-type=jdbc
----
@ -5786,13 +5786,13 @@ TIP: You can disable Spring Session by setting the `store-type` to `none`.
Each store has specific additional settings.
For instance, it is possible to customize the name of the table for the JDBC store, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.session.jdbc.table-name=SESSIONS
----
For setting the timeout of the session you can use the `spring.session.timeout` property.
If that property is not set, the auto-configuration falls back to the value of `server.servlet.session.timeout`.
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[].
@ -5912,7 +5912,7 @@ If Spring MVC is available, a regular MVC-based application context is configure
If you have only Spring WebFlux, we'll detect that and configure a WebFlux-based application context instead.
If both are present, Spring MVC takes precedence.
If you want to test a reactive web application in this scenario, you must set the `spring.main.web-application-type` property:
If you want to test a reactive web application in this scenario, you must set the configprop:spring.main.web-application-type[] property:
[source,java,indent=0]
----
@ -7070,7 +7070,7 @@ The {spring-webservices-docs}[Spring Web Services features] can be easily access
To do so, configure their location, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.webservices.wsdl-locations=classpath:/wsdl
----

40
spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc
View File

@ -410,7 +410,7 @@ If you find that specific auto-configuration classes that you do not want are be
----
If the class is not on the classpath, you can use the `excludeName` attribute of the annotation and specify the fully qualified name instead.
Finally, you can also control the list of auto-configuration classes to exclude by using the `spring.autoconfigure.exclude` property.
Finally, you can also control the list of auto-configuration classes to exclude by using the configprop:spring.autoconfigure.exclude[] property.
TIP: You can define exclusions both at the annotation level and by using the property.
@ -685,14 +685,14 @@ While caching is very beneficial in production, it can be counter-productive dur
For this reason, spring-boot-devtools disables the caching options by default.
Cache options are usually configured by settings in your `application.properties` file.
For example, Thymeleaf offers the `spring.thymeleaf.cache` property.
For example, Thymeleaf offers the configprop:spring.thymeleaf.cache[] property.
Rather than needing to set these properties manually, the `spring-boot-devtools` module automatically applies sensible development-time configuration.
Because you need more information about web requests while developing Spring MVC and Spring WebFlux applications, developer tools will enable `DEBUG` logging for the `web` logging group.
This will give you information about the incoming request, which handler is processing it, the response outcome, etc.
If you wish to log all request details (including potentially sensitive information), you can turn on the `spring.http.log-request-details` configuration property.
If you wish to log all request details (including potentially sensitive information), you can turn on the configprop:spring.http.log-request-details[] configuration property.
NOTE: If you don't want property defaults to be applied you can set `spring.devtools.add-properties` to `false` in your `application.properties`.
NOTE: If you don't want property defaults to be applied you can set configprop:spring.devtools.add-properties[] to `false` in your `application.properties`.
TIP: For a complete list of the properties that are applied by the devtools, see {spring-boot-devtools-module-code}/env/DevToolsPropertyDefaultsPostProcessor.java[DevToolsPropertyDefaultsPostProcessor].
@ -763,7 +763,7 @@ To disable the logging of the report, set the following property:
Certain resources do not necessarily need to trigger a restart when they are changed.
For example, Thymeleaf templates can be edited in-place.
By default, changing resources in `/META-INF/maven`, `/META-INF/resources`, `/resources`, `/static`, `/public`, or `/templates` does not trigger a restart but does trigger a <<using-boot-devtools-livereload, live reload>>.
If you want to customize these exclusions, you can use the `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:
[indent=0]
@ -771,24 +771,24 @@ For example, to exclude only `/static` and `/public` you would set the following
spring.devtools.restart.exclude=static/**,public/**
----
TIP: If you want to keep those defaults and _add_ additional exclusions, use the `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.
[[using-boot-devtools-restart-additional-paths]]
==== Watching Additional Paths
You may want your application to be restarted or reloaded when you make changes to files that are not on the classpath.
To do so, use the `spring.devtools.restart.additional-paths` property to configure additional paths to watch for changes.
You can use the `spring.devtools.restart.exclude` property <<using-boot-devtools-restart-exclude, described earlier>> to control whether changes beneath the additional paths trigger a full restart or a <<using-boot-devtools-livereload, live reload>>.
To do so, use the configprop:spring.devtools.restart.additional-paths[] property to configure additional paths to watch for changes.
You can use the configprop:spring.devtools.restart.exclude[] property <<using-boot-devtools-restart-exclude, described earlier>> to control whether changes beneath the additional paths trigger a full restart or a <<using-boot-devtools-livereload, live reload>>.
[[using-boot-devtools-restart-disable]]
==== Disabling Restart
If you do not want to use the restart feature, you can disable it by using the `spring.devtools.restart.enabled` property.
If you do not want to use the restart feature, you can disable it by using the configprop:spring.devtools.restart.enabled[] property.
In most cases, you can set this property in your `application.properties` (doing so still initializes the restart classloader, but it does not watch for file changes).
If you need to _completely_ disable restart support (for example, because it does not work with a specific library), you need to set the `spring.devtools.restart.enabled` `System` property to `false` before calling `SpringApplication.run(...)`, as shown in the following example:
If you need to _completely_ disable restart support (for example, because it does not work with a specific library), you need to set the configprop:spring.devtools.restart.enabled[] `System` property to `false` before calling `SpringApplication.run(...)`, as shown in the following example:
[source,java,indent=0]
----
@ -807,7 +807,7 @@ To do so, you can use a "`trigger file`", which is a special file that must be m
NOTE: Any update to the file will trigger a check, but restart only actually occurs if Devtools has detected it has something to do.
To use a trigger file, set the `spring.devtools.restart.trigger-file` property to the name (excluding any path) of your trigger file.
To use a trigger file, set the configprop:spring.devtools.restart.trigger-file[] property to the name (excluding any path) of your trigger file.
The trigger file must appear somewhere on your classpath.
For example, if you have a project with the following structure:
@ -822,7 +822,7 @@ For example, if you have a project with the following structure:
Then your `trigger-file` property would be:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.devtools.restart.trigger-file=.reloadtrigger
----
@ -881,7 +881,7 @@ If you find such a problem, you need to request a fix with the original authors.
The `spring-boot-devtools` module includes an embedded LiveReload server that can be used to trigger a browser refresh when a resource is changed.
LiveReload browser extensions are freely available for Chrome, Firefox and Safari from http://livereload.com/extensions/[livereload.com].
If you do not want to start the LiveReload server when your application runs, you can set the `spring.devtools.livereload.enabled` property to `false`.
If you do not want to start the LiveReload server when your application runs, you can set the configprop:spring.devtools.livereload.enabled[] property to `false`.
NOTE: You can only run one LiveReload server at a time.
Before starting your application, ensure that no other LiveReload servers are running.
@ -901,9 +901,9 @@ Any properties added to these file apply to _all_ Spring Boot applications on yo
For example, to configure restart to always use a <<using-boot-devtools-restart-triggerfile, trigger file>>, you would add the following property:
.~/config/spring-boot/spring-boot-devtools.properties
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.devtools.reload.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` folder is searched for the presence of a `.spring-boot-devtools.properties` file.
@ -935,9 +935,9 @@ To enable it, you need to make sure that `devtools` is included in the repackage
</build>
----
Then you need to set a `spring.devtools.remote.secret` property, as shown in the following example:
Then you need to set a configprop:spring.devtools.remote.secret[] property, as shown in the following example:
[source,properties,indent=0]
[source,properties,indent=0,configprops]
----
spring.devtools.remote.secret=mysecret
----
@ -946,7 +946,7 @@ WARNING: Enabling `spring-boot-devtools` on a remote application is a security r
You should never enable support on a production deployment.
Remote devtools support is provided in two parts: a server-side endpoint that accepts connections and a client application that you run in your IDE.
The server component is automatically enabled when the `spring.devtools.remote.secret` property is set.
The server component is automatically enabled when the configprop:spring.devtools.remote.secret[] property is set.
The client component must be launched manually.
@ -984,7 +984,7 @@ A running remote client might resemble the following listing:
----
NOTE: Because the remote client is using the same classpath as the real application it can directly read application properties.
This is how the `spring.devtools.remote.secret` property is read and passed to the server for authentication.
This is how the configprop:spring.devtools.remote.secret[] property is read and passed to the server for authentication.
TIP: It is always advisable to use `https://` as the connection protocol, so that traffic is encrypted and passwords cannot be intercepted.
@ -1017,7 +1017,7 @@ But it may also lead to application code inconsistency and failure to restart af
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]
[source,properties,indent=0,configprops]
----
spring.devtools.restart.poll-interval=2s
spring.devtools.restart.quiet-period=1s

5
spring-boot-project/spring-boot-parent/pom.xml
View File

@ -26,10 +26,11 @@
<maven.version>3.5.4</maven.version>
<maven-resolver.version>1.1.1</maven-resolver.version>
<spock.version>1.0-groovy-2.4</spock.version>
<testcontainers.version>1.12.2</testcontainers.version>
<testng.version>6.14.3</testng.version>
<spring-asciidoctor-extensions.version>0.3.0.BUILD-SNAPSHOT</spring-asciidoctor-extensions.version>
<spring-doc-resources.version>0.1.3.RELEASE</spring-doc-resources.version>
<spring-doc-resources.url>https://repo.spring.io/release/io/spring/docresources/spring-doc-resources/${spring-doc-resources.version}/spring-doc-resources-${spring-doc-resources.version}.zip</spring-doc-resources.url>
<testcontainers.version>1.12.2</testcontainers.version>
<testng.version>6.14.3</testng.version>
</properties>
<scm>
<url>https://github.com/spring-projects/spring-boot</url>

2
spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/pom.xml
View File

@ -360,7 +360,7 @@
<dependency>
<groupId>io.spring.asciidoctor</groupId>
<artifactId>spring-asciidoctor-extensions</artifactId>
<version>0.2.0.RELEASE</version>
<version>${spring-asciidoctor-extensions.version}</version>
</dependency>
</dependencies>
</plugin>