Document Querydsl annotation processor usage

pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-mongodb-parent</artifactId>
-	<version>4.4.0-SNAPSHOT</version>
+	<version>4.4.0-GH-4811-SNAPSHOT</version>
 	<packaging>pom</packaging>
 
 	<name>Spring Data MongoDB</name>

spring-data-mongodb-benchmarks/pom.xml

@@ -7,7 +7,7 @@
 	<parent>
 		<groupId>org.springframework.data</groupId>
 		<artifactId>spring-data-mongodb-parent</artifactId>
-		<version>4.4.0-SNAPSHOT</version>
+		<version>4.4.0-GH-4811-SNAPSHOT</version>
 		<relativePath>../pom.xml</relativePath>
 	</parent>
 

spring-data-mongodb-distribution/pom.xml

@@ -15,7 +15,7 @@
 	<parent>
 		<groupId>org.springframework.data</groupId>
 		<artifactId>spring-data-mongodb-parent</artifactId>
-		<version>4.4.0-SNAPSHOT</version>
+		<version>4.4.0-GH-4811-SNAPSHOT</version>
 		<relativePath>../pom.xml</relativePath>
 	</parent>
 

spring-data-mongodb/pom.xml

@@ -13,7 +13,7 @@
 	<parent>
 		<groupId>org.springframework.data</groupId>
 		<artifactId>spring-data-mongodb-parent</artifactId>
-		<version>4.4.0-SNAPSHOT</version>
+		<version>4.4.0-GH-4811-SNAPSHOT</version>
 		<relativePath>../pom.xml</relativePath>
 	</parent>
 

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

@@ -213,7 +213,7 @@ Inside the test method, we use the repository to query the datastore.
 We hand the repository a `PageRequest` instance that requests the first page of `Person` objects at a page size of 10.
 
 [[mongodb.repositories.queries.type-safe]]
-== Type-safe Query Methods
+== Type-safe Query Methods with Querydsl
 
 MongoDB repository and its reactive counterpart integrates with the http://www.querydsl.com/[Querydsl] project, which provides a way to perform type-safe queries.
 
@@ -238,7 +238,7 @@ Imperative::
 +
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 ----
-QPerson person = new QPerson("person");
+QPerson person = QPerson.person;
 List<Person> result = repository.findAll(person.address.zipCode.eq("C0123"));
 
 Page<Person> page = repository.findAll(person.lastname.contains("a"),
@@ -255,7 +255,8 @@ Flux<Person> result = repository.findAll(person.address.zipCode.eq("C0123"));
 ----
 ======
 
-`QPerson` is a class that is generated by the Java annotation post-processing tool.
+`QPerson` is a class that is generated by the Java annotation processor.
+See xref:#mongodb.repositories.queries.type-safe.apt[Setting up Annotation Processing] for how to setup Annotation Processing with your Build System.
 It is a `Predicate` that lets you write type-safe queries.
 Notice that there are no strings in the query other than the `C0123` value.
 
@@ -269,7 +270,7 @@ Imperative::
 ----
 public interface QuerydslPredicateExecutor<T> {
 
-    T findOne(Predicate predicate);
+    Optional<T> findOne(Predicate predicate);
 
     List<T> findAll(Predicate predicate);
 
@@ -281,9 +282,11 @@ public interface QuerydslPredicateExecutor<T> {
 
     List<T> findAll(OrderSpecifier<?>... orders);
 
-    Long count(Predicate predicate);
+    long count(Predicate predicate);
+
+    boolean exists(Predicate predicate);
 
-    Boolean exists(Predicate predicate);
+    <S extends T, R> R findBy(Predicate predicate, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction);
 }
 ----
 
@@ -306,6 +309,9 @@ interface ReactiveQuerydslPredicateExecutor<T> {
     Mono<Long> count(Predicate predicate);
 
     Mono<Boolean> exists(Predicate predicate);
+
+    <S extends T, R, P extends Publisher<R>> P findBy(Predicate predicate,
+            Function<FluentQuery.ReactiveFluentQuery<S>, P> queryFunction);
 }
 ----
 ======
@@ -320,7 +326,7 @@ Imperative::
 ----
 interface PersonRepository extends MongoRepository<Person, String>, QuerydslPredicateExecutor<Person> {
 
-   // additional query methods go here
+    // additional query methods go here
 }
 ----
 
@@ -332,10 +338,100 @@ Reactive::
 
 interface PersonRepository extends ReactiveMongoRepository<Person, String>, ReactiveQuerydslPredicateExecutor<Person> {
 
-   // additional query methods go here
+    // additional query methods go here
 }
 ----
 
 NOTE: Please note that joins (DBRef's) are not supported with Reactive MongoDB support.
 ====
 ======
+
+[[mongodb.repositories.queries.type-safe.apt]]
+=== Setting up Annotation Processing
+
+To use Querydsl with Spring Data MongoDB, you need to set up annotation processing in your build system that generates the `Q` classes.
+While you could write the `Q` classes by hand, it is recommended to use the Querydsl annotation processor to generate them for you to keep your `Q` classes in sync with your domain model.
+
+Spring Data MongoDB ships with an annotation processor javadoc:org.springframework.data.mongodb.repository.support.MongoAnnotationProcessor[] that isn't registered by default.
+Typically, annotation processors are registered through Java's service loader via `META-INF/services/javax.annotation.processing.Processor` that also activates these once you have them on the class path.
+Most Spring Data users do not use Querydsl, so it does not make sense to require additional mandatory dependencies for projects that would not benefit from Querydsl.
+Hence, you need to activate annotation processing in your build system.
+
+The following example shows how to set up annotation processing by mentioning dependencies and compiler config changes in Maven and Gradle:
+
+[tabs]
+======
+Maven::
++
+[source,xml,indent=0,subs="verbatim,quotes",role="primary"]
+----
+<dependencies>
+    <dependency>
+        <groupId>com.querydsl</groupId>
+        <artifactId>querydsl-mongodb</artifactId>
+        <version>${querydslVersion}</version>
+
+        <!-- Recommended: Exclude the mongo-java-driver to avoid version conflicts -->
+        <exclusions>
+            <exclusion>
+                <groupId>org.mongodb</groupId>
+                <artifactId>mongo-java-driver</artifactId>
+            </exclusion>
+        </exclusions>
+    </dependency>
+
+    <dependency>
+        <groupId>com.querydsl</groupId>
+        <artifactId>querydsl-apt</artifactId>
+        <version>${querydslVersion}</version>
+        <scope>provided</scope>
+    </dependency>
+</dependencies>
+
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <configuration>
+                <annotationProcessors>
+                    <annotationProcessor>
+                        org.springframework.data.mongodb.repository.support.MongoAnnotationProcessor
+                    </annotationProcessor>
+                </annotationProcessors>
+
+                <!-- Recommended: Some IDE's might require this configuration to include generated sources for IDE usage -->
+                <generatedTestSourcesDirectory>target/generated-test-sources</generatedTestSourcesDirectory>
+                <generatedSourcesDirectory>target/generated-sources</generatedSourcesDirectory>
+            </configuration>
+        </plugin>
+    </plugins>
+</build>
+----
+
+Gradle::
++
+====
+[source,groovy,indent=0,subs="verbatim,quotes",role="secondary"]
+----
+dependencies {
+    implementation 'com.querydsl:querydsl-mongodb:${querydslVersion}'
+
+    annotationProcessor 'com.querydsl:querydsl-apt:${querydslVersion}'
+    annotationProcessor 'org.springframework.data:spring-data-mongodb'
+
+    testAnnotationProcessor 'com.querydsl:querydsl-apt:${querydslVersion}'
+    testAnnotationProcessor 'org.springframework.data:spring-data-mongodb'
+}
+
+tasks.withType(JavaCompile).configureEach {
+    options.compilerArgs += [
+            "-processor",
+            "org.springframework.data.mongodb.repository.support.MongoAnnotationProcessor"]
+}
+----
+
+====
+======
+
+Note that the setup above shows the simplest usage omitting any other options or dependencies that your project might require.