From 1498faaf7f8d78064e7dc5c6d933909d2a279a5d Mon Sep 17 00:00:00 2001 From: Andy Wilkinson Date: Thu, 26 Oct 2023 08:42:26 +0100 Subject: [PATCH] Document auto-configuration packages and how to add to them Closes gh-27549 --- .../src/docs/asciidoc/data/nosql.adoc | 12 ++++++------ .../spring-boot-docs/src/docs/asciidoc/data/sql.adoc | 6 +++--- .../src/docs/asciidoc/howto/data-access.adoc | 10 +++++----- .../src/docs/asciidoc/using/auto-configuration.adoc | 7 +++++++ 4 files changed, 21 insertions(+), 14 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/data/nosql.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/data/nosql.adoc index 7fd96eb6077..3c8da43f45b 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/data/nosql.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/data/nosql.adoc @@ -146,7 +146,7 @@ You could take the JPA example from earlier and, assuming that `City` is now a M include::code:CityRepository[] Repositories and documents are found through scanning. -By default, the package containing your main configuration class (the one annotated with `@EnableAutoConfiguration` or `@SpringBootApplication`) and all those below it are searched. +By default, the <> are scanned. You can customize the locations to look for repositories and documents by using `@EnableMongoRepositories` and `@EntityScan` respectively. TIP: For complete details of Spring Data MongoDB, including its rich object mapping technologies, see its {spring-data-mongodb}[reference documentation]. @@ -223,7 +223,7 @@ Spring Boot supports both classic and reactive Neo4j repositories, using the `Ne When Project Reactor is available on the classpath, the reactive style is also auto-configured. Repositories and entities are found through scanning. -By default, the package containing your main configuration class (the one annotated with `@EnableAutoConfiguration` or `@SpringBootApplication`) and all those below it are searched. +By default, the <> are scanned. You can customize the locations to look for repositories and entities by using `@EnableNeo4jRepositories` and `@EntityScan` respectively. [NOTE] @@ -355,7 +355,7 @@ In fact, both Spring Data JPA and Spring Data Elasticsearch share the same commo You could take the JPA example from earlier and, assuming that `City` is now an Elasticsearch `@Document` class rather than a JPA `@Entity`, it works in the same way. Repositories and documents are found through scanning. -By default, the package containing your main configuration class (the one annotated with `@EnableAutoConfiguration` or `@SpringBootApplication`) and all those below it are searched. +By default, the <> are scanned. You can customize the locations to look for repositories and documents by using `@EnableElasticsearchRepositories` and `@EntityScan` respectively. TIP: For complete details of Spring Data Elasticsearch, see the {spring-data-elasticsearch-docs}[reference documentation]. @@ -445,7 +445,7 @@ Spring Data includes basic repository support for Cassandra. Currently, this is more limited than the JPA repositories discussed earlier and needs to annotate finder methods with `@Query`. Repositories and entities are found through scanning. -By default, the package containing your main configuration class (the one annotated with `@EnableAutoConfiguration` or `@SpringBootApplication`) and all those below it are searched. +By default, the <> are scanned. You can customize the locations to look for repositories and entities by using `@EnableCassandraRepositories` and `@EntityScan` respectively. TIP: For complete details of Spring Data Cassandra, see the https://docs.spring.io/spring-data/cassandra/docs/[reference documentation]. @@ -500,7 +500,7 @@ To take more control, one or more `ClusterEnvironmentBuilderCustomizer` beans ca Spring Data includes repository support for Couchbase. Repositories and documents are found through scanning. -By default, the package containing your main configuration class (the one annotated with `@EnableAutoConfiguration` or `@SpringBootApplication`) and all those below it are searched. +By default, the <> are scanned. You can customize the locations to look for repositories and documents by using `@EnableCouchbaseRepositories` and `@EntityScan` respectively. For complete details of Spring Data Couchbase, see the {spring-data-couchbase-docs}[reference documentation]. @@ -570,7 +570,7 @@ Make sure to flag your customized `ContextSource` as `@Primary` so that the auto Spring Data includes repository support for LDAP. Repositories and documents are found through scanning. -By default, the package containing your main configuration class (the one annotated with `@EnableAutoConfiguration` or `@SpringBootApplication`) and all those below it are searched. +By default, the <> are scanned. You can customize the locations to look for repositories and documents by using `@EnableLdapRepositories` and `@EntityScan` respectively. For complete details of Spring Data LDAP, see the https://docs.spring.io/spring-data/ldap/docs/1.0.x/reference/html/[reference documentation]. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/data/sql.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/data/sql.adoc index baaa74dedd7..e867b6ce637 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/data/sql.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/data/sql.adoc @@ -195,7 +195,7 @@ You can follow the https://spring.io/guides/gs/accessing-data-jpa/["`Accessing D ==== Entity Classes Traditionally, JPA "`Entity`" classes are specified in a `persistence.xml` file. With Spring Boot, this file is not necessary and "`Entity Scanning`" is used instead. -By default, all packages below your main configuration class (the one annotated with `@EnableAutoConfiguration` or `@SpringBootApplication`) are searched. +By default the <> are scanned. Any classes annotated with `@Entity`, `@Embeddable`, or `@MappedSuperclass` are considered. A typical entity class resembles the following example: @@ -216,7 +216,7 @@ For example, a `CityRepository` interface might declare a `findAllByState(String For more complex queries, you can annotate your method with Spring Data's {spring-data-jpa-api}/repository/Query.html[`Query`] annotation. Spring Data repositories usually extend from the {spring-data-commons-api}/repository/Repository.html[`Repository`] or {spring-data-commons-api}/repository/CrudRepository.html[`CrudRepository`] interfaces. -If you use auto-configuration, repositories are searched from the package containing your main configuration class (the one annotated with `@EnableAutoConfiguration` or `@SpringBootApplication`) down. +If you use auto-configuration, the <> are searched for repositories. TIP: You can customize the locations to look for repositories using `@EnableJpaRepositories`. @@ -506,7 +506,7 @@ For example, a `CityRepository` interface might declare a `findAllByState(String For more complex queries, you can annotate your method with Spring Data's {spring-data-r2dbc-api}/repository/Query.html[`Query`] annotation. Spring Data repositories usually extend from the {spring-data-commons-api}/repository/Repository.html[`Repository`] or {spring-data-commons-api}/repository/CrudRepository.html[`CrudRepository`] interfaces. -If you use auto-configuration, repositories are searched from the package containing your main configuration class (the one annotated with `@EnableAutoConfiguration` or `@SpringBootApplication`) down. +If you use auto-configuration, the <> are searched for repositories. The following example shows a typical Spring Data repository interface definition: diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/data-access.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/data-access.adoc index d31f095ecbd..2c06647b91b 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/data-access.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/data-access.adoc @@ -150,14 +150,14 @@ Note that each `configuration` sub namespace provides advanced settings based on [[howto.data-access.spring-data-repositories]] === Use Spring Data Repositories Spring Data can create implementations of `@Repository` interfaces of various flavors. -Spring Boot handles all of that for you, as long as those `@Repositories` are included in the same package (or a sub-package) of your `@EnableAutoConfiguration` class. +Spring Boot handles all of that for you, as long as those `@Repositories` are included in one of the <>, typically the package (or a sub-package) of your main application class that is annotated with `@SpringBootApplication` or `@EnableAutoConfiguration`. For many applications, all you need is to put the right Spring Data dependencies on your classpath. There is a `spring-boot-starter-data-jpa` for JPA, `spring-boot-starter-data-mongodb` for Mongodb, and various other starters for supported technologies. To get started, create some repository interfaces to handle your `@Entity` objects. -Spring Boot tries to guess the location of your `@Repository` definitions, based on the `@EnableAutoConfiguration` it finds. -To get more control, use the `@EnableJpaRepositories` annotation (from Spring Data JPA). +Spring Boot determines the location of your `@Repository` definitions by scanning the <>. +For more control, use the `@Enable…Repositories` annotations from Spring Data. For more about Spring Data, see the {spring-data}[Spring Data project page]. @@ -165,8 +165,8 @@ For more about Spring Data, see the {spring-data}[Spring Data project page]. [[howto.data-access.separate-entity-definitions-from-spring-configuration]] === Separate @Entity Definitions from Spring Configuration -Spring Boot tries to guess the location of your `@Entity` definitions, based on the `@EnableAutoConfiguration` it finds. -To get more control, you can use the `@EntityScan` annotation, as shown in the following example: +Spring Boot determines the location of your `@Entity` definitions by scanning the <>. +For more control, use the `@EntityScan` annotation, as shown in the following example: include::code:MyApplication[] diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using/auto-configuration.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using/auto-configuration.adoc index c11c9b95045..b3c7375f236 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using/auto-configuration.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using/auto-configuration.adoc @@ -35,3 +35,10 @@ TIP: You can define exclusions both at the annotation level and by using the pro NOTE: Even though auto-configuration classes are `public`, the only aspect of the class that is considered public API is the name of the class which can be used for disabling the auto-configuration. The actual contents of those classes, such as nested configuration classes or bean methods are for internal use only and we do not recommend using those directly. + + +[[using.auto-configuration.packages]] +=== Auto-configuration Packages +Auto-configuration packages are the packages that various auto-configured features look in by default when scanning for things such as entities and Spring Data repositories. +The `@EnableAutoConfiguration` annotation (either directly or through its presence on `@SpringBootApplication`) determines the default auto-configuration package. +Additional packages can be configured using the `@AutoConfigurationPackage` annotation.