Merge latest changes for spring-data-commons

Author: rodrigorodrigues

.mvn/wrapper/maven-wrapper.properties

@@ -1,2 +1,2 @@
-#Thu Aug 08 10:22:00 CEST 2024
-distributionUrl=https\://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.8/apache-maven-3.9.8-bin.zip
+#Thu Nov 07 09:47:21 CET 2024
+distributionUrl=https\://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip

Jenkinsfile

@@ -37,9 +37,9 @@ pipeline {
 			steps {
 				script {
 					docker.withRegistry(p['docker.proxy.registry'], p['docker.proxy.credentials']) {
-						docker.image(p['docker.java.main.image']).inside(p['docker.java.inside.basic']) {
+						docker.image(p['docker.java.main.image']).inside(p['docker.java.inside.docker']) {
 							sh 'MAVEN_OPTS="-Duser.name=' + "${p['jenkins.user.name']}" + ' -Duser.home=/tmp/jenkins-home" ' +
-								"./mvnw -s settings.xml clean dependency:list verify -Dsort -B -U"
+								"./mvnw -s settings.xml -Dmaven.repo.local=/tmp/jenkins-home/.m2/spring-data-commons -Ddevelocity.storage.directory=/tmp/jenkins-home/.develocity-root clean dependency:list verify -Dsort -B -U"
 						}
 					}
 				}
@@ -67,9 +67,9 @@ pipeline {
 					steps {
 						script {
 							docker.withRegistry(p['docker.proxy.registry'], p['docker.proxy.credentials']) {
-								docker.image(p['docker.java.next.image']).inside(p['docker.java.inside.basic']) {
+								docker.image(p['docker.java.next.image']).inside(p['docker.java.inside.docker']) {
 									sh 'MAVEN_OPTS="-Duser.name=' + "${p['jenkins.user.name']}" + ' -Duser.home=/tmp/jenkins-home" ' +
-										"./mvnw -s settings.xml clean dependency:list verify -Dsort -B"
+										"./mvnw -s settings.xml -Dmaven.repo.local=/tmp/jenkins-home/.m2/spring-data-commons -Ddevelocity.storage.directory=/tmp/jenkins-home/.develocity-root clean dependency:list verify -Dsort -B"
 								}
 							}
 						}
@@ -99,15 +99,17 @@ pipeline {
 			steps {
 				script {
 					docker.withRegistry(p['docker.proxy.registry'], p['docker.proxy.credentials']) {
-						docker.image(p['docker.java.main.image']).inside(p['docker.java.inside.basic']) {
+						docker.image(p['docker.java.main.image']).inside(p['docker.java.inside.docker']) {
 							sh 'MAVEN_OPTS="-Duser.name=' + "${p['jenkins.user.name']}" + ' -Duser.home=/tmp/jenkins-home" ' +
 									"./mvnw -s settings.xml -Pci,artifactory " +
+									"-Ddevelocity.storage.directory=/tmp/jenkins-home/.develocity-root " +
 									"-Dartifactory.server=${p['artifactory.url']} " +
 									"-Dartifactory.username=${ARTIFACTORY_USR} " +
 									"-Dartifactory.password=${ARTIFACTORY_PSW} " +
 									"-Dartifactory.staging-repository=${p['artifactory.repository.snapshot']} " +
 									"-Dartifactory.build-name=spring-data-commons " +
 									"-Dartifactory.build-number=spring-data-commons-${BRANCH_NAME}-build-${BUILD_NUMBER} " +
+									"-Dmaven.repo.local=/tmp/jenkins-home/.m2/spring-data-commons " +
 									"-Dmaven.test.skip=true clean deploy -U -B"
 						}
 					}

ci/pipeline.properties

@@ -1,6 +1,6 @@
 # Java versions
-java.main.tag=17.0.12_7-jdk-focal
-java.next.tag=22.0.2_9-jdk-jammy
+java.main.tag=17.0.13_11-jdk-focal
+java.next.tag=23.0.1_11-jdk-noble
 
 # Docker container images - standard
 docker.java.main.image=library/eclipse-temurin:${java.main.tag}
@@ -11,6 +11,7 @@ docker.mongodb.4.4.version=4.4.25
 docker.mongodb.5.0.version=5.0.21
 docker.mongodb.6.0.version=6.0.10
 docker.mongodb.7.0.version=7.0.2
+docker.mongodb.8.0.version=8.0.0
 
 # Supported versions of Redis
 docker.redis.6.version=6.2.13

pom.xml

@@ -3,9 +3,9 @@
 
 	<modelVersion>4.0.0</modelVersion>
 
-	<groupId>org.springframework.data</groupId>
+	<groupId>com.github.rodrigorodrigues</groupId>
 	<artifactId>spring-data-commons</artifactId>
-	<version>3.4.0-SNAPSHOT</version>
+	<version>3.5.0-SNAPSHOT</version>
 
 	<name>Spring Data Core</name>
 	<description>Core Spring concepts underpinning every Spring Data module.</description>
@@ -25,7 +25,7 @@
 	<parent>
 		<groupId>org.springframework.data.build</groupId>
 		<artifactId>spring-data-parent</artifactId>
-		<version>3.4.0-SNAPSHOT</version>
+		<version>3.5.0-SNAPSHOT</version>
 	</parent>
 
 	<properties>
@@ -234,7 +234,7 @@
 		<dependency>
 			<groupId>org.codehaus.groovy</groupId>
 			<artifactId>groovy-all</artifactId>
-			<version>2.4.4</version>
+			<version>2.4.21</version>
 			<scope>test</scope>
 		</dependency>
 

src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc

@@ -4,6 +4,18 @@
 The central interface in the Spring Data repository abstraction is `Repository`.
 It takes the domain class to manage as well as the identifier type of the domain class as type arguments.
 This interface acts primarily as a marker interface to capture the types to work with and to help you to discover interfaces that extend this one.
+
+[TIP]
+====
+Spring Data considers domain types to be entities, more specifically aggregates.
+So you will see the term "entity" used throughout the documentation that can be interchanged with the term "domain type" or "aggregate".
+
+As you might have noticed in the introduction it already hinted towards domain-driven concepts.
+We consider domain objects in the sense of DDD.
+Domain objects have identifiers (otherwise these would be identity-less value objects), and we somehow need to refer to identifiers when working with certain patterns to access data.
+Referring to identifiers will become more meaningful as we talk about repositories and query methods.
+====
+
 The {spring-data-commons-javadoc-base}/org/springframework/data/repository/CrudRepository.html[`CrudRepository`] and {spring-data-commons-javadoc-base}/org/springframework/data/repository/ListCrudRepository.html[`ListCrudRepository`] interfaces provide sophisticated CRUD functionality for the entity class that is being managed.
 
 [[repositories.repository]]
@@ -37,6 +49,15 @@ public interface CrudRepository<T, ID> extends Repository<T, ID> {
 The methods declared in this interface are commonly referred to as CRUD methods.
 `ListCrudRepository` offers equivalent methods, but they return `List` where the `CrudRepository` methods return an `Iterable`.
 
+[IMPORTANT]
+====
+The repository interface implies a few reserved methods like `findById(ID identifier)` that target the domain type identifier property regardless of its property name.
+Read more about this in "`xref:repositories/query-methods-details.adoc#repositories.query-methods.reserved-methods[Defining Query Methods]`".
+
+You can annotate your query method with `@Query` to provide a custom query if a property named `Id` doesn't refer to the identifier.
+Following that path can easily lead to confusion and is discouraged as you will quickly hit type limits if the `ID` type and the type of your `Id` property deviate.
+====
+
 NOTE: We also provide persistence technology-specific abstractions, such as `JpaRepository` or `MongoRepository`.
 Those interfaces extend `CrudRepository` and expose the capabilities of the underlying persistence technology in addition to the rather generic persistence technology-agnostic interfaces such as `CrudRepository`.
 

src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc

@@ -23,13 +23,32 @@ interface CustomizedUserRepository {
 ----
 class CustomizedUserRepositoryImpl implements CustomizedUserRepository {
 
+  @Override
   public void someCustomMethod(User user) {
     // Your custom implementation
   }
 }
 ----
 
-NOTE: The most important part of the class name that corresponds to the fragment interface is the `Impl` postfix.
+[NOTE]
+====
+The most important part of the class name that corresponds to the fragment interface is the `Impl` postfix.
+You can customize the store-specific postfix by setting `@Enable<StoreModule>Repositories(repositoryImplementationPostfix = …)`.
+====
+
+[WARNING]
+====
+Historically, Spring Data custom repository implementation discovery followed a
+https://docs.spring.io/spring-data/commons/docs/1.9.0.RELEASE/reference/html/#repositories.single-repository-behaviour[naming pattern]
+that derived the custom implementation class name from the repository allowing effectively a single custom implementation.
+
+A type located in the same package as the repository interface, matching _repository interface name_ followed by _implementation postfix_,
+is considered a custom implementation and will be treated as a custom implementation.
+A class following that name can lead to undesired behavior.
+
+We consider the single-custom implementation naming deprecated and recommend not using this pattern.
+Instead, migrate to a fragment-based programming model.
+====
 
 The implementation itself does not depend on Spring Data and can be a regular Spring bean.
 Consequently, you can use standard dependency injection behavior to inject references to other beans (such as a `JdbcTemplate`), take part in aspects, and so on.
@@ -63,6 +82,7 @@ interface HumanRepository {
 
 class HumanRepositoryImpl implements HumanRepository {
 
+  @Override
   public void someHumanMethod(User user) {
     // Your custom implementation
   }
@@ -77,10 +97,12 @@ interface ContactRepository {
 
 class ContactRepositoryImpl implements ContactRepository {
 
+  @Override
   public void someContactMethod(User user) {
     // Your custom implementation
   }
 
+  @Override
   public User anotherContactMethod(User user) {
     // Your custom implementation
   }
@@ -115,6 +137,7 @@ interface CustomizedSave<T> {
 
 class CustomizedSaveImpl<T> implements CustomizedSave<T> {
 
+  @Override
   public <S extends T> S save(S entity) {
     // Your custom implementation
   }
@@ -271,7 +294,7 @@ package com.acme.search;
 
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.data.domain.Limit;
-import org.springframework.data.repository.core.support.RepositoryMethodContext;
+import org.springframework.data.repository.core.RepositoryMethodContext;
 
 class DefaultSearchExtension<T> implements SearchExtension<T> {
 
@@ -281,8 +304,9 @@ class DefaultSearchExtension<T> implements SearchExtension<T> {
         this.service = service;
     }
 
+    @Override
     public List<T> search(String text, Limit limit) {
-        return search(RepositoryMethodContext.currentMethod(), text, limit);
+        return search(RepositoryMethodContext.getContext(), text, limit);
     }
 
     List<T> search(RepositoryMethodContext metadata, String text, Limit limit) {
@@ -297,12 +321,12 @@ class DefaultSearchExtension<T> implements SearchExtension<T> {
 }
 ----
 
-In the example above `RepositoryMethodContext.currentMethod()` is used to retrieve metadata for the actual method invocation.
+In the example above `RepositoryMethodContext.getContext()` is used to retrieve metadata for the actual method invocation.
 `RepositoryMethodContext` exposes information attached to the repository such as the domain type.
 In this case we use the repository domain type to identify the name of the index to be searched.
 
 Exposing invocation metadata is costly, hence it is disabled by default.
-To access `RepositoryMethodContext.currentMethod()` you need to advise the repository factory responsible for creating the actual repository to expose method metadata.
+To access `RepositoryMethodContext.getContext()` you need to advise the repository factory responsible for creating the actual repository to expose method metadata.
 
 .Expose Repository Metadata
 [tabs]
@@ -319,7 +343,7 @@ package com.acme.search;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.data.domain.Limit;
 import org.springframework.data.repository.core.support.RepositoryMetadataAccess;
-import org.springframework.data.repository.core.support.RepositoryMethodContext;
+import org.springframework.data.repository.core.RepositoryMethodContext;
 
 class DefaultSearchExtension<T> implements SearchExtension<T>, RepositoryMetadataAccess {
 
@@ -411,6 +435,7 @@ class MyRepositoryImpl<T, ID>
     this.entityManager = entityManager;
   }
 
+  @Override
   @Transactional
   public <S extends T> S save(S entity) {
     // implementation goes here

src/main/antora/modules/ROOT/pages/repositories/definition.adoc

@@ -18,7 +18,7 @@ If you are using a reactive store you might choose `ReactiveCrudRepository`, or
 
 If you are using Kotlin you might pick `CoroutineCrudRepository` which utilizes Kotlin's coroutines.
 
-Additional you can extend `PagingAndSortingRepository`, `ReactiveSortingRepository`, `RxJava3SortingRepository`, or `CoroutineSortingRepository` if you need methods that allow to specify a `Sort` abstraction or in the first case a `Pageable` abstraction.
+Additionally you can extend `PagingAndSortingRepository`, `ReactiveSortingRepository`, `RxJava3SortingRepository`, or `CoroutineSortingRepository` if you need methods that allow to specify a `Sort` abstraction or in the first case a `Pageable` abstraction.
 Note that the various sorting repositories no longer extended their respective CRUD repository as they did in Spring Data Versions pre 3.0.
 Therefore, you need to extend both interfaces if you want functionality of both.
 

src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc

@@ -21,6 +21,22 @@ Consult the store-specific documentation for the exact list of supported keyword
 |`…Distinct…`| Use a distinct query to return only unique results. Consult the store-specific documentation whether that feature is supported. This keyword can occur in any place of the subject between `find` (and the other keywords) and `by`.
 |===============
 
+[[appendix.query.method.reserved]]
+== Reserved methods
+
+The following table lists reserved methods that use predefined functionality (as defined in `CrudRepository`).
+These methods are directly invoked on the backing (store-specific) implementation of the repository proxy.
+See also "`xref:repositories/query-methods-details.adoc#repositories.query-methods.reserved-methods[Defining Query Methods]`".
+
+.Reserved methods
+|===============
+|`deleteAllById(Iterable<ID> identifiers)`
+|`deleteById(ID identifier)`
+|`existsById(ID identifier)`
+|`findAllById(Iterable<ID> identifiers)`
+|`findById(ID identifier)`
+|===============
+
 [[appendix.query.method.predicate]]
 == Supported query method predicate keywords and modifiers
 

src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc

@@ -86,6 +86,47 @@ Whether ignoring cases is supported may vary by store, so consult the relevant s
 - You can apply static ordering by appending an `OrderBy` clause to the query method that references a property and by providing a sorting direction (`Asc` or `Desc`).
 To create a query method that supports dynamic sorting, see "`xref:repositories/query-methods-details.adoc#repositories.special-parameters[Paging, Iterating Large Results, Sorting & Limiting]`".
 
+[[repositories.query-methods.reserved-methods]]
+== Reserved Method Names
+
+While derived repository methods bind to properties by name, there are a few exceptions to this rule when it comes to certain method names inherited from the base repository targeting the _identifier_ property.
+Those _reserved methods_ like `CrudRepository#findById` (or just `findById`) are targeting the _identifier_ property regardless of the actual property name used in the declared method.
+
+Consider the following domain type holding a property `pk` marked as the identifier via `@Id` and a property called `id`.
+In this case you need to pay close attention to the naming of your lookup methods as they may collide with predefined signatures:
+
+====
+[source,java]
+----
+class User {
+  @Id Long pk;                          <1>
+
+  Long id;                              <2>
+
+  // …
+}
+
+interface UserRepository extends Repository<User, Long> {
+
+  Optional<User> findById(Long id);     <3>
+
+  Optional<User> findByPk(Long pk);     <4>
+
+  Optional<User> findUserById(Long id); <5>
+}
+----
+
+<1> The identifier property (primary key).
+<2> A property named `id`, but not the identifier.
+<3> Targets the `pk` property (the one marked with `@Id` which is considered to be the identifier) as it refers to a `CrudRepository` base repository method.
+Therefore, it is not a derived query using of `id` as the property name would suggest because it is one of the _reserved methods_.
+<4> Targets the `pk` property by name as it is a derived query.
+<5> Targets the `id` property by using the descriptive token between `find` and `by` to avoid collisions with _reserved methods_.
+====
+
+This special behaviour not only targets lookup methods but also applies to the `exits` and `delete` ones.
+Please refer to the "`xref:repositories/query-keywords-reference.adoc#appendix.query.method.reserved[Repository query keywords]`" for the list of methods.
+
 [[repositories.query-methods.query-property-expressions]]
 == Property Expressions
 
@@ -198,7 +239,7 @@ class Products implements Streamable<Product> {         <2>
 
   public MonetaryAmount getTotal() {                    <3>
     return streamable.stream()
-      .map(Priced::getPrice)
+      .map(Product::getPrice)
       .reduce(Money.of(0), MonetaryAmount::add);
   }
 

src/main/antora/modules/ROOT/pages/repositories/scrolling.adoc

@@ -30,6 +30,14 @@ Query execution treats the position parameter _exclusive_, results will start _a
 `ScrollPosition#offset()` and `ScrollPosition#keyset()` as special incarnations of a `ScrollPosition` indicating the start of a scroll operation.
 ====
 
+[NOTE]
+====
+The above example shows static sorting and limiting.
+You can define query methods alternatively that accept a `Sort` object define a more complex sorting order or sorting on a per-request basis.
+In a similar way, providing a `Limit` object allows you to define a dynamic limit on a per-request basis instead of applying a static limitation.
+Read more on dynamic sorting and limiting in the xref:repositories/query-methods-details.adoc#repositories.special-parameters[Query Methods Details].
+====
+
 `WindowIterator` provides a utility to simplify scrolling across ``Window``s by removing the need to check for the presence of a next `Window` and applying the `ScrollPosition`.
 
 [source,java]