Polishing.

Refine projection documentation.

See #2757

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:

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`.
-(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-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
 
-include::{commons}@data-commons::page$repositories/projections-interface.adoc[leveloffset=1]
+You can use Projections with JPA in several ways.
+Depending on the technique and query type, you need to apply specific considerations.
 
-include::{commons}@data-commons::page$repositories/projections-class.adoc[leveloffset=1]
+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.
 
-[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:
+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.
 
-[source,java]
-----
-public class NamesOnly {
+=== String-based queries
 
-    private final String firstname;
-    private final String lastname;
+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.
+As a workaround you may use named queries with `ResultSetMapping` or the Hibernate-specific javadoc:{hibernatejavadocurl}org.hibernate.query.ResultListTransformer[]
 
-    protected NamesOnly() { }
+==== Native Queries
 
-    @PersistenceCreator
-    public NamesOnly(String firstname, String lastname) {
-        this.firstname = firstname;
-        this.lastname = lastname;
-    }
+When using <<projections.dtos,Class-based projections>>, their usage requires slightly more consideration depending on your :
 
-    // ...
-}
-----
-====
+* 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 = "…")`.