861 lines
29 KiB
Plaintext
861 lines
29 KiB
Plaintext
[appendix]
|
||
[[configuration-metadata]]
|
||
= Configuration Metadata
|
||
include::attributes.adoc[]
|
||
|
||
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 `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-additional-metadata,write part of the metadata manually>> for corner cases or more advanced use cases.
|
||
|
||
|
||
|
||
[[configuration-metadata-format]]
|
||
== Metadata Format
|
||
Configuration metadata files are located inside jars under `META-INF/spring-configuration-metadata.json`.
|
||
They use a simple JSON format with items categorized under either "`groups`" or "`properties`" and additional values hints categorized under "hints", as shown in the following example:
|
||
|
||
[source,json,indent=0]
|
||
----
|
||
{"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.address",
|
||
"type": "java.net.InetAddress",
|
||
"sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
|
||
},
|
||
{
|
||
"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` and `server.address` might be specified in `application.properties`, as follows:
|
||
|
||
[source,properties,indent=0,configprops]
|
||
----
|
||
server.port=9090
|
||
server.address=127.0.0.1
|
||
----
|
||
|
||
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.
|
||
|
||
Finally, "`hints`" are additional information used to assist the user in configuring a given property.
|
||
For example, when a developer is configuring the configprop:spring.jpa.hibernate.ddl-auto[] property, a tool can use the hints to offer some auto-completion help for the `none`, `validate`, `update`, `create`, and `create-drop` values.
|
||
|
||
|
||
|
||
[[configuration-metadata-group-attributes]]
|
||
=== Group Attributes
|
||
The JSON object contained in the `groups` array can contain the attributes shown in the following table:
|
||
|
||
[cols="1,1,4"]
|
||
|===
|
||
| Name | Type | Purpose
|
||
|
||
| `name`
|
||
| String
|
||
| The full name of the group.
|
||
This attribute is mandatory.
|
||
|
||
| `type`
|
||
| String
|
||
| The class name of the data type of the group.
|
||
For example, if the group were based on a class annotated with `@ConfigurationProperties`, the attribute would contain the fully qualified name of that class.
|
||
If it were based on a `@Bean` method, it would be the return type of that method.
|
||
If the type is not known, the attribute may be omitted.
|
||
|
||
| `description`
|
||
| String
|
||
| A short description of the group that can be displayed to users.
|
||
If no description is available, it may be omitted.
|
||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||
The last line in the description should end with a period (`.`).
|
||
|
||
| `sourceType`
|
||
| String
|
||
| The class name of the source that contributed this group.
|
||
For example, if the group were based on a `@Bean` method annotated with `@ConfigurationProperties`, this attribute would contain the fully qualified name of the `@Configuration` class that contains the method.
|
||
If the source type is not known, the attribute may be omitted.
|
||
|
||
| `sourceMethod`
|
||
| String
|
||
| The full name of the method (include parenthesis and argument types) that contributed this group (for example, the name of a `@ConfigurationProperties` annotated `@Bean` method).
|
||
If the source method is not known, it may be omitted.
|
||
|===
|
||
|
||
|
||
|
||
[[configuration-metadata-property-attributes]]
|
||
=== Property Attributes
|
||
The JSON object contained in the `properties` array can contain the attributes described in the following table:
|
||
|
||
[cols="1,1,4"]
|
||
|===
|
||
| Name | Type | Purpose
|
||
|
||
| `name`
|
||
| String
|
||
| The full name of the property.
|
||
Names are in lower-case period-separated form (for example, `server.address`).
|
||
This attribute is mandatory.
|
||
|
||
| `type`
|
||
| String
|
||
| The full signature of the data type of the property (for example, `java.lang.String`) but also a full generic type (such as `java.util.Map<java.lang.String,acme.MyEnum>`).
|
||
You can use this attribute to guide the user as to the types of values that they can enter.
|
||
For consistency, the type of a primitive is specified by using its wrapper counterpart (for example, `boolean` becomes `java.lang.Boolean`).
|
||
Note that this class may be a complex type that gets converted from a `String` as values are bound.
|
||
If the type is not known, it may be omitted.
|
||
|
||
| `description`
|
||
| String
|
||
| A short description of the property that can be displayed to users.
|
||
If no description is available, it may be omitted.
|
||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||
The last line in the description should end with a period (`.`).
|
||
|
||
| `sourceType`
|
||
| String
|
||
| The class name of the source that contributed this property.
|
||
For example, if the property were from a class annotated with `@ConfigurationProperties`, this attribute would contain the fully qualified name of that class.
|
||
If the source type is unknown, it may be omitted.
|
||
|
||
| `defaultValue`
|
||
| Object
|
||
| The default value, which is used if the property is not specified.
|
||
If the type of the property is an array, it can be an array of value(s).
|
||
If the default value is unknown, it may be omitted.
|
||
|
||
| `deprecation`
|
||
| Deprecation
|
||
| Specify whether the property is deprecated.
|
||
If the field is not deprecated or if that information is not known, it may be omitted.
|
||
The next table offers more detail about the `deprecation` attribute.
|
||
|===
|
||
|
||
The JSON object contained in the `deprecation` attribute of each `properties` element can contain the following attributes:
|
||
|
||
[cols="1,1,4"]
|
||
|===
|
||
| Name | Type | Purpose
|
||
|
||
| `level`
|
||
| String
|
||
| The level of deprecation, which can be either `warning` (the default) or `error`.
|
||
When a property has a `warning` deprecation level, it should still be bound in the environment.
|
||
However, when it has an `error` deprecation level, the property is no longer managed and is not bound.
|
||
|
||
| `reason`
|
||
| String
|
||
| A short description of the reason why the property was deprecated.
|
||
If no reason is available, it may be omitted.
|
||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||
The last line in the description should end with a period (`.`).
|
||
|
||
| `replacement`
|
||
| String
|
||
| The full name of the property that _replaces_ this deprecated property.
|
||
If there is no replacement for this property, it may be omitted.
|
||
|===
|
||
|
||
NOTE: Prior to Spring Boot 1.3, a single `deprecated` boolean attribute can be used instead of the `deprecation` element.
|
||
This is still supported in a deprecated fashion and should no longer be used.
|
||
If no reason and replacement are available, an empty `deprecation` object should be set.
|
||
|
||
Deprecation can also be specified declaratively in code by adding the `@DeprecatedConfigurationProperty` annotation to the getter exposing the deprecated property.
|
||
For instance, assume that the `app.acme.target` property was confusing and was renamed to `app.acme.name`.
|
||
The following example shows how to handle that situation:
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
@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);
|
||
}
|
||
}
|
||
----
|
||
|
||
NOTE: There is no way to set a `level`.
|
||
`warning` is always assumed, since code is still handling the property.
|
||
|
||
The preceding code makes sure that the deprecated property still works (delegating to the `name` property behind the scenes).
|
||
Once the `getTarget` and `setTarget` methods can be removed from your public API, the automatic deprecation hint in the metadata goes away as well.
|
||
If you want to keep a hint, adding manual metadata with an `error` deprecation level ensures that users are still informed about that property.
|
||
Doing so is particularly useful when a `replacement` is provided.
|
||
|
||
|
||
|
||
[[configuration-metadata-hints-attributes]]
|
||
=== Hint Attributes
|
||
The JSON object contained in the `hints` array can contain the attributes shown in the following table:
|
||
|
||
[cols="1,1,4"]
|
||
|===
|
||
| Name | Type | Purpose
|
||
|
||
| `name`
|
||
| String
|
||
| The full name of the property to which this hint refers.
|
||
Names are in lower-case period-separated form (such as `spring.mvc.servlet.path`).
|
||
If the property refers to a map (such as `system.contexts`), the hint either applies to the _keys_ of the map (`system.contexts.keys`) or the _values_ (`system.contexts.values`) of the map.
|
||
This attribute is mandatory.
|
||
|
||
| `values`
|
||
| ValueHint[]
|
||
| A list of valid values as defined by the `ValueHint` object (described in the next table).
|
||
Each entry defines the value and may have a description.
|
||
|
||
| `providers`
|
||
| ValueProvider[]
|
||
| A list of providers as defined by the `ValueProvider` object (described later in this document).
|
||
Each entry defines the name of the provider and its parameters, if any.
|
||
|===
|
||
|
||
The JSON object contained in the `values` attribute of each `hint` element can contain the attributes described in the following table:
|
||
|
||
[cols="1,1,4"]
|
||
|===
|
||
| Name | Type | Purpose
|
||
|
||
| `value`
|
||
| Object
|
||
| A valid value for the element to which the hint refers.
|
||
If the type of the property is an array, it can also be an array of value(s).
|
||
This attribute is mandatory.
|
||
|
||
| `description`
|
||
| String
|
||
| A short description of the value that can be displayed to users.
|
||
If no description is available, it may be omitted.
|
||
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
|
||
The last line in the description should end with a period (`.`).
|
||
|===
|
||
|
||
The JSON object contained in the `providers` attribute of each `hint` element can contain the attributes described in the following table:
|
||
|
||
[cols="1,1,4"]
|
||
|===
|
||
|Name | Type |Purpose
|
||
|
||
| `name`
|
||
| String
|
||
| The name of the provider to use to offer additional content assistance for the element to which the hint refers.
|
||
|
||
| `parameters`
|
||
| JSON object
|
||
| Any additional parameter that the provider supports (check the documentation of the provider for more details).
|
||
|===
|
||
|
||
|
||
|
||
[[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.
|
||
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.
|
||
|
||
|
||
|
||
[[configuration-metadata-providing-manual-hints]]
|
||
== Providing Manual Hints
|
||
To improve the user experience and further assist the user in configuring a given property, you can provide additional metadata that:
|
||
|
||
* Describes the list of potential values for a property.
|
||
* Associates a provider, to attach a well defined semantic to a property, so that a tool can discover the list of potential values based on the project's context.
|
||
|
||
|
||
=== Value Hint
|
||
The `name` attribute of each hint refers to the `name` of a property.
|
||
In the <<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 special `.keys` and `.values` suffixes must refer to the keys and the values, respectively.
|
||
|
||
Assume a `sample.contexts` maps magic `String` values to an integer, as shown in the following example:
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
@ConfigurationProperties("sample")
|
||
public class SampleProperties {
|
||
|
||
private Map<String,Integer> contexts;
|
||
// getters and setters
|
||
}
|
||
----
|
||
|
||
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-additional-metadata,the manual metadata of the module>>:
|
||
|
||
[source,json,indent=0]
|
||
----
|
||
{"hints": [
|
||
{
|
||
"name": "sample.contexts.keys",
|
||
"values": [
|
||
{
|
||
"value": "sample1"
|
||
},
|
||
{
|
||
"value": "sample2"
|
||
}
|
||
]
|
||
}
|
||
]}
|
||
----
|
||
|
||
TIP: We recommend that you use an `Enum` for those two values instead.
|
||
If your IDE supports it, this is by far the most effective approach to auto-completion.
|
||
|
||
|
||
|
||
=== Value Providers
|
||
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.
|
||
|
||
NOTE: As this is a new feature, IDE vendors must catch up with how it works.
|
||
Adoption times naturally vary.
|
||
|
||
The following table summarizes the list of supported providers:
|
||
|
||
[cols="2,4"]
|
||
|===
|
||
| Name | Description
|
||
|
||
| `any`
|
||
| Permits any additional value to be provided.
|
||
|
||
| `class-reference`
|
||
| Auto-completes the classes available in the project.
|
||
Usually constrained by a base class that is specified by the `target` parameter.
|
||
|
||
| `handle-as`
|
||
| Handles the property as if it were defined by the type defined by the mandatory `target` parameter.
|
||
|
||
| `logger-name`
|
||
| Auto-completes valid logger names and <<spring-boot-features.adoc#boot-features-custom-log-groups,logger groups>>.
|
||
Typically, package and class names available in the current project can be auto-completed as well as defined groups.
|
||
|
||
| `spring-bean-reference`
|
||
| Auto-completes the available bean names in the current project.
|
||
Usually constrained by a base class that is specified by the `target` parameter.
|
||
|
||
| `spring-profile-name`
|
||
| Auto-completes the available Spring profile names in the project.
|
||
|===
|
||
|
||
TIP: Only one provider can be active for a given property, but you can specify several providers if they can all manage the property _in some way_.
|
||
Make sure to place the most powerful provider first, as the IDE must use the first one in the JSON section that it can handle.
|
||
If no provider for a given property is supported, no special content assistance is provided, either.
|
||
|
||
|
||
|
||
==== Any
|
||
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 `on` and `off` as auto-completion values for `system.state`:
|
||
|
||
[source,json,indent=0]
|
||
----
|
||
{"hints": [
|
||
{
|
||
"name": "system.state",
|
||
"values": [
|
||
{
|
||
"value": "on"
|
||
},
|
||
{
|
||
"value": "off"
|
||
}
|
||
],
|
||
"providers": [
|
||
{
|
||
"name": "any"
|
||
}
|
||
]
|
||
}
|
||
]}
|
||
----
|
||
|
||
Note that, in the preceding example, any other value is also allowed.
|
||
|
||
==== Class Reference
|
||
The **class-reference** provider auto-completes classes available in the project.
|
||
This provider supports the following parameters:
|
||
|
||
[cols="1,1,2,4"]
|
||
|===
|
||
| Parameter | Type | Default value | Description
|
||
|
||
| `target`
|
||
| `String` (`Class`)
|
||
| _none_
|
||
| The fully qualified name of the class that should be assignable to the chosen value.
|
||
Typically used to filter out-non candidate classes.
|
||
Note that this information can be provided by the type itself by exposing a class with the appropriate upper bound.
|
||
|
||
| `concrete`
|
||
| `boolean`
|
||
| true
|
||
| Specify whether only concrete classes are to be considered as valid candidates.
|
||
|===
|
||
|
||
|
||
The following metadata snippet corresponds to the standard `server.servlet.jsp.class-name` property that defines the `JspServlet` class name to use:
|
||
|
||
[source,json,indent=0]
|
||
----
|
||
{"hints": [
|
||
{
|
||
"name": "server.servlet.jsp.class-name",
|
||
"providers": [
|
||
{
|
||
"name": "class-reference",
|
||
"parameters": {
|
||
"target": "javax.servlet.http.HttpServlet"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]}
|
||
----
|
||
|
||
|
||
|
||
==== Handle As
|
||
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.
|
||
This provider supports the following parameters:
|
||
|
||
[cols="1,1,2,4"]
|
||
|===
|
||
| Parameter | Type | Default value | Description
|
||
|
||
| **`target`**
|
||
| `String` (`Class`)
|
||
| _none_
|
||
| The fully qualified name of the type to consider for the property.
|
||
This parameter is mandatory.
|
||
|===
|
||
|
||
The following types can be used:
|
||
|
||
* Any `java.lang.Enum`: Lists the possible values for the property.
|
||
(We recommend defining the property with the `Enum` type, as no further hint should be required for the IDE to auto-complete the values)
|
||
* `java.nio.charset.Charset`: Supports auto-completion of charset/encoding values (such as `UTF-8`)
|
||
* `java.util.Locale`: auto-completion of locales (such as `en_US`)
|
||
* `org.springframework.util.MimeType`: Supports auto-completion of content type values (such as `text/plain`)
|
||
* `org.springframework.core.io.Resource`: Supports auto-completion of Spring’s Resource abstraction to refer to a file on the filesystem or on the classpath (such as `classpath:/sample.properties`)
|
||
|
||
TIP: If multiple values can be provided, use a `Collection` or _Array_ type to teach the IDE about it.
|
||
|
||
The following metadata snippet corresponds to the standard `spring.liquibase.change-log` property that defines the path to the changelog to use.
|
||
It is actually used internally as a `org.springframework.core.io.Resource` but cannot be exposed as such, because we need to keep the original String value to pass it to the Liquibase API.
|
||
|
||
[source,json,indent=0]
|
||
----
|
||
{"hints": [
|
||
{
|
||
"name": "spring.liquibase.change-log",
|
||
"providers": [
|
||
{
|
||
"name": "handle-as",
|
||
"parameters": {
|
||
"target": "org.springframework.core.io.Resource"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]}
|
||
----
|
||
|
||
|
||
|
||
==== Logger Name
|
||
The **logger-name** provider auto-completes valid logger names and <<spring-boot-features.adoc#boot-features-custom-log-groups,logger groups>>.
|
||
Typically, package and class names available in the current project can be auto-completed.
|
||
If groups are enabled (default) and if a custom logger group is identified in the configuration, auto-completion for it should be provided.
|
||
Specific frameworks may have extra magic logger names that can be supported as well.
|
||
|
||
This provider supports the following parameters:
|
||
|
||
[cols="1,1,2,4"]
|
||
|===
|
||
| Parameter | Type | Default value | Description
|
||
|
||
| `group`
|
||
| `boolean`
|
||
| `true`
|
||
| Specify whether known groups should be considered.
|
||
|===
|
||
|
||
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 `logging.level` property.
|
||
Keys are _logger names_, and values correspond to the standard log levels or any custom level.
|
||
As Spring Boot defines a few logger groups out-of-the-box, dedicated value hints have been added for those.
|
||
|
||
[source,json,indent=0]
|
||
----
|
||
{"hints": [
|
||
{
|
||
"name": "logging.level.keys",
|
||
"values": [
|
||
{
|
||
"value": "root",
|
||
"description": "Root logger used to assign the default logging level."
|
||
},
|
||
{
|
||
"value": "sql",
|
||
"description": "SQL logging group including Hibernate SQL logger."
|
||
},
|
||
{
|
||
"value": "web",
|
||
"description": "Web logging group including codecs."
|
||
}
|
||
],
|
||
"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"
|
||
}
|
||
]
|
||
}
|
||
]}
|
||
----
|
||
|
||
|
||
|
||
==== Spring Bean Reference
|
||
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:
|
||
|
||
[cols="1,1,2,4"]
|
||
|===
|
||
| Parameter | Type | Default value | Description
|
||
|
||
| `target`
|
||
| `String` (`Class`)
|
||
| _none_
|
||
| The fully qualified name of the bean class that should be assignable to the candidate.
|
||
Typically used to filter out non-candidate beans.
|
||
|===
|
||
|
||
The following metadata snippet corresponds to the standard `spring.jmx.server` property that defines the name of the `MBeanServer` bean to use:
|
||
|
||
[source,json,indent=0]
|
||
----
|
||
{"hints": [
|
||
{
|
||
"name": "spring.jmx.server",
|
||
"providers": [
|
||
{
|
||
"name": "spring-bean-reference",
|
||
"parameters": {
|
||
"target": "javax.management.MBeanServer"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]}
|
||
----
|
||
|
||
NOTE: The binder is not aware of the metadata.
|
||
If you provide that hint, you still need to transform the bean name into an actual Bean reference using by the `ApplicationContext`.
|
||
|
||
|
||
|
||
==== Spring Profile Name
|
||
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 `spring.profiles.active` property that defines the name of the Spring profile(s) to enable:
|
||
|
||
[source,json,indent=0]
|
||
----
|
||
{"hints": [
|
||
{
|
||
"name": "spring.profiles.active",
|
||
"providers": [
|
||
{
|
||
"name": "spring-profile-name"
|
||
}
|
||
]
|
||
}
|
||
]}
|
||
----
|
||
|
||
|
||
|
||
[[configuration-metadata-annotation-processor]]
|
||
== 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.
|
||
To use the processor, include a dependency on `spring-boot-configuration-processor`.
|
||
|
||
With Maven the dependency should be declared as optional, as shown in the following example:
|
||
|
||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||
----
|
||
<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 `compileOnly` configuration, as shown in the following example:
|
||
|
||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||
----
|
||
dependencies {
|
||
compileOnly "org.springframework.boot:spring-boot-configuration-processor"
|
||
}
|
||
----
|
||
|
||
With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` configuration, as shown in the following example:
|
||
|
||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||
----
|
||
dependencies {
|
||
annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
|
||
}
|
||
----
|
||
|
||
If you are using an `additional-spring-configuration-metadata.json` file, the `compileJava` task should be configured to depend on the `processResources` task, as shown in the following example:
|
||
|
||
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
||
----
|
||
compileJava.inputs.files(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 `@ConfigurationProperties`.
|
||
The Javadoc for field values within configuration classes is used to populate the `description` attribute.
|
||
|
||
NOTE: You should only use simple text with `@ConfigurationProperties` field Javadoc, since they are not processed before being added to the JSON.
|
||
|
||
If the class has a single constructor with at least one parameters, one property is created per constructor parameter.
|
||
Otherwise, 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 `@Data`, `@Getter`, and `@Setter` lombok annotations.
|
||
|
||
The annotation processor cannot auto-detect default values for ``Enum``s and ``Collections``s.
|
||
In the cases where a `Collection` or `Enum` property has a non-empty default value, <<configuration-metadata-additional-metadata,manual metadata>> should be provided.
|
||
|
||
Consider the following class:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||
----
|
||
@ConfigurationProperties(prefix = "acme.messaging")
|
||
public class MessagingProperties {
|
||
|
||
private List<String> addresses = new ArrayList<>(Arrays.asList("a", "b"));
|
||
|
||
private ContainerType containerType = ContainerType.SIMPLE;
|
||
|
||
// ... getter and setters
|
||
|
||
public enum ContainerType {
|
||
|
||
SIMPLE,
|
||
DIRECT
|
||
|
||
}
|
||
|
||
}
|
||
----
|
||
|
||
In order to document default values for properties in the class above, you could add the following content to <<configuration-metadata-additional-metadata,the manual metadata of the module>>:
|
||
|
||
[source,json,indent=0]
|
||
----
|
||
{"properties": [
|
||
{
|
||
"name": "acme.messaging.addresses",
|
||
"defaultValue": ["a", "b"]
|
||
},
|
||
{
|
||
"name": "acme.messaging.container-type",
|
||
"defaultValue": "simple"
|
||
}
|
||
]}
|
||
----
|
||
|
||
Only the `name` of the property is required to document additional fields with manual metadata.
|
||
|
||
[NOTE]
|
||
====
|
||
If you are using AspectJ in your project, you need to make sure that the annotation processor runs only once.
|
||
There are several ways to do this.
|
||
With Maven, you can configure the `maven-apt-plugin` explicitly and add the dependency to the annotation processor only there.
|
||
You could also let the AspectJ plugin run all the processing and disable annotation processing in the `maven-compiler-plugin` configuration, as follows:
|
||
|
||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||
----
|
||
<plugin>
|
||
<groupId>org.apache.maven.plugins</groupId>
|
||
<artifactId>maven-compiler-plugin</artifactId>
|
||
<configuration>
|
||
<proc>none</proc>
|
||
</configuration>
|
||
</plugin>
|
||
----
|
||
====
|
||
|
||
|
||
|
||
[[configuration-metadata-nested-properties]]
|
||
=== Nested Properties
|
||
The annotation processor automatically considers inner classes as nested properties.
|
||
Consider the following class:
|
||
|
||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||
----
|
||
@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 `server.name`, `server.host.ip`, and `server.host.port` properties.
|
||
You can use the `@NestedConfigurationProperty` annotation on a field to indicate that a regular (non-inner) class should be treated as if it were nested.
|
||
|
||
TIP: This has no effect on collections and maps, as those types are automatically identified, and a single metadata property is generated for each of them.
|
||
|
||
|
||
|
||
[[configuration-metadata-additional-metadata]]
|
||
=== Adding Additional Metadata
|
||
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.
|
||
To support such cases and let you provide custom "hints", the annotation processor automatically merges items from `META-INF/additional-spring-configuration-metadata.json` into the main metadata file.
|
||
|
||
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 `additional-spring-configuration-metadata.json` file is exactly the same as the regular `spring-configuration-metadata.json`.
|
||
The additional properties file is optional.
|
||
If you do not have any additional properties, do not add the file.
|