![]() |
Spring Boot jars include metadata files that provide details of all supported
configuration properties. The files are designed to let IDE developers offer
contextual help and “code completion” as users are working with The majority of the metadata file is generated automatically at compile time by
processing all items annotated with Configuration metadata files are located inside jars under
{"groups": [ { "name": "server", "type": "org.springframework.boot.autoconfigure.web.ServerProperties", "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties" }, { "name": "spring.jpa.hibernate", "type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate", "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties", "sourceMethod": "getHibernate()" } ... ],"properties": [ { "name": "server.port", "type": "java.lang.Integer", "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties" }, { "name": "server.servlet.path", "type": "java.lang.String", "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties", "defaultValue": "/" }, { "name": "spring.jpa.hibernate.ddl-auto", "type": "java.lang.String", "description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.", "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate" } ... ],"hints": [ { "name": "spring.jpa.hibernate.ddl-auto", "values": [ { "value": "none", "description": "Disable DDL handling." }, { "value": "validate", "description": "Validate the schema, make no changes to the database." }, { "value": "update", "description": "Update the schema if necessary." }, { "value": "create", "description": "Create the schema and destroy previous data." }, { "value": "create-drop", "description": "Create and then destroy the schema at the end of the session." } ] } ]} Each “property” is a configuration item that the user specifies with a given value.
For example, server.port=9090 server.servlet.path=/home The “groups” are higher level items that do not themselves specify a value but instead
provide a contextual grouping for properties. For example, the
Finally, “hints” are additional information used to assist the user in configuring a
given property. For example, when a developer is configuring the
The JSON object contained in the
The JSON object contained in the
The JSON object contained in the
Deprecation can also be specified declaratively in code by adding the
@ConfigurationProperties("app.acme") public class AcmeProperties { private String name; public String getName() { ... } public void setName(String name) { ... } @DeprecatedConfigurationProperty(replacement = "app.acme.name") @Deprecated public String getTarget() { return getName(); } @Deprecated public void setTarget(String target) { setName(target); } }
The preceding code makes sure that the deprecated property still works (delegating
to the The JSON object contained in the
The JSON object contained in the
The JSON object contained in the
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. To improve the user experience and further assist the user in configuring a given property, you can provide additional metadata that:
The If your property is of type Assume a @ConfigurationProperties("sample") public class SampleProperties { private Map<String,Integer> contexts; // getters and setters } The magic values are (in this example) are {"hints": [ { "name": "sample.contexts.keys", "values": [ { "value": "sample1" }, { "value": "sample2" } ] } ]}
Providers are a powerful way to attach semantics to a property. In this section, we define the official providers that you can use for your own hints. However, your favorite IDE may implement some of these or none of them. Also, it could eventually provide its own.
The following table summarizes the list of supported providers:
The special any provider value permits any additional values to be provided. Regular value validation based on the property type should be applied if this is supported. This provider is typically used if you have a list of values and any extra values should still be considered as valid. The following example offers {"hints": [ { "name": "system.state", "values": [ { "value": "on" }, { "value": "off" } ], "providers": [ { "name": "any" } ] } ]} Note that, in the preceding example, any other value is also allowed. The class-reference provider auto-completes classes available in the project. This provider supports the following parameters:
The following metadata snippet corresponds to the standard {"hints": [ { "name": "server.servlet.jsp.class-name", "providers": [ { "name": "class-reference", "parameters": { "target": "javax.servlet.http.HttpServlet" } } ] } ]} 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
The following types can be used:
The following metadata snippet corresponds to the standard {"hints": [ { "name": "spring.liquibase.change-log", "providers": [ { "name": "handle-as", "parameters": { "target": "org.springframework.core.io.Resource" } } ] } ]} The logger-name provider auto-completes valid logger names. Typically, package and class names available in the current project can be auto-completed. Specific frameworks may have extra magic logger names that can be supported as well. Since a logger name can be any arbitrary name, this provider should allow any value but could highlight valid package and class names that are not available in the project’s classpath. The following metadata snippet corresponds to the standard {"hints": [ { "name": "logging.level.keys", "values": [ { "value": "root", "description": "Root logger used to assign the default logging level." } ], "providers": [ { "name": "logger-name" } ] }, { "name": "logging.level.values", "values": [ { "value": "trace" }, { "value": "debug" }, { "value": "info" }, { "value": "warn" }, { "value": "error" }, { "value": "fatal" }, { "value": "off" } ], "providers": [ { "name": "any" } ] } ]} The spring-bean-reference provider auto-completes the beans that are defined in the configuration of the current project. This provider supports the following parameters:
The following metadata snippet corresponds to the standard {"hints": [ { "name": "spring.jmx.server", "providers": [ { "name": "spring-bean-reference", "parameters": { "target": "javax.management.MBeanServer" } } ] } ]}
The spring-profile-name provider auto-completes the Spring profiles that are defined in the configuration of the current project. The following metadata snippet corresponds to the standard {"hints": [ { "name": "spring.profiles.active", "providers": [ { "name": "spring-profile-name" } ] } ]} You can easily generate your own configuration metadata file from items annotated with
With Maven the dependency should be declared as optional, as shown in the following example: <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency> With Gradle 4.5 and earlier, the dependency should be declared in the dependencies {
compileOnly "org.springframework.boot:spring-boot-configuration-processor"
} With Gradle 4.6 and later, the dependency should be declared in the dependencies {
annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
} If you are using an compileJava.dependsOn(processResources) This dependency ensures that the additional metadata is available when the annotation processor runs during compilation. The processor picks up both classes and methods that are annotated with
Properties are discovered through the presence of standard getters and setters with
special handling for collection types (that is detected even if only a getter is present).
The annotation processor also supports the use of the
The annotation processor automatically considers inner classes as nested properties. Consider the following class: @ConfigurationProperties(prefix="server") public class ServerProperties { private String name; private Host host; // ... getter and setters public static class Host { private String ip; private int port; // ... getter and setters } } The preceding example produces metadata information for
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 If you refer to a property that has been detected automatically, the description, default value, and deprecation information are overridden, if specified. If the manual property declaration is not identified in the current module, it is added as a new property. The format of the
|