From eb9f7465d751c0872d36aaa19f08418dfd688ee9 Mon Sep 17 00:00:00 2001
From: Mark Paluch <mark.paluch@broadcom.com>
Date: Tue, 3 Dec 2024 12:08:40 +0100
Subject: [PATCH] Polishing.

Refine projection documentation.

See #2757
---
 src/main/antora/antora-playbook.yml           |  2 +-
 .../ROOT/pages/repositories/projections.adoc  | 65 ++++++++++---------
 2 files changed, 34 insertions(+), 33 deletions(-)

diff --git a/src/main/antora/antora-playbook.yml b/src/main/antora/antora-playbook.yml
index 54e23dabe..04dbefb29 100644
--- a/src/main/antora/antora-playbook.yml
+++ b/src/main/antora/antora-playbook.yml
@@ -17,7 +17,7 @@ content:
     - url: https://github.com/spring-projects/spring-data-commons
       # Refname matching:
       # https://docs.antora.org/antora/latest/playbook/content-refname-matching/
-      branches: [main, 3.2.x]
+      branches: [ main, 3.4.x ]
       start_path: src/main/antora
 asciidoc:
   attributes:
diff --git a/src/main/antora/modules/ROOT/pages/repositories/projections.adoc b/src/main/antora/modules/ROOT/pages/repositories/projections.adoc
index 3c6bca832..00a6a8c8e 100644
--- a/src/main/antora/modules/ROOT/pages/repositories/projections.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/projections.adoc
@@ -3,41 +3,42 @@
 
 :projection-collection: Collection
 
-include::{commons}@data-commons::page$repositories/projections-intro.adoc[]
+== Introduction
 
-NOTE: It is important to note that <<projections.dtos,Class-based projections>> with JPQL is limited to *constructor expressions* in your JPQL expression, e.g. `SELECT new com.example.NamesOnly(u.firstname, u.lastname) from User u`.
+include::{commons}@data-commons::page$repositories/projections-intro.adoc[leveloffset+=1]
+
+include::{commons}@data-commons::page$repositories/projections-interface.adoc[leveloffset=2]
+
+include::{commons}@data-commons::page$repositories/projections-class.adoc[leveloffset=2]
+
+== Using Projections with JPA
+
+You can use Projections with JPA in several ways.
+Depending on the technique and query type, you need to apply specific considerations.
+
+Spring Data JPA uses generally `Tuple` queries to construct interface proxies for <<projections.interfaces,Interface-based Projections>>.
+
+=== Derived queries
+
+Query derivation supports both, class-based and interface projections by introspecting the returned type.
+Class-based projections use JPA's instantiation mechanism (constructor expressions) to create the projection instance.
+
+Projections limit the selection to top-level properties of the target entity.
+Any nested properties resolving to joins select the entire nested property causing the full join to materialize.
+
+=== String-based queries
+
+Support for string-based queries covers both, JPQL queries(`@Query`) and native queries (`@NativeQuery`).
+
+==== JPQL Queries
+
+When using <<projections.dtos,Class-based projections>> with JPQL, you must use *constructor expressions* in your JPQL query, e.g. `SELECT new com.example.NamesOnly(u.firstname, u.lastname) from User u`.
 (Note the usage of a FQDN for the DTO type!) This JPQL expression can be used in `@Query` annotations as well where you define any named queries.
-And it's important to point out that class-based projections do not work with native queries AT ALL.
 As a workaround you may use named queries with `ResultSetMapping` or the Hibernate-specific javadoc:{hibernatejavadocurl}org.hibernate.query.ResultListTransformer[]
 
-include::{commons}@data-commons::page$repositories/projections-interface.adoc[leveloffset=1]
+==== Native Queries
 
-include::{commons}@data-commons::page$repositories/projections-class.adoc[leveloffset=1]
+When using <<projections.dtos,Class-based projections>>, their usage requires slightly more consideration depending on your :
 
-
-
-[NOTE]
-====
-<<projections.dtos,Class-based projection (DTO projections)>> types must declare a single constructor so that Spring Data can determine its input properties.
-If your class defines more than one constructor, then you cannot use the type without further hints for DTO projections.
-In such a case annotate the desired constructor with `@PersistenceCreator` as outlined below so that Spring Data can determine which properties to select:
-
-[source,java]
-----
-public class NamesOnly {
-
-    private final String firstname;
-    private final String lastname;
-
-    protected NamesOnly() { }
-
-    @PersistenceCreator
-    public NamesOnly(String firstname, String lastname) {
-        this.firstname = firstname;
-        this.lastname = lastname;
-    }
-
-    // ...
-}
-----
-====
+* If properties of the result type map directly to the result (the order of columns and their types match the constructor arguments), then you can declare the query result type as the DTO type without further hints (or use the DTO class through dynamic projections).
+* If the properties do not match or require transformation, use `@SqlResultSetMapping` through JPA's annotations map the result set to the DTO and provide the result mapping name through `@NativeQuery(resultSetMapping = "…")`.