If you want to use a build tool other than Maven, Gradle, or Ant, you likely need to develop your own plugin.
Executable jars need to follow a specific format and certain entries need to be written in an uncompressed form (see the "`<<executable-jar#executable-jar, executable jar format>>`" section in the appendix for details).
Executable jars need to follow a specific format and certain entries need to be written in an uncompressed form (see the "`<<executable-jar#appendix.executable-jar, executable jar format>>`" section in the appendix for details).
The Spring Boot Maven and Gradle plugins both make use of `spring-boot-loader-tools` to actually generate jars.
If you need to, you may use this library directly.
If you are interested in how the build tool plugins work, you can look at the {spring-boot-code}/spring-boot-project/spring-boot-tools[`spring-boot-tools`] module on GitHub.
More technical details of the executable jar format are covered in <<executable-jar#executable-jar,the appendix>>.
More technical details of the executable jar format are covered in <<executable-jar#appendix.executable-jar,the appendix>>.
If you have specific build-related questions, see the "`<<howto#howto, how-to>>`" guides.
@ -146,7 +146,7 @@ Doing so consults Spring Boot's default dependency metadata to deduce the artifa
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 <<dependency-versions#dependency-versions,appendix>>.
A table showing the dependencies and their versions that are included in the default metadata can be found in the <<dependency-versions#appendix.dependency-versions,appendix>>.
@ -9,7 +9,7 @@ Spring Boot jars include metadata files that provide details of all supported co
The files are designed to let IDE developers offer contextual help and "`code completion`" as users are working with `application.properties` or `application.yml` files.
The majority of the metadata file is generated automatically at compile time by processing all items annotated with `@ConfigurationProperties`.
However, it is possible to <<configuration-metadata#configuration-metadata.annotation-processor.adding-additional-metadata,write part of the metadata manually>> for corner cases or more advanced use cases.
However, it is possible to <<configuration-metadata#appendix.configuration-metadata.annotation-processor.adding-additional-metadata,write part of the metadata manually>> for corner cases or more advanced use cases.
== Generating Your Own Metadata by Using the Annotation Processor
You can easily generate your own configuration metadata file from items annotated with `@ConfigurationProperties` by using the `spring-boot-configuration-processor` jar.
The jar includes a Java annotation processor which is invoked as your project is compiled.
The processor picks up both classes and methods that are annotated with `@ConfigurationProperties`.
@ -83,7 +83,7 @@ The annotation processor applies a number of heuristics to extract the default v
Default values have to be provided statically. In particular, do not refer to a constant defined in another class.
Also, the annotation processor cannot auto-detect default values for ``Enum``s and ``Collections``s.
For cases where the default value could not be detected, <<configuration-metadata#configuration-metadata.annotation-processor.adding-additional-metadata,manual metadata>> should be provided.
For cases where the default value could not be detected, <<configuration-metadata#appendix.configuration-metadata.annotation-processor.adding-additional-metadata,manual metadata>> should be provided.
In order to document default values for properties in the class above, you could add the following content to <<configuration-metadata#configuration-metadata.annotation-processor.adding-additional-metadata,the manual metadata of the module>>:
In order to document default values for properties in the class above, you could add the following content to <<configuration-metadata#appendix.configuration-metadata.annotation-processor.adding-additional-metadata,the manual metadata of the module>>:
[source,json,indent=0,subs="verbatim"]
----
@ -111,7 +111,7 @@ NOTE: Only the `name` of the property is required to document additional metadat
Spring Boot's configuration file handling is quite flexible, and it is often the case that properties may exist that are not bound to a `@ConfigurationProperties` bean.
You may also need to tune some attributes of an existing key.
Configuration metadata files are located inside jars under `META-INF/spring-configuration-metadata.json`.
They use a JSON format with items categorized under either "`groups`" or "`properties`" and additional values hints categorized under "hints", as shown in the following example:
@ -86,7 +86,7 @@ For example, when a developer is configuring the configprop:spring.jpa.hibernate
[[configuration-metadata.format.group]]
[[appendix.configuration-metadata.format.group]]
=== Group Attributes
The JSON object contained in the `groups` array can contain the attributes shown in the following table:
@ -127,7 +127,7 @@ The JSON object contained in the `groups` array can contain the attributes shown
The `name` attribute of each hint refers to the `name` of a property.
In the <<configuration-metadata#configuration-metadata.format,initial example shown earlier>>, we provide five values for the `spring.jpa.hibernate.ddl-auto` property: `none`, `validate`, `update`, `create`, and `create-drop`.
In the <<configuration-metadata#appendix.configuration-metadata.format,initial example shown earlier>>, we provide five values for the `spring.jpa.hibernate.ddl-auto` property: `none`, `validate`, `update`, `create`, and `create-drop`.
Each value may have a description as well.
If your property is of type `Map`, you can provide hints for both the keys and the values (but not for the map itself).
The magic values are (in this example) are `sample1` and `sample2`.
In order to offer additional content assistance for the keys, you could add the following JSON to <<configuration-metadata#configuration-metadata.annotation-processor.adding-additional-metadata,the manual metadata of the module>>:
In order to offer additional content assistance for the keys, you could add the following JSON to <<configuration-metadata#appendix.configuration-metadata.annotation-processor.adding-additional-metadata,the manual metadata of the module>>:
[source,json,indent=0,subs="verbatim"]
----
@ -48,7 +48,7 @@ If your IDE supports it, this is by far the most effective approach to auto-comp
The **handle-as** provider lets you substitute the type of the property to a more high-level type.
This typically happens when the property has a `java.lang.String` type, because you do not want your configuration classes to rely on classes that may not be on the classpath.
@ -221,7 +221,7 @@ It is actually used internally as a `org.springframework.core.io.Resource` but c
The following table provides details of all of the dependency versions that are provided by Spring Boot in its CLI (Command Line Interface), Maven dependency management, and Gradle plugin.
`PropertiesLauncher` has a few special features that can be enabled with external properties (System properties, environment variables, manifest entries, or `loader.properties`).
@ -267,7 +267,7 @@ Here are some rules we follow internally to make sure descriptions are consisten
* Use `java.time.Duration` rather than `long` and describe the default unit if it differs from milliseconds, such as "If a duration suffix is not specified, seconds will be used".
* Do not provide the default value in the description unless it has to be determined at runtime.
Make sure to <<configuration-metadata#configuration-metadata.annotation-processor,trigger meta-data generation>> so that IDE assistance is available for your keys as well.
Make sure to <<configuration-metadata#appendix.configuration-metadata.annotation-processor,trigger meta-data generation>> so that IDE assistance is available for your keys as well.
You may want to review the generated metadata (`META-INF/spring-configuration-metadata.json`) to make sure your keys are properly documented.
Using your own starter in a compatible IDE is also a good idea to validate that quality of the metadata.
@ -126,7 +126,7 @@ data class KotlinExampleProperties(
}
----
TIP: To generate <<configuration-metadata#configuration-metadata.annotation-processor,your own metadata>> using the annotation processor, {kotlin-docs}kapt.html[`kapt` should be configured] with the `spring-boot-configuration-processor` dependency.
TIP: To generate <<configuration-metadata#appendix.configuration-metadata.annotation-processor,your own metadata>> using the annotation processor, {kotlin-docs}kapt.html[`kapt` should be configured] with the `spring-boot-configuration-processor` dependency.
Note that some features (such as detecting the default value or deprecated items) are not working due to limitations in the model kapt provides.
@ -337,7 +337,7 @@ To test that object JSON serialization and deserialization is working as expecte
* `Gson`
* `Jsonb`
TIP: A list of the auto-configurations that are enabled by `@JsonTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configurations that are enabled by `@JsonTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
If you need to configure elements of the auto-configuration, you can use the `@AutoConfigureJsonTesters` annotation.
@ -372,7 +372,7 @@ To test whether Spring MVC controllers are working as expected, use the `@WebMvc
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@WebMvcTest` annotation is used.
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
TIP: A list of the auto-configuration settings that are enabled by `@WebMvcTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configuration settings that are enabled by `@WebMvcTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
TIP: If you need to register extra components, such as the Jackson `Module`, you can import additional configuration classes by using `@Import` on your test.
@ -420,7 +420,7 @@ To test that {spring-framework-docs}/web-reactive.html[Spring WebFlux] controlle
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@WebFluxTest` annotation is used.
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
TIP: A list of the auto-configurations that are enabled by `@WebFluxTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configurations that are enabled by `@WebFluxTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
TIP: If you need to register extra components, such as Jackson `Module`, you can import additional configuration classes using `@Import` on your test.
@ -456,7 +456,7 @@ Regular `@Component` and `@ConfigurationProperties` beans are not scanned when t
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
(For more about using Cassandra with Spring Boot, see "<<data#data.nosql.cassandra>>", earlier in this chapter.)
TIP: A list of the auto-configuration settings that are enabled by `@DataCassandraTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configuration settings that are enabled by `@DataCassandraTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
The following example shows a typical setup for using Cassandra tests in Spring Boot:
@ -478,7 +478,7 @@ This can be disabled using the `showSql()` attribute of the annotation.
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataJpaTest` annotation is used.
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
TIP: A list of the auto-configuration settings that are enabled by `@DataJpaTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configuration settings that are enabled by `@DataJpaTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
By default, data JPA tests are transactional and roll back at the end of each test.
See the {spring-framework-docs}/testing.html#testcontext-tx-enabling-transactions[relevant section] in the Spring Framework Reference Documentation for more details.
@ -519,7 +519,7 @@ By default, it configures an in-memory embedded database and a `JdbcTemplate`.
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@JdbcTest` annotation is used.
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
TIP: A list of the auto-configurations that are enabled by `@JdbcTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configurations that are enabled by `@JdbcTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
By default, JDBC tests are transactional and roll back at the end of each test.
See the {spring-framework-docs}/testing.html#testcontext-tx-enabling-transactions[relevant section] in the Spring Framework Reference Documentation for more details.
@ -542,7 +542,7 @@ By default, it configures an in-memory embedded database, a `JdbcTemplate`, and
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@DataJdbcTest` annotation is used.
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
TIP: A list of the auto-configurations that are enabled by `@DataJdbcTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configurations that are enabled by `@DataJdbcTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
By default, Data JDBC tests are transactional and roll back at the end of each test.
See the {spring-framework-docs}/testing.html#testcontext-tx-enabling-transactions[relevant section] in the Spring Framework Reference Documentation for more details.
@ -562,7 +562,7 @@ If you want to replace it with an in-memory database, you can use `@AutoConfigur
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@JooqTest` annotation is used.
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
TIP: A list of the auto-configurations that are enabled by `@JooqTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configurations that are enabled by `@JooqTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
`@JooqTest` configures a `DSLContext`.
The following example shows the `@JooqTest` annotation in use:
@ -585,7 +585,7 @@ Regular `@Component` and `@ConfigurationProperties` beans are not scanned when t
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
(For more about using MongoDB with Spring Boot, see "<<data#data.nosql.mongodb>>", earlier in this chapter.)
TIP: A list of the auto-configuration settings that are enabled by `@DataMongoTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configuration settings that are enabled by `@DataMongoTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
The following class shows the `@DataMongoTest` annotation in use:
@ -612,7 +612,7 @@ Regular `@Component` and `@ConfigurationProperties` beans are not scanned when t
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
(For more about using Neo4J with Spring Boot, see "<<data#data.nosql.neo4j>>", earlier in this chapter.)
TIP: A list of the auto-configuration settings that are enabled by `@DataNeo4jTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configuration settings that are enabled by `@DataNeo4jTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
The following example shows a typical setup for using Neo4J tests in Spring Boot:
@ -643,7 +643,7 @@ Regular `@Component` and `@ConfigurationProperties` beans are not scanned when t
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
(For more about using Redis with Spring Boot, see "<<data#data.nosql.redis>>", earlier in this chapter.)
TIP: A list of the auto-configuration settings that are enabled by `@DataRedisTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configuration settings that are enabled by `@DataRedisTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
The following example shows the `@DataRedisTest` annotation in use:
@ -662,7 +662,7 @@ Regular `@Component` and `@ConfigurationProperties` beans are not scanned when t
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
(For more about using LDAP with Spring Boot, see "<<data#data.nosql.ldap>>", earlier in this chapter.)
TIP: A list of the auto-configuration settings that are enabled by `@DataLdapTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configuration settings that are enabled by `@DataLdapTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
The following example shows the `@DataLdapTest` annotation in use:
@ -688,7 +688,7 @@ By default, it auto-configures Jackson, GSON, and Jsonb support, configures a `R
Regular `@Component` and `@ConfigurationProperties` beans are not scanned when the `@RestClientTest` annotation is used.
`@EnableConfigurationProperties` can be used to include `@ConfigurationProperties` beans.
TIP: A list of the auto-configuration settings that are enabled by `@RestClientTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configuration settings that are enabled by `@RestClientTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
The specific beans that you want to test should be specified by using the `value` or `components` attribute of `@RestClientTest`, as shown in the following example:
@ -795,7 +795,7 @@ By default, it configures a mock `WebServiceServer` bean and automatically custo
(For more about using Web Services with Spring Boot, see "<<io#io.webservices>>", earlier in this chapter.)
TIP: A list of the auto-configuration settings that are enabled by `@WebServiceClientTest` can be <<test-auto-configuration#test-auto-configuration,found in the appendix>>.
TIP: A list of the auto-configuration settings that are enabled by `@WebServiceClientTest` can be <<test-auto-configuration#appendix.test-auto-configuration,found in the appendix>>.
The following example shows the `@WebServiceClientTest` annotation in use:
@ -149,7 +149,7 @@ If your application contains classes that you want to share with other projects,
The separate module can then be depended upon by your application and other projects.
If you cannot rearrange your code as recommended above, Spring Boot's Maven and Gradle plugins must be configured to produce a separate artifact that is suitable for use as a dependency.
The executable archive cannot be used as a dependency as the <<executable-jar#executable-jar.nested-jars.jar-structure,executable jar format>> packages application classes in `BOOT-INF/classes`.
The executable archive cannot be used as a dependency as the <<executable-jar#appendix.executable-jar.nested-jars.jar-structure,executable jar format>> packages application classes in `BOOT-INF/classes`.
This means that they cannot be found when the executable jar is used as a dependency.
To produce the two artifacts, one that can be used as a dependency and one that is executable, a classifier must be specified.
@ -300,6 +300,6 @@ There is not (and technically cannot be) an exhaustive list of all supported pro
A running application with the Actuator features has a `configprops` endpoint that shows all the bound and bindable properties available through `@ConfigurationProperties`.
The appendix includes an <<application-properties#application-properties, `application.properties`>> example with a list of the most common properties supported by Spring Boot.
The appendix includes an <<application-properties#appendix.application-properties, `application.properties`>> example with a list of the most common properties supported by Spring Boot.
The definitive list comes from searching the source code for `@ConfigurationProperties` and `@Value` annotations as well as the occasional use of `Binder`.
For more about the exact ordering of loading properties, see "<<features#features.external-config>>".
@ -236,7 +236,7 @@ As of Undertow 1.4.0+, both `h2` and `h2c` are supported on JDK 8 without any ad
Generally, you should first consider using one of the many available configuration keys and customize your web server by adding new entries in your `application.properties` or `application.yml` file.
See "`<<howto#howto.properties-and-configuration.discover-build-in-options-for-external-properties>>`").
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 <<application-properties#application-properties>>.
See the list of <<application-properties#appendix.application-properties>>.
The previous sections covered already many common use cases, such as compression, SSL or HTTP/2.
However, if a configuration key does not exist for your use case, you should then look at {spring-boot-module-api}/web/server/WebServerFactoryCustomizer.html[`WebServerFactoryCustomizer`].
@ -30,9 +30,9 @@ The reference documentation consists of the following sections:
The reference documentation has the following appendices:
[horizontal]
<<application-properties#application-properties,Application Properties>> :: Common application properties that you can use to configure your application.
<<configuration-metadata#configuration-metadata,Configuration Metadata>> :: Metadata that you can use to describe configuration properties.
<<auto-configuration-classes#auto-configuration-classes,Auto-configuration Classes>> :: Auto-configuration classes provided by Spring Boot.
<<test-auto-configuration#test-auto-configuration,Test Auto-configuration Annotations>> :: Test auto-configuration annotations that you can use to test slices of your application.
<<executable-jar#executable-jar,Executable Jars>> :: Spring Boot's executable jars, their launchers, and their format.
<<dependency-versions#dependency-versions,Dependency Versions>> :: Details of the dependencies that are managed by Spring Boot.
<<application-properties#appendix.application-properties,Application Properties>> :: Common application properties that you can use to configure your application.
<<configuration-metadata#appendix.configuration-metadata,Configuration Metadata>> :: Metadata that you can use to describe configuration properties.
<<auto-configuration-classes#appendix.auto-configuration-classes,Auto-configuration Classes>> :: Auto-configuration classes provided by Spring Boot.
<<test-auto-configuration#appendix.test-auto-configuration,Test Auto-configuration Annotations>> :: Test auto-configuration annotations that you can use to test slices of your application.
<<executable-jar#appendix.executable-jar,Executable Jars>> :: Spring Boot's executable jars, their launchers, and their format.
<<dependency-versions#appendix.dependency-versions,Dependency Versions>> :: Details of the dependencies that are managed by Spring Boot.
The following table lists the various `@...Test` annotations that can be used to test slices of your application and the auto-configuration that they import by default:
@ -330,7 +330,7 @@ For machine clients, it produces a JSON response with details of the error, the
For browser clients, there is a "`whitelabel`" error view that renders the same data in HTML format (to customize it, add a `View` that resolves to `error`).
There are a number of `server.error` properties that can be set if you want to customize the default error handling behavior.
See the <<application-properties#application-properties.server, "`Server Properties`">> section of the Appendix.
See the <<application-properties#appendix.application-properties.server, "`Server Properties`">> section of the Appendix.
To replace the default behavior completely, you can implement `ErrorController` and register a bean definition of that type or add a bean of type `ErrorAttributes` to use the existing mechanism but replace the contents.
Andy Wilkinson
3 years ago