298 lines
13 KiB
Plaintext
298 lines
13 KiB
Plaintext
[[howto.properties-and-configuration]]
|
|
== Properties and Configuration
|
|
This section includes topics about setting and reading properties and configuration settings and their interaction with Spring Boot applications.
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.expand-properties]]
|
|
=== Automatically Expand Properties at Build Time
|
|
Rather than hardcoding some properties that are also specified in your project's build configuration, you can automatically expand them by instead using the existing build configuration.
|
|
This is possible in both Maven and Gradle.
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.expand-properties.maven]]
|
|
==== Automatic Property Expansion Using Maven
|
|
You can automatically expand properties from the Maven project by using resource filtering.
|
|
If you use the `spring-boot-starter-parent`, you can then refer to your Maven '`project properties`' with `@..@` placeholders, as shown in the following example:
|
|
|
|
[source,yaml,indent=0,subs="verbatim",configblocks]
|
|
----
|
|
app:
|
|
encoding: "@project.build.sourceEncoding@"
|
|
java:
|
|
version: "@java.version@"
|
|
----
|
|
|
|
NOTE: Only production configuration is filtered that way (in other words, no filtering is applied on `src/test/resources`).
|
|
|
|
TIP: If you enable the `addResources` flag, the `spring-boot:run` goal can add `src/main/resources` directly to the classpath (for hot reloading purposes).
|
|
Doing so circumvents the resource filtering and this feature.
|
|
Instead, you can use the `exec:java` goal or customize the plugin's configuration.
|
|
See the {spring-boot-maven-plugin-docs}#getting-started[plugin usage page] for more details.
|
|
|
|
If you do not use the starter parent, you need to include the following element inside the `<build/>` element of your `pom.xml`:
|
|
|
|
[source,xml,indent=0,subs="verbatim"]
|
|
----
|
|
<resources>
|
|
<resource>
|
|
<directory>src/main/resources</directory>
|
|
<filtering>true</filtering>
|
|
</resource>
|
|
</resources>
|
|
----
|
|
|
|
You also need to include the following element inside `<plugins/>`:
|
|
|
|
[source,xml,indent=0,subs="verbatim"]
|
|
----
|
|
<plugin>
|
|
<groupId>org.apache.maven.plugins</groupId>
|
|
<artifactId>maven-resources-plugin</artifactId>
|
|
<version>2.7</version>
|
|
<configuration>
|
|
<delimiters>
|
|
<delimiter>@</delimiter>
|
|
</delimiters>
|
|
<useDefaultDelimiters>false</useDefaultDelimiters>
|
|
</configuration>
|
|
</plugin>
|
|
----
|
|
|
|
NOTE: The `useDefaultDelimiters` property is important if you use standard Spring placeholders (such as `$\{placeholder}`) in your configuration.
|
|
If that property is not set to `false`, these may be expanded by the build.
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.expand-properties.gradle]]
|
|
==== Automatic Property Expansion Using Gradle
|
|
You can automatically expand properties from the Gradle project by configuring the Java plugin's `processResources` task to do so, as shown in the following example:
|
|
|
|
[source,gradle,indent=0,subs="verbatim"]
|
|
----
|
|
tasks.named('processResources') {
|
|
expand(project.properties)
|
|
}
|
|
----
|
|
|
|
You can then refer to your Gradle project's properties by using placeholders, as shown in the following example:
|
|
|
|
[source,yaml,indent=0,subs="verbatim",configblocks]
|
|
----
|
|
app:
|
|
name: "${name}"
|
|
description: "${description}"
|
|
----
|
|
|
|
NOTE: Gradle's `expand` method uses Groovy's `SimpleTemplateEngine`, which transforms `${..}` tokens.
|
|
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: `\${..}`.
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.externalize-configuration]]
|
|
=== Externalize the Configuration of SpringApplication
|
|
A `SpringApplication` has bean property setters, so you can use its Java API as you create the application to modify its behavior.
|
|
Alternatively, you can externalize the configuration by setting properties in `+spring.main.*+`.
|
|
For example, in `application.properties`, you might have the following settings:
|
|
|
|
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
|
----
|
|
spring:
|
|
main:
|
|
web-application-type: "none"
|
|
banner-mode: "off"
|
|
----
|
|
|
|
Then the Spring Boot banner is not printed on startup, and the application is not starting an embedded web server.
|
|
|
|
Properties defined in external configuration override and replace the values specified with the Java API, with the notable exception of the primary sources.
|
|
Primary sources are those provided to the `SpringApplication` constructor:
|
|
|
|
include::code:application/MyApplication[]
|
|
|
|
Or to `sources(...)` method of a `SpringApplicationBuilder`:
|
|
|
|
include::code:builder/MyApplication[]
|
|
|
|
Given the examples above, if we have the following configuration:
|
|
|
|
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
|
----
|
|
spring:
|
|
main:
|
|
sources: "com.example.MyDatabaseConfig,com.example.MyJmsConfig"
|
|
banner-mode: "console"
|
|
----
|
|
|
|
The actual application will show the banner (as overridden by configuration) and uses three sources for the `ApplicationContext`.
|
|
The application sources are:
|
|
|
|
. `MyApplication` (from the code)
|
|
. `MyDatabaseConfig` (from the external config)
|
|
. `MyJmsConfig`(from the external config)
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.external-properties-location]]
|
|
=== Change the Location of External Properties of an Application
|
|
By default, properties from different sources are added to the Spring `Environment` in a defined order (see "`<<features#features.external-config>>`" in the '`Spring Boot features`' section for the exact order).
|
|
|
|
You can also provide the following System properties (or environment variables) to change the behavior:
|
|
|
|
* 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.
|
|
By default, if YAML is used, then files with the '`.yaml`' and '`.yml`' extension are also added to the list.
|
|
|
|
TIP: If you want detailed information about the files that are being loaded you can <<features#features.logging.log-levels, set the logging level>> of `org.springframework.boot.context.config` to `trace`.
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.short-command-line-arguments]]
|
|
=== Use '`Short`' Command Line Arguments
|
|
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,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
|
----
|
|
server:
|
|
port: "${port:8080}"
|
|
----
|
|
|
|
TIP: If you inherit from the `spring-boot-starter-parent` POM, the default filter token of the `maven-resources-plugins` has been changed from `+${*}+` to `@` (that is, `@maven.token@` instead of `${maven.token}`) to prevent conflicts with Spring-style placeholders.
|
|
If you have enabled Maven filtering for the `application.properties` directly, you may want to also change the default filter token to use https://maven.apache.org/plugins/maven-resources-plugin/resources-mojo.html#delimiters[other delimiters].
|
|
|
|
NOTE: In this specific case, the port binding works in a PaaS environment such as Heroku or Cloud Foundry.
|
|
In those two platforms, the `PORT` environment variable is set automatically and Spring can bind to capitalized synonyms for `Environment` properties.
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.yaml]]
|
|
=== Use YAML for External Properties
|
|
YAML is a superset of JSON and, as such, is a convenient syntax for storing external properties in a hierarchical format, as shown in the following example:
|
|
|
|
[source,yaml,indent=0,subs="verbatim"]
|
|
----
|
|
spring:
|
|
application:
|
|
name: "cruncher"
|
|
datasource:
|
|
driver-class-name: "com.mysql.jdbc.Driver"
|
|
url: "jdbc:mysql://localhost/test"
|
|
server:
|
|
port: 9000
|
|
----
|
|
|
|
Create a file called `application.yaml` and put it in the root of your classpath.
|
|
Then add `snakeyaml` to your dependencies (Maven coordinates `org.yaml:snakeyaml`, already included if you use the `spring-boot-starter`).
|
|
A YAML file is parsed to a Java `Map<String,Object>` (like a JSON object), and Spring Boot flattens the map so that it is one level deep and has period-separated keys, as many people are used to with `Properties` files in Java.
|
|
|
|
The preceding example YAML corresponds to the following `application.properties` file:
|
|
|
|
[source,properties,indent=0,subs="verbatim",configprops]
|
|
----
|
|
spring.application.name=cruncher
|
|
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
|
|
spring.datasource.url=jdbc:mysql://localhost/test
|
|
server.port=9000
|
|
----
|
|
|
|
See "`<<features#features.external-config.yaml>>`" in the '`Spring Boot features`' section for more information about YAML.
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.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 (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:
|
|
|
|
[source,shell,indent=0,subs="verbatim"]
|
|
----
|
|
$ java -jar -Dspring.profiles.active=production demo-0.0.1-SNAPSHOT.jar
|
|
----
|
|
|
|
In Spring Boot, you can also set the active profile in `application.properties`, as shown in the following example:
|
|
|
|
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
|
----
|
|
spring:
|
|
profiles:
|
|
active: "production"
|
|
----
|
|
|
|
A value set this way is replaced by the System property or environment variable setting but not by the `SpringApplicationBuilder.profiles()` method.
|
|
Thus, the latter Java API can be used to augment the profiles without changing the defaults.
|
|
|
|
See "`<<features#features.profiles>>`" in the "`Spring Boot features`" section for more information.
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.set-default-spring-profile-name]]
|
|
=== Set the Default Profile Name
|
|
The default profile is a profile that is enabled if no profile is active.
|
|
By default, the name of the default profile is `default`, but it could be changed using a System property (configprop:spring.profiles.default[]) or an OS environment variable (configprop:spring.profiles.default[format=envvar]).
|
|
|
|
In Spring Boot, you can also set the default profile name in `application.properties`, as shown in the following example:
|
|
|
|
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
|
----
|
|
spring:
|
|
profiles:
|
|
default: "dev"
|
|
----
|
|
|
|
See "`<<features#features.profiles>>`" in the "`Spring Boot features`" section for more information.
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.change-configuration-depending-on-the-environment]]
|
|
=== Change Configuration Depending on the Environment
|
|
Spring Boot supports multi-document YAML and Properties files (see <<features#features.external-config.files.multi-document>> for details) which can be activated conditionally based on the active profiles.
|
|
|
|
If a document contains a `spring.config.activate.on-profile` key, then the profiles value (a comma-separated list of profiles or a profile expression) is fed into the Spring `Environment.acceptsProfiles()` method.
|
|
If the profile expression matches then that document is included in the final merge (otherwise, it is not), as shown in the following example:
|
|
|
|
[source,yaml,indent=0,subs="verbatim,attributes",configprops,configblocks]
|
|
----
|
|
server:
|
|
port: 9000
|
|
---
|
|
spring:
|
|
config:
|
|
activate:
|
|
on-profile: "development"
|
|
server:
|
|
port: 9001
|
|
---
|
|
spring:
|
|
config:
|
|
activate:
|
|
on-profile: "production"
|
|
server:
|
|
port: 0
|
|
----
|
|
|
|
In the preceding example, the default port is 9000.
|
|
However, if the Spring profile called '`development`' is active, then the port is 9001.
|
|
If '`production`' is active, then the port is 0.
|
|
|
|
NOTE: The documents are merged in the order in which they are encountered.
|
|
Later values override earlier values.
|
|
|
|
|
|
|
|
[[howto.properties-and-configuration.discover-build-in-options-for-external-properties]]
|
|
=== Discover Built-in Options for External Properties
|
|
Spring Boot binds external properties from `application.properties` (or YAML files and other places) into an application at runtime.
|
|
There is not (and technically cannot be) an exhaustive list of all supported properties in a single location, because contributions can come from additional jar files on your classpath.
|
|
|
|
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#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>>".
|