@ -88,7 +88,8 @@ For example, `server.port` and `server.address` might be specified in `applicati
The "`groups`" are higher level items that do not themselves specify a value but instead provide a contextual grouping for properties.
For example, the `server.port` and `server.address` properties are part of the `server` group.
NOTE: It is not required that every "`property`" has a "`group`". Some properties might exist in their own right.
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.
@ -105,7 +106,8 @@ The JSON object contained in the `groups` array can contain the attributes shown
| `name`
| String
| The full name of the group. This attribute is mandatory.
| The full name of the group.
This attribute is mandatory.
| `type`
| String
@ -315,7 +317,8 @@ The JSON object contained in the `providers` attribute of each `hint` element ca
[[configuration-metadata-repeated-items]]
==== Repeated Metadata Items
Objects with the same "`property`" and "`group`" name can appear multiple times within a metadata file. For example, you could bind two separate classes to the same prefix, with each having potentially overlapping property names.
Objects with the same "`property`" and "`group`" name can appear multiple times within a metadata file.
For example, you could bind two separate classes to the same prefix, with each having potentially overlapping property names.
While the same names appearing in the metadata multiple times should not be common, consumers of metadata should take care to ensure that they support it.
Spring Boot provides build tool plugins for Maven and Gradle. The plugins offer a variety of features, including the packaging of executable jars.
Spring Boot provides build tool plugins for Maven and Gradle.
The plugins offer a variety of features, including the packaging of executable jars.
This section provides more details on both plugins as well as some help should you need to extend an unsupported build system.
If you are just getting started, you might want to read "`<<using-spring-boot.adoc#using-boot-build-systems>>`" from the "`<<using-spring-boot.adoc#using-boot>>`" section first.
@ -402,7 +402,8 @@ A fully executable jar can be executed like any other executable binary or it ca
This makes it very easy to install and manage Spring Boot applications in common production environments.
CAUTION: Fully executable jars work by embedding an extra script at the front of the file.
Currently, some tools do not accept this format, so you may not always be able to use this technique. For example, `jar -xf` may silently fail to extract a jar or war that has been made fully executable.
Currently, some tools do not accept this format, so you may not always be able to use this technique.
For example, `jar -xf` may silently fail to extract a jar or war that has been made fully executable.
It is recommended that you make your jar or war fully executable only if you intend to execute it directly, rather than running it with `java -jar`or deploying it to a servlet container.
To create a '`fully executable`' jar with Maven, use the following plugin configuration:
@ -522,7 +523,8 @@ One way to protect against this is to make it immutable by using `chattr`, as sh
This will prevent any user, including root, from modifying the jar.
If root is used to control the application's service and you <<deployment-script-customization-conf-file, use a `.conf` file>> to customize its startup, the `.conf` file is read and evaluated by the root user.
It should be secured accordingly. Use `chmod` so that the file can only be read by the owner and use `chown` to make root the owner, as shown in the following example:
It should be secured accordingly.
Use `chmod` so that the file can only be read by the owner and use `chown` to make root the owner, as shown in the following example:
[indent=0,subs="verbatim,quotes,attributes"]
----
@ -652,17 +654,20 @@ The following property substitutions are supported with the default script:
|
| `logFolder`
| Default value for `LOG_FOLDER`. Only valid for an `init.d` service
| Default value for `LOG_FOLDER`.
Only valid for an `init.d` service
|
|
| `logFilename`
| Default value for `LOG_FILENAME`. Only valid for an `init.d` service
| Default value for `LOG_FILENAME`.
Only valid for an `init.d` service
|
|
| `pidFolder`
| Default value for `PID_FOLDER`. Only valid for an `init.d` service
| Default value for `PID_FOLDER`.
Only valid for an `init.d` service
|
|
@ -678,7 +683,8 @@ The following property substitutions are supported with the default script:
| `true`
| `stopWaitTime`
| Default value for `STOP_WAIT_TIME` in seconds. Only valid for an `init.d` service
| Default value for `STOP_WAIT_TIME` in seconds.
Only valid for an `init.d` service
| 60
| 60
|===
@ -740,7 +746,8 @@ The following environment properties are supported with the default script:
| The time in seconds to wait when stopping the application before forcing a shutdown (`60` by default).
|===
NOTE: The `PID_FOLDER`, `LOG_FOLDER`, and `LOG_FILENAME` variables are only valid for an `init.d` service. For `systemd`, the equivalent customizations are made by using the '`service`' script.
NOTE: The `PID_FOLDER`, `LOG_FOLDER`, and `LOG_FILENAME` variables are only valid for an `init.d` service.
For `systemd`, the equivalent customizations are made by using the '`service`' script.
See the https://www.freedesktop.org/software/systemd/man/systemd.service.html[service unit configuration man page] for more details.
The `${..}` style conflicts with Spring's own property placeholder mechanism.
To use Spring property placeholders together with automatic expansion, escape the Spring property placeholders as follows: `\${..}`.
@ -648,7 +649,8 @@ Generally, you should first consider using one of the many available configurati
The `server.{asterisk}` namespace is quite useful here, and it includes namespaces like `server.tomcat.{asterisk}`, `server.jetty.{asterisk}` and others, for server-specific features.
See the list of <<common-application-properties>>.
The previous sections covered already many common use cases, such as compression, SSL or HTTP/2. However, if a configuration key doesn't exist for your use case, you should then look at {spring-boot-module-api}/web/server/WebServerFactoryCustomizer.html[`WebServerFactoryCustomizer`].
The previous sections covered already many common use cases, such as compression, SSL or HTTP/2.
However, if a configuration key doesn't exist for your use case, you should then look at {spring-boot-module-api}/web/server/WebServerFactoryCustomizer.html[`WebServerFactoryCustomizer`].
You can declare such a component and get access to the server factory relevant to your choice: you should select the variant for the chosen Server (Tomcat, Jetty, Reactor Netty, Undertow) and the chosen web stack (Servlet or Reactive).
The example below is for Tomcat with the `spring-boot-starter-web` (Servlet stack):
@ -1147,7 +1149,8 @@ If you add your own, you have to be aware of the order and in which position you
There is a useful https://spring.io/blog/2013/06/03/content-negotiation-using-views[blog about `ContentNegotiatingViewResolver`] that you might like to study to learn more, and you might also look at the source code for detail.
You can switch off the auto-configured `ContentNegotiatingViewResolver` by defining a bean named '`viewResolver`'.
* If you use Thymeleaf, you also have a `ThymeleafViewResolver` named '`thymeleafViewResolver`'.
It looks for resources by surrounding the view name with a prefix and suffix. The prefix is `spring.thymeleaf.prefix`, and the suffix is `spring.thymeleaf.suffix`.
It looks for resources by surrounding the view name with a prefix and suffix.
The prefix is `spring.thymeleaf.prefix`, and the suffix is `spring.thymeleaf.suffix`.
The values of the prefix and suffix default to '`classpath:/templates/`' and '`.html`', respectively.
You can override `ThymeleafViewResolver` by providing a bean of the same name.
* If you use FreeMarker, you also have a `FreeMarkerViewResolver` named '`freeMarkerViewResolver`'.
@ -1495,7 +1498,8 @@ The following example shows how to define a JDBC data source by setting properti
However, there is a catch.
Because the actual type of the connection pool is not exposed, no keys are generated in the metadata for your custom `DataSource` and no completion is available in your IDE (because the `DataSource` interface exposes no properties).
Also, if you happen to have Hikari on the classpath, this basic setup does not work, because Hikari has no `url` property (but does have a `jdbcUrl` property). In that case, you must rewrite your configuration as follows:
Also, if you happen to have Hikari on the classpath, this basic setup does not work, because Hikari has no `url` property (but does have a `jdbcUrl` property).
In that case, you must rewrite your configuration as follows:
[source,properties,indent=0]
----
@ -1551,7 +1555,8 @@ See "`<<spring-boot-features.adoc#boot-features-configure-datasource>>`" in the
If you need to configure multiple data sources, you can apply the same tricks that are described in the previous section.
You must, however, mark one of the `DataSource` instances as `@Primary`, because various auto-configurations down the road expect to be able to get one by type.
If you create your own `DataSource`, the auto-configuration backs off. In the following example, we provide the _exact_ same feature set as the auto-configuration provides on the primary data source:
If you create your own `DataSource`, the auto-configuration backs off.
In the following example, we provide the _exact_ same feature set as the auto-configuration provides on the primary data source:
TIP: `firstDataSourceProperties` has to be flagged as `@Primary` so that the database initializer feature uses your copy (if you use the initializer).
Both data sources are also bound for advanced customizations. For instance, you could configure them as follows:
Both data sources are also bound for advanced customizations.
For instance, you could configure them as follows:
[source,properties,indent=0]
----
@ -1699,7 +1705,8 @@ See {spring-boot-autoconfigure-module-code}/orm/jpa/HibernateJpaAutoConfiguratio
Hibernate {hibernate-docs}#caching[second-level cache] can be configured for a range of cache providers.
Rather than configuring Hibernate to lookup the cache provider again, it is better to provide the one that is available in the context whenever possible.
If you're using JCache, this is pretty easy. First, make sure that `org.hibernate:hibernate-jcache` is available on the classpath.
If you're using JCache, this is pretty easy.
First, make sure that `org.hibernate:hibernate-jcache` is available on the classpath.
Then, add a `HibernatePropertiesCustomizer` bean as shown in the following example:
[source,java,indent=0]
@ -1879,7 +1886,8 @@ This is controlled through two external properties:
You can set `spring.jpa.hibernate.ddl-auto` explicitly and the standard Hibernate property values are `none`, `validate`, `update`, `create`, and `create-drop`.
Spring Boot chooses a default value for you based on whether it thinks your database is embedded.
It defaults to `create-drop` if no schema manager has been detected or `none` in all other cases.
An embedded database is detected by looking at the `Connection` type. `hsqldb`, `h2`, and `derby` are embedded, and others are not.
An embedded database is detected by looking at the `Connection` type.
`hsqldb`, `h2`, and `derby` are embedded, and others are not.
Be careful when switching from in-memory to a '`real`' database that you do not make assumptions about the existence of the tables and data in the new platform.
You either have to set `ddl-auto` explicitly or use one of the other mechanisms to initialize the database.
@ -2090,7 +2098,8 @@ See {spring-boot-autoconfigure-module-code}/batch/BatchAutoConfiguration.java[Ba
[[howto-actuator]]
== Actuator
Spring Boot includes the Spring Boot Actuator. This section answers questions that often arise from its use.
Spring Boot includes the Spring Boot Actuator.
This section answers questions that often arise from its use.
@ -2169,7 +2178,8 @@ You can switch on the valve by adding some entries to `application.properties`,
server.tomcat.protocol-header=x-forwarded-proto
----
(The presence of either of those properties switches on the valve. Alternatively, you can add the `RemoteIpValve` by adding a `TomcatServletWebServerFactory` bean.)
(The presence of either of those properties switches on the valve.
Alternatively, you can add the `RemoteIpValve` by adding a `TomcatServletWebServerFactory` bean.)
To configure Spring Security to require a secure channel for all (or some) requests, consider adding your own `WebSecurityConfigurerAdapter` that adds the following `HttpSecurity` configuration:
@ -2191,7 +2201,8 @@ To configure Spring Security to require a secure channel for all (or some) reque
[[howto-hotswapping]]
== Hot Swapping
Spring Boot supports hot swapping. This section answers questions about how it works.
Spring Boot supports hot swapping.
This section answers questions about how it works.
@ -2760,7 +2771,8 @@ See the <<howto-build-an-application-context-hierarchy, entry on building a hier
An existing parent context that contains web-specific features usually needs to be broken up so that all the `ServletContextAware` components are in the child context.
Applications that are not already Spring applications might be convertible to Spring Boot applications, and the previously mentioned guidance may help.
However, you may yet encounter problems. In that case, we suggest https://stackoverflow.com/questions/tagged/spring-boot[asking questions on Stack Overflow with a tag of `spring-boot`].
However, you may yet encounter problems.
In that case, we suggest https://stackoverflow.com/questions/tagged/spring-boot[asking questions on Stack Overflow with a tag of `spring-boot`].
`*` can be used to select all endpoints. For example, to expose everything over HTTP except the `env` and `beans` endpoints, use the following properties:
`*` 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]
----
@ -429,7 +430,8 @@ NOTE: When making an authenticated HTTP request, the `Principal` is considered a
[[production-ready-endpoints-hypermedia]]
=== Hypermedia for Actuator Web Endpoints
A "`discovery page`" is added with links to all the endpoints. The "`discovery page`" is available on `/actuator` by default.
A "`discovery page`" is added with links to all the endpoints.
The "`discovery page`" is available on `/actuator` by default.
When a custom management context path is configured, the "`discovery page`" automatically moves from `/actuator` to the root of the management context.
For example, if the management context path is `/management`, then the discovery page is available from `/management`.
@ -640,7 +642,8 @@ The information exposed by the `health` endpoint depends on the `management.endp
| Details are shown to all users.
|===
The default value is `never`. A user is considered to be authorized when they are in one or more of the endpoint's roles.
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.
@ -749,7 +752,8 @@ To configure the severity order, add the following property to your application
----
The HTTP status code in the response reflects the overall health status (for example, `UP` maps to 200, while `OUT_OF_SERVICE` and `DOWN` map to 503).
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):
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]
----
@ -1660,7 +1664,8 @@ By default, Spring MVC-related metrics are tagged with the following information
| Request's method (for example, `GET` or `POST`)
| `outcome`
| Request's outcome based on the status code of the response. 1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`
| Request's outcome based on the status code of the response.
1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`
| `status`
| Response's HTTP status code (for example, `200` or `500`)
@ -1692,7 +1697,8 @@ By default, WebFlux-related metrics are tagged with the following information:
| Request's method (for example, `GET` or `POST`)
| `outcome`
| Request's outcome based on the status code of the response. 1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`
| Request's outcome based on the status code of the response.
1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`
| `status`
| Response's HTTP status code (for example, `200` or `500`)
@ -1744,7 +1750,8 @@ By default, Jersey server metrics are tagged with the following information:
| Request's method (for example, `GET` or `POST`)
| `outcome`
| Request's outcome based on the status code of the response. 1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`
| Request's outcome based on the status code of the response.
1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`
| `status`
| Response's HTTP status code (for example, `200` or `500`)
@ -2054,7 +2061,8 @@ If the server's context-path has been configured to anything other than `/`, the
For example, if `server.servlet.context-path=/app`, Cloud Foundry endpoints will be available at `/app/cloudfoundryapplication/*`.
If you expect the Cloud Foundry endpoints to always be available at `/cloudfoundryapplication/*`, regardless of the server's context-path, you will need to explicitly configure that in your application.
The configuration will differ depending on the web server in use. For Tomcat, the following configuration can be added:
The configuration will differ depending on the web server in use.
For Tomcat, the following configuration can be added:
@ -171,7 +171,8 @@ TIP: See subclasses of {spring-boot-cli-module-code}/compiler/CompilerAutoConfig
Spring Boot extends Groovy's standard `@Grab` support by letting you specify a dependency without a group or version (for example, `@Grab('freemarker')`).
Doing so consults Spring Boot's default dependency metadata to deduce the artifact's group and version.
NOTE: The default metadata is tied to the version of the CLI that you use. it changes only when you move to a new version of the CLI, putting you in control of when the versions of your dependencies may change.
NOTE: The default metadata is tied to the version of the CLI that you use.
It changes only when you move to a new version of the CLI, putting you in control of when the versions of your dependencies may change.
A table showing the dependencies and their versions that are included in the default metadata can be found in the <<appendix-dependency-versions, appendix>>.
@ -361,7 +362,8 @@ The command takes one or more sets of artifact coordinates in the format `group:
In addition to installing the artifacts identified by the coordinates you supply, all of the artifacts' dependencies are also installed.
To uninstall a dependency, use the `uninstall` command. As with the `install` command, it takes one or more sets of artifact coordinates in the format of `group:artifact:version`, as shown in the following example:
To uninstall a dependency, use the `uninstall` command.
As with the `install` command, it takes one or more sets of artifact coordinates in the format of `group:artifact:version`, as shown in the following example:
@ -97,10 +97,12 @@ Inside your `banner.txt` file, you can use any of the following placeholders:
For example, `Implementation-Version: 1.0` is printed as `1.0`.
| `${application.formatted-version}`
| The version number of your application, as declared in `MANIFEST.MF` and formatted for display (surrounded with brackets and prefixed with `v`). For example `(v1.0)`.
| The version number of your application, as declared in `MANIFEST.MF` and formatted for display (surrounded with brackets and prefixed with `v`).
For example `(v1.0)`.
| `${spring-boot.version}`
| The Spring Boot version that you are using. For example `{spring-boot-version}`.
| The Spring Boot version that you are using.
For example `{spring-boot-version}`.
| `${spring-boot.formatted-version}`
| The Spring Boot version that you are using, formatted for display (surrounded with brackets and prefixed with `v`).
@ -504,7 +506,8 @@ NOTE: If your application runs in a container, then JNDI properties (in `java:co
In addition to `application.properties` files, profile-specific properties can also be defined by using the following naming convention: `application-\{profile}.properties`.
The `Environment` has a set of default profiles (by default, `[default]`) that are used if no active profiles are set. In other words, if no profiles are explicitly activated, then properties from `application-default.properties` are loaded.
The `Environment` has a set of default profiles (by default, `[default]`) that are used if no active profiles are set.
In other words, if no profiles are explicitly activated, then properties from `application-default.properties` are loaded.
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.
@ -971,7 +974,8 @@ NOTE: The `prefix` value for the annotation _must_ be in kebab case (lowercase a
| Standard YAML list syntax or comma-separated values
| Environment Variables
| Upper case format with underscore as the delimiter. `_` should not be used within a property name
| Upper case format with underscore as the delimiter.
`_` should not be used within a property name
| Numeric values surrounded by underscores, such as `MY_ACME_1_OTHER = my.acme[1].other`
To specify a buffer size of 10 megabytes, `10` and `10MB` are equivalent.
A size threshold of 256 bytes can be specified as `256` or `256B`.
You can also use any of the supported units. These are:
You can also use any of the supported units.
These are:
* `B` for bytes
* `KB` for kilobytes
@ -1357,9 +1363,11 @@ Spring Boot uses https://commons.apache.org/logging[Commons Logging] for all int
Default configurations are provided for {java-api}/java/util/logging/package-summary.html[Java Util Logging], https://logging.apache.org/log4j/2.x/[Log4J2], and https://logback.qos.ch/[Logback].
In each case, loggers are pre-configured to use console output with optional file output also available.
By default, if you use the "`Starters`", Logback is used for logging. Appropriate Logback routing is also included to ensure that dependent libraries that use Java Util Logging, Commons Logging, Log4J, or SLF4J all work correctly.
By default, if you use the "`Starters`", Logback is used for logging.
Appropriate Logback routing is also included to ensure that dependent libraries that use Java Util Logging, Commons Logging, Log4J, or SLF4J all work correctly.
TIP: There are a lot of logging frameworks available for Java. Do not worry if the above list seems confusing.
TIP: There are a lot of logging frameworks available for Java.
Do not worry if the above list seems confusing.
Generally, you do not need to change your logging dependencies and the Spring Boot defaults work just fine.
@ -1387,7 +1395,8 @@ The following items are output:
* Logger name: This is usually the source class name (often abbreviated).
* The log message.
NOTE: Logback does not have a `FATAL` level. It is mapped to `ERROR`.
NOTE: Logback does not have a `FATAL` level.
It is mapped to `ERROR`.
@ -1881,7 +1890,8 @@ If you want to take complete control of Spring MVC, you can add your own `@Confi
[[boot-features-spring-mvc-message-converters]]
==== HttpMessageConverters
Spring MVC uses the `HttpMessageConverter` interface to convert HTTP requests and responses.
Sensible defaults are included out of the box. For example, objects can be automatically converted to JSON (by using the Jackson library) or XML (by using the Jackson XML extension, if available, or by using JAXB if the Jackson XML extension is not available).
Sensible defaults are included out of the box.
For example, objects can be automatically converted to JSON (by using the Jackson library) or XML (by using the Jackson XML extension, if available, or by using JAXB if the Jackson XML extension is not available).
By default, strings are encoded in `UTF-8`.
If you need to add or customize converters, you can use Spring Boot's `HttpMessageConverters` class, as shown in the following listing:
@ -1982,7 +1992,8 @@ Although this directory is a common standard, it works *only* with war packaging
Spring Boot also supports the advanced resource handling features provided by Spring MVC, allowing use cases such as cache-busting static resources or using version agnostic URLs for Webjars.
To use version agnostic URLs for Webjars, add the `webjars-locator-core` dependency.
Then declare your Webjar. Using jQuery as an example, adding `"/webjars/jquery/jquery.min.js"` results in `"/webjars/jquery/x.y.z/jquery.min.js"` where `x.y.z` is the Webjar version.
Then declare your Webjar.
Using jQuery as an example, adding `"/webjars/jquery/jquery.min.js"` results in `"/webjars/jquery/x.y.z/jquery.min.js"` where `x.y.z` is the Webjar version.
NOTE: If you use JBoss, you need to declare the `webjars-locator-jboss-vfs` dependency instead of the `webjars-locator-core`.
Otherwise, all Webjars resolve as a `404`.
@ -2000,7 +2011,8 @@ You should manually declare this filter when using JSPs.
Other template engines are currently not automatically supported but can be with custom template macros/helpers and the use of the {spring-framework-api}/web/servlet/resource/ResourceUrlProvider.html[`ResourceUrlProvider`].
When loading resources dynamically with, for example, a JavaScript module loader, renaming files is not an option.
That is why other strategies are also supported and can be combined. A "fixed" strategy adds a static version string in the URL without changing the file name, as shown in the following example:
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:
@ -2022,7 +2034,8 @@ This feature has been thoroughly described in a dedicated https://spring.io/blog
[[boot-features-spring-mvc-welcome-page]]
==== Welcome Page
Spring Boot supports both static and templated welcome pages. It first looks for an `index.html` file in the configured static content locations.
Spring Boot supports both static and templated welcome pages.
It first looks for an `index.html` file in the configured static content locations.
If one is not found, it then looks for an `index` template.
If either is found, it is automatically used as the welcome page of the application.
@ -2435,7 +2448,8 @@ For instance, relocating all resources to `/resources/**` can be achieved as fol
----
You can also customize the static resource locations by using `spring.resources.static-locations`.
Doing so replaces the default values with a list of directory locations. If you do so, the default welcome page detection switches to your custom locations.
Doing so replaces the default values with a list of directory locations.
If you do so, the default welcome page detection switches to your custom locations.
So, if there is an `index.html` in any of your locations on startup, it is the home page of the application.
In addition to the "`standard`" static resource locations listed earlier, a special case is made for https://www.webjars.org/[Webjars content].
@ -2601,7 +2615,8 @@ All the registered endpoints should be `@Components` with HTTP resource annotati
----
Since the `Endpoint` is a Spring `@Component`, its lifecycle is managed by Spring and you can use the `@Autowired` annotation to inject dependencies and use the `@Value` annotation to inject external configuration.
By default, the Jersey servlet is registered and mapped to `/*`. You can change the mapping by adding `@ApplicationPath` to your `ResourceConfig`.
By default, the Jersey servlet is registered and mapped to `/*`.
You can change the mapping by adding `@ApplicationPath` to your `ResourceConfig`.
By default, Jersey is set up as a Servlet in a `@Bean` of type `ServletRegistrationBean` named `jerseyServletRegistration`.
By default, the servlet is initialized lazily, but you can customize that behavior by setting `spring.jersey.servlet.load-on-startup`.
@ -2814,7 +2829,8 @@ Spring Boot relies on Spring Security’s content-negotiation strategy to determ
To add method-level security to a web application, you can also add `@EnableGlobalMethodSecurity` with your desired settings.
Additional information can be found in the {spring-security-docs}#jc-method[Spring Security Reference Guide].
The default `UserDetailsService` has a single user. The user name is `user`, and the password is random and is printed at INFO level when the application starts, as shown in the following example:
The default `UserDetailsService` has a single user.
The user name is `user`, and the password is random and is printed at INFO level when the application starts, as shown in the following example:
[indent=0]
----
@ -2855,7 +2871,8 @@ Spring Boot provides convenience methods that can be used to override access rul
[[boot-features-security-webflux]]
=== WebFlux Security
Similar to Spring MVC applications, you can secure your WebFlux applications by adding the `spring-boot-starter-security` dependency.
The default security configuration is implemented in `ReactiveSecurityAutoConfiguration` and `UserDetailsServiceAutoConfiguration`. `ReactiveSecurityAutoConfiguration` imports `WebFluxSecurityConfiguration` for web security and `UserDetailsServiceAutoConfiguration` configures authentication, which is also relevant in non-web applications.
The default security configuration is implemented in `ReactiveSecurityAutoConfiguration` and `UserDetailsServiceAutoConfiguration`.
`ReactiveSecurityAutoConfiguration` imports `WebFluxSecurityConfiguration` for web security and `UserDetailsServiceAutoConfiguration` configures authentication, which is also relevant in non-web applications.
To switch off the default web application security configuration completely, you can add a bean of type `WebFilterChainProxy` (doing so does not disable the `UserDetailsService` configuration or Actuator's security).
To also switch off the `UserDetailsService` configuration, you can add a bean of type `ReactiveUserDetailsService` or `ReactiveAuthenticationManager`.
@ -3047,7 +3064,8 @@ You need to populate your database when your application starts and be prepared
TIP: The "`How-to`" section includes a <<howto.adoc#howto-database-initialization, section on how to initialize a database>>.
Spring Boot can auto-configure embedded https://www.h2database.com[H2], http://hsqldb.org/[HSQL], and https://db.apache.org/derby/[Derby] databases.
You need not provide any connection URLs. You need only include a build dependency to the embedded database that you want to use.
You need not provide any connection URLs.
You need only include a build dependency to the embedded database that you want to use.
[NOTE]
====
@ -3192,7 +3210,8 @@ If more than one `JdbcTemplate` is defined and no primary candidate exists, the
[[boot-features-jpa-and-spring-data]]
=== JPA and Spring Data JPA
The Java Persistence API is a standard technology that lets you "`map`" objects to relational databases.
The `spring-boot-starter-data-jpa` POM provides a quick way to get started. It provides the following key dependencies:
The `spring-boot-starter-data-jpa` POM provides a quick way to get started.
It provides the following key dependencies:
* Hibernate: One of the most popular JPA implementations.
* Spring Data JPA: Makes it easy to implement JPA-based repositories.
@ -3365,7 +3384,8 @@ 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.
By default, the console is available at `/h2-console`.
You can customize the console's path by using the `spring.h2.console.path` property.
@ -3380,7 +3400,8 @@ Both the commercial and open source editions can be used with Spring Boot.
In order to use jOOQ type-safe queries, you need to generate Java classes from your database schema.
You can follow the instructions in the {jooq-docs}/#jooq-in-7-steps-step3[jOOQ user manual].
If you use the `jooq-codegen-maven` plugin and you also use the `spring-boot-starter-parent` "`parent POM`", you can safely omit the plugin's `<version>` tag.
You can also use Spring Boot-defined version variables (such as `h2.version`) to declare the plugin's database dependency. The following listing shows an example:
You can also use Spring Boot-defined version variables (such as `h2.version`) to declare the plugin's database dependency.
The following listing shows an example:
[source,xml,indent=0]
----
@ -3946,7 +3967,8 @@ There is a `spring-boot-starter-data-cassandra` "`Starter`" for collecting the d
[[boot-features-connecting-to-cassandra]]
==== Connecting to Cassandra
You can inject an auto-configured `CassandraTemplate` or a Cassandra `Session` instance as you would with any other Spring Bean.
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:
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]
----
@ -4376,7 +4398,8 @@ See https://github.com/infinispan/infinispan-spring-boot[Infinispan's documentat
==== 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.
These caches operate on the `Bucket` that was auto-configured. You can _also_ create additional caches on another `Bucket` by using the customizer.
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:
@ -4556,7 +4579,8 @@ If the broker is present, an embedded broker is automatically started and config
The supported modes are `embedded` (to make explicit that an embedded broker is required and that an error should occur if the broker is not available on the classpath) and `native` (to connect to a broker using the `netty` transport protocol).
When the latter is configured, Spring Boot configures a `ConnectionFactory` that connects to a broker running on the local machine with the default settings.
NOTE: If you use `spring-boot-starter-artemis`, the necessary dependencies to connect to an existing Artemis instance are provided, as well as the Spring infrastructure to integrate with JMS. Adding `org.apache.activemq:artemis-jms-server` to your application lets you use embedded mode.
NOTE: If you use `spring-boot-starter-artemis`, the necessary dependencies to connect to an existing Artemis instance are provided, as well as the Spring infrastructure to integrate with JMS.
Adding `org.apache.activemq:artemis-jms-server` to your application lets you use embedded mode.
Artemis configuration is controlled by external configuration properties in `+spring.artemis.*+`.
For example, you might declare the following section in `application.properties`:
@ -4596,7 +4620,8 @@ No JNDI lookup is involved, and destinations are resolved against their names, u
[[boot-features-jms-jndi]]
==== 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.
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:
[source,properties,indent=0]
@ -4808,7 +4833,8 @@ TIP: See {spring-amqp-api}/rabbit/annotation/EnableRabbit.html[the Javadoc of `@
If you need to create more `RabbitListenerContainerFactory` instances or if you want to override the default, Spring Boot provides a `SimpleRabbitListenerContainerFactoryConfigurer` and a `DirectRabbitListenerContainerFactoryConfigurer` that you can use to initialize a `SimpleRabbitListenerContainerFactory` and a `DirectRabbitListenerContainerFactory` with the same settings as the factories used by the auto-configuration.
TIP: It does not matter which container type you chose. Those two beans are exposed by the auto-configuration.
TIP: It does not matter which container type you chose.
Those two beans are exposed by the auto-configuration.
For instance, the following configuration class exposes another factory that uses a specific `MessageConverter`:
@ -4849,7 +4875,8 @@ Then you can use the factory in any `@RabbitListener`-annotated method, as follo
You can enable retries to handle situations where your listener throws an exception.
By default, `RejectAndDontRequeueRecoverer` is used, but you can define a `MessageRecoverer` of your own.
When retries are exhausted, the message is rejected and either dropped or routed to a dead-letter exchange if the broker is configured to do so.
By default, retries are disabled. You can also customize the `RetryTemplate` programmatically by declaring a `RabbitRetryTemplateCustomizer` bean.
By default, retries are disabled.
You can also customize the `RetryTemplate` programmatically by declaring a `RabbitRetryTemplateCustomizer` bean.
IMPORTANT: By default, if retries are disabled and the listener throws an exception, the delivery is retried indefinitely.
You can modify this behavior in two ways: Set the `defaultRequeueRejected` property to `false` so that zero re-deliveries are attempted or throw an `AmqpRejectAndDontRequeueException` to signal the message should be rejected.
@ -5194,7 +5221,8 @@ You can customize the location of this directory by setting a `spring.jta.log-di
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.
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.
@ -5302,7 +5330,8 @@ If Quartz is available, a `Scheduler` is auto-configured (through the `Scheduler
Beans of the following types are automatically picked up and associated with the `Scheduler`:
* `JobDetail`: defines a particular Job. `JobDetail` instances can be built with the `JobBuilder` API.
* `JobDetail`: defines a particular Job.
`JobDetail` instances can be built with the `JobBuilder` API.
* `Calendar`.
* `Trigger`: defines when a particular job is triggered.
@ -6054,7 +6083,8 @@ If that is not what you want, you can disable transaction management for a test
Data JPA tests may also inject a {spring-boot-test-autoconfigure-module-code}/orm/jpa/TestEntityManager.java[`TestEntityManager`] bean, which provides an alternative to the standard JPA `EntityManager` that is specifically designed for tests.
If you want to use `TestEntityManager` outside of `@DataJpaTest` instances, you can also use the `@AutoConfigureTestEntityManager` annotation.
A `JdbcTemplate` is also available if you need that. The following example shows the `@DataJpaTest` annotation in use:
A `JdbcTemplate` is also available if you need that.
The following example shows the `@DataJpaTest` annotation in use:
[source,java,indent=0]
----
@ -7166,7 +7196,8 @@ Feel free to join the #spring channel of https://slack.kotlinlang.org/[Kotlin Sl
[[boot-features-kotlin-requirements]]
=== Requirements
Spring Boot supports Kotlin 1.2.x. To use Kotlin, `org.jetbrains.kotlin:kotlin-stdlib` and `org.jetbrains.kotlin:kotlin-reflect` must be present on the classpath.
Spring Boot supports Kotlin 1.2.x.
To use Kotlin, `org.jetbrains.kotlin:kotlin-stdlib` and `org.jetbrains.kotlin:kotlin-reflect` must be present on the classpath.
The `kotlin-stdlib` variants `kotlin-stdlib-jdk7` and `kotlin-stdlib-jdk8` can also be used.
Since https://discuss.kotlinlang.org/t/classes-final-by-default/166[Kotlin classes are final by default], you are likely to want to configure {kotlin-docs}compiler-plugins.html#spring-support[kotlin-spring] plugin in order to automatically open Spring-annotated classes so that they can be proxied.
@ -32,7 +32,8 @@ NOTE: You can still specify a version and override Spring Boot's recommendations
The curated list contains all the spring modules that you can use with Spring Boot as well as a refined list of third party libraries.
The list is available as a standard <<using-boot-maven-without-a-parent,Bills of Materials (`spring-boot-dependencies`)>> that can be used with both <<using-boot-maven-parent-pom,Maven>> and <<using-boot-gradle,Gradle>>.
WARNING: Each release of Spring Boot is associated with a base version of the Spring Framework. We **highly** recommend that you not specify its version.
WARNING: Each release of Spring Boot is associated with a base version of the Spring Framework.
We **highly** recommend that you not specify its version.
@ -277,7 +278,8 @@ TIP: For a list of additional community contributed starters, see the {spring-bo
[[using-boot-structuring-your-code]]
== Structuring Your Code
Spring Boot does not require any specific code layout to work. However, there are some best practices that help.
Spring Boot does not require any specific code layout to work.
However, there are some best practices that help.
@ -295,7 +297,8 @@ TIP: We recommend that you follow Java's recommended package naming conventions
=== Locating the Main Application Class
We generally recommend that you locate your main application class in a root package above other classes.
The <<using-boot-using-springbootapplication-annotation, `@SpringBootApplication` annotation>> is often placed on your main class, and it implicitly defines a base "`search package`" for certain items.
For example, if you are writing a JPA application, the package of the `@SpringBootApplication` annotated class is used to search for `@Entity` items. Using a root package also allows component scan to apply only on your project.
For example, if you are writing a JPA application, the package of the `@SpringBootApplication` annotated class is used to search for `@Entity` items.
Using a root package also allows component scan to apply only on your project.
TIP: If you don't want to use `@SpringBootApplication`, the `@EnableAutoConfiguration` and `@ComponentScan` annotations that it imports defines that behavior so you can also use that instead.
@ -536,9 +539,11 @@ In this example, `Application` is just like any other Spring Boot application ex
[[using-boot-running-your-application]]
== Running Your Application
One of the biggest advantages of packaging your application as a jar and using an embedded HTTP server is that you can run your application as you would any other.
Debugging Spring Boot applications is also easy. You do not need any special IDE plugins or extensions.
Debugging Spring Boot applications is also easy.
You do not need any special IDE plugins or extensions.
NOTE: This section only covers jar based packaging. If you choose to package your application as a war file, you should refer to your server and IDE documentation.
NOTE: This section only covers jar based packaging.
If you choose to package your application as a war file, you should refer to your server and IDE documentation.
@ -550,10 +555,12 @@ Import steps vary depending on your IDE and build system.
Most IDEs can import Maven projects directly.
For example, Eclipse users can select `Import...` -> `Existing Maven Projects` from the `File` menu.
If you cannot directly import your project into your IDE, you may be able to generate IDE metadata by using a build plugin. Maven includes plugins for https://maven.apache.org/plugins/maven-eclipse-plugin/[Eclipse] and https://maven.apache.org/plugins/maven-idea-plugin/[IDEA].
If you cannot directly import your project into your IDE, you may be able to generate IDE metadata by using a build plugin.
Maven includes plugins for https://maven.apache.org/plugins/maven-eclipse-plugin/[Eclipse] and https://maven.apache.org/plugins/maven-idea-plugin/[IDEA].
Gradle offers plugins for {gradle-docs}/userguide.html[various IDEs].
TIP: If you accidentally run a web application twice, you see a "`Port already in use`" error. STS users can use the `Relaunch` button rather than the `Run` button to ensure that any existing instance is closed.
TIP: If you accidentally run a web application twice, you see a "`Port already in use`" error.
STS users can use the `Relaunch` button rather than the `Run` button to ensure that any existing instance is closed.
@ -665,7 +672,8 @@ If that does not apply to you (i.e. if you run your application from a container
TIP: Flagging the dependency as optional in Maven or using a custom`developmentOnly` configuration in Gradle (as shown above) is a best practice that prevents devtools from being transitively applied to other modules that use your project.
TIP: Repackaged archives do not contain devtools by default. If you want to use a <<using-boot-devtools-remote,certain remote devtools feature>>, you need to disable the `excludeDevtools` build property to include it.
TIP: Repackaged archives do not contain devtools by default.
If you want to use a <<using-boot-devtools-remote,certain remote devtools feature>>, you need to disable the `excludeDevtools` build property to include it.
The property is supported with both the Maven and Gradle plugins.
@ -712,7 +720,8 @@ NOTE: As long as forking is enabled, you can also start your application by usin
By default, Gradle and Maven do that when they detect DevTools on the classpath.
TIP: Automatic restart works very well when used with LiveReload.
<<using-boot-devtools-livereload,See the LiveReload section>> for details. If you use JRebel, automatic restarts are disabled in favor of dynamic class reloading.
<<using-boot-devtools-livereload,See the LiveReload section>> for details.
If you use JRebel, automatic restarts are disabled in favor of dynamic class reloading.
Other devtools features (such as LiveReload and property overrides) can still be used.
NOTE: DevTools relies on the application context's shutdown hook to close it during a restart.
@ -852,7 +861,8 @@ The value of the property is a regex pattern that is applied to the classpath, a
NOTE: All property keys must be unique. As long as a property starts with `restart.include.` or `restart.exclude.` it is considered.
NOTE: All property keys must be unique.
As long as a property starts with `restart.include.` or `restart.exclude.` it is considered.
TIP: All `META-INF/spring-devtools.properties` from the classpath are loaded.
You can package files inside your project, or in the libraries that the project consumes.
@ -876,7 +886,8 @@ LiveReload browser extensions are freely available for Chrome, Firefox and Safar
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`.
NOTE: You can only run one LiveReload server at a time. Before starting your application, ensure that no other LiveReload servers are running.
NOTE: You can only run one LiveReload server at a time.
Before starting your application, ensure that no other LiveReload servers are running.
If you start multiple applications from your IDE, only the first has LiveReload support.
Andy Wilkinson
5 years ago