root
/
spring-boot
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

Merge pull request #10874 from Buzzardo:editing_appendix_configuration_metadata

Browse Source 
* pr/10874:
  Polish "Make editorial changes to appendix-configuration-metadata.adoc"
  Make editorial changes to appendix-configuration-metadata.adoc
pull/10818/merge
Stephane Nicoll 7 years ago
parent 85176debf3 08272c92db
commit f59986f100
1 changed files with 221 additions and 209 deletions
Show Stats Download Patch File Download Diff File

430
spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-configuration-metadata.adoc
Unescape Escape View File

@ -1,24 +1,24 @@
[appendix] [appendix]
[[configuration-metadata]] [[configuration-metadata]]
== Configuration meta-data == Configuration Metadata
Spring Boot jars are shipped with meta-data files that provide details of all supported Spring Boot jars include metadata files that provide details of all supported
configuration properties. The files are designed to allow IDE developers to offer configuration properties. The files are designed to let IDE developers offer
contextual help and "`code completion`" as users are working with `application.properties` contextual help and "`code completion`" as users are working with `application.properties`
or `application.yml` files. or `application.yml` files.
The majority of the meta-data file is generated automatically at compile time by The majority of the metadata file is generated automatically at compile time by
processing all items annotated with `@ConfigurationProperties`. However, it is possible processing all items annotated with `@ConfigurationProperties`. However, it is possible
to <<configuration-metadata-additional-metadata,write part of the meta-data manually>> to <<configuration-metadata-additional-metadata,write part of the metadata manually>>
for corner cases or more advanced use cases. for corner cases or more advanced use cases.
[[configuration-metadata-format]] [[configuration-metadata-format]]
=== Meta-data format === Metadata Format
Configuration meta-data files are located inside jars under Configuration metadata files are located inside jars under
`META-INF/spring-configuration-metadata.json` They use a simple JSON format with items `META-INF/spring-configuration-metadata.json` They use a simple JSON format with items
categorized under either "`groups`" or "`properties`" and additional values hint categorized under either "`groups`" or "`properties`" and additional values hints
categorized under "hints": categorized under "hints", as shown in the following example:
[source,json,indent=0] [source,json,indent=0]
---- ----
@ -84,8 +84,8 @@ categorized under "hints":
---- ----
Each "`property`" is a configuration item that the user specifies with a given value. Each "`property`" is a configuration item that the user specifies with a given value.
For example `server.port` and `server.servlet.path` might be specified in For example, `server.port` and `server.servlet.path` might be specified in
`application.properties` as follows: `application.properties`, as follows:
[source,properties,indent=0] [source,properties,indent=0]
---- ----
@ -93,23 +93,25 @@ For example `server.port` and `server.servlet.path` might be specified in
server.servlet.path=/home server.servlet.path=/home
---- ----
The "`groups`" are higher level items that don't themselves specify a value, but instead 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 provide a contextual grouping for properties. For example, the `server.port` and
`server.servlet.path` properties are part of the `server` group. `server.servlet.path` properties are part of the `server` group.
NOTE: It is not required that every "`property`" has a "`group`", some properties might NOTE: It is not required that every "`property`" has a "`group`". Some properties might
just exist in their own right. exist in their own right.
Finally, "`hints`" are additional information used to assist the user in configuring a Finally, "`hints`" are additional information used to assist the user in configuring a
given property. When configuring the `spring.jpa.hibernate.ddl-auto` property, a tool can given property. For example, when a developer is configuring the
use it to offer some auto-completion help for the `none`, `validate`, `update`, `create` `spring.jpa.hibernate.ddl-auto` property, a tool can use the hints to offer some
and `create-drop` values. auto-completion help for the `none`, `validate`, `update`, `create`, and `create-drop`
values.
[[configuration-metadata-group-attributes]] [[configuration-metadata-group-attributes]]
==== Group Attributes ==== Group Attributes
The JSON object contained in the `groups` array can contain the following attributes: The JSON object contained in the `groups` array can contain the attributes shown in the
following table:
[cols="1,1,4"] [cols="1,1,4"]
|=== |===
@ -121,37 +123,38 @@ The JSON object contained in the `groups` array can contain the following attrib
|`type` |`type`
| String | String
| The class name of the data type of the group. For example, if the group was based | 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 on a class annotated with `@ConfigurationProperties`, the attribute would contain the
fully qualified name of that class. If it was based on a `@Bean` method, it would be fully qualified name of that class. If it were based on a `@Bean` method, it would be
the return type of that method. The attribute may be omitted if the type is not known. the return type of that method. If the type is not known, the attribute may be omitted.
|`description` |`description`
| String | String
| A short description of the group that can be displayed to users. May be omitted if no | A short description of the group that can be displayed to users. If not description is
description is available. It is recommended that descriptions are a short paragraphs, 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 with the first line providing a concise summary. The last line in the description should
end with a period (`.`). end with a period (`.`).
|`sourceType` |`sourceType`
| String | String
| The class name of the source that contributed this group. For example, if the group | The class name of the source that contributed this group. For example, if the group
was based on a `@Bean` method annotated with `@ConfigurationProperties` this attribute were based on a `@Bean` method annotated with `@ConfigurationProperties`, this attribute
would contain the fully qualified name of the `@Configuration` class containing the would contain the fully qualified name of the `@Configuration` class that contains the
method. The attribute may be omitted if the source type is not known. method. If the source type is not known, the attribute may be omitted.
|`sourceMethod` |`sourceMethod`
| String | String
| The full name of the method (include parenthesis and argument types) that contributed | The full name of the method (include parenthesis and argument types) that contributed
this group. For example, the name of a `@ConfigurationProperties` annotated `@Bean` this group (for example, the name of a `@ConfigurationProperties` annotated `@Bean`
method. May be omitted if the source method is not known. method). If the source method is not known, it may be omitted.
|=== |===
[[configuration-metadata-property-attributes]] [[configuration-metadata-property-attributes]]
==== Property Attributes ==== Property Attributes
The JSON object contained in the `properties` array can contain the following attributes: The JSON object contained in the `properties` array can contain the attributes described
in the following table:
[cols="1,1,4"] [cols="1,1,4"]
|=== |===
@ -159,43 +162,44 @@ The JSON object contained in the `properties` array can contain the following at
|`name` |`name`
| String | String
| The full name of the property. Names are in lowercase dashed form (e.g. | The full name of the property. Names are in lower-case period-separated form (for
`server.servlet.path`). This attribute is mandatory. example, `server.servlet.path`). This attribute is mandatory.
|`type` |`type`
| String | String
| The full signature of the data type of the property. For example, `java.lang.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.util.String,acme.MyEnum>`. but also a full generic type (such as `java.util.Map<java.util.String,acme.MyEnum>`).
This attribute can be used to guide the user as to the types of values that they can 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 using its wrapper enter. For consistency, the type of a primitive is specified by using its wrapper
counterpart, i.e. `boolean` becomes `java.lang.Boolean`. Note that this class may be counterpart (for example, `boolean` becomes `java.lang.Boolean`). Note that this class
a complex type that gets converted from a String as values are bound. May be omitted may be a complex type that gets converted from a `String` as values are bound. If the
if the type is not known. type is not known, it may be omitted.
|`description` |`description`
| String | String
| A short description of the group that can be displayed to users. May be omitted if no | A short description of the group that can be displayed to users. If no description is
description is available. It is recommended that descriptions are a short paragraphs, 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 with the first line providing a concise summary. The last line in the description should
end with a period (`.`). end with a period (`.`).
|`sourceType` |`sourceType`
| String | String
| The class name of the source that contributed this property. For example, if the | The class name of the source that contributed this property. For example, if the
property was from a class annotated with `@ConfigurationProperties` this attribute property were from a class annotated with `@ConfigurationProperties`, this attribute
would contain the fully qualified name of that class. May be omitted if the source type would contain the fully qualified name of that class. If the source type is unknown, it
is not known. may be omitted.
|`defaultValue` |`defaultValue`
| Object | Object
| The default value which will be used if the property is not specified. Can also be an | The default value, which is used if the property is not specified. If the type of the
array of value(s) if the type of the property is an array. May be omitted if the default property is an array, it can be an array of value(s). If the default value is unknown,
value is not known. it may be omitted.
|`deprecation` |`deprecation`
| Deprecation | Deprecation
| Specify if the property is deprecated. May be omitted if the field is not deprecated | Specify whether the property is deprecated. If the field is not deprecated or if that
or if that information is not known. See below for more details. 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 The JSON object contained in the `deprecation` attribute of each `properties` element can
@ -207,22 +211,22 @@ contain the following attributes:
|`level` |`level`
|String |String
|The level of deprecation, can be either `warning` (default) or `error`. When a property |The level of deprecation, which can be either `warning` (the default) or `error`. When a
has a `warning` deprecation level it should still be bound in the environment. When it property has a `warning` deprecation level, it should still be bound in the environment.
has an `error` deprecation level however, the property is no longer managed and will not However, when it has an `error` deprecation level, the property is no longer managed and
be bound. is not bound.
|`reason` |`reason`
|String |String
|A short description of the reason why the property was deprecated. May be omitted if no |A short description of the reason why the property was deprecated. If no reason is
reason is available. It is recommended that descriptions are a short paragraphs, 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 with the first line providing a concise summary. The last line in the description should
end with a period (`.`). end with a period (`.`).
|`replacement` |`replacement`
|String |String
|The full name of the property that is _replacing_ this deprecated property. May be omitted |The full name of the property that _replaces_ this deprecated property. If there is no
if there is no replacement for this property. replacement for this property, it may be omitted.
|=== |===
NOTE: Prior to Spring Boot 1.3, a single `deprecated` boolean attribute can be used NOTE: Prior to Spring Boot 1.3, a single `deprecated` boolean attribute can be used
@ -232,8 +236,8 @@ should no longer be used. If no reason and replacement are available, an empty
Deprecation can also be specified declaratively in code by adding the Deprecation can also be specified declaratively in code by adding the
`@DeprecatedConfigurationProperty` annotation to the getter exposing the deprecated `@DeprecatedConfigurationProperty` annotation to the getter exposing the deprecated
property. For instance, let's assume the `app.foo.target` property was confusing and property. For instance, assume that the `app.foo.target` property was confusing and
was renamed to `app.foo.name` was renamed to `app.foo.name`. The following example shows how to handle that situation:
[source,java,indent=0] [source,java,indent=0]
---- ----
@ -259,21 +263,22 @@ was renamed to `app.foo.name`
} }
---- ----
NOTE: There is no way to set a `level` as `warning` is always assumed since code is still NOTE: There is no way to set a `level`. `warning` is always assumed, since code is still
handling the property. handling the property.
The code above makes sure that the deprecated property still works (delegating The preceding code makes sure that the deprecated property still works (delegating
to the `name` property behind the scenes). Once the `getTarget` and `setTarget` 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 methods can be removed from your public API, the automatic deprecation hint in the
meta-data will go away as well. If you want to keep a hint, adding manual meta-data with 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 and an `error` deprecation level ensures that users are still informed about that property.
is particularly useful when a `replacement` is provided. Doing so is particularly useful when a `replacement` is provided.
[[configuration-metadata-hints-attributes]] [[configuration-metadata-hints-attributes]]
==== Hint Attributes ==== Hint Attributes
The JSON object contained in the `hints` array can contain the following attributes: The JSON object contained in the `hints` array can contain the attributes shown in the
following table:
[cols="1,1,4"] [cols="1,1,4"]
|=== |===
@ -281,25 +286,26 @@ The JSON object contained in the `hints` array can contain the following attribu
|`name` |`name`
| String | String
| The full name of the property that this hint refers to. Names are in lowercase dashed | The full name of the property to which this hint refers. Names are in lower-case
form (e.g. `server.servlet.path`). If the property refers to a map (e.g. period-separated form (such as `server.servlet.path`). If the property refers to a map
`system.contexts`) the hint either applies to the _keys_ of the map (`system.context.keys`) (such as `system.contexts`), the hint either applies to the _keys_ of the map
or the values (`system.context.values`). This attribute is mandatory. (`system.context.keys`) or the _values_ (`system.context.values`) of the map. This
attribute is mandatory.
|`values` |`values`
| ValueHint[] | ValueHint[]
| A list of valid values as defined by the `ValueHint` object (see below). Each entry defines | A list of valid values as defined by the `ValueHint` object (described in the next
the value and may have a description table). Each entry defines the value and may have a description.
|`providers` |`providers`
| ValueProvider[] | ValueProvider[]
| A list of providers as defined by the `ValueProvider` object (see below). Each entry defines | A list of providers as defined by the `ValueProvider` object (described later in this
the name of the provider and its parameters, if any. 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 The JSON object contained in the `values` attribute of each `hint` element can contain
following attributes: the attributes described in the following table:
[cols="1,1,4"] [cols="1,1,4"]
|=== |===
@ -307,19 +313,19 @@ following attributes:
|`value` |`value`
| Object | Object
| A valid value for the element to which the hint refers to. Can also be an array of value(s) | A valid value for the element to which the hint refers. If the type of the property is
if the type of the property is an array. This attribute is mandatory. an array, it can also be an array of value(s). This attribute is mandatory.
|`description` |`description`
| String | String
| A short description of the value that can be displayed to users. May be omitted if no | A short description of the value that can be displayed to users. If no description is
description is available. It is recommended that descriptions are a short paragraphs, 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 with the first line providing a concise summary. The last line in the description should
end with a period (`.`). end with a period (`.`).
|=== |===
The JSON object contained in the `providers` attribute of each `hint` element can contain the The JSON object contained in the `providers` attribute of each `hint` element can contain
following attributes: the attributes described in the following table:
[cols="1,1,4"] [cols="1,1,4"]
|=== |===
@ -328,7 +334,7 @@ following attributes:
|`name` |`name`
| String | String
| The name of the provider to use to offer additional content assistance for the element | The name of the provider to use to offer additional content assistance for the element
to which the hint refers to. to which the hint refers.
|`parameters` |`parameters`
| JSON object | JSON object
@ -339,127 +345,129 @@ following attributes:
[[configuration-metadata-repeated-items]] [[configuration-metadata-repeated-items]]
==== Repeated meta-data items ==== Repeated Metadata Items
It is perfectly acceptable for "`property`" and "`group`" objects with the same name to Objects with the same "`property`" and "`group`" name can appear multiple times within a
appear multiple times within a meta-data file. For example, you could bind two separate metadata file. For example, you could bind two separate classes to the same prefix, with
classes to the same prefix, with each potentially offering overlap of property names. each having potentially overlapping property names. While the same names appearing in the
While this is not supposed to be a frequent scenario, consumers of meta-data should take metadata multiple times should not be common, consumers of metadata should take care to
care to ensure that they support such scenarios. ensure that they support it.
[[configuration-metadata-providing-manual-hints]] [[configuration-metadata-providing-manual-hints]]
=== Providing manual hints === Providing Manual Hints
To improve the user experience and further assist the user in configuring a given To improve the user experience and further assist the user in configuring a given
property, you can provide additional meta-data that: property, you can provide additional metadata that:
1. Describes the list of potential values for a property. * Describes the list of potential values for a property.
2. Associates a provider to attach a well-defined semantic to a property so that a tool * 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. can discover the list of potential values based on the project's context.
==== Value hint ==== Value Hint
The `name` attribute of each hint refers to the `name` of a property. In the initial The `name` attribute of each hint refers to the `name` of a property. In the
example above, we provide 5 values for the `spring.jpa.hibernate.ddl-auto` property: <<configuration-metadata-format,initial example shown earlier>>, we provide five values
`none`, `validate`, `update`, `create` and `create-drop`. Each value may have a for the `spring.jpa.hibernate.ddl-auto` property: `none`, `validate`, `update`, `create`,
description as well. 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 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 values (but not for the map itself). The special `.keys` and `.values` suffixes must
be used to refer to the keys and the values respectively. refer to the keys and the values, respectively.
Let's assume a `foo.contexts` that maps magic String values to an integer: Assume a `sample.contexts` maps magic `String` values to an integer, as shown in the
following example:
[source,java,indent=0] [source,java,indent=0]
---- ----
@ConfigurationProperties("foo") @ConfigurationProperties("sample")
public class FooProperties { public class SampleProperties {
private Map<String,Integer> contexts; private Map<String,Integer> contexts;
// getters and setters // getters and setters
} }
---- ----
The magic values are foo and bar for instance. In order to offer additional content The magic values are (in this example) are `sample1` and `sample2`. In order to offer
assistance for the keys, you could add the following to additional content assistance for the keys, you could add the following JSON to
<<configuration-metadata-additional-metadata,the manual meta-data of the module>>: <<configuration-metadata-additional-metadata,the manual metadata of the module>>:
[source,json,indent=0] [source,json,indent=0]
---- ----
{"hints": [ {"hints": [
{ {
"name": "foo.contexts.keys", "name": "sample.contexts.keys",
"values": [ "values": [
{ {
"value": "foo" "value": "sample1"
}, },
{ {
"value": "bar" "value": "sample2"
} }
] ]
} }
]} ]}
---- ----
NOTE: Of course, you should have an `Enum` for those two values instead. This is by far TIP: We recommend that you use an `Enum` for those two values instead. If your IDE
the most effective approach to auto-completion if your IDE supports it. supports it, this is by far the most effective approach to auto-completion.
==== Value provider ==== Value Providers
Providers are a powerful way of attaching semantics to a property. We define in the section Providers are a powerful way to attach semantics to a property. In this section, we
below the official providers that you can use for your own hints. Bare in mind however that define the official providers that you can use for your own hints. However, your favorite
your favorite IDE may implement some of these or none of them. It could eventually provide IDE may implement some of these or none of them. Also, it could eventually provide its
its own as well. own.
NOTE: As this is a new feature, IDE vendors will have to catch up with this new feature. NOTE: As this is a new feature, IDE vendors must catch up with how it works. Adoption
times naturally vary.
The table below summarizes the list of supported providers: The following table summarizes the list of supported providers:
[cols="2,4"] [cols="2,4"]
|=== |===
|Name | Description |Name | Description
|`any` |`any`
|Permit any additional value to be provided. |Permits any additional value to be provided.
|`class-reference` |`class-reference`
|Auto-complete the classes available in the project. Usually constrained by a base |Auto-completes the classes available in the project. Usually constrained by a base
class that is specified via the `target` parameter. class that is specified by the `target` parameter.
|`handle-as` |`handle-as`
|Handle the property as if it was defined by the type defined via the mandatory `target` parameter. |Handles the property as if it were defined by the type defined by the mandatory `target`
parameter.
|`logger-name` |`logger-name`
|Auto-complete valid logger names. Typically, package and class names available in |Auto-completes valid logger names. Typically, package and class names available in
the current project can be auto-completed. the current project can be auto-completed.
|`spring-bean-reference` |`spring-bean-reference`
|Auto-complete the available bean names in the current project. Usually constrained |Auto-completes the available bean names in the current project. Usually constrained
by a base class that is specified via the `target` parameter. by a base class that is specified by the `target` parameter.
|`spring-profile-name` |`spring-profile-name`
|Auto-complete the available Spring profile names in the project. |Auto-completes the available Spring profile names in the project.
|=== |===
TIP: No more than one provider can be active for a given property but you can specify TIP: Only one provider can be active for a given property, but you can specify several
several providers if they can all manage the property _in some ways_. Make sure to place providers if they can all manage the property _in some way_. Make sure to place the most
the most powerful provider first as the IDE must use the first one in the JSON section it 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 can handle. If no provider for a given property is supported, no special content
assistance is provided either. assistance is provided, either.
===== Any ===== Any
The **any** provider permits any additional values to be provided. Regular value The special **any** provider value permits any additional values to be provided. Regular
validation based on the property type should be applied if this is supported. value validation based on the property type should be applied if this is supported.
This provider will be typically used if you have a list of values and any extra values This provider is typically used if you have a list of values and any extra values
are still to be considered as valid. should still be considered as valid.
The example below offers `on` and `off` as auto-completion values for `system.state`; any The following example offers `on` and `off` as auto-completion values for `system.state`:
other value is also allowed:
[source,json,indent=0] [source,json,indent=0]
---- ----
@ -483,11 +491,11 @@ other value is also allowed:
]} ]}
---- ----
Note that, in the preceding example, any other value is also allowed.
===== Class Reference
===== Class reference
The **class-reference** provider auto-completes classes available in the project. This The **class-reference** provider auto-completes classes available in the project. This
provider supports these parameters: provider supports the following parameters:
[cols="1,1,2,4"] [cols="1,1,2,4"]
|=== |===
@ -497,17 +505,17 @@ provider supports these parameters:
|`String` (`Class`) |`String` (`Class`)
|_none_ |_none_
|The fully qualified name of the class that should be assignable to the chosen value. |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 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. be provided by the type itself by exposing a class with the appropriate upper bound.
|`concrete` |`concrete`
|`boolean` |`boolean`
|true |true
|Specify if only concrete classes are to be considered as valid candidates. |Specify whether only concrete classes are to be considered as valid candidates.
|=== |===
The meta-data snippet below corresponds to the standard `server.servlet.jsp.class-name` The following metadata snippet corresponds to the standard `server.servlet.jsp.class-name`
property that defines the `JspServlet` class name to use: property that defines the `JspServlet` class name to use:
[source,json,indent=0] [source,json,indent=0]
@ -530,10 +538,10 @@ property that defines the `JspServlet` class name to use:
===== Handle As ===== Handle As
The **handle-as** provider allows you to substitute the type of the property to a more 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 high-level type. This typically happens when the property has a `java.lang.String` type,
because you don't want your configuration classes to rely on classes that may not be because you do not want your configuration classes to rely on classes that may not be
on the classpath. This provider supports these parameters: on the classpath. This provider supports the following parameters:
[cols="1,1,2,4"] [cols="1,1,2,4"]
|=== |===
@ -542,27 +550,31 @@ on the classpath. This provider supports these parameters:
| **`target`** | **`target`**
| `String` (`Class`) | `String` (`Class`)
|_none_ |_none_
|The fully qualified name of the type to consider for the property. This parameter is mandatory. |The fully qualified name of the type to consider for the property. This parameter is
mandatory.
|=== |===
The following types can be used: The following types can be used:
* Any `java.lang.Enum` that lists the possible values for the property (By all means, try to * Any `java.lang.Enum`: Lists the possible values for the property. (We recommend
define the property with the `Enum` type instead as no further hint should be required for defining the property with the `Enum` type, as no further hint should be required for
the IDE to auto-complete the values). the IDE to auto-complete the values.)
* `java.nio.charset.Charset`: auto-completion of charset/encoding values (e.g. `UTF-8`) * `java.nio.charset.Charset`: Supports auto-completion of charset/encoding values (such as
* `java.util.Locale`: auto-completion of locales (e.g. `en_US`) `UTF-8`)
* `org.springframework.util.MimeType`: auto-completion of content type values (e.g. `text/plain`) * `java.util.Locale`: auto-completion of locales (such as `en_US`)
* `org.springframework.core.io.Resource`: auto-completion of Spring’s Resource abstraction to * `org.springframework.util.MimeType`: Supports auto-completion of content type values
refer to a file on the filesystem or on the classpath. (e.g. `classpath:/foo.properties`) (such as `text/plain`)
* `org.springframework.core.io.Resource`: Supports auto-completion of Spring’s Resource
NOTE: If multiple values can be provided, use a `Collection` or _Array_ type to teach the IDE abstraction to refer to a file on the filesystem or on the classpath. (such as
about it. `classpath:/sample.properties`)
The meta-data snippet below corresponds to the standard `spring.liquibase.change-log` 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 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 as we need to keep the `org.springframework.core.io.Resource` but cannot be exposed as such, because we need to
original String value to pass it to the Liquibase API. keep the original String value to pass it to the Liquibase API.
[source,json,indent=0] [source,json,indent=0]
---- ----
@ -583,18 +595,18 @@ original String value to pass it to the Liquibase API.
===== Logger name ===== Logger Name
The **logger-name** provider auto-completes valid logger names. Typically, package and 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 class names available in the current project can be auto-completed. Specific frameworks
may have extra magic logger names that could be supported as well. may have extra magic logger names that can be supported as well.
Since a logger name can be any arbitrary name, really, this provider should allow any Since a logger name can be any arbitrary name, this provider should allow any
value but could highlight valid packages and class names that are not available in the value but could highlight valid package and class names that are not available in the
project's classpath. project's classpath.
The meta-data snippet below corresponds to the standard `logging.level` property, keys 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 are _logger names_, and values correspond to the standard log levels or any custom
level: level.
[source,json,indent=0] [source,json,indent=0]
---- ----
@ -650,9 +662,9 @@ level:
===== Spring bean reference ===== Spring Bean Reference
The **spring-bean-reference** provider auto-completes the beans that are defined in The **spring-bean-reference** provider auto-completes the beans that are defined in
the configuration of the current project. This provider supports these parameters: the configuration of the current project. This provider supports the following parameters:
[cols="1,1,2,4"] [cols="1,1,2,4"]
|=== |===
@ -662,10 +674,10 @@ the configuration of the current project. This provider supports these parameter
| `String` (`Class`) | `String` (`Class`)
|_none_ |_none_
|The fully qualified name of the bean class that should be assignable to the candidate. |The fully qualified name of the bean class that should be assignable to the candidate.
Typically used to filter out non candidate beans. Typically used to filter out non-candidate beans.
|=== |===
The meta-data snippet below corresponds to the standard `spring.jmx.server` property The following metadata snippet corresponds to the standard `spring.jmx.server` property
that defines the name of the `MBeanServer` bean to use: that defines the name of the `MBeanServer` bean to use:
[source,json,indent=0] [source,json,indent=0]
@ -685,17 +697,16 @@ that defines the name of the `MBeanServer` bean to use:
]} ]}
---- ----
NOTE: The binder is not aware of the meta-data so if you provide that hint, you NOTE: The binder is not aware of the metadata. If you provide that hint, you still need
will still need to transform the bean name into an actual Bean reference using to transform the bean name into an actual Bean reference using by the `ApplicationContext`.
the `ApplicationContext`.
===== Spring profile name ===== Spring Profile Name
The **spring-profile-name** provider auto-completes the Spring profiles that are The **spring-profile-name** provider auto-completes the Spring profiles that are
defined in the configuration of the current project. defined in the configuration of the current project.
The meta-data snippet below corresponds to the standard `spring.profiles.active` The following metadata snippet corresponds to the standard `spring.profiles.active`
property that defines the name of the Spring profile(s) to enable: property that defines the name of the Spring profile(s) to enable:
[source,json,indent=0] [source,json,indent=0]
@ -715,12 +726,12 @@ property that defines the name of the Spring profile(s) to enable:
[[configuration-metadata-annotation-processor]] [[configuration-metadata-annotation-processor]]
=== Generating your own meta-data using the annotation processor === Generating Your Own Metadata by Using the Annotation Processor
You can easily generate your own configuration meta-data file from items annotated with You can easily generate your own configuration metadata file from items annotated with
`@ConfigurationProperties` by using the `spring-boot-configuration-processor` jar. `@ConfigurationProperties` by using the `spring-boot-configuration-processor` jar.
The jar includes a Java annotation processor which is invoked as your project is The jar includes a Java annotation processor which is invoked as your project is
compiled. To use the processor, simply include `spring-boot-configuration-processor` as compiled. To use the processor, include `spring-boot-configuration-processor` as
an optional dependency, for example with Maven you would add: an optional dependency. For example, with Maven, you can add:
[source,xml,indent=0,subs="verbatim,quotes,attributes"] [source,xml,indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -732,7 +743,7 @@ an optional dependency, for example with Maven you would add:
---- ----
With Gradle, you can use the https://github.com/spring-gradle-plugins/propdeps-plugin[propdeps-plugin] With Gradle, you can use the https://github.com/spring-gradle-plugins/propdeps-plugin[propdeps-plugin]
and specify: and specify the following dependency:
[source,groovy,indent=0,subs="verbatim,quotes,attributes"] [source,groovy,indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -744,28 +755,29 @@ and specify:
---- ----
NOTE: You need to add `compileJava.dependsOn(processResources)` to your build to ensure NOTE: You need to add `compileJava.dependsOn(processResources)` to your build to ensure
that resources are processed before code is compiled. Without this directive any that resources are processed before code is compiled. Without this directive, any
`additional-spring-configuration-metadata.json` files will not be processed. `additional-spring-configuration-metadata.json` files are not processed.
The processor will pick up both classes and methods that are annotated with The processor picks up both classes and methods that are annotated with
`@ConfigurationProperties`. The Javadoc for field values within configuration classes `@ConfigurationProperties`. The Javadoc for field values within configuration classes
will be used to populate the `description` attribute. is used to populate the `description` attribute.
NOTE: You should only use simple text with `@ConfigurationProperties` field Javadoc since NOTE: You should only use simple text with `@ConfigurationProperties` field Javadoc, since
they are not processed before being added to the JSON. they are not processed before being added to the JSON.
Properties are discovered via the presence of standard getters and setters with special Properties are discovered through the presence of standard getters and setters with
handling for collection types (that will be detected even if only a getter is present). The special handling for collection types (that is detected even if only a getter is present).
annotation processor also supports the use of the `@Data`, `@Getter` and `@Setter` lombok The annotation processor also supports the use of the `@Data`, `@Getter`, and `@Setter`
annotations. lombok annotations.
[NOTE] [NOTE]
==== ====
If you are using AspectJ in your project, you need to make sure that the annotation If you are using AspectJ in your project, you need to make sure that the annotation
processor only runs once. There are several ways to do this: with Maven, you can 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 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 processor only there. You could also let the AspectJ plugin run all the processing
and disable annotation processing in the `maven-compiler-plugin` configuration: and disable annotation processing in the `maven-compiler-plugin` configuration, as
follows:
[source,xml,indent=0,subs="verbatim,quotes,attributes"] [source,xml,indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -782,9 +794,9 @@ and disable annotation processing in the `maven-compiler-plugin` configuration:
[[configuration-metadata-nested-properties]] [[configuration-metadata-nested-properties]]
==== Nested properties ==== Nested Properties
The annotation processor will automatically consider inner classes as nested properties. The annotation processor automatically considers inner classes as nested properties.
For example, the following class: Consider the following class:
[source,java,indent=0,subs="verbatim,quotes,attributes"] [source,java,indent=0,subs="verbatim,quotes,attributes"]
---- ----
@ -810,29 +822,29 @@ For example, the following class:
} }
---- ----
Will produce meta-data information for `server.name`, `server.host.ip` and The preceding example produces metdata information for `server.name`, `server.host.ip`,
`server.host.port` properties. You can use the `@NestedConfigurationProperty` 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 annotation on a field to indicate that a regular (non-inner) class should be treated as
if it were nested. if it were nested.
TIP: This has no effect on collections and maps as those types are automatically TIP: This has no effect on collections and maps, as those types are automatically
identified and a single meta-data property is generated for each of them. identified, and a single metadata property is generated for each of them.
[[configuration-metadata-additional-metadata]] [[configuration-metadata-additional-metadata]]
==== Adding additional meta-data ==== Adding Additional Metadata
Spring Boot's configuration file handling is quite flexible; and it is often the case 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 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 allow may also need to tune some attributes of an existing key. To support such cases and let
you to provide custom "hints", the annotation processor will automatically merge items you provide custom "hints", the annotation processor automatically merges items
from `META-INF/additional-spring-configuration-metadata.json` into the main meta-data from `META-INF/additional-spring-configuration-metadata.json` into the main metadata
file. file.
If you refer to a property that has been detected automatically, the description, 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 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 brand new property declaration is not identified in the current module, it is added as a new
property. property.
The format of the `additional-spring-configuration-metadata.json` file is exactly the same 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 as the regular `spring-configuration-metadata.json`. The additional properties file is
optional, if you don't have any additional properties, simply don't add it. optional. If you do not have any additional properties, do not add the file.

Write Preview
Loading…
Cancel
Save