Merge branch 'spring-projects:main' into main

Author: rodrigorodrigues

.mvn/wrapper/maven-wrapper.properties

@@ -1,2 +1,2 @@
-#Fri Jun 03 09:32:43 CEST 2022
-distributionUrl=https\://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.8.5/apache-maven-3.8.5-bin.zip
+#Tue Jun 13 08:54:57 CEST 2023
+distributionUrl=https\://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.2/apache-maven-3.9.2-bin.zip

Jenkinsfile

@@ -1,7 +1,7 @@
 def p = [:]
 node {
-    checkout scm
-    p = readProperties interpolate: true, file: 'ci/pipeline.properties'
+	checkout scm
+	p = readProperties interpolate: true, file: 'ci/pipeline.properties'
 }
 
 pipeline {
@@ -18,7 +18,7 @@ pipeline {
 	}
 
 	stages {
-		stage("test: baseline (Java 17)") {
+		stage("test: baseline (main)") {
 			when {
 				beforeAgent(true)
 				anyOf {
@@ -42,6 +42,34 @@ pipeline {
 			}
 		}
 
+		stage("Test other configurations") {
+			when {
+				beforeAgent(true)
+				allOf {
+					branch(pattern: "main|(\\d\\.\\d\\.x)", comparator: "REGEXP")
+					not { triggeredBy 'UpstreamCause' }
+				}
+			}
+			parallel {
+				stage("test: baseline (next)") {
+					agent {
+						label 'data'
+					}
+					options { timeout(time: 30, unit: 'MINUTES') }
+					environment {
+						ARTIFACTORY = credentials("${p['artifactory.credentials']}")
+					}
+					steps {
+						script {
+							docker.image(p['docker.java.next.image']).inside(p['docker.java.inside.basic']) {
+								sh 'MAVEN_OPTS="-Duser.name=jenkins -Duser.home=/tmp/jenkins-home" ./mvnw -s settings.xml clean dependency:list verify -Dsort -U -B'
+							}
+						}
+					}
+				}
+			}
+		}
+
 		stage('Release to artifactory') {
 			when {
 				beforeAgent(true)

ci/pipeline.properties

@@ -1,16 +1,18 @@
 # Java versions
-java.main.tag=17.0.4.1_1-jdk-focal
+java.main.tag=17.0.6_10-jdk-focal
+java.next.tag=20-jdk-jammy
 
 # Docker container images - standard
 docker.java.main.image=harbor-repo.vmware.com/dockerhub-proxy-cache/library/eclipse-temurin:${java.main.tag}
+docker.java.next.image=harbor-repo.vmware.com/dockerhub-proxy-cache/library/eclipse-temurin:${java.next.tag}
 
 # Supported versions of MongoDB
-docker.mongodb.4.4.version=4.4.17
-docker.mongodb.5.0.version=5.0.13
-docker.mongodb.6.0.version=6.0.2
+docker.mongodb.4.4.version=4.4.18
+docker.mongodb.5.0.version=5.0.14
+docker.mongodb.6.0.version=6.0.4
 
 # Supported versions of Redis
-docker.redis.6.version=6.2.6
+docker.redis.6.version=6.2.10
 
 # Supported versions of Cassandra
 docker.cassandra.3.version=3.11.14

pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-commons</artifactId>
-	<version>3.0.0-SNAPSHOT</version>
+	<version>3.2.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.0.0-SNAPSHOT</version>
+		<version>3.2.0-SNAPSHOT</version>
 	</parent>
 
 	<properties>
@@ -366,16 +366,19 @@
 
 	<repositories>
 		<repository>
-			<id>spring-libs-snapshot</id>
-			<url>https://repo.spring.io/libs-snapshot</url>
+			<id>spring-snapshot</id>
+			<url>https://repo.spring.io/snapshot</url>
+			<snapshots>
+				<enabled>true</enabled>
+			</snapshots>
+			<releases>
+				<enabled>false</enabled>
+			</releases>
+		</repository>
+		<repository>
+			<id>spring-milestone</id>
+			<url>https://repo.spring.io/milestone</url>
 		</repository>
 	</repositories>
 
-	<pluginRepositories>
-		<pluginRepository>
-			<id>spring-plugins-release</id>
-			<url>https://repo.spring.io/plugins-release</url>
-		</pluginRepository>
-	</pluginRepositories>
-
 </project>

src/main/asciidoc/dependencies.adoc

@@ -30,7 +30,7 @@ The version name follows `${calver}` for GA releases and service releases and th
 * `M1`, `M2`, and so on: Milestones
 * `RC1`, `RC2`, and so on: Release candidates
 
-You can find a working example of using the BOMs in our https://github.com/spring-projects/spring-data-examples/tree/master/bom[Spring Data examples repository]. With that in place, you can declare the Spring Data modules you would like to use without a version in the `<dependencies />` block, as follows:
+You can find a working example of using the BOMs in our https://github.com/spring-projects/spring-data-examples/tree/main/bom[Spring Data examples repository]. With that in place, you can declare the Spring Data modules you would like to use without a version in the `<dependencies />` block, as follows:
 
 .Declaring a dependency to a Spring Data module
 ====
@@ -48,8 +48,12 @@ You can find a working example of using the BOMs in our https://github.com/sprin
 [[dependencies.spring-boot]]
 == Dependency Management with Spring Boot
 
-Spring Boot selects a recent version of Spring Data modules for you. If you still want to upgrade to a newer version, set
-the `spring-data-releasetrain.version` property to the <<dependencies.train-version,train version and iteration>> you would like to use.
+Spring Boot selects a recent version of the Spring Data modules for you. If you still want to upgrade to a newer version,
+set the `spring-data-bom.version` property to the <<dependencies.train-version,train version and iteration>>
+you would like to use.
+
+See Spring Boot's https://docs.spring.io/spring-boot/docs/current/reference/html/dependency-versions.html#appendix.dependency-versions.properties[documentation]
+(search for "Spring Data Bom") for more details.
 
 [[dependencies.spring-framework]]
 == Spring Framework

src/main/asciidoc/index.adoc

@@ -2,6 +2,7 @@
 Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Pollack; Thomas Risberg; Mark Paluch; Jay Bryant
 :revnumber: {version}
 :revdate: {localdate}
+:feature-scroll: true
 ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]]
 
 (C) 2008-2022 The original authors.

src/main/asciidoc/kotlin.adoc

@@ -11,15 +11,15 @@ This comprehensive https://spring.io/guides/tutorials/spring-boot-kotlin/[tutori
 [[kotlin.requirements]]
 == Requirements
 
-Spring Data supports Kotlin 1.3 and requires https://bintray.com/bintray/jcenter/org.jetbrains.kotlin%3Akotlin-stdlib[`kotlin-stdlib`] (or one of its variants, such as https://bintray.com/bintray/jcenter/org.jetbrains.kotlin%3Akotlin-stdlib-jdk8[`kotlin-stdlib-jdk8`]) and https://bintray.com/bintray/jcenter/org.jetbrains.kotlin%3Akotlin-reflect[`kotlin-reflect`] to be present on the classpath.
+Spring Data supports Kotlin 1.3 and requires `kotlin-stdlib` (or one of its variants, such as `kotlin-stdlib-jdk8`) and `kotlin-reflect` to be present on the classpath.
 Those are provided by default if you bootstrap a Kotlin project via https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io].
 
 [[kotlin.null-safety]]
 == Null Safety
 
-One of Kotlin's key features is https://kotlinlang.org/docs/reference/null-safety.html[null safety], which cleanly deals with `null` values at compile time.
+One of Kotlin's key features is https://kotlinlang.org/docs/null-safety.html[null safety], which cleanly deals with `null` values at compile time.
 This makes applications safer through nullability declarations and the expression of "`value or no value`" semantics without paying the cost of wrappers, such as `Optional`.
-(Kotlin allows using functional constructs with nullable values. See this https://www.baeldung.com/kotlin-null-safety[comprehensive guide to Kotlin null safety].)
+(Kotlin allows using functional constructs with nullable values. See this https://www.baeldung.com/kotlin/null-safety[comprehensive guide to Kotlin null safety].)
 
 Although Java does not let you express null safety in its type system, Spring Data API is annotated with https://jcp.org/en/jsr/detail?id=305[JSR-305] tooling friendly annotations declared in the `org.springframework.lang` package.
 By default, types from Java APIs used in Kotlin are recognized as https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types], for which null checks are relaxed.

src/main/asciidoc/object-mapping.adoc

@@ -203,8 +203,8 @@ The wither method is optional as the persistence constructor (see 6) is effectiv
 <3> The `age` property is an immutable but derived one from the `birthday` property.
 With the design shown, the database value will trump the defaulting as Spring Data uses the only declared constructor.
 Even if the intent is that the calculation should be preferred, it's important that this constructor also takes `age` as parameter (to potentially ignore it) as otherwise the property population step will attempt to set the age field and fail due to it being immutable and no `with…` method being present.
-<4> The `comment` property is mutable is populated by setting its field directly.
-<5> The `remarks` properties are mutable and populated by setting the `comment` field directly or by invoking the setter method for
+<4> The `comment` property is mutable and is populated by setting its field directly.
+<5> The `remarks` property is mutable and is populated by invoking the setter method.
 <6> The class exposes a factory method and a constructor for object creation.
 The core idea here is to use factory methods instead of additional constructors to avoid the need for constructor disambiguation through `@PersistenceCreator`.
 Instead, defaulting of properties is handled within the factory method.

src/main/asciidoc/preface.adoc

@@ -7,6 +7,6 @@ The Spring Data Commons project applies core Spring concepts to the development
 
 * Version control: https://github.com/spring-projects/spring-data-commons
 * Bugtracker: https://github.com/spring-projects/spring-data-commons/issues
-* Release repository: https://repo.spring.io/libs-release
-* Milestone repository: https://repo.spring.io/libs-milestone
-* Snapshot repository: https://repo.spring.io/libs-snapshot
+* Release repository: https://repo1.maven.org/maven2/
+* Milestone repository: https://repo.spring.io/milestone/
+* Snapshot repository: https://repo.spring.io/snapshot/

src/main/asciidoc/repositories-null-handling.adoc

@@ -0,0 +1,97 @@
+[[repositories.nullability]]
+=== Null Handling of Repository Methods
+
+As of Spring Data 2.0, repository CRUD methods that return an individual aggregate instance use Java 8's `Optional` to indicate the potential absence of a value.
+Besides that, Spring Data supports returning the following wrapper types on query methods:
+
+* `com.google.common.base.Optional`
+* `scala.Option`
+* `io.vavr.control.Option`
+
+Alternatively, query methods can choose not to use a wrapper type at all.
+The absence of a query result is then indicated by returning `null`.
+Repository methods returning collections, collection alternatives, wrappers, and streams are guaranteed never to return `null` but rather the corresponding empty representation.
+See "`<<repository-query-return-types>>`" for details.
+
+[[repositories.nullability.annotations]]
+==== Nullability Annotations
+
+You can express nullability constraints for repository methods by using {spring-framework-docs}/core.html#null-safety[Spring Framework's nullability annotations].
+They provide a tooling-friendly approach and opt-in `null` checks during runtime, as follows:
+
+* {spring-framework-javadoc}/org/springframework/lang/NonNullApi.html[`@NonNullApi`]: Used on the package level to declare that the default behavior for parameters and return values is, respectively, neither to accept nor to produce `null` values.
+* {spring-framework-javadoc}/org/springframework/lang/NonNull.html[`@NonNull`]: Used on a parameter or return value that must not be `null` (not needed on a parameter and return value where `@NonNullApi` applies).
+* {spring-framework-javadoc}/org/springframework/lang/Nullable.html[`@Nullable`]: Used on a parameter or return value that can be `null`.
+
+Spring annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305] annotations (a dormant but widely used JSR).
+JSR 305 meta-annotations let tooling vendors (such as https://www.jetbrains.com/help/idea/nullable-and-notnull-annotations.html[IDEA], https://help.eclipse.org/latest/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm[Eclipse], and link:https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[Kotlin]) provide null-safety support in a generic way, without having to hard-code support for Spring annotations.
+To enable runtime checking of nullability constraints for query methods, you need to activate non-nullability on the package level by using Spring’s `@NonNullApi` in `package-info.java`, as shown in the following example:
+
+.Declaring Non-nullability in `package-info.java`
+====
+[source,java]
+----
+@org.springframework.lang.NonNullApi
+package com.acme;
+----
+====
+
+Once non-null defaulting is in place, repository query method invocations get validated at runtime for nullability constraints.
+If a query result violates the defined constraint, an exception is thrown.
+This happens when the method would return `null` but is declared as non-nullable (the default with the annotation defined on the package in which the repository resides).
+If you want to opt-in to nullable results again, selectively use `@Nullable` on individual methods.
+Using the result wrapper types mentioned at the start of this section continues to work as expected: an empty result is translated into the value that represents absence.
+
+The following example shows a number of the techniques just described:
+
+.Using different nullability constraints
+====
+[source,java]
+----
+package com.acme;                                                       <1>
+
+import org.springframework.lang.Nullable;
+
+interface UserRepository extends Repository<User, Long> {
+
+  User getByEmailAddress(EmailAddress emailAddress);                    <2>
+
+  @Nullable
+  User findByEmailAddress(@Nullable EmailAddress emailAdress);          <3>
+
+  Optional<User> findOptionalByEmailAddress(EmailAddress emailAddress); <4>
+}
+----
+<1> The repository resides in a package (or sub-package) for which we have defined non-null behavior.
+<2> Throws an `EmptyResultDataAccessException` when the query does not produce a result.
+Throws an `IllegalArgumentException` when the `emailAddress` handed to the method is `null`.
+<3> Returns `null` when the query does not produce a result.
+Also accepts `null` as the value for `emailAddress`.
+<4> Returns `Optional.empty()` when the query does not produce a result.
+Throws an `IllegalArgumentException` when the `emailAddress` handed to the method is `null`.
+====
+
+[[repositories.nullability.kotlin]]
+==== Nullability in Kotlin-based Repositories
+
+Kotlin has the definition of https://kotlinlang.org/docs/reference/null-safety.html[nullability constraints] baked into the language.
+Kotlin code compiles to bytecode, which does not express nullability constraints through method signatures but rather through compiled-in metadata.
+Make sure to include the `kotlin-reflect` JAR in your project to enable introspection of Kotlin's nullability constraints.
+Spring Data repositories use the language mechanism to define those constraints to apply the same runtime checks, as follows:
+
+.Using nullability constraints on Kotlin repositories
+====
+[source,kotlin]
+----
+interface UserRepository : Repository<User, String> {
+
+  fun findByUsername(username: String): User     <1>
+
+  fun findByFirstname(firstname: String?): User? <2>
+}
+----
+<1> The method defines both the parameter and the result as non-nullable (the Kotlin default).
+The Kotlin compiler rejects method invocations that pass `null` to the method.
+If the query yields an empty result, an `EmptyResultDataAccessException` is thrown.
+<2> This method accepts `null` for the `firstname` parameter and returns `null` if the query does not produce a result.
+====