"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/developing-auto-configuration.adoc" between
spring-boot-2.7.3.tar.gz and spring-boot-2.7.4.tar.gz

About: Spring Boot 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

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)