helps to create Spring-powered, production-grade applications and services.
| developing-auto-configuration.adoc (spring-boot-2.7.3) | : | developing-auto-configuration.adoc (spring-boot-2.7.4) |
|---|
| [[features.developing-auto-configuration]] | | [[features.developing-auto-configuration]] |
| == Creating Your Own Auto-configuration | | == Creating Your Own Auto-configuration |
| If you work in a company that develops shared libraries, or if you work on an op
en-source or commercial library, you might want to develop your own auto-configu
ration. | | If you work in a company that develops shared libraries, or if you work on an op
en-source or commercial library, you might want to develop your own auto-configu
ration. |
| Auto-configuration classes can be bundled in external jars and still be picked-u
p by Spring Boot. | | Auto-configuration classes can be bundled in external jars and still be picked-u
p by Spring Boot. |
| | |
| Auto-configuration can be associated to a "`starter`" that provides the auto-con
figuration code as well as the typical libraries that you would use with it. | | Auto-configuration can be associated to a "`starter`" that provides the auto-con
figuration code as well as the typical libraries that you would use with it. |
| We first cover what you need to know to build your own auto-configuration and th
en we move on to the <<features#features.developing-auto-configuration.custom-st
arter,typical steps required to create a custom starter>>. | | We first cover what you need to know to build your own auto-configuration and th
en we move on to the <<features#features.developing-auto-configuration.custom-st
arter,typical steps required to create a custom starter>>. |
| | |
|
| TIP: A https://github.com/snicoll-demos/spring-boot-master-auto-configuration[de | | |
| mo project] is available to showcase how you can create a starter step-by-step. | | |
| | | |
| [[features.developing-auto-configuration.understanding-auto-configured-beans]] | | [[features.developing-auto-configuration.understanding-auto-configured-beans]] |
| === Understanding Auto-configured Beans | | === Understanding Auto-configured Beans |
|
| Under the hood, auto-configuration is implemented with the `@AutoConfiguration`
annotation. | | Classes that implement auto-configuration are annotated with `@AutoConfiguration
`. |
| This annotation itself is meta-annotated with `@Configuration`, making auto-conf
igurations standard `@Configuration` classes. | | This annotation itself is meta-annotated with `@Configuration`, making auto-conf
igurations standard `@Configuration` classes. |
| Additional `@Conditional` annotations are used to constrain when the auto-config
uration should apply. | | Additional `@Conditional` annotations are used to constrain when the auto-config
uration should apply. |
| Usually, auto-configuration classes use `@ConditionalOnClass` and `@ConditionalO
nMissingBean` annotations. | | Usually, auto-configuration classes use `@ConditionalOnClass` and `@ConditionalO
nMissingBean` annotations. |
| This ensures that auto-configuration applies only when relevant classes are foun
d and when you have not declared your own `@Configuration`. | | This ensures that auto-configuration applies only when relevant classes are foun
d and when you have not declared your own `@Configuration`. |
| | |
|
| You can browse the source code of {spring-boot-autoconfigure-module-code}[`sprin
g-boot-autoconfigure`] to see the `@Configuration` classes that Spring provides
(see the {spring-boot-code}/spring-boot-project/spring-boot-autoconfigure/src/ma
in/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfigur
ation.imports[`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfig
uration.imports`] file). | | You can browse the source code of {spring-boot-autoconfigure-module-code}[`sprin
g-boot-autoconfigure`] to see the `@AutoConfiguration` classes that Spring provi
des (see the {spring-boot-code}/spring-boot-project/spring-boot-autoconfigure/sr
c/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConf
iguration.imports[`META-INF/spring/org.springframework.boot.autoconfigure.AutoCo
nfiguration.imports`] file). |
| | |
| [[features.developing-auto-configuration.locating-auto-configuration-candidates]
] | | [[features.developing-auto-configuration.locating-auto-configuration-candidates]
] |
| === Locating Auto-configuration Candidates | | === Locating Auto-configuration Candidates |
| | |
| Spring Boot checks for the presence of a `META-INF/spring/org.springframework.bo
ot.autoconfigure.AutoConfiguration.imports` file within your published jar. | | Spring Boot checks for the presence of a `META-INF/spring/org.springframework.bo
ot.autoconfigure.AutoConfiguration.imports` file within your published jar. |
|
| The file should list your configuration classes, as shown in the following examp
le: | | The file should list your configuration classes, with one class name per line, a
s shown in the following example: |
| | |
| [indent=0] | | [indent=0] |
| ---- | | ---- |
| com.mycorp.libx.autoconfigure.LibXAutoConfiguration | | com.mycorp.libx.autoconfigure.LibXAutoConfiguration |
| com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration | | com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration |
| ---- | | ---- |
| | |
|
| TIP: You can use comments via `#` in this file. | | TIP: You can add comments to the imports file using the `#` character. |
| | |
|
| NOTE: Auto-configurations must be loaded that way _only_. | | NOTE: Auto-configurations must be loaded _only_ by being named in the imports fi
le. |
| Make sure that they are defined in a specific package space and that they are ne
ver the target of component scanning. | | Make sure that they are defined in a specific package space and that they are ne
ver the target of component scanning. |
| Furthermore, auto-configuration classes should not enable component scanning to
find additional components. | | Furthermore, auto-configuration classes should not enable component scanning to
find additional components. |
| Specific ``@Import``s should be used instead. | | Specific ``@Import``s should be used instead. |
| | |
|
| You can use the {spring-boot-autoconfigure-module-code}/AutoConfigureAfter.java[
`@AutoConfigureAfter`] or {spring-boot-autoconfigure-module-code}/AutoConfigureB
efore.java[`@AutoConfigureBefore`] annotations if your configuration needs to be
applied in a specific order. | | If your configuration needs to be applied in a specific order, you can use the `
before`, `beforeName`, `after` and `afterName` attributes on the {spring-boot-au
toconfigure-module-code}/AutoConfiguration.java[`@AutoConfiguration`] annotation
or the dedicated {spring-boot-autoconfigure-module-code}/AutoConfigureBefore.ja
va[`@AutoConfigureBefore`] and {spring-boot-autoconfigure-module-code}/AutoConfi
gureAfter.java[`@AutoConfigureAfter`] annotations. |
| For example, if you provide web-specific configuration, your class may need to b
e applied after `WebMvcAutoConfiguration`. | | For example, if you provide web-specific configuration, your class may need to b
e applied after `WebMvcAutoConfiguration`. |
| | |
|
| TIP: If you are using the {spring-boot-autoconfigure-module-code}/AutoConfigurat | | |
| ion.java[`@AutoConfiguration`] annotation, you can use the `before`, `beforeName | | |
| `, `after` and `afterName` attribute aliases instead of the dedicated annotation | | |
| s. | | |
| | | |
| If you want to order certain auto-configurations that should not have any direct
knowledge of each other, you can also use `@AutoConfigureOrder`. | | If you want to order certain auto-configurations that should not have any direct
knowledge of each other, you can also use `@AutoConfigureOrder`. |
| That annotation has the same semantic as the regular `@Order` annotation but pro
vides a dedicated order for auto-configuration classes. | | That annotation has the same semantic as the regular `@Order` annotation but pro
vides a dedicated order for auto-configuration classes. |
| | |
| As with standard `@Configuration` classes, the order in which auto-configuration
classes are applied only affects the order in which their beans are defined. | | As with standard `@Configuration` classes, the order in which auto-configuration
classes are applied only affects the order in which their beans are defined. |
| The order in which those beans are subsequently created is unaffected and is det
ermined by each bean's dependencies and any `@DependsOn` relationships. | | The order in which those beans are subsequently created is unaffected and is det
ermined by each bean's dependencies and any `@DependsOn` relationships. |
| | |
| [[features.developing-auto-configuration.condition-annotations]] | | [[features.developing-auto-configuration.condition-annotations]] |
| === Condition Annotations | | === Condition Annotations |
| You almost always want to include one or more `@Conditional` annotations on your
auto-configuration class. | | You almost always want to include one or more `@Conditional` annotations on your
auto-configuration class. |
| The `@ConditionalOnMissingBean` annotation is one common example that is used to
allow developers to override auto-configuration if they are not happy with your
defaults. | | The `@ConditionalOnMissingBean` annotation is one common example that is used to
allow developers to override auto-configuration if they are not happy with your
defaults. |
| | |
| skipping to change at line 235 | | skipping to change at line 231 |
|---|
| [[features.developing-auto-configuration.custom-starter.autoconfigure-module]] | | [[features.developing-auto-configuration.custom-starter.autoconfigure-module]] |
| ==== The "`autoconfigure`" Module | | ==== The "`autoconfigure`" Module |
| The `autoconfigure` module contains everything that is necessary to get started
with the library. | | The `autoconfigure` module contains everything that is necessary to get started
with the library. |
| It may also contain configuration key definitions (such as `@ConfigurationProper
ties`) and any callback interface that can be used to further customize how the
components are initialized. | | It may also contain configuration key definitions (such as `@ConfigurationProper
ties`) and any callback interface that can be used to further customize how the
components are initialized. |
| | |
| TIP: You should mark the dependencies to the library as optional so that you can
include the `autoconfigure` module in your projects more easily. | | TIP: You should mark the dependencies to the library as optional so that you can
include the `autoconfigure` module in your projects more easily. |
| If you do it that way, the library is not provided and, by default, Spring Boot
backs off. | | If you do it that way, the library is not provided and, by default, Spring Boot
backs off. |
| | |
| Spring Boot uses an annotation processor to collect the conditions on auto-confi
gurations in a metadata file (`META-INF/spring-autoconfigure-metadata.properties
`). | | Spring Boot uses an annotation processor to collect the conditions on auto-confi
gurations in a metadata file (`META-INF/spring-autoconfigure-metadata.properties
`). |
| If that file is present, it is used to eagerly filter auto-configurations that d
o not match, which will improve startup time. | | If that file is present, it is used to eagerly filter auto-configurations that d
o not match, which will improve startup time. |
|
| It is recommended to add the following dependency in a module that contains auto | | |
| -configurations: | | When building with Maven, it is recommended to add the following dependency in a |
| | module that contains auto-configurations: |
| | |
| [source,xml,indent=0,subs="verbatim"] | | [source,xml,indent=0,subs="verbatim"] |
| ---- | | ---- |
| <dependency> | | <dependency> |
| <groupId>org.springframework.boot</groupId> | | <groupId>org.springframework.boot</groupId> |
| <artifactId>spring-boot-autoconfigure-processor</artifactId> | | <artifactId>spring-boot-autoconfigure-processor</artifactId> |
| <optional>true</optional> | | <optional>true</optional> |
| </dependency> | | </dependency> |
| ---- | | ---- |
| | |
| | |
| skipping to change at line 270 | | skipping to change at line 267 |
|---|
| <artifactId>sprin
g-boot-autoconfigure-processor</artifactId> | | <artifactId>sprin
g-boot-autoconfigure-processor</artifactId> |
| </exclude> | | </exclude> |
| </excludes> | | </excludes> |
| </configuration> | | </configuration> |
| </plugin> | | </plugin> |
| </plugins> | | </plugins> |
| </build> | | </build> |
| </project> | | </project> |
| ---- | | ---- |
| | |
|
| With Gradle 4.5 and earlier, the dependency should be declared in the `compileOn | | With Gradle, the dependency should be declared in the `annotationProcessor` conf |
| ly` configuration, as shown in the following example: | | iguration, as shown in the following example: |
| | |
| [source,gradle,indent=0,subs="verbatim"] | | |
| dependencies { | | |
| compileOnly "org.springframework.boot:spring-boot-autoconfigure-p | | |
| rocessor" | | |
| } | | |
| | |
| With Gradle 4.6 and later, the dependency should be declared in the `annotationP | | |
| rocessor` configuration, as shown in the following example: | | |
| | |
| [source,gradle,indent=0,subs="verbatim"] | | [source,gradle,indent=0,subs="verbatim"] |
| ---- | | ---- |
| dependencies { | | dependencies { |
| annotationProcessor "org.springframework.boot:spring-boot-autocon
figure-processor" | | annotationProcessor "org.springframework.boot:spring-boot-autocon
figure-processor" |
| } | | } |
| ---- | | ---- |
| | |
| [[features.developing-auto-configuration.custom-starter.starter-module]] | | [[features.developing-auto-configuration.custom-starter.starter-module]] |
| ==== Starter Module | | ==== Starter Module |
| | | |
| End of changes. 10 change blocks. |
|---|
| 27 lines changed or deleted | | 11 lines changed or added |
|---|
"Fossies" - the Fresh Open Source Software Archive 