Change Delete by Id with @SoftDelete to performs soft delete rather than hard delete

composites/ebean-clickhouse/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-clickhouse</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-cockroach/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-db2/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-db2</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-h2/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-h2</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-hana/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-hana</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-mariadb/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-mariadb</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-mysql/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-mysql</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-net-postgis/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -14,7 +14,7 @@
 
   <properties>
     <postgis.jdbc.version>2023.1.0</postgis.jdbc.version>
-    <postgres.jdbc.version>42.7.11</postgres.jdbc.version>
+    <postgres.jdbc.version>42.7.2</postgres.jdbc.version>
   </properties>
 
   <dependencies>
@@ -22,13 +22,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -47,19 +47,19 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-net-postgis-types</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>

composites/ebean-nuodb/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-nuodb</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-oracle/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-oracle</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-pgvector/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -22,13 +22,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -47,19 +47,19 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-pgvector-types</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>

composites/ebean-postgis/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -22,13 +22,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -47,19 +47,19 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-postgis-types</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>

composites/ebean-postgres/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-sqlite/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-sqlite</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-sqlserver/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-sqlserver</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-yugabyte/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/ebean/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -41,7 +41,7 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-jackson-mapper</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -60,13 +60,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-all</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
   </dependencies>

composites/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
   </parent>
 
   <artifactId>composites</artifactId>

docs/LIBRARY.md

@@ -54,8 +54,7 @@ Ebean is an ORM library for Java and Kotlin focused on relational data access, t
 | `exists()` | Efficient existence checks | `new QCustomer().email.equalTo(email).exists();` |
 | `findOne()` | Unique/single-row retrieval | `new QCustomer().id.equalTo(id).findOne();` |
 | `findList()` | List retrieval | `new QCustomer().findList();` |
-| `asDto(...).findList()` | Flat DTO projection reads | `new QOrder().asDto(OrderSummary.class).findList();` |
-| `mapTo(...).findList()` | Nested DTO graph projection reads | `new QCustomer().mapTo(CustomerDto.class).findList();` |
+| `asDto(...).findList()` | DTO projection reads | `new QOrder().asDto(OrderSummary.class).findList();` |
 
 ### Entity mapping and lifecycle annotations
 
@@ -189,7 +188,6 @@ database.save(customer);
 | Model entity beans correctly | [entity-bean-creation.md](guides/entity-bean-creation.md) |
 | Use Lombok safely with entities | [lombok-with-ebean-entity-beans.md](guides/lombok-with-ebean-entity-beans.md) |
 | Write type-safe query bean queries | [writing-ebean-query-beans.md](guides/writing-ebean-query-beans.md) |
-| Map nested entity graphs to DTO graphs | [mapping-entity-graphs-to-dtos.md](guides/mapping-entity-graphs-to-dtos.md) |
 | Persist changes and manage transactions | [persisting-and-transactions-with-ebean.md](guides/persisting-and-transactions-with-ebean.md) |
 | Build test entities quickly | [testing-with-testentitybuilder.md](guides/testing-with-testentitybuilder.md) |
 

docs/dto-mapping-design.md

@@ -1,990 +0,0 @@
-# Nested DTO Mapping — API Design
-
-Design spike for the accepted requirements in [dto-mapping-requirements.md](./dto-mapping-requirements.md),
-covering issue #2540. This captures the concrete API shape, annotations, and open-question decisions made
-during design review — before implementation begins.
-
-## Two source-vs-target mapping pipelines
-
-Ebean now has (or will have) two distinct DTO pipelines. It's important callers can tell which one they're
-using:
-
-1. **`asDto(Dto.class)`** (existing) — a `DtoQuery`, executed directly against a flat SQL `ResultSet`.
-   One row -> one DTO, via constructor/setter matching. No nested ToOne/ToMany support, no entity graph
-   involved.
-2. **`mapTo(Dto.class)`** (new) — runs the normal ORM entity query (joins/fetches as usual), producing an
-   *unmodifiable entity graph*, then maps that Java object graph into a DTO graph. Supports nested
-   ToOne/ToMany, identity-aware de-duplication, and derives its own fetch spec from the DTO shape.
-
-## Proposed API
-
-```java
-// Existing flat DtoQuery pipeline — unchanged
-new QUser().valid.eq(true)
-    .select(firstName, lastName)
-    .asDto(UserInfo.class)
-    .findList();
-```
-
-```java
-// NEW: nested DTO graph pipeline
-public class CustomerDto {
-  Long id;
-  String name;
-  AddressDto billingAddress;      // ToOne -> nested DTO, matched by property name "billingAddress"
-  List<ContactDto> contacts;      // ToMany -> nested DTO list, matched by property name "contacts"
-
-  @DtoPath("billingAddress.line1")
-  String billingLine1;            // renamed / flattened path
-}
-
-public class ContactDto {
-  Long id;
-  String firstName;
-  String lastName;
-
-  @DtoRef
-  Long customerId;                // id-only back-reference, avoids re-embedding CustomerDto (cycle)
-}
-
-List<CustomerDto> dtos = new QCustomer()
-    .status.eq(Status.ACTIVE)
-    .mapTo(CustomerDto.class)
-    .findList();
-```
-
-Computed values (e.g. `cityOrUnknown` derived from `coalesce(billingAddress.city, 'Unknown')`) are
-**not** modeled with a `@Formula2` annotation directly on the DTO - that was explored and rejected
-(see "Formula2-on-DTO scope" below). Instead they're modeled as a plain matching field on the DTO,
-sourced from an `@Entity @View` entity that itself carries the `@Formula2` - see "Computed/aggregate
-properties" below for the worked example.
-
-`mapTo(CustomerDto.class)`:
-- Introspects `CustomerDto` (recursively, at codegen time) to derive the `select(...)`/`.fetch(...)` spec
-  automatically from the DTO's declared shape.
-- Forces `setUnmodifiable(true)` under the hood — gives fail-fast + a cheap, non-mutable source graph
-  (satisfies the fail-fast requirement without a separate flag).
-- Runs the query, then runs a mapper over the resulting entity graph, de-duplicating DTO instances by id
-  for repeated nested references (identity-aware, mirrors the source entity graph's own de-duplication).
-
-## Decisions made
-
-### Fetch spec: auto-derived from DTO shape
-
-The DTO's declared structure (fields, nested DTO types, `@DtoPath` overrides) is the single source of truth
-for what gets selected/fetched from the database. Callers do not need to separately maintain a `.fetch(...)`
-spec in parallel with the DTO — this directly addresses the original issue's pain point (DTO and query
-projection drifting out of sync).
-
-### Entry point naming: `mapTo(Dto.class)`
-
-Chosen over `asGraph(...)` / `into(...)` / overloading `findList(Class)`. Reads clearly as "map the
-resulting entity graph to this DTO type" and is unambiguous against the existing `asDto(...)` (flat,
-SQL-row-based) mechanism.
-
-### Cycle handling: codegen-time DAG check + `@DtoRef` escape hatch
-
-Because the fetch spec and mapper are both derived from the *static* DTO type graph (not live object
-traversal), cycle detection is a compile-time/codegen-time concern, not a runtime one. This is stronger
-than the common approach in the ecosystem:
-
-- **MapStruct** does not auto-detect cycles. It offers an opt-in `@Context` "cycle guard" pattern (an
-  identity map of already-mapped source -> target objects) that the developer must wire up manually to
-  avoid infinite recursion mapping bidirectional object graphs.
-- **Blaze-Persistence / QueryDSL / JOOQ record mapping** avoid the problem architecturally: view/projection
-  types are required to be a strict tree; a back-reference is modeled as an id or a much shallower type,
-  never the same full view type again.
-
-Ebean's approach: fail the build at annotation-processing time if a DTO's declared type graph is not a DAG,
-with a clear error message. Provide `@DtoRef` as an explicit escape hatch for intentional back-references
-(e.g. `Contact.customer`) — it maps only the id, not the full nested DTO, breaking the cycle by design
-rather than by runtime guard.
-
-### `@DtoPath` / `@DtoRef`: parallels for readers coming from MapStruct or Blaze-Persistence
-
-Neither annotation is a novel concept - both map onto things MapStruct and Blaze-Persistence users will
-already recognise, which is worth spelling out explicitly so it's easy to "grok fast":
-
-- **`@DtoPath("billingAddress.line1")` is Ebean's equivalent of MapStruct's dot-path `source` flattening**
-  — e.g. `@Mapping(target = "line1", source = "billingAddress.line1")`. MapStruct auto-generates a
-  null-safe chain of getter calls for a dotted `source`; `@DtoPath` does exactly the same thing, just
-  declared on the DTO field itself rather than on a mapper method parameter list. It is also close to
-  Blaze-Persistence's `@Mapping("billingAddress.line1")` on an `@EntityView` attribute, which is a JPQL
-  path expression evaluated the same way — Blaze's placement (directly on the target view property) is
-  actually the closer analogue of the two, since Ebean's `@DtoPath` is likewise placed on the DTO field.
-  The difference from Blaze: `@DtoPath` is restricted to plain getter-chain navigation (no arbitrary JPQL/
-  SQL expression) - see "Formula2-on-DTO scope" below for the boundary and why full expression support is
-  deliberately deferred.
-- **`@DtoRef` has no dedicated equivalent in either tool** - both MapStruct and Blaze would express the
-  same "just the id" mapping as a plain dot-path to `.id` (`@Mapping(source = "customer.id")` / Blaze
-  `@Mapping("customer.id")`), with no special marker for it. What `@DtoRef` adds beyond that shorthand is
-  *intent*: it tells the codegen this property is a deliberate cycle-breaking reference, so (a) it adds
-  just the association's own name (not a dotted `.id` path) to the generated fetch spec's root
-  `select(...)` - reading the FK column directly with no join, and skipped entirely if that same
-  association is already fully fetched by a `NESTED_ONE`/`NESTED_MANY` property elsewhere on the same DTO
-  (see `DtoMapperWriter.fetchGroupChainCalls()`'s `case REF` branch) - and (b) it participates in the
-  codegen-time DAG cycle check above as an explicit "this is fine, don't flag it" signal, rather than
-  requiring a suppression escape hatch bolted on afterwards.
-
-  **Bug found and fixed while building the aggregation worked example below:** the original implementation
-  excluded `REF` properties from the fetch spec *entirely*, on the assumption the id is "already available
-  off an unfetched reference without triggering a fetch/lazy load". That assumption is only true when some
-  *other* property on the same DTO happens to also fetch that association (as was always the case in the
-  existing hand-built examples). Tested directly against a bare `@ManyToOne` with no other fetch of it:
-  accessing `.getCustomer().getId()` in that case triggers a full lazy-reload of the owning row (extra SQL,
-  not free) - and for an aggregation query it's worse, since the property being grouped by must be selected
-  or the query can't group correctly at all. Fixed so `REF` always contributes its association name to the
-  root `select(...)` (deduped against any existing `NESTED_ONE`/`NESTED_MANY` fetch of the same path).
-
-**Bug found and fixed (validation phase, testing against `central-access`): primitive-typed field +
-nullable intermediate hop = unboxing `NullPointerException`.** A multi-hop `@DtoPath` (or `@DtoRef`,
-which is always 2-hop) null-guards each intermediate getter with a ternary, e.g.
-`(source.getOrganisation() == null ? null : source.getOrganisation().getId())`. That ternary's static
-type is always the boxed wrapper (`Long`), since one branch is the `null` literal - fine when the DTO
-field is itself a reference type (`Long organisationId`), but when the DTO field is a **primitive**
-(`long organisationId`), passing that boxed expression to the constructor auto-unboxes it, throwing an
-unhelpful `NullPointerException` at runtime whenever the relation really is `null`. This compiled clean
-and only failed at runtime with real (nullable) production data - exactly the kind of gap a hand-written
-mapper would defensively guard against (e.g. `cEbox.getOrganisation() == null ? 0 : ...getId()`) but
-generated code didn't.
-
-Fixed in the generator: when a multi-hop `SCALAR`/`REF` property's DTO field type is primitive, the
-whole null-guarded chain is now wrapped in a small runtime helper (`io.ebean.DtoMapperSupport`) that
-resolves it safely:
-- **Default** (`@DtoPath` with no `failOnNull`, or any `@DtoRef`): silently defaults to the primitive's
-  zero-equivalent value (`0`/`false`/etc.) - matches the old hand-written-mapper convention.
-- **`@DtoPath(failOnNull = true)`**: throws a clear `IllegalStateException` naming the offending property
-  path instead, for callers who'd rather fail fast than silently mask a null they don't expect.
-
-`@DtoRef` has no `failOnNull` attribute (it has no other attributes at all) - it always uses the
-default (silent zero) behaviour. See `PrimitiveNullPathDto`/`PrimitiveNullPathFailOnNullDto` /
-`TestPrimitiveNullPath` for regression coverage.
-
-### Read-only entity memory overhead: `InterceptReadOnly`
-`setUnmodifiable(true)` isn't just a behavioural fail-fast flag - it also swaps the per-bean intercept
-implementation to `InterceptReadOnly`, which is deliberately minimal: just a `boolean[] loaded` (one flag
-per property) and a `boolean frozen`, plus the inherited owner reference and `fullyLoadedBean` flag. Compare
-to `InterceptReadWrite` (the mutable/updatable variant), which additionally carries a `ReentrantLock`, four
-transient collaborator references (`NodeUsageCollector`, `PersistenceContext`, `BeanLoader`,
-`PreGetterCallback`), a `byte[] flags` array (per-property loaded+changed+dirty+orig-value-set state),
-`Object[] origValues`, `Exception[] loadErrors`, `MutableValueInfo[]`/`MutableValueNext[]`, and several more
-scalar bookkeeping fields. None of that is needed for a bean that will only ever be read, so
-`setUnmodifiable(true)` graphs carry meaningfully less per-instance overhead than normal fetched entities -
-relevant here because `mapTo(Dto.class)` forces `setUnmodifiable(true)` on its underlying query, making the
-*source* graph for a DTO mapping cheaper than the equivalent normal (writable) entity graph would be.
-
-### Ad-hoc computed/formula properties: model as `@Entity @View`/`@Sql`, not ad-hoc SQL-on-DTO
-
-The "fully ad-hoc SQL-on-DTO" stretch goal above (closer to Blaze's arbitrary `@Mapping` expressions) doesn't
-need to be built as a bespoke DTO-annotation-processing feature. Ebean already supports modelling read-only,
-computed, or view-backed data as ordinary entities via `@Entity` + `@View` (backed by a SQL view, e.g. one
-with aggregates/computed columns) or `@Entity` + `@Sql` (backed by arbitrary `RawSql`, no base table). Given
-that, the Blaze-Persistence-style "an entity view attribute backed by an arbitrary SQL expression" need can
-usually be satisfied by:
-
-1. Modelling the computed/derived shape as its own `@Entity @View` (or `@Sql`) "read entity" - the SQL
-   expression/aggregation lives in the view definition, not in a new annotation-processed DTO mechanism.
-   `@View`'s `name()` doesn't have to point at a genuinely separate database view - it can just point at
-   an *existing* table (e.g. `@View(name = "contact")` on a second entity class reading the same table as
-   `Contact`) purely to mark the entity as view-like/read-only, in which case Ebean's DDL generator emits
-   **no new table or view at all** for it - it's just a second lens onto the same physical data.
-2. Mapping *that* entity into a plain DTO using the existing, already-implemented `@DtoMapping` machinery -
-   no ad-hoc-SQL-on-DTO support required, since there's no computed expression left to resolve at the DTO
-   layer at all; it's just another entity-to-DTO mapping.
-3. This read entity benefits from the same `setUnmodifiable(true)`/`InterceptReadOnly` memory efficiency
-   above when used purely as `mapTo(...)` input, so there's no meaningful cost to preferring this over a
-   hypothetical native ad-hoc-SQL-on-DTO feature.
-
-This significantly narrows (and may eliminate) the case for a dedicated ad-hoc-SQL-on-DTO mechanism - it
-remains listed as an open stretch goal below primarily for the case where a computed value's SQL is genuinely
-one-off/DTO-specific and not worth promoting to a standalone `@View`/`@Sql` entity.
-
-**Worked example** (`tests/test-dto-mapping`): `ContactSummary` is `@Entity @View(name = "contact")` (no new
-DDL - reads the same table as `Contact`) with `@Formula2("concat(firstName, ' ', lastName)")` computing
-`fullName`; `ContactSummaryDto` is a plain two-field DTO; `@DtoMapping(source = ContactSummary.class, target
-= ContactSummaryDto.class)` generates `ContactSummaryDtoMapper` exactly like any other entity→DTO pair - the
-formula property is just selected like any other field (`select("id,fullName")` in the generated
-`fetchGroup()`). See `TestContactSummaryDtoMapping`.
-
-### Aggregate/group-by computed properties: `@Sum`/`@Aggregation` as `@Entity @View`, same pattern
-
-Ebean's `@Sum` (shorthand for `@Aggregation("sum($1)")`) and `@Aggregation("count(...)"/"sum(...)"/"avg(...)"/
-"min(...)"/"max(...)")` are the group-by parallel to the formula pattern above - the same `@Entity @View`
-approach applies, just with an implicit `GROUP BY` instead of a per-row computed column. Ebean auto-derives
-the `GROUP BY` clause from whichever non-aggregate properties end up in the query's `select()`/`fetch()` - so
-a second `@Entity @View(name = <same base table>)` entity with one or more `@Sum`/`@Aggregation` properties
-plus a `@ManyToOne` grouping key becomes a per-parent rollup, with **no new table/view and no explicit
-`.groupBy()` call required**. This is Ebean's parallel to Blaze-Persistence entity view correlated aggregate
-mappings, e.g. `@Mapping("SIZE(contacts)")` / `@Mapping("SUM(contacts.engagementScore)")` on an `@EntityView`.
-
-**Nuance found while building the worked example, and since fixed: `@DtoRef` originally didn't fit the
-grouping key.** `@DtoRef` was originally excluded from the generated `select()`/`fetch()` spec entirely, on
-the premise that the id is already available off an unfetched reference for an ordinary entity graph. That
-premise doesn't hold for an aggregation query: the `@ManyToOne` *is* the property being grouped by, so if
-it's never selected, the query has nothing to group by. It turned out the premise didn't fully hold for
-ordinary entity graphs either - see the `@DtoRef` bug writeup above. Fixed so `@DtoRef` now adds the
-association's own name to the root `select(...)` (reading the FK column directly, no join) - which both
-supplies the grouping key here and fixes the general-case gap.
-
-**Worked example** (`tests/test-dto-mapping`): `ContactStats` is `@Entity @View(name = "contact")` (no new
-DDL - reads the same table as `Contact`/`ContactSummary`) with `@Aggregation("count(id)") contactCount` and
-`@Sum Integer engagementScore` (a new nullable field added to `Contact` purely to have something to sum),
-grouped by its `@ManyToOne customer`. `ContactStatsDto` is a flat 3-field DTO (`customerId`, `contactCount`,
-`engagementScore`), with `customerId` mapped via plain `@DtoRef`. The generated `ContactStatsDtoMapper`:
-
-```java
-this.fetchGroup = FetchGroup.of(ContactStats.class)
-  .select("customer,contactCount,engagementScore")
-  .build();
-...
-// skip DtoMapContext, only ever a top-level mapping
-return new ContactStatsDto(
-  (source.getCustomer() == null ? null : source.getCustomer().getId()),
-  source.getContactCount(),
-  source.getEngagementScore());
-```
-
-confirmed (via `LoggedSql`) to produce `select t0.customer_id, count(t0.id), sum(t0.engagement_score) from
-contact t0 ... group by t0.customer_id` - **no join**, one row per customer, correctly summed and counted.
-See `TestContactStatsDtoMapping`.
-
-### Formula2-on-DTO scope (v1): existing entity formulas only
-
-`@Formula2` on a DTO property in v1 only pulls in a formula **already declared on the source entity** (or
-a reachable associated entity) — it does not support fully ad-hoc SQL declared directly on the DTO with no
-matching entity property. Fully ad-hoc SQL-on-DTO (closer to Blaze's arbitrary `@Mapping` expressions) is a
-separate, larger stretch goal to revisit once the core graph-mapping mechanism is proven.
-
-**Attempted and rejected for v1.** A narrower version was implemented (`@Formula2(value)` resolved exactly
-like `@DtoPath` - a dot-path getter chain - plus a codegen-time validation that the resolved entity property
-is itself `@Formula2`/`@Formula`-annotated) but was rejected: for the common case (a DTO field with the same
-name as the entity's formula property) it generated **identical code to a plain unannotated field** - the
-only difference was the validation, which wasn't judged enough distinct value to justify a new annotation
-surface. Not implemented. The only way `@Formula2`-on-DTO would add real value is the full ad-hoc-SQL
-capability described above, which remains an open stretch goal.
-
-### Mapper implementation strategy: codegen, not reflection (native-image constraint)
-
-Native-image support is a core Ebean requirement, so the entity-graph -> DTO-graph mapper must not rely on
-runtime reflection or `MethodHandles`. This ruled out an initial reflection-based spike:
-
-- Ebean's existing flat `DtoQuery` (`DtoMetaConstructor`) already uses `MethodHandles` via
-  `Lookups.getLookup()`, but there is no `reflect-config.json` / native-image reachability metadata shipped
-  for it anywhere in the repo. That existing approach is not a clean precedent to copy for a bigger,
-  native-image-first feature.
-- Instead, the approach mirrors `querybean-generator`, which already generates real `.java` source for
-  `Q*` query bean types (not reflection) — consistent with the wider avaje-ecosystem convention
-  (avaje-inject / avaje-jsonb are explicitly reflection-free via compile-time codegen).
-
-**Implementation sequencing:** hand-write the mapper in the exact shape the annotation processor will
-eventually generate (plain Java, direct getter/constructor/setter calls, zero reflection) for one concrete
-example first, to validate the mapping algorithm and API shape quickly without ever introducing throwaway
-reflective code. That hand-written mapper then becomes the target/acceptance-test shape for the
-`querybean-generator` annotation processor that automates producing it.
-
-### Codegen target: Java first
-
-The mapper generation (requirement r2) targets `querybean-generator` (the existing APT module that already
-generates `Q*` query beans, reusing its `PropertyMeta` / `ProcessingContext` machinery). Kotlin parity via
-`kotlin-querybean-generator` is deferred to a later phase — not blocking initial delivery.
-
-### Mapper composition: one mapper per entity/DTO pair, generic `DtoMapper<SOURCE, TARGET>` interface
-
-Rather than one large mapper inlining every nested DTO type, each entity/DTO pair gets its own small
-mapper class - mirroring MapStruct's per-type mapper generation. All mappers implement a shared generic
-interface (prototyped as `org.tests.dtomapping.DtoMapper<SOURCE, TARGET>` in the spike, expected to move to
-`io.ebean` as a public type once solidified):
-
-```java
-public interface DtoMapper<SOURCE, TARGET> {
-  TARGET map(SOURCE source);
-  default List<TARGET> mapList(List<SOURCE> source) { ... }
-}
-```
-
-A parent mapper composes nested mappers via **constructor injection**, not a static singleton:
-
-```java
-public final class CustomerDtoMapper implements DtoMapper<Customer, CustomerDto> {
-  private final DtoMapper<Address, AddressDto> addressMapper;
-
-  public CustomerDtoMapper() {
-    this(new AddressDtoMapper());
-  }
-
-  public CustomerDtoMapper(DtoMapper<Address, AddressDto> addressMapper) {
-    this.addressMapper = addressMapper;
-  }
-
-  @Override
-  public CustomerDto map(Customer source) {
-    if (source == null) return null;
-    return new CustomerDto(source.getId(), source.getName(), addressMapper.map(source.getBillingAddress()));
-  }
-}
-```
-
-Rationale:
-- **Composability & reuse** - the same nested DTO type (e.g. `AddressDto`) used from multiple parent DTOs
-  reuses one generated mapper class rather than duplicating inline mapping logic.
-- **Constructor injection over static state** - avoids a global mutable singleton; a no-arg constructor
-  gives the common case (default nested mapper), while an overload accepting the nested mapper explicitly
-  allows substitution (tests, customization) without touching global state.
-- **Codegen-friendly** - this shape generates naturally: one top-level mapper class per DTO type, each
-  constructor-injecting the mappers for any nested DTO types it references.
-
-## ToMany collections and identity de-duplication (dto-spike-tomany-identity)
-
-Extending the spike (`ebean-test/src/test/java/org/tests/dtomapping/`) to a `Customer` with a
-`List<Contact> contacts` ToMany, where each `Contact` has a `customer` back-reference, surfaced
-two things worth recording.
-
-### The `DtoMapper` interface threads a shared context
-
-`DtoMapper<SOURCE, TARGET>` was extended so that mapping is always done against a `DtoMapContext`:
-
-```java
-public interface DtoMapper<SOURCE, TARGET> {
-  TARGET map(SOURCE source, DtoMapContext context);
-
-  default TARGET map(SOURCE source) {
-    return map(source, new DtoMapContext());
-  }
-
-  default List<TARGET> mapList(List<SOURCE> source, DtoMapContext context) { ... }
-
-  default List<TARGET> mapList(List<SOURCE> source) {
-    return mapList(source, new DtoMapContext());
-  }
-}
-```
-
-`DtoMapContext` is an identity-keyed cache of already-mapped source -> target instances, created
-once per top-level `mapList(...)`/`map(...)` call and threaded through every nested `map(...)`
-call. This lets repeated references to the *same* source entity instance - which Ebean's own
-persistence context already de-duplicates within one query (`contact.getCustomer() == customer`
-for the enclosing `Customer`, confirmed by an existing test) - map to the *same* target DTO
-instance, rather than each producing an equal-but-distinct copy. This is what makes the mapped
-DTO output "graph shaped" rather than "tree of copies shaped", and is required for r1/r3.
-
-### Bug found and fixed: the cache must be partitioned by target type, not just source identity
-
-The first cut of `DtoMapContext` was a single `IdentityHashMap<Object, Object>` keyed only by the
-source instance. This breaks as soon as the *same* source instance legitimately needs to map to
-*two different target types* within one graph - which happens immediately with a back-reference:
-
-- The top-level `CustomerDtoMapper` maps a `Customer` -> full `CustomerDto`.
-- The nested `ContactDtoMapper`, mapping `contact.getCustomer()` (the *same* `Customer` instance,
-  by identity), maps it -> shallow `CustomerRefDto` (the `@DtoRef`-style escape hatch that avoids
-  the `Customer -> Contact -> Customer` cycle).
-
-With a single un-partitioned identity map, whichever mapper runs first "wins" the cache slot for
-that `Customer` instance, and the other mapper incorrectly receives the wrong-typed cached result
-(a `ClassCastException` at best, silently wrong data at worst). This was caught by a failing test
-during the spike and fixed by partitioning the cache per target type:
-
-```java
-public final class DtoMapContext {
-  private final Map<Class<?>, Map<Object, Object>> mappedByType = new HashMap<>();
-
-  public <S, T> T computeIfAbsent(Class<T> targetType, S source, Function<S, T> mappingFunction) {
-    Map<Object, Object> mapped = mappedByType.computeIfAbsent(targetType, t -> new IdentityHashMap<>());
-    // ... existing/create/put ...
-  }
-}
-```
-
-Each generated mapper passes its own target DTO `Class` as the first argument, so `Customer ->
-CustomerDto` and `Customer -> CustomerRefDto` are cached independently even though the key
-(`Customer` instance) is identical. **This is an implementation detail the codegen must get
-right** - worth flagging explicitly when `dto-codegen-mapper` starts, since it's easy to
-regress if the generator is written from scratch without this test coverage in front of it.
-
-### Codegen optimization: skip the `DtoMapContext` cache for types that are never nested elsewhere
-
-`DtoMapContext.computeIfAbsent` only ever produces a cache *hit* when the exact same source
-instance is presented to `map()` more than once within one top-level call - which can only happen
-when the target type is reachable via more than one path in the graph, i.e. it's used as a
-`NESTED_ONE`/`NESTED_MANY` property by some *other* `@DtoMapping` pair (e.g. `CustomerRefDto`
-reached from many `Contact`s via a shared `Customer`, or `AddressDto` shared as `billingAddress`
-across customers). A type that's only ever a top-level `mapTo(...)`/`mapList(...)` entry point can
-never receive the same source instance twice within one call - Ebean's own query engine already
-de-duplicates root entity instances - so the cache lookup/insert there is pure overhead with a
-guaranteed-never-hit `IdentityHashMap`.
-
-Since all `@DtoMapping` pairs are resolved together at codegen time (`DtoMappingReader.
-resolveAndValidate()`), it's straightforward to compute this: after cycle exclusion, walk every
-surviving `DtoBeanMeta`'s properties and mark any `nested()` target as `nestedElsewhere()`. The
-generated `map()` method then branches per mapper:
-
-```java
-// CustomerDto - never nested by another mapper, only a mapTo()/mapList() entry point
-public CustomerDto map(Customer source, DtoMapContext context) {
-  if (source == null) return null;
-  // DtoMapContext for nested mappers only
-  return new CustomerDto(source.getId(), source.getName(),
-    billingAddressMapper.map(source.getBillingAddress(), context),
-    contactsMapper.mapList(source.getContacts(), context));
-}
-
-// AddressDto - nested under CustomerDto.billingAddress, so may be shared across customers
-public AddressDto map(Address source, DtoMapContext context) {
-  if (source == null) return null;
-  // dedup using DtoMapContext, same Address instance can be reached via more than one path in the graph
-  return context.computeIfAbsent(AddressDto.class, source, s -> new AddressDto(
-    s.getId(), s.getLine1(), s.getCity()));
-}
-
-// ContactSummaryDto - flat, top-level only, no nested children at all
-public ContactSummaryDto map(ContactSummary source, DtoMapContext context) {
-  if (source == null) return null;
-  // skip DtoMapContext, only ever a top-level mapping
-  return new ContactSummaryDto(source.getId(), source.getFullName());
-}
-```
-
-Deliberately terse, single-line comments - just enough for a developer skimming generated code (e.g.
-per the earlier `@Formula2`-on-DTO worked example) to know at a glance *why* a given mapper does or
-doesn't use the cache, without spelling out the full reachability argument inline every time (that
-lives here in the design doc instead). Note `CustomerDto`'s own construction skips the cache even
-though it *has* nested children - `context` is still threaded down to `billingAddressMapper`/
-`contactsMapper` since those target types (`AddressDto`, `ContactDto`) *are* nested elsewhere and
-still need the identity cache for themselves - hence the distinct "for nested mappers only" wording
-from the "only ever a top-level mapping" case (`ContactSummaryDto`), which has no children to thread
-a context to at all.
-
-### Fetching a ToOne back-reference used only for its FK/id needs the FK property fetched too
-
-Confirmed (via a first-cut test failure) that if a ToMany's element type has a ToOne back to its
-parent (e.g. `Contact.customer`), that FK property must itself be included in the fetch
-(`.fetch("contacts", "id,firstName,lastName,customer")`) even when the mapper only reads the id
-off the reference. Omitting it throws `LazyInitialisationException: Property not loaded:
-customer` on the `getCustomer()` call itself (not merely on a property access on the returned
-reference) - i.e. the earlier "ToOne reference access alone doesn't lazy load" finding
-(dto-validate-fetch-pagination) only holds once the ToOne/FK property is itself part of the
-fetch/select spec. This reinforces r6 (auto-deriving the fetch spec from DTO shape): the codegen
-must include a ToOne property in the fetch spec whenever a DTO needing it (even just its id) is
-reachable through a ToMany, not just at the top level.
-
-### Test coverage added
-
-- `TestCustomerDtoGraphMapping` extended to cover `contacts` ToMany mapping and to assert that
-  sibling `ContactDto`s under the same customer share the identical `CustomerRefDto` instance.
-- `TestContactDtoGraphMapping` (new) - standalone `ContactDtoMapper` test focused specifically on
-  the identity de-dup guarantee and null-source handling.
-
-## Codegen foundation: avaje-prisms adopted in querybean-generator (dto-codegen-mapper, step 1)
-
-Before writing the DTO-mapper annotation-processing logic itself, adopted `avaje-prisms`
-(`io.avaje:avaje-prisms`) in `querybean-generator` as the mechanism for reading the new
-`@DtoPath`/`@DtoRef` annotations at APT time, replacing what would otherwise be more hand-rolled
-`AnnotationMirror` walking (the existing pattern in `FindDbName.java`/`ReadModuleInfo.java`,
-left as-is/unmigrated - only the *new* annotations use prisms).
-
-This mirrors the proven pattern already used in two sibling projects in the same ecosystem -
-`avaje-inject`'s `inject-generator` and `avaje-jsonb`'s `jsonb-generator` - both declare
-`@GeneratePrism(SomeAnnotation.class)` once and get a generated `SomeAnnotationPrism` with
-`isPresent(element)` / `getInstanceOn(element)` / `getOptionalOn(element)` and typed accessors
-for every annotation member (correctly handling `Class`-valued members, avoiding the classic
-`MirroredTypeException` dance).
-
-Key property preserved: `querybean-generator` has **zero runtime/compile dependencies today**
-(confirmed via `mvn dependency:list` returning "none"), matching annotations by FQN string
-constants (`Constants.java`) rather than importing the actual annotation classes - deliberately
-keeping the processor free of any dependency footprint for consumers. Adding `avaje-prisms` (to
-generate the prism wrapper) and `ebean-annotation` (to reference `@DtoPath`/`@DtoRef` as literal
-`Class` values in `@GeneratePrism(...)`) as `optional` dependencies preserves this: `mvn
-dependency:list -DincludeScope=runtime` confirms every one of these (plus their own transitive
-deps: `avaje-prism-core`, `avaje-spi-service`, `avaje-spi-core`) is marked `(optional)`, so none
-of it propagates to a project that depends on `querybean-generator` (whether as a normal
-dependency or via `annotationProcessorPaths`).
-
-New annotations were added to the separate `ebean-annotation` repo (`io.ebean.annotation`
-package, alongside `@Formula2`), not this repo:
-
-```java
-@DtoPath("billingAddress.line1")
-String billingLine1;   // rename/flatten a DTO property from a nested source path
-
-@DtoRef
-Integer customerId;    // id-only back-reference, breaks what would otherwise be a graph cycle
-```
-
-Both use `@Target({FIELD, METHOD})` and `RetentionPolicy.CLASS` - visible to the annotation
-processor (including across module boundaries, since `CLASS` retention survives in the compiled
-`.class` file) but absent from runtime reflection, consistent with DTOs remaining plain,
-framework-free types with no runtime footprint.
-
-Wiring changes in `querybean-generator`:
-- `pom.xml`: added `avaje-prisms` (`optional`, plus `annotationProcessorPaths` entry) and
-  `ebean-annotation` (`optional`) dependencies; removed the previous `-proc:none` compiler arg
-  (which would have suppressed `avaje-prisms`' own processor from running to generate the prism
-  source) - annotation processing is now scoped to exactly `avaje-prisms` via the explicit
-  `annotationProcessorPaths` list, so no other processor is auto-discovered.
-- `module-info.java`: added `requires static io.avaje.prism;` and `requires static
-  io.ebean.annotation;` (`static` = compile-time only, matching the `optional` Maven scope).
-- New `package-info.java` declaring `@GeneratePrism(DtoPath.class)` and
-  `@GeneratePrism(DtoRef.class)`, generating `DtoPathPrism`/`DtoRefPrism` into
-  `target/generated-sources/annotations`.
-
-Verified: full `querybean-generator` build + existing test suite pass unchanged, and a downstream
-full rebuild (`ebean-test` with `-am`) - which exercises the existing Q-bean codegen - also
-passes with no regressions.
-
-### Trigger mechanism: `@DtoMapping(source, target)` on a neutral package-info.java
-
-Considered and rejected: putting a `source`/entity-referencing annotation directly on the DTO
-class itself (e.g. `@Dto(Customer.class)` on `CustomerDto`). Rejected because DTO types are
-often owned/generated elsewhere (e.g. from an OpenAPI spec) and must not be forced to reference
-an internal persistence/entity type - that would leak internal domain types into a
-public-facing/generated DTO module.
-
-Instead, adopted the same pattern `avaje-jsonb` uses for external/foreign types it doesn't own
-(`@Json.Import`): a repeatable annotation declared on a *neutral* holder - a `package-info.java`
-- naming the `source` entity and `target` DTO as a pair:
-
-```java
-@DtoMapping(source = Customer.class, target = CustomerDto.class)
-@DtoMapping(source = Contact.class, target = ContactDto.class)
-package org.example.dto;
-```
-
-`@DtoMapping` (new, in `ebean-annotation`) is `@Target({PACKAGE, MODULE})`,
-`@Retention(SOURCE)` (pure codegen trigger, never needed at runtime - unlike `@DtoPath`/
-`@DtoRef` which need `CLASS` retention to remain visible to the DTO field itself),
-`@Repeatable(DtoMapping.List.class)` following Java's own repeatable-annotation idiom. Neither
-the entity nor the DTO needs any annotation of its own.
-
-**Generated mapper package placement** - also modeled directly on `avaje-jsonb`'s handling of
-`@Json.Import` for external types (`AdapterName`/`ProcessingContext.isImported`): defaults to the
-target DTO's own package, *unless* the source or target type belongs to a different Java module
-than the one being processed, in which case the generated mapper is placed in a package derived
-from the processing module's own name instead - avoiding a JPMS "split package" violation that
-would occur from generating source into a package owned by another module. An explicit
-`mapperPackage` attribute is available to override this for edge cases. Same-module (or
-non-modular/unnamed-module) projects are unaffected and just get the mapper alongside the DTO.
-
-### mapTo(Class) dispatch: Class-token API + generated compile-time-safe registry
-
-The original API sketch above (`mapTo(CustomerDto.class)`) predates the native-image/no-reflection
-decision. Rather than switching to an instance-based API (`mapTo(new CustomerDtoMapper())`),
-decided to keep the `Class`-token shape and generate a compile-time-safe registry to resolve it -
-no reflection, no `Class.forName`, just literal `Class` comparisons generated at build time, e.g.:
-
-```java
-<S, D> DtoMapper<S, D> mapperFor(Class<S> sourceType, Class<D> targetType) {
-  if (sourceType == Customer.class && targetType == CustomerDto.class) {
-    return (DtoMapper<S, D>) new CustomerDtoMapper();
-  }
-  if (sourceType == Contact.class && targetType == ContactDto.class) {
-    return (DtoMapper<S, D>) new ContactDtoMapper();
-  }
-  return null;
-}
-```
-
-Dispatch is keyed on the **(source, target) pair**, not target alone - this matches how
-`@DtoMapping(source, target)` pairs are declared, allows the same DTO type to be mapped from more
-than one source entity without ambiguity, and lets `query.mapTo(dtoType)` fail fast with a clear
-`PersistenceException` (rather than an incorrect match) when `query.getBeanType()` doesn't pair
-with the requested DTO.
-
-This mirrors the existing, already-proven `EbeanEntityRegister`/`EntityClassRegister` mechanism
-(`SimpleModuleInfoWriter.java`) that `querybean-generator` already generates per module for entity
-classes - a `List<Class<?>>` built from literal `SomeEntity.class` references, registered via
-`META-INF/services` (`ServiceLoader`, itself native-image-friendly with no extra reflection
-config needed for simple no-arg-constructor implementations). The DTO mapper registry follows the
-same per-module aggregation + `META-INF/services` registration shape, giving `mapTo(Class)` a
-concrete generated implementation to dispatch through at runtime without reflection anywhere in
-the chain.
-
-### mapTo(Dto.class) runtime wiring (implemented)
-
-`query.mapTo(dtoType)` returns a `MappedQuery<D>` (`findList()`/`findOne()`/`findOneOrEmpty()`/
-`findStream()`/`findPagedList()`/`usingMaster(boolean)`/`usingTransaction(Transaction)`/`usingConnection(Connection)`).
-On first use it resolves the generated `DtoMapper<S, D>` for the query's `(getBeanType(), dtoType)`
-pair via a `DtoMapperManager` (a `ServiceLoader`-backed aggregator over all generated
-`DtoMapperRegister`s, analogous to `DtoBeanManager`), then:
-
-- applies `mapper.fetchGroup()` to the query via `query.select(fetchGroup)` - the fetch/select spec
-  is entirely derived from the DTO's declared shape, no manual `.select()`/`.fetch()` needed;
-- forces `query.setUnmodifiable(true)` - the resulting entity graph is read-only input to the
-  mapper, and any DTO property whose source wasn't actually fetched fails fast with
-  `LazyInitialisationException` rather than silently lazy loading or returning `null`;
-- executes the query and maps the result(s) via `mapper.map(...)`/`mapper.mapList(...)`.
-
-An unregistered `(source, dtoType)` pair throws a `PersistenceException` with a suggested
-`@DtoMapping` fix, at first use (i.e. `findList()`/`findOne()`), not at `mapTo(dtoType)` call time.
-
-`MappedQuery<D>.usingMaster(boolean)`, `.usingTransaction(Transaction)`, and `.usingConnection(Connection)`
-all delegate directly to the underlying entity query, mirroring `Query`/`QueryBuilder`. This lets a
-caller retry against the master data source after a read-replica failure by calling
-`usingMaster(true)` on the *same* `MappedQuery` instance and re-invoking a find method - there's no
-need to rebuild the query and call `.mapTo(...)` again.
-
-`MappedQuery<D>.findStream()` mirrors `QueryBuilder#findStream()` - the underlying entity query is
-streamed (supporting very large result sets, potentially using multiple persistence contexts
-internally) and each entity is mapped to its target DTO lazily as the stream is consumed. One
-`DtoMapContext` is shared across the whole stream (not per-element), so identity de-duplication of
-nested DTOs (e.g. several `Contact`s sharing the same `Customer`) still holds even when the source
-entities are never materialized into one `List` at all. As with the entity-level `findStream()`,
-callers must consume it via try-with-resources to ensure the underlying resources are closed.
-
-
-## Still open / to revisit during implementation
-
-- Whether `.fetch(...)` calls can still be layered on top of a `mapTo(Dto.class)` query for explicit
-  overrides. Currently the mapper's `fetchGroup()` is the *only* source of the fetch spec - any
-  `.select()`/`.fetch()` calls made before `.mapTo(...)` are overwritten by it.
-- Whether `@DtoPath`/`@DtoRef` need additional attributes beyond a bare path/marker (e.g. an explicit
-  target type on `@DtoRef` for disambiguation) once real DTOs with more complex shapes are codegen'd.
-- Behavior when a DTO property has no matching entity property and no `@DtoPath`/`@Formula2` override
-  (fail at codegen time, most likely, consistent with the "fail fast" philosophy).
-- `@Formula2`-on-DTO mapping to Blaze-Persistence/QueryDSL-style computed properties - not yet
-  implemented (see requirements doc); a narrower validation-only variant was attempted and rejected
-  as not distinct enough from `@DtoPath` (see "Formula2-on-DTO scope" above). The broader ad-hoc-SQL
-  case likely doesn't need a dedicated DTO feature at all - see "Ad-hoc computed/formula properties"
-  above for the `@Entity @View`/`@Sql` alternative.
-- **Fetch-path collision between a `NESTED_ONE`/`NESTED_MANY` property and a `@DtoPath` property -
-  found and fixed**: `DtoMapperWriter.fetchGroupChainCalls()` builds one `.fetch(path, ...)`
-  chain-call per distinct fetch path, but the underlying `OrmQueryDetail.fetch(...)` unconditionally
-  **overwrites** (rather than merges) any existing entry for the same path key. If a DTO declared a
-  `NESTED_ONE`/`NESTED_MANY` property AND a `@DtoPath` property whose fetch-path prefix is the *exact
-  same* path (e.g. a nested `AddressDto billingAddress` alongside `@DtoPath("billingAddress.line1")`
-  on the same DTO - both resolve to fetch path `"billingAddress"`), the generator would emit two
-  `.fetch("billingAddress", ...)` calls and the second would silently discard the first's selected
-  properties. Merging wasn't practical - the nested property's `.fetch(path, mapper.fetchGroup())`
-  call passes another mapper's own pre-built, immutable, shared `FetchGroup`, so there's no clean way
-  to splice an extra scalar property into it at the call site. Fixed instead with a **fail-fast
-  compile-time error**: `DtoMapperWriter` now detects the collision and raises a clear
-  `ctx.logError(...)` (annotation-processor `ERROR` diagnostic, fails the compile) naming the
-  colliding property and fetch path, and suggesting the two ways out - move the property onto the
-  nested DTO type instead, or pick a `@DtoPath` that reaches a different, non-colliding path (as
-  `ContactDto.customerCity` already does deliberately, per its own comment, using a 3-segment path).
-  Verified empirically by compiling a small reproduction with a colliding `@DtoPath` and confirming
-  the expected error fires; a permanent regression test
-  (`DtoMapperFetchPathCollisionTest` in `querybean-generator`) now runs this same repro directly
-  through `javax.tools.JavaCompiler` with the `Processor` registered, asserting the compile fails with
-  the expected diagnostic message.
-- **Compile-time verification of `select(...).asDto(...)` (r6, aspirational) - explored and closed as
-  rejected**: raw SQL is an opaque `String` at compile time, and even the typed query-bean
-  `.select(...)` form only type-checks against the *entity* - the match to the target DTO's constructor
-  still happens at runtime via reflection (`DtoQueryPlanConstructor`), and the `.asDto(...)` call site
-  can be arbitrarily distant from the `.select(...)` call, so there's no fixed AST shape an annotation
-  processor could reliably verify (unlike QueryDSL, whose compile-time safety actually comes from typed
-  `Projections.constructor(...)`/generated Q-type constructor calls, not from checking a select-list
-  against a DTO). `mapTo(Dto.class)` already closes the underlying gap in the tractable direction - it
-  derives the select/fetch spec *from* the DTO's declared shape at APT time, so it is compile-time safe
-  by construction. Recommend `mapTo()` whenever compile-time-checked DTO projection matters, and treat
-  `asDto()`/`findDto()` as the flexible, runtime-checked escape hatch for raw/dynamic SQL. See
-  `dto-mapping-requirements.md` requirement r6.
-- **Custom property conversion (`@DtoConvert`/`@DtoMixin`, r13/r14) - implemented**: motivated by a
-  real hand-written mapper (`DriverMapper`, central-access) needing both a dependency-free scalar
-  coercion (`short` -> `boolean`) and a dependency-backed conversion (AES decryption via an injected
-  cipher). Final design (see `dto-mapping-requirements.md` section E), as built:
-  - `@DtoConvert(value = ConverterType.class, method = "name")` on a DTO property (combinable with
-    `@DtoPath`); the generator dispatches on whether the referenced method is `static` - static means a
-    direct inlined static call (no registration, covers common reusable coercions), instance means
-    dispatch via a new `DtoConverterManager.get(ConverterType.class).method(...)` call, with the
-    resolved instance wired as a real constructor parameter/field on the generated mapper (same shape
-    as existing nested-mapper constructor injection). Multiple properties on the same mapper sharing
-    the same converter type are deduplicated to a single constructor parameter/field
-    (`DtoBeanMeta.converterDeps()`).
-  - `DtoConverterManager` (`ebean-api`, `io.ebean` package) is a small, narrowly-scoped static put/get
-    bridge - the app registers an already-DI-constructed converter singleton (e.g. built by
-    avaje-inject) *before* building the `Database`. This is a deliberate, narrow exception to the
-    general no-static-mutable-state convention: `ServiceLoader`-discovered, no-arg-constructed
-    generated code (`EbeanDtoMapperRegister`) has no other way to reach an already-DI-constructed
-    singleton. `DtoConverterManager.get(type)` throws immediately if nothing was registered for that
-    type, so a missing converter fails fast at Database-startup time (an eager field initializer on
-    `EbeanDtoMapperRegister`, and equally on each mapper's own no-arg constructor, which resolves the
-    same way via `DtoConverterManager.get(...)` for standalone/test construction), not lazily on first
-    use - `DtoMapperRegister`'s `mapperFor(...)` signature and `DtoMapperManager` are otherwise
-    completely unchanged, as originally planned.
-  - Two alternatives were explored and rejected first: (a) a `DtoMapContext.service(Class)` lookup -
-    wrong lifetime, `DtoMapContext` is a short-lived per-call identity-cache only; (b) a
-    `ServiceLoader`-discovered `DtoConverterSource` SPI mirroring `DtoMapperRegister` itself - can't
-    bridge to an *already* DI-constructed dependency without reconstructing/duplicating it.
-  - `@DtoMixin(Target.class)` - a companion type overlaying `@DtoPath`/`@DtoConvert`/`@DtoRef`
-    annotations onto a DTO that can't be annotated directly (e.g. OpenAPI-generated). Discovered via
-    `roundEnv.getElementsAnnotatedWith(...)` (added to `Processor.getSupportedAnnotationTypes()`,
-    since - unlike `@DtoPath`/`@DtoRef`/`@DtoConvert` - a mixin doesn't annotate an already-iterated
-    field of a known `@DtoMapping` target, so it can't be found lazily). `DtoMappingReader` resolves
-    each target property's annotations from the field itself first, falling back to a same-named
-    method on the registered mixin (`DtoMappingReader.prismOn(...)`) - directly mirrors avaje-jsonb's
-    proven `@Json.MixIn` mechanism.
-  - Implemented in `ebean-annotation` (`DtoConvert`, `DtoMixin`), `ebean-api` (`DtoConverterManager`),
-    and `querybean-generator` (`DtoConverterMeta`, `DtoBeanMeta.converterDeps()`,
-    `DtoMappingReader`/`DtoMapperWriter`/`DtoMapperRegisterWriter` changes). Test coverage:
-    `tests/test-dto-mapping` `TestDtoConvert` (static + instance dispatch, fail-fast unregistered-type
-    check) and `TestDtoMixin` (mixin overlay, including instance-dispatch conversion resolved purely
-    from mixin-declared annotations). The instance-dispatch converter is registered via a
-    `DatabaseConfigProvider` (ServiceLoader hook run before the `Database` is built) rather than a test
-    `@BeforeAll`, since `EbeanDtoMapperRegister`'s mapper fields (including any needing
-    `DtoConverterManager`) are all constructed eagerly during `Database` startup, which can be
-    triggered by whichever test class in the module happens to run first.
-
-- **Fixed (validation phase, found via `central-access`): `@DtoPath` through a computed/derived
-  getter now fails at compile time, with an explicit `requires()` escape hatch.** `@DtoPath`
-  assumes every dotted segment names a real, fetchable Ebean bean property - so a path like
-  `@DtoPath("currentMachine.organisationMachine.registrationPlate")`, where `getOrganisationMachine()`
-  is a hand-written derived getter (not a real relation/column), used to **compile cleanly** (the
-  codegen had no way to tell it apart from a real property from source alone) but **fail at
-  runtime** with a `PersistenceException: No property found for [organisationMachine] in
-  expression ...`, because the generated `FetchGroup` builder tried to `fetch`/`select` it as if it
-  were a real Ebean property.
-  - Two genuinely separate sub-problems: (1) *detecting* that a path segment isn't a real,
-    fetchable property - solvable at compile time, since a real persistent property always has a
-    backing field (Ebean requires one to enhance), checked via `javax.lang.model`
-    (`ElementFilter.fieldsIn(...)` over the type + superclass chain, see `DtoMappingReader.hasField(...)`);
-    versus (2) *knowing what the computed getter needs fetched* to execute safely - not solvable at
-    compile time without full static/bytecode analysis of the getter's method body, out of scope.
-  - Resolution: don't attempt to infer (2) automatically. When `DtoMappingReader` detects a `@DtoPath`
-    segment with no backing field, it now fails fast at compile time (`ctx.logError(...)`) unless the
-    developer explicitly declares the real entity paths that must be fetched via
-    `@DtoPath(requires = {...})` (dot-notation, same convention as `@DtoPath`'s own `value()`) - e.g.
-    `@DtoPath(value = "primaryContact.lastName", requires = "contacts")` where `getPrimaryContact()`
-    picks the first entry out of the `contacts` collection. The real prefix before the computed
-    segment (if any) is automatically combined with the declared `requires()` paths, so the developer
-    doesn't need to redundantly repeat it. Declared paths are emitted as bare `.fetch(path)` calls in
-    the generated `FetchGroup` (distinct from the `.fetch(path, "props")` shape used for ordinary
-    scalar `@DtoPath` properties, since there's no specific target property list to narrow to here).
-  - **The zero-extra-fetch case is also supported, via an explicit `requires = {}`** - e.g.
-    `@DtoPath(value = "idBadge", requires = {})` where `getIdBadge()` derives purely from `id`
-    (always fetched regardless). An explicit empty array confirms "nothing extra needed", distinct
-    from omitting `requires()` entirely ("not yet considered", still a compile error) - `requires()`
-    itself can't tell the two cases apart (both read back as an empty `List`), so `DtoMappingReader`
-    checks the avaje-prism-generated `DtoPathPrism.values.requires()` instead, which returns `null`
-    only when the member was left at its default (i.e. omitted from source). `DtoPropertyMeta`
-    correspondingly carries `hasComputedSegment()` as its own boolean flag (set whenever a computed
-    segment was detected at all), independent of whether `requiredFetchPaths()` happens to be empty -
-    an earlier version conflated the two (inferring "has a computed segment" from "has a non-empty
-    requiredFetchPaths list"), which broke exactly this explicit-empty case by falling through to the
-    ordinary scalar `.select(...)` path and failing at runtime with `PersistenceException: Property
-    not found - idBadge` (`idBadge` isn't a real Ebean property, so it can't be selected).
-  - Implemented in `ebean-annotation` (`DtoPath.requires()`), and `querybean-generator`
-    (`DtoMappingReader` computed-segment detection/validation, `DtoPropertyMeta.requiredFetchPaths()`/
-    `hasComputedSegment()`, `DtoMapperWriter.fetchGroupChainCalls()` bare-fetch emission). Test
-    coverage: `tests/test-dto-mapping` `ComputedPathDto`/`TestComputedPath` (happy path, `requires`
-    correctly fetches the dependency and the mapped value is correct), `ComputedPathNoFetchDto`/
-    `TestComputedPathNoFetch` (explicit `requires = {}`, genuinely nothing extra needed), and
-    `querybean-generator`'s `DtoMapperComputedPathTest` (negative case - omitting `requires` on a
-    computed segment is a compile-time `ERROR` diagnostic, verified via direct `javax.tools.JavaCompiler`
-    compilation, mirroring `DtoMapperFetchPathCollisionTest`).
-  - Known gap: the dedup between the computed segment's required fetch paths and existing
-    `pathSelect`/`nestedAssocPaths` keys in `DtoMapperWriter` is a simplified exact-path-string check
-    (skip emitting a duplicate `.fetch(path)`), not full collision detection like the existing
-    NESTED_ONE/MANY vs `@DtoPath` check - a bare `fetch(path)` and an existing `fetch(path,
-    "specific,props")` for the same path string are not merged/reconciled, just left as two separate
-    calls if that edge case arises.
-
-- **Fixed: a single-hop `@DtoPath` rename through a computed/derived getter whose return type is
-  itself a registered nested DTO (`NESTED_ONE`/`NESTED_MANY`, not `SCALAR`) bypassed the
-  computed-segment validation above entirely.** E.g. `@DtoPath("primaryContact")` where the DTO
-  field's declared type is `ContactDto` (a type with its own `@DtoMapping(source = Contact.class,
-  target = ContactDto.class)`) and `getPrimaryContact()` is a computed getter with no backing
-  field on `Customer`. This resolves to a single-segment path, so `DtoMappingReader.resolveProperty()`
-  took its `properties.size() == 1` nested-lookup shortcut and returned early - before the
-  `computedFrom`/`requires()` validation block (added for the `SCALAR` case above) ever ran. The
-  generated `FetchGroup` then emitted a broken `fetch("primaryContact",
-  contactMapper.fetchGroup())` call (`"primaryContact"` isn't a real Ebean fetch path), failing at
-  runtime rather than compile time - the exact class of bug the `SCALAR` fix was meant to close off
-  entirely.
-  - Resolution: restructured `resolveProperty()` so the computed-segment detection/validation block
-    runs *before* the `properties.size() == 1` nested-lookup branch, so both `SCALAR` and
-    `NESTED_ONE`/`NESTED_MANY` paths share the same detection/validation. `DtoPropertyMeta` gained a
-    matching constructor overload for `NESTED_ONE`/`NESTED_MANY` carrying `computedSegment`/
-    `requiredFetchPaths`. In `DtoMapperWriter.fetchGroupChainCalls()`, a `NESTED_ONE`/`NESTED_MANY`
-    property with `hasComputedSegment()` true is routed into `extraFetchPaths` (the same bare
-    `.fetch(path)` mechanism as the `SCALAR` case) instead of emitting `fetch(path,
-    mapper.fetchGroup())` - since the nested mapper's own `FetchGroup` requirements can't be
-    meaningfully attached under a path name that doesn't exist on the source entity.
-  - Note the nested mapper's *own* fetch requirements (e.g. if `ContactDto` itself needed
-    `customer.billingAddress`) are **not** automatically propagated up through a computed segment -
-    only whatever the computed getter itself needs (via `requires()`) is fetched. The nested
-    mapper's `map(...)` call still works via plain Java method invocation regardless (Ebean
-    transparent lazy loading covers any gap), but relying on that silently reintroduces N+1 queries,
-    so the nested DTO used through a computed segment should ideally be a "leaf" shape needing
-    nothing beyond what `requires()` already declares.
-  - Implemented in `querybean-generator` (`DtoMappingReader.resolveProperty()` restructuring,
-    `DtoPropertyMeta`'s new constructor overload, `DtoMapperWriter.fetchGroupChainCalls()`). Test
-    coverage: `tests/test-dto-mapping` `ContactLeafDto`/`ComputedNestedDto`/`TestComputedNestedPath`
-    (happy path - generated `FetchGroup` is `.select("id").fetch("contacts")`, no broken
-    `fetch("primaryContact", ...)` call, and the mapped value is correct end-to-end), and
-    `querybean-generator`'s `DtoMapperComputedPathTest#dtoPathThroughComputedGetter_targetingNestedDto_withoutRequires_expectCompileError`
-    (negative case, mirroring the `SCALAR` one). The `NESTED_MANY` variant (a computed getter
-    returning a `List` of a type with its own registered nested DTO mapping) shares the identical
-    code path but had no dedicated regression test until later confirmed via `Customer
-    .getRecentContacts()` / `ComputedNestedListDto` / `TestComputedNestedListPath` (coverage only,
-    not a bug fix - passed cleanly first try, confirming the shared code path does work end-to-end
-    for both `NESTED_ONE` and `NESTED_MANY`).
-
-- **Fixed: `@DtoRef` never checked for a computed/derived association getter at all.** Unlike
-  `@DtoPath`, `@DtoRef`'s association name (derived by stripping the `Id` suffix off the field
-  name, e.g. `primaryContactId` -> `primaryContact`) was never checked against `hasField(...)` -
-  so `@DtoRef` on a computed getter (e.g. `getPrimaryContact()` picking the first entry out of a
-  `contacts` collection) compiled cleanly and generated a broken `FetchGroup.select("primaryContact")`
-  call (`"primaryContact"` isn't a real Ebean property), failing at runtime rather than compile
-  time - the same class of bug as the original `@DtoPath` fix, just entirely unaddressed for
-  `@DtoRef`'s separate code path.
-  - Resolution: `@DtoRef` gained its own `requires()` attribute (dot-notation, same convention and
-    explicit-empty semantics as `@DtoPath#requires()`, using the same `DtoRefPrism.values.requires()
-    == null` omitted-vs-explicit-empty technique). `DtoMappingReader`'s `@DtoRef` branch now checks
-    `hasField(meta.source(), assocName)` and fails fast at compile time (`ctx.logError(...)`) when
-    the association has no backing field and `requires()` wasn't specified. `DtoPropertyMeta`'s
-    `REF` properties now carry `computedSegment`/`requiredFetchPaths` through the existing fields
-    (no new constructor needed - the full constructor already had the right shape).
-    `DtoMapperWriter.fetchGroupChainCalls()`'s `REF` case now checks `hasComputedSegment()` and
-    routes into `extraFetchPaths` (bare `.fetch(path)`) instead of `rootSelect.add(assoc)` when
-    true - the value expression itself (`source.getPrimaryContact().getId()`, null-guarded) is
-    unaffected, since it's plain Java method invocation regardless of whether the association name
-    is a real Ebean property.
-  - Implemented in `ebean-annotation` (`DtoRef.requires()`), and `querybean-generator`
-    (`DtoMappingReader`'s `@DtoRef` branch, `DtoMapperWriter.fetchGroupChainCalls()`'s `REF` case).
-    Test coverage: `tests/test-dto-mapping` `ComputedRefDto`/`TestComputedRefPath` (happy path -
-    generated `FetchGroup` is `.select("id").fetch("contacts")`, no broken `select("primaryContact")`
-    call, and the mapped id is correct end-to-end), and `querybean-generator`'s
-    `DtoMapperComputedPathTest#dtoRefThroughComputedGetter_withoutRequires_expectCompileError`
-    (negative case, mirroring the `@DtoPath` ones).
-
-- **Fixed: `requires()` path values themselves were never validated against the source type's
-  real property graph.** `@DtoPath(requires = {...})`/`@DtoRef(requires = {...})` values are
-  handed straight through to `FetchGroup.fetch(...)` unmodified - a typo (e.g. `requires =
-  "contactz"` for the real `contacts` property) compiled cleanly, since only the *computed
-  segment itself* was checked against `hasField(...)`, not the developer-declared dependency
-  paths meant to fix it. That silently reintroduced the exact runtime `PersistenceException` the
-  whole `requires()` escape hatch exists to prevent, just one step removed and harder to spot.
-  - Resolution: added `DtoMappingReader.validateRequiresPath(...)`, which walks each dot-notation
-    segment of a declared `requires()` value from the source root (`meta.source()`), checking
-    `hasField(...)` at every hop exactly like `@DtoPath#value()`'s own segments are checked, and
-    unwrapping a `java.util.List`-typed intermediate hop to its element type (via
-    `listElementType(TypeMirror)`) so a collection segment followed by a further hop resolves
-    correctly - needed a new `getterReturnTypeMirror(...)` helper (returning the raw `TypeMirror`
-    rather than converting straight to `TypeElement`, which can't distinguish a `List` from any
-    other declared type) alongside the existing `getterReturnType(...)`. Called for every entry in
-    `pathPrism.requires()`/`refPrism.requires()` right after they're read, for both the `@DtoPath`
-    and `@DtoRef` branches. The already-validated real prefix (segments before the computed one in
-    a `@DtoPath#value()`) is intentionally *not* re-validated, since it was already checked while
-    walking `value()` itself.
-  - Implemented in `querybean-generator` (`DtoMappingReader.validateRequiresPath(...)`,
-    `getterReturnTypeMirror(...)`, called from both the `@DtoPath` and `@DtoRef` branches). Test
-    coverage: `querybean-generator`'s
-    `DtoMapperComputedPathTest#dtoPathRequires_withTypoInPathValue_expectCompileError` (negative
-    case - a typo'd `requires()` segment is a compile-time `ERROR` diagnostic); existing
-    `tests/test-dto-mapping`/`central-access` suites (real multi-segment `requires()` values like
-    `"currentMachine.organisationMachines"`) continue to pass unchanged, confirming the validation
-    doesn't false-positive on legitimate paths.
-
-- **Fixed: a bare, full `requires()` fetch and a sibling property's narrowed `@DtoPath` fetch of
-  the exact same path silently conflicted, with the narrow one always (incorrectly) winning.**
-  `DtoMapperWriter.fetchGroupChainCalls()`'s dedup logic used to skip emitting a computed
-  segment's bare `fetch(path)` call whenever another property's `@DtoPath` already had a narrowed
-  `fetch(path, "specific,props")` entry for that exact path string - on the assumption the two
-  were interchangeable/redundant. They aren't: `FetchGroup`'s builder (`OrmQueryDetail.fetch(...)`)
-  keys fetch calls by path in a plain `Map` and **replaces** rather than merges same-path entries,
-  so whichever call format was emitted meant the *other* was silently discarded. Since the narrow
-  entry was always emitted first and the bare one skipped whenever it existed, the narrow selection
-  always won - meaning a computed getter's `requires()` declaration could be completely ignored
-  whenever an unrelated sibling `@DtoPath` happened to narrow-select the exact same path, leaving
-  whatever extra properties the computed getter actually touches unfetched (a silent lazy load, or
-  a hard `LazyInitialisationException` outside a persistence context).
-  - Resolution: reversed the priority - `fetchGroupChainCalls()` now skips a narrowed `pathSelect`
-    entry when `extraFetchPaths` (the computed segment's `requires()`) declares the exact same
-    path, letting the bare, full `fetch(path)` call win instead. This is always safe since a full
-    fetch is a superset of any narrower property selection - the narrow entry's own properties are
-    included within it regardless. The existing `nestedAssocPaths` priority (a `NESTED_ONE`/
-    `NESTED_MANY` property's full `fetch(path, mapper.fetchGroup())` always wins over a bare
-    `fetch(path)`) was correct already and left unchanged - a nested mapper's own `FetchGroup` is
-    strictly richer than either form and must not be replaced by either.
-  - Implemented in `querybean-generator` (`DtoMapperWriter.fetchGroupChainCalls()`). Test coverage:
-    `tests/test-dto-mapping` `FetchCollisionDto`/`TestFetchCollisionPath`, plus a new computed
-    getter `Customer.getBillingSummary()` (reads `billingAddress.getLine1()`, deliberately a
-    different `Address` property to the `city` narrowly selected by a sibling `@DtoPath` on the
-    same DTO) - confirmed to reproduce `LazyInitialisationException: Property not loaded: line1`
-    when the fix is reverted, and pass cleanly (correct `line1`-derived value, generated
-    `FetchGroup` is `.select("id").fetch("billingAddress")` with no narrowed variant at all) with
-    it in place.
-
-- **Fixed: two `@DtoMixin` companion types targeting the same DTO class silently conflicted, with
-  the second-processed one winning.** `DtoMappingReader.collectMixins()` keyed a single
-  `mixinsByTarget` map by the target DTO's FQN, and `Map.put(...)` unconditionally overwrote any
-  existing entry - so if two mixin interfaces (e.g. a legitimate one plus an accidental duplicate,
-  or two independently-added mixins that both happened to target the same generated/unowned DTO)
-  both declared `@DtoMixin(SameDto.class)`, whichever was visited last by
-  `roundEnv.getElementsAnnotatedWith(...)` silently won, and *all* of the other mixin's
-  `@DtoPath`/`@DtoRef`/`@DtoConvert` overlays were discarded with no diagnostic at all.
-  - Resolution: `collectMixins()` now checks for an existing registration before storing a new one
-    and raises a compile `ERROR` naming both the target and the already-registered mixin's
-    qualified name, rather than silently overwriting it.
-  - Implemented in `querybean-generator` (`DtoMappingReader.collectMixins()`). Test coverage: new
-    negative compile-error test `DtoMapperComputedPathTest#duplicateDtoMixin_forSameTarget_expectCompileError`
-    (two minimal `@DtoMixin(FooDto.class)` interfaces both declaring a `bar()` method, compiled
-    together, asserting the `Duplicate @DtoMixin` diagnostic is raised); existing
-    `tests/test-dto-mapping` `TestDtoMixin` (single, legitimate mixin usage) continues to pass
-    unchanged.
-
-- **Fixed: `@DtoRef` and `@DtoPath` both present on the same field silently conflicted, with
-  `@DtoRef` always (invisibly) winning.** `resolveProperty()` checked `refPrism != null` first and
-  returned immediately whenever present, so a field carrying both annotations at once - whether by
-  copy/paste mistake, a half-finished rename from one style to the other, or simple confusion
-  between the two escape hatches - had its `@DtoPath` completely ignored with no diagnostic at all.
-  - Resolution: `resolveProperty()` now resolves both prisms upfront and raises a compile `ERROR`
-    naming the field when both are present, rather than silently picking `@DtoRef` and discarding
-    `@DtoPath`.
-  - Implemented in `querybean-generator` (`DtoMappingReader.resolveProperty()`). Test coverage: new
-    negative compile-error test `DtoMapperComputedPathTest#dtoRefAndDtoPath_onSameField_expectCompileError`
-    (a field carrying both `@DtoRef` and `@DtoPath("bar.id")` over a real, non-computed association,
-    isolating the conflict diagnostic from the separate computed-getter `requires()` diagnostics).
-
-- **Fixed: `@DtoConvert` on a `NESTED_ONE`/`NESTED_MANY` property was silently ignored.**
-  `resolveProperty()` resolves the property's `DtoConverterMeta` unconditionally up front (before
-  it's known whether the property will resolve to `SCALAR`/`REF`/`NESTED_ONE`/`NESTED_MANY`), but
-  only the `SCALAR`/`REF` `DtoPropertyMeta` constructors actually accept/store a converter - the
-  `NESTED_ONE`/`NESTED_MANY` constructor calls never took one, so a resolved converter was simply
-  dropped on the floor with no diagnostic. A developer adding `@DtoConvert` to a nested-DTO field
-  (e.g. hoping to post-process the nested mapper's result) would see it silently do nothing -
-  `DtoMapperWriter.propertyValueExpression()`'s `NESTED_ONE`/`NESTED_MANY` cases call straight into
-  `mapperFieldName(property) + ".map(...)"`/`".mapList(...)"` with no converter wrapping at all.
-  - Resolution: added `rejectConverterOnNested(...)`, called at each of the four call sites that
-    construct a `NESTED_ONE`/`NESTED_MANY` `DtoPropertyMeta` (the single-hop `@DtoPath`-rename
-    branch's two cases, and the plain non-`@DtoPath` branch's two cases) - raises a compile `ERROR`
-    naming the field whenever a converter was resolved for it, rather than silently discarding it.
-  - Implemented in `querybean-generator` (`DtoMappingReader.resolveProperty()`,
-    `rejectConverterOnNested()`). Test coverage: new negative compile-error test
-    `DtoMapperComputedPathTest#dtoConvertOnNestedOne_expectCompileError` (a `NESTED_ONE` field
-    carrying `@DtoConvert` over a legitimately nested, separately-`@DtoMapping`-registered type);
-    existing `tests/test-dto-mapping` suite (no nested property currently combines `@DtoConvert`
-    with `NESTED_ONE`/`NESTED_MANY`) continues to pass unchanged, confirming no false positives on
-    plain nested properties.
-
-- **Fixed: `@DtoConvert(method = ...)` resolution ignored parameter arity/overloads.** The shared
-  `findMethod(type, name)` helper (also used for the builder's `build()` lookup and `@DtoMixin`
-  companion-method lookup) matches purely by simple name - the first `ExecutableElement` found -
-  with no arity or parameter-type check at all. For `@DtoConvert` specifically this is a real risk:
-  its documented contract is a method "taking the source property value and returning the
-  converted DTO property value" (i.e. exactly one parameter), but a shared/reusable conversion
-  utility class is a very plausible place to have multiple same-named overloads (e.g. `format
-  (Instant)` and `format(LocalDate)`) - `findMethod` would silently bind to whichever one
-  `ElementFilter.methodsIn` happened to return first, independent of which one the developer
-  actually meant, generating either a confusing arity/type-mismatch compile error in the generated
-  mapper or, if both overloads happened to be call-compatible, silently invoking the wrong one.
-  - Resolution: added a dedicated `findConverterMethod(...)` (used only by `resolveConverter()`,
-    leaving the shared `findMethod()` untouched for the builder/mixin call sites which have their
-    own, different arity expectations) that filters same-named candidates down to those taking
-    exactly one parameter. Zero matches raises a clear "not found ... taking exactly one
-    parameter" error; more than one match (multiple 1-arg overloads sharing the name) raises an
-    "ambiguous - N overloads take exactly one parameter" error, since `@DtoConvert` has no
-    parameter-type-based way to disambiguate and the developer must rename one of the overloads.
-  - Implemented in `querybean-generator` (`DtoMappingReader.resolveConverter()`,
-    `findConverterMethod()`). Test coverage: new negative compile-error tests
-    `DtoMapperComputedPathTest#dtoConvertMethod_withAmbiguousOverloads_expectCompileError` (two
-    same-named 1-arg overloads) and `#dtoConvertMethod_withWrongArity_expectCompileError` (a
-    same-named 0-arg method, no 1-arg candidate at all); existing `tests/test-dto-mapping`
-    converter usage (a single, unambiguous 1-arg method per converter type) continues to resolve
-    and pass unchanged.
-
-## References
-
-- Requirements: [dto-mapping-requirements.md](./dto-mapping-requirements.md)
-- Issue: https://github.com/ebean-orm/ebean/issues/2540
-- MapStruct cycle mapping: https://mapstruct.org/documentation/stable/reference/html/#mapping-object-cycles

docs/dto-mapping-requirements.md

@@ -1,337 +0,0 @@
-# Nested DTO Mapping — Requirements
-
-Design requirements distilled from [issue #2540 "Support nested DTO mapping"](https://github.com/ebean-orm/ebean/issues/2540),
-reviewed against comparable features in QueryDSL (`@QueryProjection`) and Blaze-Persistence (`@EntityView`).
-
-## Context
-
-Ebean already supports:
-
-- Partial/flat DTO queries via `DB.findDto(...)` and `query.select(...).asDto(Dto.class)`.
-- `@Formula` / `@Formula2` — path-based, auto-joined computed SQL expressions, but only on managed entities.
-- `query.setUnmodifiable(true)` — builds a read-only, non-lazy-loading entity graph (`InterceptReadOnly`,
-  see PR #2626). Accessing an unloaded property throws `LazyInitializationException`; mutating throws
-  `UnmodifiableEntityException`.
-
-Unlike Hibernate, Ebean does dirty-detection on the bean itself (no dynamic proxies), so there is very little
-extra cost to an entity-graph query versus a DTO query. This makes an **unmodifiable entity graph** a cheap,
-natural intermediate representation to map *from* when producing a DTO graph — we don't need Blaze/Hibernate's
-proxy-based `EntityView` mechanism to get the performance benefit they are chasing.
-
-The goal is nested DTO graph support (DTOs containing ToOne/ToMany child DTOs), not just today's flat DTOs,
-while keeping DTOs as plain, framework-unattached classes.
-
-## Accepted Requirements
-
-### A. Nested DTO graphs
-
-- **Support nested DTO graphs (ToOne/ToMany)**
-  Allow mapping a query result into a DTO graph where DTO fields are themselves DTOs (ToOne) or
-  `List`/`Set<Dto>` (ToMany), not just flat DTOs. Use the existing `setUnmodifiable(true)` entity graph as
-  the intermediate, de-duplicated, identity-consistent source to map from.
-  *Inspiration: Blaze `@EntityView` subviews/subview collections; Jimmer fetcher DTOs.*
-
-- **Auto-generated entity → DTO graph mapper**
-  Given an unmodifiable entity graph plus a target nested DTO type, generate (via annotation processing,
-  reflection-free) a mapper that walks the graph and populates the DTO graph, matching properties by
-  name/type with override annotations for renames, computed values, and collection element types.
-  *Inspiration: Blaze `@EntityView` + subview mapping; conceptually similar to MapStruct but Ebean-generated
-  and graph/identity aware.*
-
-- **Identity-aware de-duplication in nested collections**
-  When mapping nested collections referencing the same underlying entity instance multiple times, reuse the
-  same DTO instance (mirrors Blaze/Jimmer identity semantics) rather than producing independent copies.
-  *Inspiration: Blaze/Jimmer identity handling.*
-
-### B. Formula-style DTO annotations
-
-- **`@Formula2`-like annotations on DTO fields**
-  Bring the existing `@Formula` / `@Formula2` concept (auto-joined, path-based computed SQL expressions) to
-  DTO classes so a DTO field can request a computed/aggregated value with the join auto-derived, instead of
-  only being available on managed entities.
-  *Inspiration: User suggestion; Ebean `@Formula2`; Blaze `@Mapping` computed expressions.*
-  *Status: a narrower version (pulling in an existing entity-level `@Formula2` by path) was implemented and
-  then rejected - for the common same-name case it generated code identical to a plain unannotated field, so
-  the annotation added no real value beyond a codegen-time validation. See `docs/dto-mapping-design.md`
-  ("Formula2-on-DTO scope" and "Ad-hoc computed/formula properties" sections). The broader goal - arbitrary
-  ad-hoc computed SQL on a DTO field - is better served by modelling the computed value as its own
-  `@Entity @View`/`@Sql` read entity and mapping *that* into a plain DTO, reusing the existing (already
-  accepted) nested-DTO mapping machinery rather than a new DTO-level annotation.
-
-- **Path-based property mapping annotation on DTO**
-  Allow a DTO field or constructor param to be annotated with a source path expression (e.g. `parent.name`)
-  so Ebean can auto-derive the select clause plus joins for nested/renamed properties, reducing manual
-  constructor wiring for non-trivial mappings.
-  *Inspiration: Blaze `@Mapping`; QueryDSL constructor expressions.*
-
-### C. Compile-time safety
-
-- **Compile-time verification of `select(...).asDto(...)` mapping** *(explored, rejected as impractical -
-  `mapTo()` accepted as the alternative)*
-  Today `select(props).asDto(Dto.class)` is only checked at runtime. Explored an annotation-processor
-  based mechanism to verify at compile time that selected properties match the DTO constructor or setters,
-  mirroring QueryDSL's `@QueryProjection` compile-time Q-type generation. Rejected as impractical: raw SQL
-  is an opaque `String` at compile time, and even the typed query-bean `.select(...)` form only
-  type-checks against the *entity* - the match to the target DTO still happens at runtime via reflection
-  (`DtoQueryPlanConstructor`), and the `.asDto(...)` call site can be arbitrarily distant from the
-  `.select(...)` call, so there's no fixed AST shape an annotation processor could reliably verify.
-  QueryDSL's actual compile-time safety comes from a different mechanism entirely - typed
-  `Projections.constructor(...)`/generated Q-type constructor calls, not from checking an
-  independently-built select-list against a DTO. `mapTo(Dto.class)` (see section A) already closes the
-  underlying gap in the opposite, tractable direction: it derives the select/fetch spec *from* the DTO's
-  declared shape at APT time, so it is compile-time safe by construction, with no separate select-list to
-  drift out of sync. Recommendation: document `mapTo()` as the compile-time-safe answer for DTO
-  projections, and treat `asDto()`/`findDto()` explicitly as the flexible, runtime-checked escape hatch
-  for raw/dynamic SQL.
-  *Inspiration: QueryDSL `@QueryProjection` compile-time Q-type generation.*
-
-- **Fail-fast on unmapped or lazy property access**
-  Ensure a clear, documented, minimal-ceremony way to fail fast if code touches a property not included in
-  the query projection, instead of silently lazy loading or returning null. `query.setUnmodifiable(true)`
-  already satisfies this (throws `LazyInitializationException`) — document/promote it as the answer, and
-  evaluate whether a lighter-weight flag decoupled from full unmodifiable/read-only semantics is needed.
-  *Inspiration: Original issue ask; already solved via `setUnmodifiable()` (PR #2626 `InterceptReadOnly`).*
-
-### D. Fetch strategy and performance
-
-- **Fetch strategy control for DTO graph relationships**
-  Existing entity query fetch hints (join vs. select/subselect secondary query, `+query`/`+lazy`) should
-  transparently carry over when the target of the query is a DTO graph rather than an entity graph.
-  `query.mapTo(Dto.class)` applies the DTO-derived `FetchGroup` only when the query has no
-  `select()`/`fetch()` already set - a manually tuned fetch spec always takes precedence and is never
-  overridden, allowing manual query optimisation when needed (at the cost of falling back to the
-  existing fail-fast-on-unmapped-property behaviour if the manual spec doesn't cover what the DTO needs).
-  *Inspiration: Blaze FETCH/SELECT/SUBSELECT fetch strategies.*
-
-- **Pagination support for DTO graph queries**
-  Confirm existing pagination works unchanged when projecting into nested DTO graphs.
-  *Inspiration: Blaze pagination and keyset pagination support.*
-
-### E. Custom property conversion
-
-- **Per-property custom scalar conversion (`@DtoConvert`)**
-  Motivated by real hand-written mapper code (`DriverMapper`, central-access) doing per-property scalar
-  coercion (`short` -> `boolean`) and dependency-backed conversion (AES decryption via an injected cipher).
-  Introduce a `@DtoConvert(value = ConverterType.class, method = "name")` annotation (combinable with
-  `@DtoPath` for source-getter override) on a DTO property. The generator dispatches based on whether the
-  referenced method is `static`:
-  - **Static method** -> a direct static call is inlined (`ConverterType.method(source.getX())`), zero
-    ceremony, no registration - covers common, reusable, dependency-free scalar coercions (e.g.
-    `short`/`boolean`, enum <-> `String`) that could apply across many unrelated entity/DTO pairs.
-  - **Instance method** -> dispatched via `DtoConverterManager.get(ConverterType.class).method(source.getX())`
-    and wired as a real constructor parameter/field on the generated mapper (same shape as existing
-    nested-mapper constructor injection) - covers conversions needing a real dependency (e.g. a cipher).
-  `DtoConverterManager` is a small, deliberately-scoped static put/get bridge: the app registers an
-  already-DI-constructed converter singleton (e.g. built by avaje-inject) *before* building the `Database`.
-  This is a narrow, accepted exception to the general no-static-mutable-state convention - it exists solely
-  to bridge an already-DI-constructed singleton into `ServiceLoader`-discovered, no-arg-constructed generated
-  code, which cannot otherwise reach a DI container. `DtoConverterManager.get(type)` throws immediately if
-  nothing was registered, so a missing converter fails fast at Database-startup time (an eager field
-  initializer on the generated `EbeanDtoMapperRegister`), not lazily on first use.
-  *Design exploration considered and rejected two alternatives first: (a) a `DtoMapContext.service(Class)`
-  lookup - rejected because `DtoMapContext` is a short-lived per-call identity-cache only, wrong lifetime for
-  a real singleton dependency; (b) a `ServiceLoader`-discovered `DtoConverterSource` SPI mirroring
-  `DtoMapperRegister` itself - rejected because a `ServiceLoader`-instantiated (no-arg) source cannot bridge
-  to an *already* DI-constructed dependency (e.g. a cipher needing config/secrets) without reconstructing it
-  itself, duplicating/bypassing the app's own DI-managed instance.*
-  *Inspiration: `DriverMapper` (central-access) hand-written pattern; MapStruct qualified converter methods.*
-  *Status: implemented - `@DtoConvert` (ebean-annotation), `io.ebean.DtoConverterManager` (ebean-api), and
-  querybean-generator codegen support (static/instance dispatch, constructor wiring deduplicated by converter
-  type). Test coverage: `tests/test-dto-mapping` `TestDtoConvert`.*
-
-- **Type-pair (package-level) custom scalar conversion**
-  Motivated by real hand-written mapper code (`EboxMapper`, central-access): the same conversion repeats
-  across many unrelated properties on one target - `DateUtils.toCalendar(...)` on ~9 fields,
-  `parseEnum(EnumType.class, value)` on ~3 - under today's `@DtoConvert` every one of those properties must
-  carry its own repeated annotation. MapStruct solves this by letting a conversion method be defined once
-  (in the mapper or a `uses = {...}` helper) and auto-applying it to *every* property whose source/target
-  types match that method's signature - no per-field wiring. Proposed: a package-level, repeatable
-  `@DtoConverters({ConverterType.class, ...})` (sibling to `@DtoMapping` in `package-info.java`) - the
-  generator indexes every public static/instance method on the referenced type(s) by `(paramType ->
-  returnType)`, then for any property whose source getter type doesn't already match the target field type
-  and which carries no explicit per-property `@DtoConvert`, looks up that type pair and wires it in
-  automatically (same static-vs-instance/`DtoConverterManager` dispatch rules as `@DtoConvert` today). An
-  explicit per-property `@DtoConvert` always overrides the type-level default. Deliberately no built-in
-  conversions shipped by Ebean itself (no implicit `Enum.valueOf`/`.name()`) - the app still owns
-  exception/null-handling semantics (e.g. `parseEnum`'s catch-and-null-on-bad-value), just declares it once
-  instead of per-field.
-  **Status: implemented.** `@DtoConverters(ConverterType.class, ...)` (a single non-repeatable annotation
-  taking a `Class<?>[]`, `@Target({PACKAGE, MODULE})`) is registered once per package/module alongside
-  `@DtoMapping`. The generator indexes every public, single-arg, non-void method on each referenced type by
-  exact `(paramType -> returnType)`; any SCALAR property (plain or `@DtoPath`-renamed) with no explicit
-  `@DtoConvert` and a source/target type mismatch is auto-wired to the matching method (a duplicate/ambiguous
-  type pair across the registered types is a compile-time processor error). List-element-wise conversion and
-  `@DtoRef` (FK-id) properties are out of scope. Test coverage:
-  `tests/test-dto-mapping/.../TestDtoConverters.java` (`UuidConverters`/`UuidShortCodeConverter`,
-  `ContactTypeConverterDto`) - covers same-name auto-dispatch, `@DtoPath`-renamed auto-dispatch, and explicit
-  `@DtoConvert` overriding the registered default.
-  *Inspiration: `EboxMapper` (central-access) hand-written pattern; MapStruct type-signature-matched
-  conversion methods.*
-
-- **`@DtoMixin` for DTOs that cannot be annotated directly**
-  Some DTOs are generated (e.g. from an OpenAPI spec) and not editable/annotatable, so `@DtoPath`/
-  `@DtoConvert`/`@DtoRef` cannot always be placed directly on the DTO. Introduce a `@DtoMixin(Target.class)`
-  companion interface/type, discovered by scanning the compilation round and overlaying its per-property
-  annotations onto the real target's properties by name-match - directly mirrors avaje-jsonb's
-  `@Json.MixIn` mechanism (`KingfisherMixin`/`CrewMateMixIn` pattern), a proven prior-art solution to the
-  exact same "can't annotate a generated/unowned type" problem.
-  *Inspiration: avaje-jsonb `@Json.MixIn`.*
-  *Status: implemented - `@DtoMixin` (ebean-annotation) and querybean-generator round-scanning/overlay
-  support (matches mixin methods to target properties by name, applying whichever of `@DtoPath`/`@DtoRef`/
-  `@DtoConvert` is present as if declared on the target field itself). Test coverage: `tests/test-dto-mapping`
-  `TestDtoMixin`.*
-
-### F. DI-friendly manual mapper usage
-
-- **Public `DtoMapperManager` with `get(Class<T> mapperType)` for DI**
-  Motivated by `DriverMapper`/`DriverService` (central-access): `DriverMapper` is a hand-written
-  `@Component` constructor-injected into `DriverService`. Moved `DtoMapperManager` from internal
-  (`io.ebeaninternal.server.dto`) to public `io.ebean` - unchanged `mapperFor(source, dto)`, plus a new
-  `get(Class<T> mapperType)` keyed by the generated mapper's own concrete class (e.g.
-  `manager.get(CustomerDtoMapper.class)`), for direct/concrete-typed DI injection. `DtoMapperRegister`
-  gained a default `mapperOfType(Class<T>)` method (non-breaking); the generator emits the real if-chain
-  body (mirrors `mapperFor`'s if-chain). `DtoMapperManager` has zero `Database` dependency (constructor
-  only does `ServiceLoader.load(DtoMapperRegister.class)`), so it can be constructed standalone,
-  independent of/before a `Database` - e.g. as an avaje-inject bean.
-  *Inspiration: `DriverMapper`/`DriverService` (central-access).*
-  *Status: implemented.*
-
-- **`DtoMapperManager` sharing via `DatabaseBuilder.putServiceObject`**
-  So `query.mapTo()` and application-injected mappers share the exact same `DtoMapperManager` instance
-  (and hence the same underlying generated mapper singletons) rather than each independently constructing
-  its own, `InternalConfiguration` checks `config.getServiceObject(DtoMapperManager.class)` first (mirrors
-  the existing `AutoMigrationRunner`/`GeoTypeProvider` `putServiceObject`/`getServiceObject` pattern),
-  falling back to constructing a default `new DtoMapperManager()` if none was supplied.
-  *Inspiration: user proposal following `DriverMapper`/`DriverService` review.*
-  *Status: implemented.*
-
-*Rejected: generator-emitted `builder(source)` method* - `DriverMapper` exposes `builder(cDriver)`
-returning a partially-populated `DriverBuilder` so callers can add extra caller-supplied fields (e.g.
-fleets) before `build()`. Rejected as a generator feature - `Driver`/`DriverSummary` already use
-avaje-recordbuilder's `@RecordBuilder`, which generates `Target.builder(existingInstance)`
-(seed-from-instance). The same effect is already achievable with zero ebean changes:
-`mapper.map(source)` then `Builder.builder(mapped).extraField(x).build()`. Documented as a recipe
-instead (see "Recipe: adding extra caller-supplied fields after mapping" in
-`docs/guides/mapping-entity-graphs-to-dtos.md`).
-
-### G. Large-target construction and shape variants
-
-- **Builder-based target construction for large DTOs**
-  Motivated by `UserService`/`User` (central-access): `User` is a 24-field OpenAPI-generated record with
-  a `@RecordBuilder`-generated `UserBuilder`, hand-mapped via a long fluent builder chain rather than a
-  positional constructor to stay readable/refactor-safe. The generator auto-detects a RecordBuilder-style
-  builder on the target (static `Target.builder()` + fluent per-property setters + `build()`) and uses
-  `Target.builder().prop(x)....build()` instead of `new Target(a, b, c, ...)` whenever (a) a builder is
-  detected and (b) the target has more than a threshold number of properties (default 5), falling back to
-  the positional constructor otherwise. An explicit `@DtoMapping` attribute (`builder = AUTO | ALWAYS |
-  NEVER`) overrides the heuristic in either direction. Applies regardless of whether the target class is
-  hand-authored or foreign/generated (e.g. an OpenAPI record) - `@DtoMapping` is already declared
-  externally via `package-info.java`, not on the target class, so this was already compatible with
-  foreign target types.
-  *Inspiration: `UserService`/`User` (central-access).*
-  *Status: implemented.*
-
-- **Named mapper variants excluding nested paths, sharing one generated class**
-  Motivated by `UserService`/`User` (central-access): `CUser` -> `User` is mapped in two shapes - with
-  nested `fleets` (`findUserByGid`) and without (`findAll`, bulk listing) - to avoid an unnecessary
-  join/fetch on the common bulk-listing path. Keeps the existing "shape always derived from declaration,
-  fetch spec always wins" philosophy (rejected relaxing that rule / rejected a runtime
-  is-property-loaded auto-skip check as less deterministic). The same `(source, target)` pair can be
-  declared more than once in `package-info.java` via a named variant, e.g.
-  `@DtoMapping(source = CUser.class, target = User.class)` (base/full) plus
-  `@DtoMapping(source = CUser.class, target = User.class, name = "noFleets", exclude = "fleets")`
-  (variant). Both variants are generated into the **same** mapper class (one class per target, not one
-  per variant) and share a single private `build(source, context, boolean includeXxx, ...)` method
-  containing the common field population written once; each excluded nested path becomes a `boolean
-  includeXxx` parameter of that shared method rather than a precomputed value, so `build()` still
-  evaluates every property - included or excluded - inline, at its own declared field position (a
-  `includeFleets ? fleetsMapper.mapList(...) : List.of()` ternary in place, not hoisted out as a
-  pre-evaluated call argument). This preserves the DTO's declared property order as the true evaluation
-  order regardless of which properties a variant happens to exclude. The base `map()` passes `true` for
-  every flag; each named variant (exposed as a same-named accessor, e.g. `noFleets()`, returning a single
-  shared/cached instance of its own small `DtoMapper<SOURCE, TARGET>`-implementing inner class - not
-  reconstructed per call) passes `false` for the paths it excludes and omits that path from its own
-  `fetchGroup`. Selected via a new `query.mapTo(Class<D> dtoType, DtoMapper<T, D> mapper)` overload
-  taking an already-resolved mapper instance directly (e.g. `query.mapTo(User.class,
-  userMapper.noFleets())`) - no string-based variant lookup, and no changes needed to
-  `DtoMapperRegister`/`DtoMapperManager`.
-  *Inspiration: `UserService`/`User` (central-access).*
-  *Status: implemented.*
-
-- **Setter-based (mutable JavaBean) target construction**
-  Motivated by `EboxMapper` (central-access): its target types (`Ebox`, `MachineSummaryInfo`, from
-  `nz.co.eroad.schema.eroadtypes`, JAXB/XSD-generated legacy SOAP shapes) are plain mutable JavaBeans - a
-  public no-arg constructor plus a `void setXxx(...)` setter per property - neither a positional constructor
-  match nor a RecordBuilder-style fluent builder (see section G above). The generator currently only
-  recognizes those two construction strategies, so this common third shape (typical of JAXB/XSD-generated
-  and many hand-written mutable POJOs) can't be targeted by `@DtoMapping` at all today. Proposed: detect a
-  no-arg constructor plus a `void setXxx(propertyType)` setter per mapped property as a third construction
-  strategy, generating `Target target = new Target(); target.setX(...); ...; return target;` (mirroring the
-  existing `build = AUTO | ALWAYS | NEVER` override precedent from section G for explicit control over which
-  strategy applies). Would also unblock the `mapToBuilder()`-style "populate ignored/derived properties after
-  the generated mapping, before finishing construction" pattern for these targets (currently only available
-  for builder-shaped targets) - relevant to `EboxMapper`'s `machineSummaryInfo` (a genuinely composite,
-  multi-association derived value, out of reach of `@DtoConvert`/`@DtoPath` regardless of this gap, but a
-  natural fit for the same "map base fields via codegen, then set the derived one by hand" pattern already
-  used for `Fleet.assignedMachines`/`assignedDrivers`).
-  *Inspiration: `EboxMapper` (central-access); JAXB/XSD-generated SOAP DTO shapes generally.*
-  **Status: implemented.** `@DtoMapping(setter = AUTO | ALWAYS | NEVER)` mirrors `builder()`'s override
-  precedent. Detection requires a public no-arg constructor plus a public `setXxx(...)` setter for every
-  mapped property - either `void` or fluent-style (returning the target type itself, e.g. `public Target
-  setXxx(...) { ...; return this; }`); the generated code always calls the setter as a bare statement and
-  discards any return value, so either shape works identically. A builder, when selected, always takes
-  priority over setter-based construction. Under the default `AUTO`, setter-based construction is only
-  attempted when the target has no positional constructor matching the mapped properties (arity-based) and
-  no builder was selected - existing positional-constructor and builder-shaped targets are entirely
-  unaffected. `ALWAYS` requires the shape (codegen-time error otherwise); `NEVER` always uses a positional
-  constructor. Generated shape: `Target target = new Target(); target.setX(...); ...; return target;` (a
-  `computeIfAbsent(...)`-wrapped block-lambda variant when the target is nested elsewhere in the graph).
-  Deliberately **no** `mapToBuilder(...)`-style post-construction accessor is generated for this strategy -
-  the returned target is already the final, fully mutable instance (setters are required to be `public`), so
-  a caller can already call e.g. `dto.setExternalRef(...)` directly on the mapped result, exactly the pattern
-  `EboxMapper` already uses by hand; this is unlike the builder strategy, where the intermediate builder is
-  otherwise unreachable after its one-shot `build()` call. Test coverage:
-  `tests/test-dto-mapping/.../TestDtoSetterConstruction.java` (`ContactSetterDto`) - covers auto-detected
-  setter-chain construction plus post-construction population of two `@DtoIgnore` properties (a plain scalar
-  and a `List`) via their public setters; plus `ContactSetterFluentDto` - covers the fluent-setter-return-shape
-  variant.
-
-### H. Record entity sources
-
-- **Record-style (bare/fluent) accessors on the source (entity) side**
-  Ebean supports entity beans declared as Java `record`s (e.g. `public record CourseRecordEntity(@Id long id,
-  String name, String notes) {}` - see `test-java16`), whose only accessor shape is the bare component name
-  (`active()`, `name()`, `id()`) - never `getXxx()`/`isXxx()`. This bare-accessor convention isn't limited to
-  an actual `record` type though - an ordinary class can just as easily expose bare/fluent-style accessors
-  with no `get`/`is` prefix at all. The generator resolves the real accessor for each source type (the direct
-  source, or an intermediate `@DtoPath`/`@DtoRef` association type) by checking which shape actually exists as
-  a method, in order: (1) `isXxx()` returning `boolean` (JavaBean boolean convention), (2) `getXxx()` (JavaBean
-  convention), (3) the bare `propertyName()` itself - falling back to a guessed `getXxx()` only if none of the
-  three are found. Resolution is entirely name/existence-based (no dependency on whether the type is actually
-  a `record`). The Ebean bean-property name used in generated `FetchGroup.select(...)`/`.fetch(...)` calls is
-  tracked directly from the original property/segment name (not reverse-parsed from the resolved accessor's
-  method name), so it's correct regardless of which of the three accessor shapes was used.
-  *Inspiration: Ebean's own record-entity support (`test-java16`); user-reported gap during review.*
-  *Status: implemented.*
-
-## Rejected Requirements
-
-These were considered and explicitly rejected as out of scope:
-
-- **DTO as interface / dynamic proxy views** — Blaze `@EntityView` defines views as interfaces backed by
-  runtime proxies. This conflicts with Ebean's preference for plain, framework-unattached DTO classes.
-- **Updatable or creatable entity views (persist through DTO)** — Blaze's `@UpdatableEntityView` /
-  `@CreatableEntityView` cascade persist/update through the view. This would duplicate Ebean's existing
-  entity persistence model and introduce a second, ambiguous dirty-checking/cascade model.
-- **New predicate/filter DSL for subview collections** — Blaze allows filter expressions directly in
-  `@Mapping` (e.g. filtering a collection by an attribute value). Ebean already has typed query bean
-  predicates and `.filterMany()` for filtering child collections in queries; no new embedded filter
-  expression language is needed on the DTO itself.
-
-## References
-
-- Issue: https://github.com/ebean-orm/ebean/issues/2540
-- PR #2626: `InterceptReadOnly` / `InterceptReadWrite` split enabling the unmodifiable entity graph fast path
-- Ebean docs: https://ebean.io/docs/query/option#unmodifiable
-- QueryDSL: `@QueryProjection` (constructor-based, compile-time-checked projections)
-- Blaze-Persistence Entity Views: https://persistence.blazebit.com/documentation/1.6/entity-view/manual/en_US/

docs/guides/AGENTS.md

@@ -14,7 +14,6 @@ Key guides (fetch and follow when performing the relevant task):
 - Migrate to `Database.builder()`: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-to-database-builder.md
 - Migrate JSON APIs from Jackson core to avaje-json-core: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-json-jackson-core-to-avaje-json-core.md
 - Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
-- Mapping entity graphs to DTOs (`mapTo`): https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/mapping-entity-graphs-to-dtos.md
 - Derived / formula properties (`@Formula`, `@Formula2`): https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/derived-formula-properties.md
 - Persisting and transactions: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md
 - Query metrics and naming: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-metrics.md

docs/guides/README.md

@@ -47,7 +47,6 @@ existing Maven project. Complete the steps in order.
 | Guide | Description |
 |-------|-------------|
 | [Write Ebean queries with query beans](writing-ebean-query-beans.md) | Step-by-step guidance for AI agents to write type-safe Ebean queries; choose the right terminal method; tune `select()` / `fetch()` / `fetchQuery()`; and project to DTOs when entity beans are not the right output |
-| [Mapping entity graphs to DTOs (`mapTo`)](mapping-entity-graphs-to-dtos.md) | Map a nested entity graph query result to a nested DTO graph via `query.mapTo(Dto.class)`; `@DtoPath`/`@DtoRef` for renamed/flattened/id-only properties; identity-aware de-dup via `DtoMapContext`; computed/aggregate DTO values via `@Entity @View` + `@Formula2`/`@Sum`/`@Aggregation`; comparison with the flat `asDto()` pipeline |
 | [Immutable bean cache for read-only references](immutable-bean-cache.md) | Use `ImmutableBeanCache` and `ImmutableBeanCaches.loading(...)` to resolve assoc-one references in read-only/unmodifiable queries, including secondary `fetchQuery`/`fetchLazy` loads |
 | [Using `RawSql` with Ebean](using-rawsql-with-ebean.md) | Choose between `RawSqlBuilder.parse()`, `unparsed()`, and `withPlaceholders()`; the `${where}`/`${andWhere}`/`${having}`/`${andHaving}` placeholder reference for CTEs, window functions, and subqueries; column mapping; and using `RawSql` with query beans |
 
@@ -154,7 +153,6 @@ Key guides (fetch and follow these when performing the relevant task):
 - Database configuration: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md
 - Migrate to `Database.builder()`: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-to-database-builder.md
 - Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
-- Mapping entity graphs to DTOs (`mapTo`): https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/mapping-entity-graphs-to-dtos.md
 - Immutable bean cache for read-only references: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/immutable-bean-cache.md
 - Ebean OpenTelemetry tracing: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-opentelemetry.md
 - Query metrics and naming: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-metrics.md
@@ -184,7 +182,6 @@ Key guides (fetch and follow these when performing the relevant task):
 - Database configuration: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md
 - Migrate to `Database.builder()`: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-to-database-builder.md
 - Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
-- Mapping entity graphs to DTOs (`mapTo`): https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/mapping-entity-graphs-to-dtos.md
 - Persisting and transactions: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md
 - Test container setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-test-container.md
 - DB migration generation: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-db-migration-generation.md

docs/guides/add-ebean-postgres-maven-pom.md

@@ -101,7 +101,7 @@ Inside the `<dependencies>` block, add the PostgreSQL JDBC driver:
 <dependency>
     <groupId>org.postgresql</groupId>
     <artifactId>postgresql</artifactId>
-    <version>42.7.11</version>
+    <version>42.7.8</version>
 </dependency>
 ```
 

docs/guides/mapping-entity-graphs-to-dtos.md

@@ -1,785 +0,0 @@
-# Guide: Mapping entity graphs to DTOs — `query.mapTo(Dto.class)`
-
-## Purpose
-
-`query.mapTo(SomeDto.class)` maps an entity query result to a **nested DTO graph** —
-DTO fields can themselves be DTOs (`ToOne`) or `List<Dto>`/`Set<Dto>` (`ToMany`), not
-just flat scalar columns. Ebean generates the mapper (reflection-free), automatically
-derives the query's `select()`/`fetch()` spec from the target DTO's declared shape, and
-forces `setUnmodifiable(true)` so any property the mapper needs but wasn't fetched fails
-fast with `LazyInitialisationException` instead of silently lazy loading.
-
-This is distinct from the existing flat `asDto(Dto.class)` — see
-[Quick comparison](#quick-comparison-mapto-vs-asdto-vs-plain-entity-query) below.
-
-```java
-Optional<CustomerDto> dto = new QCustomer()
-  .id.eq(customerId)
-  .mapTo(CustomerDto.class)
-  .findOneOrEmpty();
-```
-
-```java
-List<CustomerDto> dtos = DB.find(Customer.class)
-  .where().eq("status", Status.ACTIVE)
-  .mapTo(CustomerDto.class)   // no .select()/.fetch() needed - derived from CustomerDto's shape
-  .findList();
-```
-
----
-
-## Quick comparison: `mapTo()` vs `asDto()` vs plain entity query
-
-| | `mapTo(Dto.class)` | `asDto(Dto.class)` | Plain entity query |
-|---|---|---|---|
-| Shape | Nested DTO **graph** (ToOne/ToMany) | Flat, single-row DTO | Entity graph |
-| Fetch spec | Auto-derived from the DTO's declared shape | Whatever `select()`/SQL you write | Whatever `select()`/`fetch()` you write |
-| Mismatch caught | At compile time (unregistered pair fails fast at first use; codegen fails fast on structural problems) | At runtime (reflection-based constructor/setter matching) | N/A (real entity properties) |
-| Identity/de-dup | Yes - repeated source instances map to the same DTO instance (`DtoMapContext`) | N/A (one row in, one DTO out) | Yes (entity/persistence-context identity) |
-| Backing pipeline | Executes the entity ORM query, `setUnmodifiable(true)`, maps the resulting graph | Executes SQL directly against a flat `ResultSet` | Executes the entity ORM query |
-| Best for | API/read-model responses that mirror a **nested** entity shape | Flat summary rows, reports, native/vendor SQL | Data you intend to mutate and save back |
-
-See also [writing-ebean-query-beans.md](writing-ebean-query-beans.md) (Step 8/9) for
-`asDto()` and the general query-shape decision guide.
-
----
-
-## Basic usage
-
-### 1. Declare a plain DTO
-
-DTOs are plain classes with **no framework attachment** — no annotations required for
-the common case (properties matched to the source entity by name):
-
-```java
-public class CustomerDto {
-  private final Long id;
-  private final String name;
-  private final AddressDto billingAddress;   // nested ToOne
-  private final List<ContactDto> contacts;   // nested ToMany
-
-  public CustomerDto(Long id, String name, AddressDto billingAddress, List<ContactDto> contacts) {
-    this.id = id;
-    this.name = name;
-    this.billingAddress = billingAddress;
-    this.contacts = contacts;
-  }
-
-  public Long getId() { return id; }
-  public String getName() { return name; }
-  public AddressDto getBillingAddress() { return billingAddress; }
-  public List<ContactDto> getContacts() { return contacts; }
-}
-```
-
-A constructor whose parameters match (by name) a source entity/DTO property is used
-for mapping — same shape convention as the existing `DtoQuery`. Getters are used to
-read the source's properties — a bare/fluent accessor like `active()` is resolved
-automatically too, not just `getActive()`/`isActive()` (useful both for Ebean's own
-record entity beans and for ordinary classes that just expose bare-name accessors).
-
-### 2. Register the (source, target) pair
-
-Declare each entity → DTO pair with `@DtoMapping` on a `package-info.java` (a neutral
-holder — see [Why `package-info.java`?](#why-package-infojava)):
-
-```java
-@DtoMapping(source = Customer.class, target = CustomerDto.class)
-@DtoMapping(source = Address.class, target = AddressDto.class)
-@DtoMapping(source = Contact.class, target = ContactDto.class)
-package org.example.dto;
-
-import io.ebean.annotation.DtoMapping;
-```
-
-This triggers `querybean-generator` (the existing annotation processor) to generate a
-`CustomerDtoMapper implements DtoMapper<Customer, CustomerDto>` for each pair — no new
-Maven/Gradle setup beyond what query beans already require.
-
-### 3. Query with `mapTo(...)`
-
-```java
-List<CustomerDto> dtos = DB.find(Customer.class)
-  .where().eq("status", Status.ACTIVE)
-  .mapTo(CustomerDto.class)
-  .findList();
-
-CustomerDto one = new QCustomer().id.eq(id).mapTo(CustomerDto.class).findOne();
-
-Optional<CustomerDto> maybe = new QCustomer().id.eq(id).mapTo(CustomerDto.class).findOneOrEmpty();
-```
-
-`mapTo(...)` works the same from a query bean (`QCustomer`) or a plain `DB.find(...)`/
-`ExpressionList` query.
-
-### Paging - `findPagedList()`
-
-`findPagedList()` mirrors `Query#findPagedList()` — the underlying entity query is paged
-as normal and each page's result is mapped to the target DTO list:
-
-```java
-PagedList<CustomerDto> paged = DB.find(Customer.class)
-  .where().eq("status", Status.ACTIVE)
-  .orderBy().asc("name")
-  .setFirstRow(0)
-  .setMaxRows(50)
-  .mapTo(CustomerDto.class)
-  .findPagedList();
-
-int totalRowCount = paged.getTotalCount();      // page metadata - unaffected by DTO mapping
-List<CustomerDto> page1 = paged.getList();       // mapped DTOs for this page
-```
-
-Page metadata (`getTotalCount()`, `getTotalPageCount()`, `hasNext()`, `hasPrev()`,
-`loadCount()`, ...) reflects the underlying entity query directly; only `getList()`
-is mapped (once, cached) to the DTO type.
-
-### An unregistered pair fails fast
-
-If `(Customer.class, SomeDto.class)` was never declared via `@DtoMapping`, the first
-`mapTo(SomeDto.class)` call throws immediately:
-
-```
-PersistenceException: No DtoMapper registered mapping Customer -> SomeDto
-  - check @DtoMapping(source = Customer.class, target = SomeDto.class) is declared
-    on a package-info.java processed by querybean-generator
-```
-
----
-
-## Auto-derived fetch spec
-
-You never write `.select()`/`.fetch()` for a `mapTo(...)` query — the generated mapper
-exposes a `fetchGroup()` built directly from the DTO's declared shape, and `mapTo(...)`
-applies it automatically:
-
-```java
-public CustomerDtoMapper() {
-  this(new AddressDtoMapper(), new ContactDtoMapper());
-}
-
-public CustomerDtoMapper(DtoMapper<Address, AddressDto> billingAddressMapper,
-                          DtoMapper<Contact, ContactDto> contactsMapper) {
-  this.fetchGroup = FetchGroup.of(Customer.class)
-    .select("id,name")
-    .fetch("billingAddress", billingAddressMapper.fetchGroup())
-    .fetch("contacts", contactsMapper.fetchGroup())
-    .build();
-}
-```
-
-Each nested DTO gets its own generated mapper (mirroring MapStruct's per-type mapper
-generation), wired together via constructor injection — mappers are stateless and
-substitutable, not static singletons. Mapper instances are constructed once, in
-dependency order, and reused — see [DtoMapperManager](#one-mapper-instance-per-pair)
-below.
-
----
-
-## Nested collections and identity-aware de-duplication
-
-When the same source entity instance is reachable via more than one path in the graph
-(e.g. two `Contact`s sharing the same `Customer`, or the same `Address` referenced from
-two paths), the mapper reuses the **same** target DTO instance rather than creating
-duplicate-but-equal copies — mirroring the identity semantics the entity graph already
-has:
-
-```java
-List<CustomerDto> dtos = DB.find(Customer.class).mapTo(CustomerDto.class).findList();
-
-CustomerDto customer = dtos.get(0);
-// both contacts share the exact same customer.billingAddress AddressDto instance
-assertThat(customer.getContacts().get(0).getCustomer())
-  .isSameAs(customer.getContacts().get(1).getCustomer());
-```
-
-This is done via a `DtoMapContext` threaded through every nested `map(...)` call within
-one top-level `mapList(...)`/`findList()` invocation. The generated code only pays for
-this when it can actually matter — a DTO that's never nested under another DTO skips
-`DtoMapContext` entirely (there's nothing else in scope to de-duplicate against):
-
-```java
-// AddressDto is nested under CustomerDto (reachable via multiple contacts) - dedup needed
-// dedup using DtoMapContext, same Address instance can be reached via more than one path in the graph
-return context.computeIfAbsent(AddressDto.class, source, s -> new AddressDto(...));
-
-// ContactSummaryDto is only ever mapped as a top-level query result - no dedup possible
-// skip DtoMapContext, only ever a top-level mapping
-return new ContactSummaryDto(source.getId(), source.getFullName());
-
-// CustomerDto has nested mappers (billingAddress, contacts) but is never itself nested
-// DtoMapContext for nested mappers only
-return new CustomerDto(source.getId(), source.getName(), ...);
-```
-
-The generated comment tells you at a glance which of the three cases applies — useful
-when debugging why a `DtoMapContext` is (or isn't) in the generated code for a
-particular mapper.
-
----
-
-## Using generated mappers directly (outside `query.mapTo()`)
-
-Every generated `XxxDtoMapper` is a plain public class — you don't need `ServiceLoader`,
-a registry, or a `Database` just to construct or call one directly (though
-`DtoMapperManager`, below, is available if you want a shared, DI-friendly lookup). It
-always has a public no-arg constructor (delegating to defaults for any nested mappers/
-`@DtoConvert` converters) plus an explicit constructor taking those dependencies directly,
-and implements `DtoMapper<SOURCE, TARGET>`'s `map(...)`/`mapList(...)`:
-
-```java
-CustomerDtoMapper mapper = new CustomerDtoMapper();
-CustomerDto dto = mapper.map(customer);       // any Customer you already have on hand
-List<CustomerDto> dtos = mapper.mapList(customers);
-```
-
-This works on **any** entity graph, not just one that just came out of a `mapTo(...)`
-query — e.g. entities you loaded with a plain `.fetch(...)` query, entities you just
-`.save()`d, or entities built by hand in a test. The only requirement is that whatever the
-mapper reads (via plain getters) is actually populated — there's no lazy-loading fallback.
-
-### Testing the mapping in isolation
-
-Because mappers are plain, constructor-injected classes, you can unit test the mapping
-logic itself — independent of `query.mapTo()`, the DTO-pair registry, and (for
-`@DtoConvert` instance-dispatch converters) `DtoConverterManager` — by passing a test
-double straight into the explicit constructor:
-
-```java
-SecretCipher upperCasingTestCipher = String::toUpperCase;
-ContactConversionDto dto = new ContactConversionDtoMapper(upperCasingTestCipher).map(contact);
-
-assertThat(dto.getSecretCode()).isEqualTo("SHH");
-```
-
-No `DtoConverterManager.put(...)` registration needed for this kind of test — the real
-production wiring (`DtoConverterManager.get(SecretCipher.class)`) only happens in the
-generated no-arg constructor, which the explicit-constructor call above bypasses entirely.
-See `TestCustomerDtoGraphMapping` (mapper called directly against a manually queried
-graph) and `TestMapperManualUsage` (mapper called directly against hand-built/just-saved
-entities, plus the converter test-double case above) in `tests/test-dto-mapping`.
-
-### `DtoMapperManager` — resolving a generated mapper for dependency injection
-
-`new CustomerDtoMapper()` is enough for a single mapper, but if your application wants a
-single shared instance of *every* generated mapper (mirroring how `query.mapTo()` resolves
-them internally) - e.g. to wire one up for constructor injection into a service, replacing
-a hand-written mapper class - use `io.ebean.DtoMapperManager`:
-
-```java
-DtoMapperManager manager = new DtoMapperManager();   // ServiceLoader discovery only - no Database needed
-CustomerDtoMapper mapper = manager.get(CustomerDtoMapper.class);
-```
-
-`DtoMapperManager` has no dependency on `Database` at all - its constructor only does
-`ServiceLoader.load(DtoMapperRegister.class)` - so it can be constructed independently,
-before (or entirely without) a `Database`, e.g. as a bean in an avaje-inject (or any DI
-framework's) dependency graph:
-
-```java
-@Factory
-class DtoMapperFactory {
-
-  @Bean
-  DtoMapperManager dtoMapperManager() {
-    return new DtoMapperManager();
-  }
-
-  @Bean
-  CustomerDtoMapper customerDtoMapper(DtoMapperManager manager) {
-    return manager.get(CustomerDtoMapper.class);
-  }
-}
-```
-
-If you also want `query.mapTo(...)` to use that *exact same* manager instance (so there's
-only ever one instance of each generated mapper, whichever path resolves it), register it
-via `DatabaseBuilder.putServiceObject` before building the `Database` - this is the same
-`putServiceObject`/`getServiceObject` mechanism already used for things like
-`AutoMigrationRunner`:
-
-```java
-DtoMapperManager sharedManager = new DtoMapperManager();
-
-Database db = Database.builder()
-  .putServiceObject(DtoMapperManager.class, sharedManager)
-  .build();
-
-// query.mapTo(...) against `db` now resolves mappers via `sharedManager`
-```
-
-If nothing is registered via `putServiceObject`, the `Database` builds its own default
-`DtoMapperManager` instance instead - registering one is entirely optional. A standalone
-`DtoMapperManager()` construction bypasses the `DatabaseConfigProvider` hook (that hook is
-specifically about `Database` startup ordering), so if any of your mappers need a
-`@DtoConvert` instance-dispatch converter, register it via `DtoConverterManager.put(...)`
-yourself first, exactly as you would before building a `Database`. See
-`TestDtoMapperManager` and `TestDtoMapperManagerSharing` in `tests/test-dto-mapping`.
-
-### Recipe: adding extra caller-supplied fields after mapping
-
-Sometimes a target DTO needs a field that isn't sourced from the entity graph at all - e.g.
-populated from a separate query or business rule, only when a caller-supplied flag is set.
-Rather than the generator supporting partial/builder-based mapping directly, if your DTO is
-a record with a "seed from instance" builder (e.g. via `avaje-recordbuilder`'s
-`@RecordBuilder`, which generates `Target.builder(existingInstance)`), just map the
-graph-sourced fields as usual and layer the extra field on afterwards:
-
-```java
-Driver base = mapper.map(cDriver);
-Driver full = DriverBuilder.builder(base).fleets(fleets).build();
-```
-
-No generator changes needed - the mapped instance is simply the seed for the builder.
-
----
-
-## Large targets: builder-based construction and named variants
-
-Two features aimed at large, builder-shaped target DTOs (typically OpenAPI-generated records
-with a generated builder), where a positional constructor call is unwieldy and a single query
-needs to populate the target in more than one shape.
-
-### Builder-based construction (`builder = AUTO | ALWAYS | NEVER`)
-
-If the target has a static no-arg `Target.builder()` factory returning a type with a fluent
-(returns-itself) setter per property plus a `build()` method - the shape
-`avaje-recordbuilder`'s `@RecordBuilder` generates - the generated mapper can construct the
-target via `Target.builder().prop(x)....build()` instead of `new Target(a, b, c, ...)`:
-
-```java
-public record User(Long id, String name, String email, /* ... 21 more fields */) {
-
-  public static UserBuilder builder() {
-    return UserBuilder.builder();
-  }
-}
-```
-
-```java
-@DtoMapping(source = CUser.class, target = User.class)
-package org.example.dto;
-```
-
-By default (`builder = AUTO`), the generator auto-detects a matching builder and uses it only
-once the target has more than 5 properties, falling back to a positional constructor for
-smaller DTOs. Override explicitly either direction:
-
-```java
-@DtoMapping(source = CUser.class, target = User.class, builder = DtoMapping.Builder.ALWAYS)
-```
-
-`builder = ALWAYS` is a codegen-time error if no matching builder shape is found; `builder =
-NEVER` always uses a positional constructor even if a builder is detected. This applies
-regardless of whether the target is hand-authored or foreign/generated - `@DtoMapping` is
-already declared externally via `package-info.java`, so no annotation on the target itself is
-needed either way.
-
-### Named variants excluding nested paths (`name=`, `exclude=`)
-
-The same `(source, target)` pair can be registered more than once - one base mapping (leaving
-`name()` empty) plus any number of named variants, each excluding one or more nested
-ToOne/ToMany properties:
-
-```java
-@DtoMapping(source = CUser.class, target = User.class)
-@DtoMapping(source = CUser.class, target = User.class, name = "noFleets", exclude = "fleets")
-package org.example.dto;
-```
-
-Both variants are generated into the **same** mapper class (one class per target, not one per
-variant) - the generated `noFleets()` accessor returns a single shared/cached `DtoMapper<CUser,
-User>` view (not reconstructed per call), omitting `fleets` from both its mapped output (`null`
-for a ToOne, `List.of()` for a ToMany) and its own `fetchGroup()`. Each excluded property is still
-evaluated inline at its own declared field position internally (guarded by a boolean flag) - a
-variant's exclusions never change the evaluation order of the DTO's other properties. Select it
-with the `query.mapTo(Class, DtoMapper)` overload, which takes an already-resolved mapper instance
-directly - no string-based lookup:
-
-```java
-UserMapper userMapper = new UserMapper();
-
-// full shape, with fleets fetched/mapped
-List<User> withFleets = DB.find(CUser.class)
-  .mapTo(User.class, userMapper) // or plain .mapTo(User.class)
-  .findList();
-
-// bulk listing shape - fleets excluded from both the fetch spec and the output
-List<User> noFleets = DB.find(CUser.class)
-  .mapTo(User.class, userMapper.noFleets())
-  .findList();
-```
-
-Only nested ToOne/ToMany properties can be excluded - a scalar or `@DtoRef` property can't be,
-since there's no type-safe "absent" value for an arbitrary scalar type. Named variants are
-scoped to independent, top-level query results only - unlike the base mapping, they don't
-participate in `DtoMapContext` identity de-duplication when nested elsewhere in a graph, since a
-variant is never intended to be nested inside another DTO's mapping.
-
----
-
-## `@DtoPath` — renamed or flattened properties
-
-By default a DTO property is matched to the source entity property (or nested DTO
-mapper) of the **same name**. `@DtoPath` overrides that, allowing a DTO property to be
-renamed and/or flattened from a nested path using dot-notation:
-
-```java
-public class ContactDto {
-  private final long id;
-  private final String firstName;
-  private final String lastName;
-
-  @DtoPath("customer.billingAddress.city")
-  private final String customerCity;   // flattened, 2 hops through customer
-
-  // constructor / getters ...
-}
-```
-
-The generated mapper reads the path with a null-guard at each hop and adds the
-necessary joins to the fetch spec automatically:
-
-```java
-(s.getCustomer() == null ? null
-  : (s.getCustomer().getBillingAddress() == null ? null
-      : s.getCustomer().getBillingAddress().getCity()))
-```
-
-`@DtoPath` is purely a compile-time/codegen-time hint — the DTO class itself carries no
-runtime dependency on the annotation.
-
-### Fetch-path collisions are a compile-time error
-
-A `@DtoPath` whose fetch path is identical to a nested `ToOne`/`ToMany` property's own
-fetch path on the *same* DTO (e.g. a nested `customer` field alongside
-`@DtoPath("customer.name")` — both resolve to fetch path `"customer"`) fails the build
-with a clear error, rather than silently discarding one side's fetched properties:
-
-```
-error: @DtoPath property 'customerName' on FooDto resolves to fetch path 'customer',
-  which collides with the nested mapping already using that same fetch path - Ebean's
-  fetch spec can only carry one set of properties per path, so one silently discards
-  the other. Move 'customerName' onto the nested DTO type instead, or choose a
-  @DtoPath that reaches into a different, non-colliding path.
-```
-
-Fix it either way it suggests: move the property onto the nested DTO type, or choose a
-`@DtoPath` that reaches a different path (as `customerCity` above does deliberately,
-using a 3-segment path through `customer.billingAddress` rather than colliding with a
-plain `customer` nested field).
-
----
-
-## `@DtoRef` — id-only back-references (breaking cycles)
-
-The DTO graph derived from a set of DTO types must form a DAG — codegen fails if it
-doesn't. `@DtoRef` is the explicit escape hatch for an intentional back-reference, e.g.
-a `Contact` DTO referencing its parent `Customer` by id only, rather than re-embedding
-a full `CustomerDto` (which would recreate the `Customer → Contact → Customer` cycle):
-
-```java
-public class ContactDto {
-  private final long id;
-
-  @DtoRef
-  private final Long customerId;   // id-only, no nested CustomerDto re-embedded
-
-  // constructor / getters ...
-}
-```
-
-The generated fetch spec adds the association to the **root** `select(...)` rather
-than a nested `.fetch(...)` — this reads the foreign-key column directly off the base
-table (no SQL join):
-
-```java
-this.fetchGroup = FetchGroup.of(ContactStats.class)
-  .select("customer,contactCount,engagementScore")   // "customer" -> FK column, no join
-  .build();
-```
-
-```java
-(source.getCustomer() == null ? null : source.getCustomer().getId())
-```
-
-If the same association is *also* independently nested-fetched elsewhere on the DTO
-(e.g. `ContactDto` has both a nested `customer` field **and** `@DtoRef Long
-customerId`), the generator recognizes the association is already covered and doesn't
-add a redundant/duplicate select — no join is added twice.
-
----
-
-## `@DtoConvert` — custom property conversion
-
-Some properties need more than a plain getter copy — a scalar coercion (`short` to
-`boolean`), an enum-to-`String` mapping, or a conversion needing a real dependency (e.g.
-decrypting a value with a cipher). `@DtoConvert(value = ConverterType.class, method =
-"name")` covers both, combinable with `@DtoPath` when the source value also needs a
-path/rename override:
-
-```java
-public class ContactDto {
-  @DtoPath("status")
-  @DtoConvert(value = ContactConversions.class, method = "toActive")
-  private final boolean active;             // Contact.status (Short) -> boolean
-
-  @DtoConvert(value = SecretCipher.class, method = "decode")
-  private final String secretCode;          // decrypted via a registered SecretCipher
-
-  // constructor / getters ...
-}
-```
-
-The generator resolves the referenced method at codegen time and dispatches one of two
-ways, purely based on whether it's `static`:
-
-- **Static method** — inlined as a direct static call
-  (`ContactConversions.toActive(source.getStatus())`). No registration needed at all —
-  use this for common, reusable, dependency-free coercions.
-- **Instance method** — the generated mapper resolves one shared instance via
-  `DtoConverterManager.get(SecretCipher.class)`, wired as a constructor
-  parameter/field (the same shape as nested-mapper constructor injection), then calls
-  `secretCipher.decode(source.getSecretCode())`. Use this when the conversion needs a
-  real dependency.
-
-### Registering an instance-dispatch converter
-
-`DtoConverterManager` is a small, deliberately-scoped static put/get bridge — register
-an already-constructed converter instance (e.g. built by your DI container) **before**
-building the `Database`:
-
-```java
-AES256Cipher cipher = ...;                                    // already DI-constructed
-DtoConverterManager.put(SecretCipher.class, cipher::decrypt); // or a small adapter class
-
-Database db = DatabaseFactory.create(...); // generated mappers resolve converters from here
-```
-
-If nothing is registered for a required type, `DtoConverterManager.get(...)` throws a
-`PersistenceException` immediately — this happens as an eager field initializer on the
-generated `EbeanDtoMapperRegister`, so a missing registration fails fast at `Database`
-build time, not lazily on first `mapTo(...)` call.
-
-> **Testing tip:** since `EbeanDtoMapperRegister`'s mapper fields are all constructed
-> together when the `Database` starts, register converters via a `DatabaseConfigProvider`
-> (a `ServiceLoader` hook that runs before the `Database` is built) rather than a test
-> `@BeforeAll`, so registration always happens before *any* test triggers startup —
-> regardless of which test class runs first.
-
-## `@DtoMixin` — overlaying annotations onto a DTO you can't edit
-
-Some DTOs are generated elsewhere (e.g. from an OpenAPI spec, regenerated on every
-build) and can't be annotated directly. `@DtoMixin(Target.class)` overlays
-`@DtoPath`/`@DtoRef`/`@DtoConvert` from a separate companion type instead — directly
-mirroring avaje-jsonb's `@Json.MixIn` mechanism. Declare a companion interface (or
-class) whose method names match the target DTO's property names:
-
-```java
-// ContactMixinDto itself carries no Ebean annotations at all
-public class ContactMixinDto {
-  public ContactMixinDto(long id, String firstName, boolean active, String secretCode) { ... }
-  // getters ...
-}
-
-@DtoMixin(ContactMixinDto.class)
-interface ContactMixinDtoMixin {
-
-  @DtoPath("status")
-  @DtoConvert(value = ContactConversions.class, method = "toActive")
-  boolean active();
-
-  @DtoConvert(value = SecretCipher.class, method = "decode")
-  String secretCode();
-}
-```
-
-The processor matches each mixin method to the target's property by name and applies
-whichever annotations are present as if they were declared on the target field itself.
-The mixin type is never instantiated and carries no runtime footprint — it's purely a
-compile-time/codegen-time hint.
-
----
-
-## Computed / aggregate properties via `@Entity @View`
-
-There's no dedicated "formula on DTO" annotation (a narrower `@Formula2`-on-DTO
-variant was explored and rejected — see
-[dto-mapping-design.md](../dto-mapping-design.md) for the reasoning). Instead, model
-the computed value as its own read-only entity using `@View`, then map that entity to a
-plain DTO with the same `@DtoMapping` machinery described above. `@View(name = "...")`
-here just points a second entity at an **existing** table — it does not create a new
-database view or table.
-
-### Worked example — computed column (`@Formula2`)
-
-```java
-@Entity
-@View(name = "contact")   // reads the existing 'contact' table, no new DDL
-public class ContactSummary {
-  @Id
-  private Long id;
-  private String firstName;
-  private String lastName;
-
-  @Formula2("concat(firstName, ' ', lastName)")
-  private String fullName;
-
-  // getters ...
-}
-```
-
-```java
-public class ContactSummaryDto {
-  private final Long id;
-  private final String fullName;
-  // constructor / getters ...
-}
-```
-
-```java
-@DtoMapping(source = ContactSummary.class, target = ContactSummaryDto.class)
-```
-
-```java
-List<ContactSummaryDto> summaries = DB.find(ContactSummary.class)
-  .mapTo(ContactSummaryDto.class)
-  .findList();
-```
-
-### Worked example — group-by aggregation (`@Sum`/`@Aggregation`)
-
-The same `@View`-on-base-table pattern applies to Ebean's `@Sum`/`@Aggregation`
-group-by formulas — the Blaze-Persistence parallel is an `@EntityView` with
-`@Mapping("SIZE(...)")`/`@Mapping("SUM(...)")` correlated mappings:
-
-```java
-@Entity
-@View(name = "contact")
-public class ContactStats {
-  @Id
-  private Long id;              // required so @Aggregation("count(id)") has something to
-                                 // count; deliberately never selected/mapped - selecting it
-                                 // would defeat the aggregation (one row per contact
-                                 // instead of one row per customer)
-  @ManyToOne
-  private Customer customer;
-
-  @Aggregation("count(id)")
-  private Long contactCount;
-
-  @Sum
-  private Integer engagementScore;
-
-  // getters ...
-}
-```
-
-```java
-public class ContactStatsDto {
-  @DtoRef
-  private final Long customerId;   // also the implicit GROUP BY key
-  private final Long contactCount;
-  private final Integer engagementScore;
-  // constructor / getters ...
-}
-```
-
-Because `customerId` uses `@DtoRef`, the generated fetch spec is
-`select("customer,contactCount,engagementScore")` with **no join** — the query groups
-by the FK column directly:
-
-```sql
-select t0.customer_id, count(t0.id), sum(t0.engagement_score)
-from contact t0
-group by t0.customer_id
-```
-
----
-
-## Performance notes
-
-### Fail-fast, no accidental lazy loading
-
-`mapTo(...)` forces `query.setUnmodifiable(true)` under the hood. If the mapper ever
-needs a property that wasn't fetched, it throws `LazyInitialisationException`
-immediately rather than silently issuing an extra query per row or returning `null`.
-`InterceptReadOnly` (the unmodifiable-graph bean state) is also cheap — a `boolean[]
-loaded` flag array plus a `frozen` flag, not a full second copy of bean state.
-
-### One mapper instance per pair
-
-Generated mappers are constructed once (in dependency order — a mapper with nested
-mappers takes them as constructor params) and reused across every `mapTo(...)` call for
-that pair, resolved and cached by `DtoMapperManager` keyed on `(sourceType, dtoType)`.
-
-### `DtoMapContext` overhead only where it earns its keep
-
-As shown above, the generator only involves `DtoMapContext` for mappers that can
-actually be reached via more than one path in some graph (dedup) or that have nested
-mappers of their own (need to thread the context down); a DTO that's only ever a
-top-level query result skips it entirely.
-
-### Fetch strategy and pagination carry over unchanged
-
-Existing fetch-strategy control (`+query`/`+lazy`, `fetchQuery()`) and pagination
-(including keyset pagination and `findPagedList()`) work the same whether the query
-target is an entity graph or a `mapTo(...)` DTO graph — no special-casing needed.
-
----
-
-## Which should I use?
-
-- **`mapTo(Dto.class)`** — the target is a **nested** shape (has its own ToOne/ToMany
-  DTO fields) that should mirror part of the entity graph; you want the fetch spec
-  derived automatically and verified to match the DTO's declared shape.
-- **`asDto(Dto.class)`** / `DB.findDto(...)` — the target is a **flat** row (report,
-  summary, native/vendor SQL); you're comfortable with runtime-checked column-to-bean
-  matching, or the SQL doesn't map cleanly to entity property paths at all.
-- **Plain entity query** — the caller needs a real, persistable, mutable entity — not a
-  read-only projection.
-
----
-
-## Reference
-
-### Why `package-info.java`?
-
-`@DtoMapping` is declared on a package (`ElementType.PACKAGE`), not the DTO or the
-entity, because:
-- the DTO type is often owned/generated elsewhere (e.g. from an OpenAPI spec) and
-  shouldn't need to be annotated with an internal persistence/entity type;
-- one entity may be the source for several different DTOs (e.g. a summary vs. a detail
-  view), and the same entity/DTO pair may need registering from multiple consuming
-  modules.
-
-### Annotations at a glance
-
-| Annotation | Target | Purpose |
-|---|---|---|
-| `@DtoMapping(source=, target=)` | `package-info.java` | Registers an entity → DTO pair, triggers mapper generation |
-| `@DtoMapping(..., builder=)` | `package-info.java` | `AUTO` (default, threshold-based) / `ALWAYS` / `NEVER` - builder-chain vs positional constructor |
-| `@DtoMapping(..., name=, exclude=)` | `package-info.java` | Registers a named variant sharing the base mapping's generated class, excluding nested paths |
-| `@DtoPath("a.b.c")` | DTO field/getter | Renamed and/or flattened multi-hop property mapping |
-| `@DtoRef` | DTO field/getter | Id-only back-reference; breaks a cycle; root-selects the FK (no join) |
-| `@DtoConvert(value=, method=)` | DTO field/getter | Custom scalar conversion - static (no registration) or instance (via `DtoConverterManager`) dispatch |
-| `@DtoMixin(Target.class)` | Companion interface/class | Overlays `@DtoPath`/`@DtoRef`/`@DtoConvert` onto a DTO that can't be annotated directly |
-
-### Parallels with other tools
-
-If you're coming from another mapping library, here's the rough correspondence:
-
-| Ebean | MapStruct | Blaze-Persistence |
-|---|---|---|
-| Generated `DtoMapper` per (source, DTO) pair | Generated `@Mapper` implementation | `@EntityView` (interface + runtime proxy) |
-| `@DtoPath("a.b.c")` | `@Mapping(target = "x", source = "a.b.c")` | `@Mapping("a.b.c")` |
-| `@DtoRef` | `@Context`/manual cycle-breaking (no dedicated annotation) | Sub-view referencing an id-only projection |
-| `@DtoConvert(value=, method=)` | `@Mapping(qualifiedByName = "...")` / custom mapper methods | Custom converter/`@Mapping` expression |
-| `@DtoMixin(Target.class)` | N/A (annotate the `@Mapper` interface's abstract methods instead) | N/A |
-| `DtoMapContext` identity de-dup | Not built in (opt-in `@MappingTarget`/manual caching) | Built in (entity-view identity) |
-| `@Entity @View` + `@Formula2`/`@Sum`/`@Aggregation` for computed DTO values | N/A (MapStruct doesn't touch SQL) | `@Mapping("SIZE(...)")` / `@Mapping("SUM(...)")` correlated mappings |
-
-See [dto-mapping-design.md](../dto-mapping-design.md) for the full design rationale and
-[dto-mapping-requirements.md](../dto-mapping-requirements.md) for the accepted/rejected
-requirements this feature was scoped against (issue
-[#2540](https://github.com/ebean-orm/ebean/issues/2540)).

docs/guides/writing-ebean-query-beans.md

@@ -462,11 +462,6 @@ List<CustomerSummary> summaries = new QCustomer()
 - the result is not going to be updated and saved back as an entity
 - the query contains formulas or aggregation intended for a read model
 
-`asDto(...)` maps a **flat**, single-row result. If the target DTO itself needs nested
-DTO fields (ToOne/ToMany) mirroring part of the entity graph, use
-`mapTo(Dto.class)` instead — see
-[Mapping entity graphs to DTOs](mapping-entity-graphs-to-dtos.md).
-
 ---
 
 ## Step 9 - Only fall back to raw SQL when the ORM query is not a good fit

ebean-api/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
   </parent>
 
   <name>ebean api</name>

ebean-api/src/main/java/io/ebean/DB.java

@@ -457,10 +457,6 @@ public final class DB {
 
   /**
    * Same as {@link #checkUniqueness(Object)} but with given transaction.
-   * <p>
-   * For control over query cache use and whether to skip the check when the bean's unique
-   * properties are unchanged, use {@link Database#checkUniqueness(Object, Transaction, boolean, boolean)}
-   * via {@link #getDefault()} instead.
    */
   public static Set<Property> checkUniqueness(Object bean, Transaction transaction) {
     return getDefault().checkUniqueness(bean, transaction);

ebean-api/src/main/java/io/ebean/Database.java

@@ -1078,21 +1078,12 @@ public interface Database {
    * @param bean The entity bean to check uniqueness on
    * @return a set of Properties if constraint validation was detected or empty list.
    */
-  default Set<Property> checkUniqueness(Object bean) {
-    return checkUniqueness(bean, null, false, true);
-  }
+  Set<Property> checkUniqueness(Object bean);
 
   /**
    * Same as {@link #checkUniqueness(Object)}. but with given transaction.
    */
-  default Set<Property> checkUniqueness(Object bean, Transaction transaction) {
-    return checkUniqueness(bean, transaction, false, true);
-  }
-
-  /**
-   * Same as {@link #checkUniqueness(Object)}. but with given transaction and extended search options.
-   */
-  Set<Property> checkUniqueness(Object bean, Transaction transaction, boolean useQueryCache, boolean skipClean);
+  Set<Property> checkUniqueness(Object bean, Transaction transaction);
 
   /**
    * Marks the entity bean as dirty.

ebean-api/src/main/java/io/ebean/DatabaseBuilder.java

@@ -62,10 +62,9 @@ public interface DatabaseBuilder {
   /**
    * Build and return the Database instance.
    * <p>
-   * When {@link #setRegister(boolean)} is set to true (the default), and a database
-   * with the same name is already registered, this throws an {@link IllegalStateException}.
-   * Use a unique name, or use {@link #setRegister(boolean)} with {@code false} if the
-   * Database instance is not intended to be registered/looked up by name.
+   * When {@link #setRegister(boolean)} is set to true, and a database with the same
+   * name is already registered, this may return the existing registered database
+   * rather than creating a new one.
    */
   Database build();
 

ebean-api/src/main/java/io/ebean/DatabaseFactory.java

@@ -7,6 +7,8 @@ import jakarta.persistence.PersistenceException;
 
 import java.util.concurrent.locks.ReentrantLock;
 
+import static java.lang.System.Logger.Level.WARNING;
+
 /**
  * Low-level factory for creating {@link Database} instances.
  * <p>
@@ -79,10 +81,10 @@ public final class DatabaseFactory {
         // We're explicitly creating a database to be registered, so avoid
         // triggering DbContext static initialisation to auto-create a default one.
         DbPrimary.setSkip(true);
-        if (DbContext.getInstance().contains(name)) {
-          throw new IllegalStateException("A Database with name [" + name + "] is already registered."
-            + " Use a unique DatabaseConfig name, or set DatabaseConfig.setRegister(false)"
-            + " if this Database instance is not intended to be registered/looked up by name.");
+        Database existing = DbContext.getInstance().getRegistered(name);
+        if (existing != null) {
+          EbeanVersion.log.log(WARNING, "Using existing database with name:{0}", name);
+          return existing;
         }
       }
       Database server = createInternal(config);
@@ -121,24 +123,6 @@ public final class DatabaseFactory {
     }
   }
 
-  /**
-   * Remove the registration of this Database.
-   * <p>
-   * This is invoked when a Database is shutdown so that its registered name
-   * becomes available again for a subsequently created Database with the same name.
-   */
-  public static void unregister(Database server) {
-    lock.lock();
-    try {
-      DbContext.getInstance().deregister(server);
-      if (server.name().equals(defaultServerName)) {
-        defaultServerName = null;
-      }
-    } finally {
-      lock.unlock();
-    }
-  }
-
   /**
    * Shutdown gracefully all Database instances cleaning up any resources as required.
    * <p>

ebean-api/src/main/java/io/ebean/DbContext.java

@@ -4,6 +4,7 @@ import io.ebean.config.BeanNotEnhancedException;
 import io.ebean.datasource.DataSourceConfigurationException;
 
 import jakarta.persistence.PersistenceException;
+import org.jspecify.annotations.Nullable;
 
 import java.util.HashMap;
 import java.util.concurrent.ConcurrentHashMap;
@@ -76,8 +77,9 @@ final class DbContext {
     return defaultDatabase;
   }
 
-  boolean contains(String name) {
-    return concMap.containsKey(name);
+  @Nullable
+  Database getRegistered(String name) {
+    return concMap.get(name);
   }
 
   /**
@@ -120,27 +122,6 @@ final class DbContext {
     registerWithName(server.name(), server, isDefault);
   }
 
-  /**
-   * Remove the registration for this Database (typically on shutdown) so that
-   * its name becomes available again for a subsequently created Database.
-   * <p>
-   * Only removes the registration if it currently maps to this exact instance
-   * (avoids removing a different Database subsequently registered with the same name).
-   */
-  void deregister(Database server) {
-    lock.lock();
-    try {
-      String name = server.name();
-      concMap.remove(name, server);
-      syncMap.remove(name, server);
-      if (defaultDatabase == server) {
-        defaultDatabase = null;
-      }
-    } finally {
-      lock.unlock();
-    }
-  }
-
   private void registerWithName(String name, Database server, boolean isDefault) {
     lock.lock();
     try {

ebean-api/src/main/java/io/ebean/DtoConverterManager.java

@@ -1,65 +0,0 @@
-package io.ebean;
-
-import jakarta.persistence.PersistenceException;
-
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
-
-/**
- * Static bridge registering custom {@code @DtoConvert} converter instances so generated DTO
- * mappers can reach them.
- * <p>
- * Generated mappers (see {@code query.mapTo(SomeDto.class)}) are wired via {@code ServiceLoader}
- * as plain, no-arg-constructed, compile-time singletons (mirroring how entity/query-bean
- * registration already works) - they have no way to reach a dependency-injection container, or
- * any particular {@code Database} instance, at construction time. When a
- * {@code @DtoConvert(value = ConverterType.class, method = "...")} property's converter is an
- * <b>instance</b> method (as opposed to a {@code static} one, which is called directly with no
- * registration needed at all), the generated mapper resolves it via {@link #get(Class)} - so the
- * application must register an instance here, typically one already built by its own DI
- * container, <b>before</b> building the {@code Database}:
- * <pre>{@code
- * AES256Cipher cipher = ...; // already DI-constructed
- * DtoConverterManager.put(DriverConversions.class, new DriverConversionsImpl(cipher));
- *
- * Database db = DatabaseFactory.create(...); // generated mappers resolve converters from here
- * }</pre>
- * <p>
- * This is a deliberate, narrowly-scoped exception to preferring dependency injection over static
- * mutable state - it exists solely to bridge an already-DI-constructed singleton into
- * {@code ServiceLoader}-discovered, no-arg-constructed generated code, which cannot otherwise
- * reach a DI container or a specific {@code Database} instance. {@link #get(Class)} throws
- * immediately if nothing was registered for the given type, so a missing/late registration fails
- * fast at {@code Database} build time (a generated mapper's eager field initializer) rather than
- * lazily on first use.
- */
-public final class DtoConverterManager {
-
-  private static final Map<Class<?>, Object> converters = new ConcurrentHashMap<>();
-
-  private DtoConverterManager() {
-  }
-
-  /**
-   * Register a converter instance for the given type - must be called before the
-   * {@code Database} using it is built.
-   */
-  public static <T> void put(Class<T> type, T instance) {
-    converters.put(type, instance);
-  }
-
-  /**
-   * Return the registered converter instance for the given type.
-   *
-   * @throws PersistenceException if no instance was registered for {@code type}.
-   */
-  @SuppressWarnings("unchecked")
-  public static <T> T get(Class<T> type) {
-    T instance = (T) converters.get(type);
-    if (instance == null) {
-      throw new PersistenceException("No " + type.getName() + " registered - call "
-        + "DtoConverterManager.put(" + type.getSimpleName() + ".class, ...) before starting the Database");
-    }
-    return instance;
-  }
-}

ebean-api/src/main/java/io/ebean/DtoMapContext.java

@@ -1,51 +0,0 @@
-package io.ebean;
-
-import java.util.HashMap;
-import java.util.IdentityHashMap;
-import java.util.Map;
-import java.util.function.Function;
-
-/**
- * Identity-keyed cache of already-mapped source -> target instances, shared across one
- * top-level {@link DtoMapper#mapList(java.util.List)} call (or an explicitly shared context).
- * <p>
- * Keyed by source object <b>identity</b> (an {@link IdentityHashMap}, not {@code equals()}/
- * {@code hashCode()}) because the source is an Ebean entity graph, where repeated references to
- * the same row within one query already resolve to the same Java object instance.
- * <p>
- * The identity map is partitioned <b>per target DTO type</b>. This matters because the same
- * source instance can legitimately need to be mapped to more than one target type within a
- * single graph - e.g. a top-level {@code CustomerDtoMapper} maps a {@code Customer} to a full
- * {@code CustomerDto}, while a nested {@code ContactDtoMapper} maps the very same {@code Customer}
- * instance (accessed via {@code contact.getCustomer()}) to a shallow {@code CustomerRefDto} to
- * avoid a cycle. A single un-partitioned {@code IdentityHashMap<Object,Object>} would have the
- * two mappers collide on the same source key and incorrectly hand back the other mapper's
- * (wrong-typed) cached result. Partitioning by target type keeps each mapper's cache isolated
- * while still sharing one context/instance per top-level mapping call.
- * <p>
- * Not thread-safe - a context is expected to be created per top-level mapping call and not
- * shared across threads.
- */
-public final class DtoMapContext {
-
-  private final Map<Class<?>, Map<Object, Object>> mappedByType = new HashMap<>();
-
-  /**
-   * Return the already-mapped target for the given source instance if present, otherwise map it
-   * via {@code mappingFunction}, register it, and return it.
-   *
-   * @param targetType the DTO type being produced - used to partition the identity cache so that
-   *     mapping the same source to different target types never collides.
-   */
-  @SuppressWarnings("unchecked")
-  public <S, T> T computeIfAbsent(Class<T> targetType, S source, Function<S, T> mappingFunction) {
-    Map<Object, Object> mapped = mappedByType.computeIfAbsent(targetType, t -> new IdentityHashMap<>());
-    T existing = (T) mapped.get(source);
-    if (existing != null) {
-      return existing;
-    }
-    T created = mappingFunction.apply(source);
-    mapped.put(source, created);
-    return created;
-  }
-}

ebean-api/src/main/java/io/ebean/DtoMapper.java

@@ -1,76 +0,0 @@
-package io.ebean;
-
-import java.util.ArrayList;
-import java.util.List;
-
-/**
- * Mapper interface implemented by generated (or hand-written) entity -> DTO graph mappers.
- * <p>
- * Used with nested entity-to-DTO graph mapping (see {@code query.mapTo(SomeDto.class)}) as
- * distinct from the existing flat, single-row {@link DtoQuery} pipeline. Each entity/DTO type
- * pair gets its own small, composable mapper implementation (mirroring MapStruct's per-type
- * mapper generation) rather than one large mapper inlining every nested type. Nested mappers are
- * wired together via constructor injection, not static singletons - this keeps mappers stateless,
- * substitutable (e.g. for tests) and avoids global mutable state.
- * <p>
- * A {@link DtoMapContext} is threaded through every nested {@code map(...)} call within one
- * top-level {@link #mapList(List)} invocation, so that repeated references to the same source
- * entity instance (e.g. several {@code Contact}s sharing the same {@code Customer}) map to the
- * <b>same</b> target DTO instance rather than creating duplicate-but-equal copies. This mirrors
- * the identity semantics Ebean's own entity graph already has, and is what makes the resulting
- * DTO graph "graph shaped" rather than "tree of copies shaped".
- * <p>
- * Implementations contain no reflection or {@code MethodHandles} - only direct getter calls and
- * constructor invocation - so generated mappers are safe under GraalVM native-image with zero
- * additional reachability metadata.
- *
- * @param <SOURCE> the source entity (or embeddable) type
- * @param <TARGET> the target DTO type
- */
-public interface DtoMapper<SOURCE, TARGET> {
-
-  /**
-   * Return the {@link FetchGroup} of exactly the source properties (and nested paths) needed to
-   * populate the target DTO graph - the select()/fetch() spec is derived from the DTO's declared
-   * shape rather than maintained separately by hand. Used by {@code query.mapTo(TARGET.class)}
-   * to automatically apply the correct fetch spec before the query is executed.
-   */
-  FetchGroup<SOURCE> fetchGroup();
-
-  /**
-   * Map a single source instance to its target DTO, reusing/registering the mapping in the
-   * given context so that repeated references to the same source instance de-duplicate to the
-   * same target instance. Must return {@code null} when given {@code null}.
-   */
-  TARGET map(SOURCE source, DtoMapContext context);
-
-  /**
-   * Map a single source instance using a fresh, one-off context. Convenience for mapping a
-   * single object in isolation (no de-duplication opportunity since there's nothing else in
-   * scope to de-duplicate against).
-   */
-  default TARGET map(SOURCE source) {
-    return map(source, new DtoMapContext());
-  }
-
-  /**
-   * Map a list of source instances to a list of target DTOs sharing the given context,
-   * preserving order.
-   */
-  default List<TARGET> mapList(List<SOURCE> source, DtoMapContext context) {
-    List<TARGET> result = new ArrayList<>(source.size());
-    for (SOURCE s : source) {
-      result.add(map(s, context));
-    }
-    return result;
-  }
-
-  /**
-   * Map a list of source instances to a list of target DTOs using a fresh context shared across
-   * the whole list - this is the usual top-level entry point, e.g. mapping the result of a
-   * {@code query.findList()} call.
-   */
-  default List<TARGET> mapList(List<SOURCE> source) {
-    return mapList(source, new DtoMapContext());
-  }
-}

ebean-api/src/main/java/io/ebean/DtoMapperManager.java

@@ -1,125 +0,0 @@
-package io.ebean;
-
-import io.ebean.config.DtoMapperRegister;
-import jakarta.persistence.PersistenceException;
-
-import java.util.ArrayList;
-import java.util.List;
-import java.util.ServiceLoader;
-import java.util.concurrent.ConcurrentHashMap;
-
-/**
- * Loads all generated {@link DtoMapperRegister} implementations (via {@code ServiceLoader},
- * mirroring how {@code EntityClassRegister} is discovered) once, and resolves the {@link
- * DtoMapper} for a given (source, dto) pair, or by the generated mapper's own concrete type, on
- * request.
- * <p>
- * Has no dependency on {@link Database} - it can be constructed independently, before (or
- * without) a {@code Database} existing at all, e.g. as a DI-managed singleton constructed
- * alongside the rest of an application's dependency graph. If you want the exact same instance
- * (and hence the exact same underlying mapper instances) shared between {@code query.mapTo(...)}
- * and your own application code, construct it yourself and register it via {@code
- * DatabaseBuilder.putServiceObject(DtoMapperManager.class, myManager)} before building the {@code
- * Database} - it is then used instead of a Database-internal default instance.
- * <p>
- * Resolved mappers are cached so that repeated lookups only ever pay the cost of iterating the
- * generated registers and constructing the mapper (and its nested mapper/{@code FetchGroup}
- * graph) once - after that, every lookup is a single hash-map hit regardless of how many entity/
- * DTO pairs are registered.
- */
-public final class DtoMapperManager {
-
-  private final List<DtoMapperRegister> registers;
-  private final ConcurrentHashMap<MapperKey, DtoMapper<?, ?>> pairCache = new ConcurrentHashMap<>();
-  private final ConcurrentHashMap<Class<?>, Object> typeCache = new ConcurrentHashMap<>();
-
-  public DtoMapperManager() {
-    this.registers = load();
-  }
-
-  private static List<DtoMapperRegister> load() {
-    List<DtoMapperRegister> result = new ArrayList<>();
-    for (DtoMapperRegister register : ServiceLoader.load(DtoMapperRegister.class)) {
-      result.add(register);
-    }
-    return result;
-  }
-
-  /**
-   * Return the {@link DtoMapper} for the given (source, dto) pair.
-   *
-   * @throws PersistenceException if no generated mapper is registered for that pair.
-   */
-  @SuppressWarnings("unchecked")
-  public <S, D> DtoMapper<S, D> mapperFor(Class<S> sourceType, Class<D> dtoType) {
-    return (DtoMapper<S, D>) pairCache.computeIfAbsent(new MapperKey(sourceType, dtoType), this::resolve);
-  }
-
-  /**
-   * Return the generated mapper instance of the given concrete mapper type - e.g. {@code
-   * manager.get(CustomerDtoMapper.class)} - typically used to resolve a mapper instance for
-   * dependency injection into application code (e.g. an avaje-inject {@code @Factory} bean
-   * method).
-   *
-   * @throws PersistenceException if no generated mapper of that type is registered.
-   */
-  @SuppressWarnings("unchecked")
-  public <T> T get(Class<T> mapperType) {
-    return (T) typeCache.computeIfAbsent(mapperType, this::resolveByType);
-  }
-
-  private DtoMapper<?, ?> resolve(MapperKey key) {
-    for (DtoMapperRegister register : registers) {
-      DtoMapper<?, ?> mapper = register.mapperFor(key.sourceType, key.dtoType);
-      if (mapper != null) {
-        return mapper;
-      }
-    }
-    throw new PersistenceException("No DtoMapper registered mapping " + key.sourceType + " -> " + key.dtoType
-      + " - check @DtoMapping(source = " + key.sourceType.getSimpleName() + ".class, target = "
-      + key.dtoType.getSimpleName() + ".class) is declared on a package-info.java processed by querybean-generator");
-  }
-
-  private Object resolveByType(Class<?> mapperType) {
-    for (DtoMapperRegister register : registers) {
-      Object mapper = register.mapperOfType(mapperType);
-      if (mapper != null) {
-        return mapper;
-      }
-    }
-    throw new PersistenceException("No DtoMapper of type " + mapperType.getName() + " registered"
-      + " - check a @DtoMapping(...) pair generating " + mapperType.getSimpleName()
-      + " is declared on a package-info.java processed by querybean-generator");
-  }
-
-  /**
-   * Cache key pairing the source entity type and target DTO type.
-   */
-  private static final class MapperKey {
-
-    private final Class<?> sourceType;
-    private final Class<?> dtoType;
-
-    MapperKey(Class<?> sourceType, Class<?> dtoType) {
-      this.sourceType = sourceType;
-      this.dtoType = dtoType;
-    }
-
-    @Override
-    public boolean equals(Object o) {
-      if (this == o) {
-        return true;
-      }
-      if (!(o instanceof MapperKey)) {
-        return false;
-      }
-      MapperKey other = (MapperKey) o;
-      return sourceType == other.sourceType && dtoType == other.dtoType;
-    }
-
-    @Override
-    public int hashCode() {
-      return 31 * sourceType.hashCode() + dtoType.hashCode();
-    }
-  }
-}

ebean-api/src/main/java/io/ebean/DtoMapperSupport.java

@@ -1,137 +0,0 @@
-package io.ebean;
-
-/**
- * Runtime helpers used by generated {@link DtoMapper} implementations to safely resolve a
- * primitive-typed DTO field whose value is derived from a multi-hop {@code @DtoPath} that
- * traverses a nullable intermediate relation.
- * <p>
- * A {@code null}-guarded getter-chain (e.g. {@code source.getOrganisation() == null ? null :
- * source.getOrganisation().getId()}) always types as the boxed wrapper (since one branch is the
- * {@code null} literal). When the DTO's target field is a primitive (e.g. {@code long
- * organisationId}), passing that boxed expression to the constructor auto-unboxes it - which
- * throws a raw, unhelpful {@link NullPointerException} if the relation really is {@code null}.
- * <p>
- * These methods give the generated mapper a choice, controlled by {@code @DtoPath#failOnNull()}:
- * default to the primitive's zero-equivalent value ({@code orZero} methods, the default), or
- * throw a clear, descriptive exception naming the offending property path ({@code require}
- * methods, opted into via {@code failOnNull = true}).
- *
- * @see io.ebean.annotation.DtoPath
- */
-public final class DtoMapperSupport {
-
-  private DtoMapperSupport() {
-  }
-
-  /** Return {@code 0} if {@code value} is {@code null}, otherwise its unboxed value. */
-  public static long orZero(Long value) {
-    return value == null ? 0L : value;
-  }
-
-  /** Return {@code 0} if {@code value} is {@code null}, otherwise its unboxed value. */
-  public static int orZero(Integer value) {
-    return value == null ? 0 : value;
-  }
-
-  /** Return {@code 0} if {@code value} is {@code null}, otherwise its unboxed value. */
-  public static short orZero(Short value) {
-    return value == null ? 0 : value;
-  }
-
-  /** Return {@code 0} if {@code value} is {@code null}, otherwise its unboxed value. */
-  public static byte orZero(Byte value) {
-    return value == null ? 0 : value;
-  }
-
-  /** Return {@code 0.0} if {@code value} is {@code null}, otherwise its unboxed value. */
-  public static double orZero(Double value) {
-    return value == null ? 0.0 : value;
-  }
-
-  /** Return {@code 0.0f} if {@code value} is {@code null}, otherwise its unboxed value. */
-  public static float orZero(Float value) {
-    return value == null ? 0.0f : value;
-  }
-
-  /** Return {@code false} if {@code value} is {@code null}, otherwise its unboxed value. */
-  public static boolean orZero(Boolean value) {
-    return value != null && value;
-  }
-
-  /** Return {@code '\u0000'} if {@code value} is {@code null}, otherwise its unboxed value. */
-  public static char orZero(Character value) {
-    return value == null ? '\u0000' : value;
-  }
-
-  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
-  public static long require(Long value, String path) {
-    if (value == null) {
-      throw failure(path);
-    }
-    return value;
-  }
-
-  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
-  public static int require(Integer value, String path) {
-    if (value == null) {
-      throw failure(path);
-    }
-    return value;
-  }
-
-  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
-  public static short require(Short value, String path) {
-    if (value == null) {
-      throw failure(path);
-    }
-    return value;
-  }
-
-  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
-  public static byte require(Byte value, String path) {
-    if (value == null) {
-      throw failure(path);
-    }
-    return value;
-  }
-
-  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
-  public static double require(Double value, String path) {
-    if (value == null) {
-      throw failure(path);
-    }
-    return value;
-  }
-
-  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
-  public static float require(Float value, String path) {
-    if (value == null) {
-      throw failure(path);
-    }
-    return value;
-  }
-
-  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
-  public static boolean require(Boolean value, String path) {
-    if (value == null) {
-      throw failure(path);
-    }
-    return value;
-  }
-
-  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
-  public static char require(Character value, String path) {
-    if (value == null) {
-      throw failure(path);
-    }
-    return value;
-  }
-
-  private static IllegalStateException failure(String path) {
-    return new IllegalStateException(
-      "@DtoPath(\"" + path + "\") resolved to null via a nullable intermediate relation, but the"
-        + " target DTO field is primitive and failOnNull=true - either handle the null case in"
-        + " source data, use a boxed wrapper type for the DTO field, or remove failOnNull to"
-        + " default to the primitive's zero-equivalent value instead.");
-  }
-}

ebean-api/src/main/java/io/ebean/DtoQuery.java

@@ -1,9 +1,16 @@
 package io.ebean;
 
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
+import javax.sql.DataSource;
+import java.sql.Connection;
 import java.util.Collection;
 import java.util.List;
+import java.util.Optional;
+import java.util.function.Consumer;
+import java.util.function.Predicate;
+import java.util.stream.Stream;
 
 /**
  * Query for performing native SQL queries that return DTO Bean's.
@@ -36,7 +43,12 @@ import java.util.List;
  * }</pre>
  */
 @NullMarked
-public interface DtoQuery<T> extends StreamableQuery<DtoQuery<T>, T> {
+public interface DtoQuery<T> extends CancelableQuery {
+
+  /**
+   * Execute the query returning a list.
+   */
+  List<T> findList();
 
   /**
    * Execute the query iterating a row at a time.
@@ -47,6 +59,56 @@ public interface DtoQuery<T> extends StreamableQuery<DtoQuery<T>, T> {
    */
   QueryIterator<T> findIterate();
 
+  /**
+   * Execute the query returning a Stream.
+   * <p>
+   * Note that the Stream holds resources related to the underlying
+   * resultSet and potentially connection and MUST be closed. We should use
+   * the Stream in a <em>try with resource block</em>.
+   */
+  Stream<T> findStream();
+
+  /**
+   * Execute the query iterating a row at a time.
+   * <p>
+   * This streaming type query is useful for large query execution as only 1 row needs to be held in memory.
+   * </p>
+   */
+  void findEach(Consumer<T> consumer);
+
+  /**
+   * Execute the query iterating the results and batching them for the consumer.
+   * <p>
+   * This runs like findEach streaming results from the database but just collects the results
+   * into batches to pass to the consumer.
+   *
+   * @param batch    The number of dto beans to collect before given them to the consumer
+   * @param consumer The consumer to process the batch of DTO beans
+   */
+  void findEach(int batch, Consumer<List<T>> consumer);
+
+  /**
+   * Execute the query iterating a row at a time with the ability to stop consuming part way through.
+   * <p>
+   * Returning false after processing a row stops the iteration through the query results.
+   * </p>
+   * <p>
+   * This streaming type query is useful for large query execution as only 1 row needs to be held in memory.
+   * </p>
+   */
+  void findEachWhile(Predicate<T> consumer);
+
+  /**
+   * Execute the query returning a single bean.
+   */
+  @Nullable
+  T findOne();
+
+  /**
+   * Execute the query returning an optional bean.
+   */
+  Optional<T> findOneOrEmpty();
+
   /**
    * Bind all the parameters using index positions.
    * <p>
@@ -153,41 +215,35 @@ public interface DtoQuery<T> extends StreamableQuery<DtoQuery<T>, T> {
   DtoQuery<T> setBufferFetchSizeHint(int bufferFetchSizeHint);
 
   /**
-   * Return a PagedList for this query using firstRow and maxRows.
-   * <p>
-   * The benefit of using this over findList() is that it provides functionality to get the
-   * total row count etc.
-   * <p>
-   * If maxRows is not set on the query prior to calling findPagedList() then a
-   * PersistenceException is thrown.
-   * <p>
-   * This is only supported for a DtoQuery that is derived from an ORM query via
-   * {@link Query#asDto(Class)} / {@link ExpressionList#asDto(Class)}. It is not supported
-   * for a DtoQuery based on raw SQL (e.g. via {@link Database#findDto(Class, String)}) as
-   * there is no query structure available from which to derive a matching row count query -
-   * a PersistenceException is thrown in that case.
-   * <pre>{@code
-   *
-   *  PagedList<OrderDto> pagedList =
-   *    DB.find(Order.class)
-   *       .where().eq("status", Order.Status.NEW)
-   *       .orderBy().asc("id")
-   *       .setFirstRow(50)
-   *       .setMaxRows(20)
-   *       .asDto(OrderDto.class)
-   *       .findPagedList();
-   *
-   *       // fetch the total row count in the background
-   *       pagedList.loadCount();
-   *
-   *       List<OrderDto> orders = pagedList.getList();
-   *       int totalRowCount = pagedList.getTotalCount();
-   *
-   * }</pre>
-   *
-   * @return The PagedList
+   * Use the explicit transaction to execute the query.
    */
-  @Override
-  PagedList<T> findPagedList();
+  DtoQuery<T> usingTransaction(Transaction transaction);
+
+  /**
+   * Execute the query using the given connection.
+   */
+  DtoQuery<T> usingConnection(Connection connection);
+
+  /**
+   * Ensure that the master DataSource is used if there is a read only data source
+   * being used (that is using a read replica database potentially with replication lag).
+   * <p>
+   * When the database is configured with a read-only DataSource via
+   * say {@link io.ebean.DatabaseBuilder#readOnlyDataSource(DataSource)} then
+   * by default when a query is run without an active transaction, it uses the read-only data
+   * source. We use {@code usingMaster()} to instead ensure that the query is executed
+   * against the master data source.
+   */
+  default DtoQuery<T> usingMaster() {
+    return usingMaster(true);
+  }
+
+  /**
+   * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
+   * data source can be used if defined.
+   *
+   * @see #usingMaster()
+   */
+  DtoQuery<T> usingMaster(boolean useMaster);
 
 }

ebean-api/src/main/java/io/ebean/ExpressionList.java

@@ -10,7 +10,6 @@ import java.sql.Timestamp;
 import java.util.*;
 import java.util.function.Consumer;
 import java.util.function.Predicate;
-import java.util.function.Supplier;
 
 /**
  * List of Expressions that make up a where or having clause.
@@ -104,29 +103,6 @@ public interface ExpressionList<T> {
    */
   <D> DtoQuery<D> asDto(Class<D> dtoClass);
 
-  /**
-   * Map the query result to a nested DTO graph, automatically deriving the select()/fetch() spec
-   * from the target DTO's declared shape and forcing {@code setUnmodifiable(true)}.
-   * <p>
-   * Distinct from {@link #asDto(Class)} (the flat, single-row SQL pipeline) - this supports
-   * nested ToOne/ToMany DTO graphs, mapped from the normal ORM entity query result.
-   *
-   * @throws jakarta.persistence.PersistenceException if no generated {@link DtoMapper} is
-   *     registered for this (entity, dto) pair.
-   */
-  <D> MappedQuery<D> mapTo(Class<D> dtoType);
-
-  /**
-   * Map the query result to a nested DTO graph using an already-resolved {@link DtoMapper}
-   * instance, rather than looking one up by (entity, dtoType) - e.g. to select a named variant
-   * mapper (see {@code @DtoMapping(name = "...", exclude = "...")}), such as
-   * {@code query.mapTo(User.class, userMapper.noFleets())}.
-   *
-   * @param dtoType the DTO type mapped to (must match {@code mapper}'s target type)
-   * @param mapper the mapper instance to use, e.g. a named variant accessor on a generated mapper
-   */
-  <D> MappedQuery<D> mapTo(Class<D> dtoType, DtoMapper<T, D> mapper);
-
   /**
    * Return the underlying query as an UpdateQuery.
    * <p>
@@ -422,26 +398,6 @@ public interface ExpressionList<T> {
    */
   Optional<T> findOneOrEmpty();
 
-  /**
-   * Execute the query returning a single bean or throwing a {@link jakarta.persistence.EntityNotFoundException}
-   * if there is no matching bean.
-   *
-   * @see Query#findOneOrThrow()
-   */
-  default T findOneOrThrow() {
-    return query().findOneOrThrow();
-  }
-
-  /**
-   * Execute the query returning a single bean or throwing the exception produced by the
-   * given supplier if there is no matching bean.
-   *
-   * @see Query#findOneOrThrow(Supplier)
-   */
-  default T findOneOrThrow(Supplier<? extends RuntimeException> exceptionSupplier) {
-    return query().findOneOrThrow(exceptionSupplier);
-  }
-
   /**
    * Execute find row count query in a background thread.
    * <p>

ebean-api/src/main/java/io/ebean/FindableQuery.java

@@ -1,89 +0,0 @@
-package io.ebean;
-
-import org.jspecify.annotations.NullMarked;
-import org.jspecify.annotations.Nullable;
-
-import jakarta.persistence.EntityNotFoundException;
-import javax.sql.DataSource;
-import java.sql.Connection;
-import java.util.List;
-import java.util.Optional;
-import java.util.function.Supplier;
-
-/**
- * Common find operations shared by the query types that can execute and return
- * results - {@link SqlQuery}, {@link DtoQuery}, {@link MappedQuery} and {@link QueryBuilder}.
- *
- * @param <SELF> The query type (used for method chaining)
- * @param <T>    The type of the result
- */
-@NullMarked
-public interface FindableQuery<SELF extends FindableQuery<SELF, T>, T> extends CancelableQuery {
-
-  /**
-   * Execute the query returning the list of results.
-   */
-  List<T> findList();
-
-  /**
-   * Execute the query returning a single result, or {@code null} if there is no matching row.
-   * <p>
-   * If more than 1 row is found for this query then a PersistenceException is thrown.
-   */
-  @Nullable
-  T findOne();
-
-  /**
-   * Execute the query returning an optional result.
-   */
-  Optional<T> findOneOrEmpty();
-
-  /**
-   * Execute the query returning a single result or throwing a
-   * {@link jakarta.persistence.EntityNotFoundException} if there is no matching row.
-   */
-  default T findOneOrThrow() {
-    return findOneOrEmpty().orElseThrow(() -> new EntityNotFoundException("Not found"));
-  }
-
-  /**
-   * Execute the query returning a single result or throwing the exception produced
-   * by the given supplier if there is no matching row.
-   */
-  default T findOneOrThrow(Supplier<? extends RuntimeException> exceptionSupplier) {
-    return findOneOrEmpty().orElseThrow(exceptionSupplier);
-  }
-
-  /**
-   * Execute the query using the given transaction.
-   */
-  SELF usingTransaction(Transaction transaction);
-
-  /**
-   * Execute the query using the given connection.
-   */
-  SELF usingConnection(Connection connection);
-
-  /**
-   * Ensure that the master DataSource is used if there is a read only data source
-   * being used (that is using a read replica database potentially with replication lag).
-   * <p>
-   * When the database is configured with a read-only DataSource via
-   * say {@link DatabaseBuilder#readOnlyDataSource(DataSource)} then
-   * by default when a query is run without an active transaction, it uses the read-only data
-   * source. We use {@code usingMaster()} to instead ensure that the query is executed
-   * against the master data source.
-   */
-  default SELF usingMaster() {
-    return usingMaster(true);
-  }
-
-  /**
-   * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
-   * data source can be used if defined.
-   *
-   * @see #usingMaster()
-   */
-  SELF usingMaster(boolean useMaster);
-
-}

ebean-api/src/main/java/io/ebean/MappedQuery.java

@@ -1,111 +0,0 @@
-package io.ebean;
-
-import org.jspecify.annotations.NullMarked;
-
-import java.util.List;
-import java.util.function.Consumer;
-import java.util.function.Predicate;
-import java.util.stream.Stream;
-
-/**
- * Query that maps an entity graph query result to a nested DTO graph, produced by
- * {@code query.mapTo(SomeDto.class)}.
- * <p>
- * Distinct from the existing flat, single-row {@link DtoQuery} pipeline (see {@link
- * QueryBuilder#asDto(Class)}) - this executes the underlying entity ORM query (with the
- * select()/fetch() spec automatically derived from the target DTO's declared shape, see
- * {@link DtoMapper#fetchGroup()}), forces {@code setUnmodifiable(true)}, and then maps the
- * resulting (unmodifiable) entity graph into a DTO graph via the generated {@link DtoMapper},
- * supporting nested ToOne/ToMany and identity-aware de-duplication.
- *
- * @param <D> the target DTO type
- */
-@NullMarked
-public interface MappedQuery<D> extends StreamableQuery<MappedQuery<D>, D> {
-
-  /**
-   * Execute the query returning the mapped DTO list.
-   */
-  @Override
-  List<D> findList();
-
-  /**
-   * Execute the query returning a paged list of mapped DTOs.
-   * <p>
-   * Mirrors {@code Query#findPagedList()} - the underlying entity graph query is paged (via
-   * {@code setFirstRow(int)}/{@code setMaxRows(int)}) and executed as normal, then each page's
-   * result is mapped to the target DTO graph. Row-count/page-index metadata
-   * ({@link PagedList#getTotalCount()}, {@link PagedList#hasNext()}, etc.) reflects the
-   * underlying entity query and is unaffected by the DTO mapping.
-   */
-  @Override
-  PagedList<D> findPagedList();
-
-  /**
-   * Execute the query returning the result as a Stream of mapped DTOs.
-   * <p>
-   * Mirrors {@link QueryBuilder#findStream()} - the underlying entity graph query is streamed
-   * (supporting very large queries iterating any number of results, potentially using multiple
-   * persistence contexts internally) and each entity is mapped to its target DTO lazily as the
-   * stream is consumed, sharing one {@link DtoMapContext} across the whole stream so that
-   * repeated references to the same source entity still de-duplicate to the same DTO instance.
-   * <pre>{@code
-   *
-   *  // use try with resources to ensure Stream is closed
-   *
-   *  try (Stream<CustomerDto> stream = query.mapTo(CustomerDto.class).findStream()) {
-   *    stream
-   *    .map(...)
-   *    .collect(...);
-   *  }
-   *
-   * }</pre>
-   */
-  @Override
-  Stream<D> findStream();
-
-  /**
-   * Execute the query processing the mapped DTOs one at a time.
-   * <p>
-   * Mirrors {@link QueryBuilder#findEach(Consumer)} - the underlying entity graph query is
-   * streamed one entity at a time and each entity is mapped to its target DTO lazily as it is
-   * consumed, sharing one {@link DtoMapContext} across the whole callback so that repeated
-   * references to the same source entity still de-duplicate to the same DTO instance.
-   * <p>
-   * This method is appropriate to process very large query results as the mapped DTOs are
-   * consumed one at a time and do not need to be held in memory (unlike {@link #findList()}).
-   *
-   * @param consumer the consumer used to process the mapped DTOs.
-   */
-  @Override
-  void findEach(Consumer<D> consumer);
-  /**
-   * Execute findEach streaming query batching the mapped DTOs for consuming.
-   * <p>
-   * Mirrors {@link QueryBuilder#findEach(int, Consumer)} - typically used when we want to do
-   * further processing on the mapped DTOs in batch form, for example 100 at a time. Each batch
-   * shares one {@link DtoMapContext} with the rest of the query so that repeated references to
-   * the same source entity still de-duplicate to the same DTO instance.
-   *
-   * @param batch    The number of mapped DTOs processed in the batch
-   * @param consumer Process the batch of mapped DTOs
-   */
-  @Override
-  void findEach(int batch, Consumer<List<D>> consumer);
-
-  /**
-   * Execute the query using callbacks to process the resulting mapped DTOs one at a time,
-   * with the ability to stop processing part way through.
-   * <p>
-   * Mirrors {@link QueryBuilder#findEachWhile(Predicate)} - returning {@code false} after
-   * processing a DTO stops the iteration through the query results. Sharing one
-   * {@link DtoMapContext} across the whole callback so that repeated references to the same
-   * source entity still de-duplicate to the same DTO instance.
-   *
-   * @param consumer the consumer used to process the mapped DTOs, returning {@code false} to
-   *                 stop processing.
-   */
-  @Override
-  void findEachWhile(Predicate<D> consumer);
-
-}

ebean-api/src/main/java/io/ebean/Query.java

@@ -151,7 +151,7 @@ import org.jspecify.annotations.Nullable;
  * @param <T> the type of Entity bean this query will fetch.
  */
 @NullMarked
-public interface Query<T> extends QueryBuilder<Query<T>, T> {
+public interface Query<T> extends CancelableQuery, QueryBuilder<Query<T>, T> {
 
   /**
    * The lock type (strength) to use with query FOR UPDATE row locking.

ebean-api/src/main/java/io/ebean/QueryBuilder.java

@@ -2,7 +2,8 @@ package io.ebean;
 
 import org.jspecify.annotations.Nullable;
 
-import jakarta.persistence.EntityNotFoundException;
+import javax.sql.DataSource;
+import java.sql.Connection;
 import java.sql.Timestamp;
 import java.util.List;
 import java.util.Map;
@@ -10,6 +11,8 @@ import java.util.Optional;
 import java.util.Set;
 import java.util.function.BooleanSupplier;
 import java.util.function.Consumer;
+import java.util.function.Predicate;
+import java.util.stream.Stream;
 
 /**
  * Build and execute an ORM query.
@@ -17,7 +20,7 @@ import java.util.function.Consumer;
  * @param <SELF> The type of the builder
  * @param <T>    The entity bean type
  */
-public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends QueryBuilderProjection<SELF, T>, StreamableQuery<SELF, T> {
+public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends QueryBuilderProjection<SELF, T> {
 
   /**
    * Set root table alias.
@@ -74,32 +77,6 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
    */
   <D> DtoQuery<D> asDto(Class<D> dtoClass);
 
-  /**
-   * Map the query result to a nested DTO graph, automatically deriving the select()/fetch() spec
-   * from the target DTO's declared shape and forcing {@code setUnmodifiable(true)}.
-   * <p>
-   * Distinct from {@link #asDto(Class)} (the flat, single-row SQL pipeline) - this supports
-   * nested ToOne/ToMany DTO graphs, mapped from the normal ORM entity query result.
-   *
-   * @throws jakarta.persistence.PersistenceException if no generated {@link DtoMapper} is
-   *     registered for this (entity, dto) pair.
-   */
-  <D> MappedQuery<D> mapTo(Class<D> dtoType);
-
-  /**
-   * Map the query result to a nested DTO graph using an already-resolved {@link DtoMapper}
-   * instance, rather than looking one up by (entity, dtoType). Bypasses {@link DtoMapperManager}
-   * entirely, so it's the way to select a named variant mapper (see {@code @DtoMapping(name =
-   * "...", exclude = "...")}) - e.g. {@code query.mapTo(User.class, userMapper.noFleets())}.
-   * <p>
-   * Also forces {@code setUnmodifiable(true)} and derives the select()/fetch() spec from
-   * {@code mapper.fetchGroup()}, same as {@link #mapTo(Class)}.
-   *
-   * @param dtoType the DTO type mapped to (must match {@code mapper}'s target type)
-   * @param mapper the mapper instance to use, e.g. a named variant accessor on a generated mapper
-   */
-  <D> MappedQuery<D> mapTo(Class<D> dtoType, DtoMapper<T, D> mapper);
-
   /**
    * Convert the query to a UpdateQuery.
    * <p>
@@ -143,16 +120,48 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
    */
   SELF copy();
 
+  /**
+   * Execute the query using the given transaction.
+   */
+  SELF usingTransaction(Transaction transaction);
+
   /**
    * Execute this query using immutable bean cache values for matching bean types.
    */
   SELF using(ImmutableBeanCache<?> beanCache);
 
+  /**
+   * Execute the query using the given connection.
+   */
+  SELF usingConnection(Connection connection);
+
   /**
    * Execute the query using the given database.
    */
   SELF usingDatabase(Database database);
 
+  /**
+   * Ensure that the master DataSource is used if there is a read only data source
+   * being used (that is using a read replica database potentially with replication lag).
+   * <p>
+   * When the database is configured with a read-only DataSource via
+   * say {@link io.ebean.config.DatabaseConfig#setReadOnlyDataSource(DataSource)} then
+   * by default when a query is run without an active transaction, it uses the read-only data
+   * source. We we use {@code usingMaster()} to instead ensure that the query is executed
+   * against the master data source.
+   */
+  default SELF usingMaster() {
+    return usingMaster(true);
+  }
+
+  /**
+   * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
+   * data source can be used if defined.
+   *
+   * @see #usingMaster()
+   */
+  SELF usingMaster(boolean useMaster);
+
   /**
    * Set the base table to use for this query.
    * <p>
@@ -644,24 +653,88 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
   boolean exists();
 
   /**
-   * Execute the query returning a single bean or throwing a {@link jakarta.persistence.EntityNotFoundException}
-   * if there is no matching bean.
+   * Execute the query returning either a single bean or null (if no matching
+   * bean is found).
+   * <p>
+   * If more than 1 row is found for this query then a PersistenceException is
+   * thrown.
+   * <p>
+   * This is useful when your predicates dictate that your query should only
+   * return 0 or 1 results.
    * <p>
-   * This is a convenience alternative to:
    * <pre>{@code
-   *   query.findOneOrEmpty()
-   *     .orElseThrow(() -> new EntityNotFoundException(...));
+   *
+   * // assuming the sku of products is unique...
+   * Product product =
+   *     new QProduct()
+   *         .sku.equalTo("aa113")
+   *         .findOne();
+   * ...
    * }</pre>
    * <p>
-   * The exception message is a best effort - it uses the id when this is effectively a
-   * find-by-id query, or the single equality predicate when the query is filtered by what
-   * looks like a natural/unique key, otherwise a generic "not found" message.
+   * It is also useful with finding objects by their id when you want to specify
+   * further join information to optimise the query.
+   * <p>
+   * <pre>{@code
+   *
+   * // Fetch order 42 and additionally fetch join its order details...
+   * Order order =
+   *     new QOrder()
+   *         .fetch("details") // eagerly load the order details
+   *         .id.equalTo(42)
+   *         .findOne();
+   *
+   * // the order details were eagerly loaded
+   * List<OrderDetail> details = order.getDetails();
+   * ...
+   * }</pre>
    */
-  @Override
-  default T findOneOrThrow() {
-    return findOneOrEmpty().orElseThrow(() ->
-      new EntityNotFoundException(getBeanType().getSimpleName() + " not found"));
-  }
+  @Nullable
+  T findOne();
+
+  /**
+   * Execute the query returning an optional bean.
+   */
+  Optional<T> findOneOrEmpty();
+
+  /**
+   * Execute the query returning the list of objects.
+   * <p>
+   * This query will execute against the EbeanServer that was used to create it.
+   * <p>
+   * <pre>{@code
+   *
+   * List<Customer> customers =
+   *     new QCustomer()
+   *       .name.ilike("rob%")
+   *       .findList();
+   *
+   * }</pre>
+   *
+   * @see Query#findList()
+   */
+  List<T> findList();
+
+  /**
+   * Execute the query returning the result as a Stream.
+   * <p>
+   * Note that this can support very large queries iterating
+   * any number of results. To do so internally it can use
+   * multiple persistence contexts.
+   * </p>
+   * <pre>{@code
+   *
+   *  // use try with resources to ensure Stream is closed
+   *
+   *  try (Stream<Customer> stream = query.findStream()) {
+   *    stream
+   *    .map(...)
+   *    .collect(...);
+   *  }
+   *
+   * }</pre>
+   */
+  Stream<T> findStream();
 
   /**
    * Execute the query returning the set of objects.
@@ -806,6 +879,84 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
    */
   <A> Set<A> findSingleAttributeSet();
 
+  /**
+   * Execute the query processing the beans one at a time.
+   * <p>
+   * This method is appropriate to process very large query results as the
+   * beans are consumed one at a time and do not need to be held in memory
+   * (unlike #findList #findSet etc)
+   * <p>
+   * Note that internally Ebean can inform the JDBC driver that it is expecting larger
+   * resultSet and specifically for MySQL this hint is required to stop it's JDBC driver
+   * from buffering the entire resultSet. As such, for smaller resultSets findList() is
+   * generally preferable.
+   * <p>
+   * Compared with #findEachWhile this will always process all the beans where as
+   * #findEachWhile provides a way to stop processing the query result early before
+   * all the beans have been read.
+   * <p>
+   * This method is functionally equivalent to findIterate() but instead of using an
+   * iterator uses the Consumer interface which is better suited to use with closures.
+   *
+   * <pre>{@code
+   *
+   *  new QCustomer()
+   *     .status.equalTo(Status.NEW)
+   *     .orderBy().id.asc()
+   *     .findEach((Customer customer) -> {
+   *
+   *       // do something with customer
+   *       System.out.println("-- visit " + customer);
+   *     });
+   *
+   * }</pre>
+   *
+   * @param consumer the consumer used to process the queried beans.
+   */
+  void findEach(Consumer<T> consumer);
+
+  /**
+   * Execute findEach streaming query batching the results for consuming.
+   * <p>
+   * This query execution will stream the results and is suited to consuming
+   * large numbers of results from the database.
+   * <p>
+   * Typically, we use this batch consumer when we want to do further processing on
+   * the beans and want to do that processing in batch form, for example - 100 at
+   * a time.
+   *
+   * @param batch    The number of beans processed in the batch
+   * @param consumer Process the batch of beans
+   */
+  void findEach(int batch, Consumer<List<T>> consumer);
+
+  /**
+   * Execute the query using callbacks to a visitor to process the resulting
+   * beans one at a time.
+   * <p>
+   * This method is functionally equivalent to findIterate() but instead of using an
+   * iterator uses the Predicate interface which is better suited to use with closures.
+   *
+   * <pre>{@code
+   *
+   *  new QCustomer()
+   *     .status.equalTo(Status.NEW)
+   *     .orderBy().id.asc()
+   *     .findEachWhile((Customer customer) -> {
+   *
+   *       // do something with customer
+   *       System.out.println("-- visit " + customer);
+   *
+   *       // return true to continue processing or false to stop
+   *       return (customer.getId() < 40);
+   *     });
+   *
+   * }</pre>
+   *
+   * @param consumer the consumer used to process the queried beans.
+   */
+  void findEachWhile(Predicate<T> consumer);
+
   /**
    * Return versions of a @History entity bean.
    * <p>
@@ -871,4 +1022,33 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
    */
   <K> FutureMap<K,T> findFutureMap();
 
+  /**
+   * Return a PagedList for this query using firstRow and maxRows.
+   * <p>
+   * The benefit of using this over findList() is that it provides functionality to get the
+   * total row count etc.
+   * <p>
+   * If maxRows is not set on the query prior to calling findPagedList() then a
+   * PersistenceException is thrown.
+   * <p>
+   * <pre>{@code
+   *
+   *  PagedList<Order> pagedList =
+   *    new QOrder()
+   *       .setFirstRow(50)
+   *       .setMaxRows(20)
+   *       .findPagedList();
+   *
+   *       // fetch the total row count in the background
+   *       pagedList.loadRowCount();
+   *
+   *       List<Order> orders = pagedList.getList();
+   *       int totalRowCount = pagedList.getTotalRowCount();
+   *
+   * }</pre>
+   *
+   * @return The PagedList
+   */
+  PagedList<T> findPagedList();
+
 }

ebean-api/src/main/java/io/ebean/SqlQuery.java

@@ -3,6 +3,7 @@ package io.ebean;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
+import javax.sql.DataSource;
 import java.io.Serializable;
 import java.sql.Connection;
 import java.util.Collection;
@@ -40,7 +41,44 @@ import java.util.function.Predicate;
  * }</pre>
  */
 @NullMarked
-public interface SqlQuery extends Serializable, FindableQuery<SqlQuery, SqlRow> {
+public interface SqlQuery extends Serializable, CancelableQuery {
+
+  /**
+   * Execute the query using the given transaction.
+   */
+  SqlQuery usingTransaction(Transaction transaction);
+
+  /**
+   * Execute the query using the given connection.
+   */
+  SqlQuery usingConnection(Connection connection);
+
+  /**
+   * Ensure that the master DataSource is used if there is a read only data source
+   * being used (that is using a read replica database potentially with replication lag).
+   * <p>
+   * When the database is configured with a read-only DataSource via
+   * say {@link io.ebean.DatabaseBuilder#readOnlyDataSource(DataSource)}then
+   * by default when a query is run without an active transaction, it uses the read-only data
+   * source. We use {@code usingMaster()} to instead ensure that the query is executed
+   * against the master data source.
+   */
+  default SqlQuery usingMaster() {
+    return usingMaster(true);
+  }
+
+  /**
+   * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
+   * data source can be used if defined.
+   *
+   * @see #usingMaster()
+   */
+  SqlQuery usingMaster(boolean useMaster);
+
+  /**
+   * Execute the query returning a list.
+   */
+  List<SqlRow> findList();
 
   /**
    * Execute the SqlQuery iterating a row at a time.
@@ -61,6 +99,16 @@ public interface SqlQuery extends Serializable, FindableQuery<SqlQuery, SqlRow>
    */
   void findEachWhile(Predicate<SqlRow> consumer);
 
+  /**
+   * Execute the query returning a single row or null.
+   * <p>
+   * If this query finds 2 or more rows then it will throw a
+   * PersistenceException.
+   * </p>
+   */
+  @Nullable
+  SqlRow findOne();
+
   /**
    * Execute the query reading each row from ResultSet using the RowConsumer.
    * <p>
@@ -91,6 +139,11 @@ public interface SqlQuery extends Serializable, FindableQuery<SqlQuery, SqlRow>
    */
   void findEachRow(RowConsumer consumer);
 
+  /**
+   * Execute the query returning an optional row.
+   */
+  Optional<SqlRow> findOneOrEmpty();
+
   /**
    * Set one of more positioned parameters.
    * <p>
@@ -312,7 +365,7 @@ public interface SqlQuery extends Serializable, FindableQuery<SqlQuery, SqlRow>
    *
    * @param <T> The type of the scalar values
    */
-  interface TypeQuery<T> extends FindableQuery<TypeQuery<T>, T> {
+  interface TypeQuery<T> {
 
     /**
      * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
@@ -320,38 +373,27 @@ public interface SqlQuery extends Serializable, FindableQuery<SqlQuery, SqlRow>
      *
      * @see SqlQuery#usingMaster(boolean)
      */
-    @Override
     TypeQuery<T> usingMaster(boolean useMaster);
 
     /**
      * Execute the query using the given transaction.
      */
-    @Override
     TypeQuery<T> usingTransaction(Transaction transaction);
 
-    /**
-     * Execute the query using the given connection.
-     */
-    @Override
-    TypeQuery<T> usingConnection(Connection connection);
-
     /**
      * Return the single value.
      */
     @Nullable
-    @Override
     T findOne();
 
     /**
      * Return the single value that is optional.
      */
-    @Override
     Optional<T> findOneOrEmpty();
 
     /**
      * Return the list of values.
      */
-    @Override
     List<T> findList();
 
     /**

ebean-api/src/main/java/io/ebean/SqlUpdate.java

@@ -158,15 +158,6 @@ public interface SqlUpdate {
    */
   int executeNow();
 
-  /**
-   * Set an explicit transaction to use to execute this statement.
-   * <p>
-   * When not set, {@link #execute()} and {@link #executeNow()} use whatever transaction
-   * is currently active on the thread (or auto-commit if none is active) - consistent
-   * with {@link Database#execute(SqlUpdate, Transaction)}.
-   */
-  SqlUpdate usingTransaction(Transaction transaction);
-
   /**
    * Execute when addBatch() has been used to batch multiple bind executions.
    *

ebean-api/src/main/java/io/ebean/StreamableQuery.java

@@ -1,101 +0,0 @@
-package io.ebean;
-
-import org.jspecify.annotations.NullMarked;
-
-import java.util.List;
-import java.util.function.Consumer;
-import java.util.function.Predicate;
-import java.util.stream.Stream;
-
-/**
- * A {@link FindableQuery} that additionally supports streaming results and paging.
- *
- * @param <SELF> The query type (used for method chaining)
- * @param <T>    The type of the result
- */
-@NullMarked
-public interface StreamableQuery<SELF extends StreamableQuery<SELF, T>, T> extends FindableQuery<SELF, T> {
-
-  /**
-   * Execute the query returning the result as a Stream.
-   * <p>
-   * Note that this can support very large queries iterating any number of results.
-   * To do so internally it can use multiple persistence contexts.
-   * <p>
-   * Note that the Stream holds resources related to the underlying resultSet and
-   * potentially connection and MUST be closed. We should use the Stream in a
-   * <em>try with resource block</em>.
-   * <pre>{@code
-   *
-   *  // use try with resources to ensure Stream is closed
-   *
-   *  try (Stream<T> stream = query.findStream()) {
-   *    stream
-   *    .map(...)
-   *    .collect(...);
-   *  }
-   *
-   * }</pre>
-   */
-  Stream<T> findStream();
-
-  /**
-   * Return a PagedList for this query using firstRow and maxRows.
-   * <p>
-   * The benefit of using this over findList() is that it provides functionality to get the
-   * total row count etc.
-   * <p>
-   * If maxRows is not set on the query prior to calling findPagedList() then a
-   * PersistenceException is thrown.
-   *
-   * @return The PagedList
-   */
-  PagedList<T> findPagedList();
-
-  /**
-   * Execute the query processing the results one at a time.
-   * <p>
-   * This method is appropriate to process very large query results as the results are
-   * consumed one at a time and do not need to be held in memory (unlike {@link #findList()}).
-   * <p>
-   * Note that internally Ebean can inform the JDBC driver that it is expecting a larger
-   * resultSet and specifically for MySQL this hint is required to stop its JDBC driver
-   * from buffering the entire resultSet. As such, for smaller resultSets findList() is
-   * generally preferable.
-   * <p>
-   * Compared with {@link #findEachWhile(Predicate)} this will always process all the results
-   * whereas findEachWhile() provides a way to stop processing the query result early before
-   * all the results have been read.
-   *
-   * @param consumer the consumer used to process the queried results.
-   */
-  void findEach(Consumer<T> consumer);
-
-  /**
-   * Execute findEach streaming query batching the results for consuming.
-   * <p>
-   * This query execution will stream the results and is suited to consuming
-   * large numbers of results from the database.
-   * <p>
-   * Typically, we use this batch consumer when we want to do further processing on
-   * the results and want to do that processing in batch form, for example - 100 at
-   * a time.
-   *
-   * @param batch    The number of results processed in the batch
-   * @param consumer Process the batch of results
-   */
-  void findEach(int batch, Consumer<List<T>> consumer);
-
-  /**
-   * Execute the query using callbacks to process the resulting results one at a time,
-   * with the ability to stop processing part way through.
-   * <p>
-   * Returning {@code false} after processing a result stops the iteration through the
-   * query results.
-   *
-   * @param consumer the consumer used to process the queried results, returning
-   *                 {@code false} to stop processing.
-   */
-  void findEachWhile(Predicate<T> consumer);
-
-}

ebean-api/src/main/java/io/ebean/Update.java

@@ -84,15 +84,6 @@ public interface Update<T> {
    */
   int execute();
 
-  /**
-   * Set an explicit transaction to use to execute this statement.
-   * <p>
-   * When not set, {@link #execute()} uses whatever transaction is currently active on
-   * the thread (or auto-commit if none is active) - consistent with
-   * {@link Database#execute(Update, Transaction)}.
-   */
-  Update<T> usingTransaction(Transaction transaction);
-
   /**
    * Set an ordered bind parameter.
    * <p>

ebean-api/src/main/java/io/ebean/config/DtoMapperRegister.java

@@ -1,31 +0,0 @@
-package io.ebean.config;
-
-import io.ebean.DtoMapper;
-
-/**
- * Loads and returns the {@link DtoMapper} to use for a given DTO type, generated per-module by
- * the querybean-generator annotation processor for each {@code io.ebean.annotation.DtoMapping}
- * registered pair.
- * <p>
- * Implementations resolve purely via literal {@code Class} comparisons (no reflection,
- * {@code Class.forName}, or {@code MethodHandles}) - safe under GraalVM native-image with zero
- * additional reachability metadata - mirroring {@link EntityClassRegister}.
- */
-public interface DtoMapperRegister {
-
-  /**
-   * Return the mapper for the given DTO type, or {@code null} if this register has no mapper for
-   * that type.
-   */
-  <SOURCE,TARGET> DtoMapper<SOURCE, TARGET> mapperFor(Class<SOURCE> sourceType, Class<TARGET> targetType);
-
-  /**
-   * Return the mapper instance of the given concrete generated mapper type, or {@code null} if
-   * this register has no mapper of that type.
-   * <p>
-   * An alternative to {@link #mapperFor(Class, Class)} for looking up a mapper by its own class
-   * (e.g. {@code CustomerDtoMapper.class}) rather than by its (source, target) pair - typically
-   * used to resolve a mapper instance for dependency injection into application code.
-   */
-  <T> T mapperOfType(Class<T> mapperType);
-}

ebean-api/src/main/java/io/ebean/config/dbplatform/DatabasePlatform.java

@@ -162,18 +162,6 @@ public class DatabasePlatform {
   protected boolean selectCountWithAlias;
   protected boolean selectCountWithColumnAlias;
 
-  /**
-   * Set true for platforms where {@code exists(...)} can only be used as a predicate
-   * and not as a directly selectable scalar boolean expression (e.g. SQL Server, Oracle).
-   */
-  protected boolean existsWithCaseWhen;
-
-  /**
-   * Clause appended after the {@code case when exists(...) then 1 else 0 end} exists query
-   * for platforms that require a FROM clause on every select (e.g. {@code from dual} on Oracle).
-   */
-  protected String existsFromClause = "";
-
   /**
    * If set then use the FORWARD ONLY hint when creating ResultSets for
    * findIterate() and findVisit().
@@ -672,21 +660,6 @@ public class DatabasePlatform {
     return selectCountWithColumnAlias;
   }
 
-  /**
-   * Return true if a scalar boolean {@code exists(...)} expression is not supported
-   * as a select expression and needs to be wrapped as {@code case when exists(...) then 1 else 0 end}.
-   */
-  public boolean existsWithCaseWhen() {
-    return existsWithCaseWhen;
-  }
-
-  /**
-   * Return the clause to append after the exists case-when wrapping (e.g. {@code from dual} on Oracle).
-   */
-  public String existsFromClause() {
-    return existsFromClause;
-  }
-
 
   public String completeSql(String sql, Query<?> query) {
     if (query.isForUpdate()) {

ebean-api/src/main/java/io/ebean/event/ShutdownManager.java

@@ -1,7 +1,6 @@
 package io.ebean.event;
 
 import io.ebean.Database;
-import io.ebean.DatabaseFactory;
 import io.ebean.EbeanVersion;
 import io.ebean.service.SpiContainer;
 
@@ -189,7 +188,6 @@ public final class ShutdownManager {
    */
   public static void unregisterDatabase(Database server) {
     databases.remove(server);
-    DatabaseFactory.unregister(server);
   }
 
   private static class ShutdownHook extends Thread {

ebean-bench/pom.xml

@@ -6,7 +6,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
   </parent>
 
   <artifactId>ebean-bench</artifactId>

ebean-bom/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
   </parent>
 
   <name>ebean bom</name>
@@ -89,25 +89,25 @@
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-api</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-core</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-core-type</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
@@ -125,13 +125,13 @@
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-jackson-mapper</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-ddl-generator</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
@@ -155,37 +155,37 @@
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-querybean</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>querybean-generator</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>kotlin-querybean-generator</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-test</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-redis</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-spring-txn</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <!-- platforms -->
@@ -193,91 +193,91 @@
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-clickhouse</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-db2</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-h2</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-hana</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-mariadb</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-mysql</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-nuodb</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-oracle</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-postgres</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-postgis</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-postgis-types</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-pgvector</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-pgvector-types</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-sqlite</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
       <dependency>
         <groupId>io.ebean</groupId>
         <artifactId>ebean-sqlserver</artifactId>
-        <version>18.3.0</version>
+        <version>18.2.0</version>
       </dependency>
 
     </dependencies>

ebean-core-json/pom.xml

@@ -3,7 +3,7 @@
   <parent>
     <groupId>io.ebean</groupId>
     <artifactId>ebean-parent</artifactId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
   </parent>
   <artifactId>ebean-core-json</artifactId>
   <name>ebean-core-json</name>
@@ -16,7 +16,7 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>

ebean-core-type/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
   </parent>
 
   <artifactId>ebean-core-type</artifactId>
@@ -16,7 +16,7 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -29,7 +29,7 @@
     <dependency>
       <groupId>org.postgresql</groupId>
       <artifactId>postgresql</artifactId>
-      <version>42.7.11</version>
+      <version>42.7.2</version>
       <optional>true</optional>
     </dependency>
 

ebean-core/pom.xml

@@ -3,7 +3,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>18.3.0</version>
+    <version>18.2.0</version>
   </parent>
 
   <artifactId>ebean-core</artifactId>
@@ -22,13 +22,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core-json</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -52,7 +52,7 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core-type</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
     </dependency>
 
     <dependency>
@@ -149,7 +149,7 @@
     <dependency>
       <groupId>org.postgresql</groupId>
       <artifactId>postgresql</artifactId>
-      <version>42.7.11</version>
+      <version>42.7.2</version>
       <optional>true</optional>
     </dependency>
 
@@ -157,21 +157,21 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-h2</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
       <scope>test</scope>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
       <scope>test</scope>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-sqlserver</artifactId>
-      <version>18.3.0</version>
+      <version>18.2.0</version>
       <scope>test</scope>
     </dependency>
 

ebean-core/src/main/java/io/ebeaninternal/api/SpiEbeanServer.java

@@ -294,16 +294,6 @@ public interface SpiEbeanServer extends SpiServer, BeanCollectionLoader {
    */
   <D> DtoQuery<D> findDto(Class<D> dtoType, SpiQuery<?> ormQuery);
 
-  /**
-   * Return the generated {@link DtoMapper} for mapping the given source entity type to the given
-   * DTO type, discovered (via {@code ServiceLoader}) from the {@code DtoMapperRegister}s
-   * generated by {@code querybean-generator} - used by {@code query.mapTo(dtoType)}.
-   *
-   * @throws jakarta.persistence.PersistenceException if no mapper is registered for that
-   *     (source, dto) pair.
-   */
-  <S, D> DtoMapper<S, D> dtoMapper(Class<S> sourceType, Class<D> dtoType);
-
   /**
    * Execute the underlying ORM query returning as a JDBC ResultSet to map to DTO beans.
    */
@@ -334,12 +324,6 @@ public interface SpiEbeanServer extends SpiServer, BeanCollectionLoader {
    */
   int executeNow(SpiSqlUpdate sqlUpdate);
 
-  /**
-   * Execute the sql update regardless of transaction batch mode using the given
-   * explicit transaction (or the current ambient transaction when null).
-   */
-  int executeNow(SpiSqlUpdate sqlUpdate, @Nullable Transaction transaction);
-
   /**
    * Create a query bind capture for the given query plan.
    */

ebean-core/src/main/java/io/ebeaninternal/api/SpiExpressionValidation.java

@@ -12,7 +12,6 @@ public final class SpiExpressionValidation {
 
   private final BeanType<?> desc;
   private final LinkedHashSet<String> unknown = new LinkedHashSet<>();
-  private final LinkedHashSet<String> all = new LinkedHashSet<>();
 
   public SpiExpressionValidation(BeanType<?> desc) {
     this.desc = desc;
@@ -22,7 +21,6 @@ public final class SpiExpressionValidation {
    * Validate that the property expression (path) is valid.
    */
   public void validate(String propertyName) {
-    all.add(propertyName);
     if (!desc.isValidExpression(propertyName)) {
       unknown.add(propertyName);
     }
@@ -35,14 +33,4 @@ public final class SpiExpressionValidation {
     return unknown;
   }
 
-  /**
-   * Return the set of all property names visited during this validation, regardless of
-   * whether they were considered valid against the bean type. Used to inspect the shape of
-   * an expression (for example, to check whether it references any associated/joined path)
-   * without needing a correctly-typed bean descriptor.
-   */
-  public Set<String> allProperties() {
-    return all;
-  }
-
 }

ebean-core/src/main/java/io/ebeaninternal/api/SpiQueryManyJoin.java

@@ -15,19 +15,4 @@ public interface SpiQueryManyJoin {
    */
   String fetchOrderBy();
 
-  /**
-   * Return true if this many relationship has an order column stored on the
-   * ManyToMany intersection table (rather than a target descriptor property).
-   */
-  default boolean hasIntersectionOrderColumn() {
-    return false;
-  }
-
-  /**
-   * Return the db column name of the ManyToMany intersection table order column (or null).
-   */
-  default String intersectionOrderColumn() {
-    return null;
-  }
-
 }

ebean-core/src/main/java/io/ebeaninternal/server/core/DefaultServer.java

@@ -90,7 +90,6 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
   private final DtoQueryEngine dtoQueryEngine;
   private final ServerCacheManager serverCacheManager;
   private final DtoBeanManager dtoBeanManager;
-  private final DtoMapperManager dtoMapperManager;
   private final BeanDescriptorManager descriptorManager;
   private final AutoTuneService autoTuneService;
   private final ReadAuditPrepare readAuditPrepare;
@@ -123,7 +122,6 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
   public DefaultServer(InternalConfiguration config, ServerCacheManager cache) {
     this.logManager = config.getLogManager();
     this.dtoBeanManager = config.getDtoBeanManager();
-    this.dtoMapperManager = config.getDtoMapperManager();
     this.config = config.getConfig();
     this.disableL2Cache = this.config.isDisableL2Cache();
     this.serverCacheManager = cache;
@@ -901,11 +899,6 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
     return new DefaultDtoQuery<>(this, descriptor, ormQuery);
   }
 
-  @Override
-  public <S, D> DtoMapper<S, D> dtoMapper(Class<S> sourceType, Class<D> dtoType) {
-    return dtoMapperManager.mapperFor(sourceType, dtoType);
-  }
-
   @Override
   public SpiResultSet findResultSet(SpiQuery<?> ormQuery) {
     SpiOrmQueryRequest<?> request = createQueryRequest(ormQuery.type(), ormQuery);
@@ -1249,6 +1242,9 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
   }
 
   private <T> int delete(SpiQuery<T> query, boolean permanent) {
+    if (query.getId() != null && query.whereExpressions() == null && query.descriptor().isSoftDelete()) {
+      return executeInTrans((txn) -> persister.delete(query.getBeanType(), query.getId(), txn, permanent), query.transaction());
+    }
     SpiOrmQueryRequest<T> request = createQueryRequest(Type.DELETE, query);
     try {
       request.initTransIfRequired();
@@ -1938,12 +1934,7 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
 
   @Override
   public int executeNow(SpiSqlUpdate sqlUpdate) {
-    return executeNow(sqlUpdate, null);
-  }
-
-  @Override
-  public int executeNow(SpiSqlUpdate sqlUpdate, @Nullable Transaction transaction) {
-    return persister.executeSqlUpdateNow(sqlUpdate, transaction);
+    return persister.executeSqlUpdateNow(sqlUpdate, null);
   }
 
   @Override
@@ -2208,7 +2199,12 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
   }
 
   @Override
-  public Set<Property> checkUniqueness(Object bean, @Nullable Transaction transaction, boolean useQueryCache, boolean skipClean) {
+  public Set<Property> checkUniqueness(Object bean) {
+    return checkUniqueness(bean, null);
+  }
+
+  @Override
+  public Set<Property> checkUniqueness(Object bean, @Nullable Transaction transaction) {
     EntityBean entityBean = checkEntityBean(bean);
     BeanDescriptor<?> beanDesc = descriptor(entityBean.getClass());
     BeanProperty idProperty = beanDesc.idProperty();
@@ -2220,15 +2216,14 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
     if (entityBean._ebean_getIntercept().isNew() && id != null) {
       // Primary Key is changeable only on new models - so skip check if we are not new
       SpiQuery<?> query = new DefaultOrmQuery<>(beanDesc, this, expressionFactory);
-      query.setUseQueryCache(useQueryCache);
       query.usingTransaction(transaction);
       query.setId(id);
-      if (exists(query)) {
+      if (findCount(query) > 0) {
         return Collections.singleton(idProperty);
       }
     }
     for (BeanProperty[] props : beanDesc.uniqueProps()) {
-      Set<Property> ret = checkUniqueness(entityBean, beanDesc, props, transaction, useQueryCache, skipClean);
+      Set<Property> ret = checkUniqueness(entityBean, beanDesc, props, transaction);
       if (ret != null) {
         return ret;
       }
@@ -2236,34 +2231,13 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
     return Collections.emptySet();
   }
 
-  /**
-   * Checks, if any property is dirty.
-   */
-  private boolean isAnyPropertyDirty(EntityBean entityBean, BeanProperty[] props) {
-    if (entityBean._ebean_getIntercept().isNew()) {
-      return true;
-    }
-    for (BeanProperty prop : props) {
-      if (entityBean._ebean_getIntercept().isDirtyProperty(prop.propertyIndex())) {
-        return true;
-      }
-    }
-    return false;
-  }
-
   /**
    * Returns a set of properties if saving the bean will violate the unique constraints (defined by given properties).
    */
   @Nullable
-  private Set<Property> checkUniqueness(EntityBean entityBean, BeanDescriptor<?> beanDesc, BeanProperty[] props, @Nullable Transaction transaction,
-                                        boolean useQueryCache, boolean skipClean) {
-    if (skipClean && !isAnyPropertyDirty(entityBean, props)) {
-      return null;
-    }
-
+  private Set<Property> checkUniqueness(EntityBean entityBean, BeanDescriptor<?> beanDesc, BeanProperty[] props, @Nullable Transaction transaction) {
     BeanProperty idProperty = beanDesc.idProperty();
     SpiQuery<?> query = new DefaultOrmQuery<>(beanDesc, this, expressionFactory);
-    query.setUseQueryCache(useQueryCache);
     query.usingTransaction(transaction);
     ExpressionList<?> exprList = query.where();
     if (!entityBean._ebean_getIntercept().isNew()) {
@@ -2277,7 +2251,7 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
       }
       exprList.eq(prop.name(), value);
     }
-    if (exists(query)) {
+    if (findCount(query) > 0) {
       Set<Property> ret = new LinkedHashSet<>();
       Collections.addAll(ret, props);
       return ret;

ebean-core/src/main/java/io/ebeaninternal/server/core/DefaultSqlUpdate.java

@@ -2,7 +2,6 @@ package io.ebeaninternal.server.core;
 
 import io.ebean.DB;
 import io.ebean.SqlUpdate;
-import io.ebean.Transaction;
 import io.ebean.Update;
 import io.ebeaninternal.api.BindParams;
 import io.ebeaninternal.api.SpiEbeanServer;
@@ -141,7 +140,7 @@ public final class DefaultSqlUpdate implements Serializable, SpiSqlUpdate {
         server.executeBatch(this, transaction);
         return -1;
       }
-      return server.execute(this, transaction);
+      return server.execute(this);
     } else {
       // Hopefully this doesn't catch anyone out...
       return DB.getDefault().execute(this);
@@ -151,18 +150,12 @@ public final class DefaultSqlUpdate implements Serializable, SpiSqlUpdate {
   @Override
   public int executeNow() {
     if (server != null) {
-      return server.executeNow(this, transaction);
+      return server.executeNow(this);
     } else {
       throw new IllegalStateException("server is null?");
     }
   }
 
-  @Override
-  public SqlUpdate usingTransaction(Transaction transaction) {
-    this.transaction = (SpiTransaction) transaction;
-    return this;
-  }
-
   @Override
   public int[] executeBatch() {
     if (server == null) {

ebean-core/src/main/java/io/ebeaninternal/server/core/InternalConfiguration.java

@@ -2,7 +2,6 @@ package io.ebeaninternal.server.core;
 
 import io.avaje.json.stream.JsonStream;
 import io.ebean.DatabaseBuilder;
-import io.ebean.DtoMapperManager;
 import io.ebean.ExpressionFactory;
 import io.ebean.annotation.Platform;
 import io.ebean.cache.*;
@@ -77,7 +76,6 @@ public final class InternalConfiguration {
   private final DeployInherit deployInherit;
   private final TypeManager typeManager;
   private final DtoBeanManager dtoBeanManager;
-  private final DtoMapperManager dtoMapperManager;
   private final Clock clock;
   private final DataTimeZone dataTimeZone;
   private final Binder binder;
@@ -127,7 +125,6 @@ public final class InternalConfiguration {
 
     final InternalConfigXmlMap xmlMap = initExternalMapping();
     this.dtoBeanManager = new DtoBeanManager(typeManager, xmlMap.readDtoMapping());
-    this.dtoMapperManager = initDtoMapperManager();
     this.dataSourceSupplier = createDataSourceSupplier();
     this.beanDescriptorManager = new BeanDescriptorManager(this);
     Map<String, String> asOfTableMapping = beanDescriptorManager.deploy(xmlMap.xmlDeployment());
@@ -156,17 +153,6 @@ public final class InternalConfiguration {
     }
   }
 
-  /**
-   * Use an application-provided {@link DtoMapperManager} (registered via {@code
-   * config.putServiceObject(DtoMapperManager.class, ...)} before building the Database) if
-   * present, so the exact same instance (and hence the same underlying mapper instances) can be
-   * shared between {@code query.mapTo(...)} and application code, otherwise construct a default.
-   */
-  private DtoMapperManager initDtoMapperManager() {
-    DtoMapperManager manager = config.getServiceObject(DtoMapperManager.class);
-    return manager != null ? manager : new DtoMapperManager();
-  }
-
   private List<XmapEbean> readExternalMapping() {
     final XmapService xmapService = service(XmapService.class);
     if (xmapService == null) {
@@ -534,10 +520,6 @@ public final class InternalConfiguration {
     return dtoBeanManager;
   }
 
-  DtoMapperManager getDtoMapperManager() {
-    return dtoMapperManager;
-  }
-
   SpiLogManager getLogManager() {
     return logManager;
   }

ebean-core/src/main/java/io/ebeaninternal/server/deploy/BeanDescriptor.java

@@ -43,8 +43,6 @@ import io.ebeaninternal.server.deploy.meta.DeployBeanDescriptor;
 import io.ebeaninternal.server.deploy.meta.DeployBeanPropertyLists;
 import io.ebeaninternal.server.el.*;
 import io.ebeaninternal.server.persist.DeleteMode;
-import io.ebeaninternal.server.persist.MultiValueWrapper;
-import io.ebeaninternal.server.type.ScalarTypeArray;
 import io.ebeaninternal.server.query.*;
 import io.ebeaninternal.server.querydefn.DefaultOrmQuery;
 import io.ebeaninternal.server.querydefn.OrmQueryDetail;
@@ -755,16 +753,7 @@ public class BeanDescriptor<T> implements BeanType<T>, STreeType, SpiBeanType {
   public void bindElementValue(SqlUpdate insert, Object value) {
     EntityBean bean = (EntityBean) value;
     for (BeanProperty property : propertiesBaseScalar) {
-      Object propertyValue = property.getValue(bean);
-      if (property.isArrayType() && propertyValue instanceof Collection) {
-        // Bind with the declared element type rather than relying on MultiValueWrapper's default
-        // constructor which infers the element type from the first value - this fails with a
-        // NoSuchElementException for an empty collection. See #2477.
-        Class<?> elementType = ((ScalarTypeArray) property.scalarType()).elementType();
-        insert.setParameter(new MultiValueWrapper((Collection<?>) propertyValue, elementType));
-      } else {
-        insert.setParameter(propertyValue);
-      }
+      insert.setParameter(property.getValue(bean));
     }
   }
 

ebean-core/src/main/java/io/ebeaninternal/server/deploy/BeanDescriptorCacheHelp.java

@@ -372,15 +372,14 @@ abstract class BeanDescriptorCacheHelp<T> {
    * Hit the bean cache with the given ids returning the hits.
    */
   BeanCacheResult<T> cacheIdLookup(PersistenceContext context, boolean unmodifiable, Collection<?> ids) {
+    Set<Object> keys = new HashSet<>(ids.size());
+    for (Object id : ids) {
+      keys.add(desc.cacheKey(id));
+    }
     if (ids.isEmpty()) {
       return new BeanCacheResult<>();
     }
-    // map cacheKey -> original id to support type coercion
-    Map<Object, Object> keyToOriginalId = new HashMap<>(ids.size());
-    for (Object id : ids) {
-      keyToOriginalId.put(desc.cacheKey(id), id);
-    }
-    Map<Object, Object> beanDataMap = beanCache().getAll(keyToOriginalId.keySet());
+    Map<Object, Object> beanDataMap = beanCache().getAll(keys);
     if (beanLog.isLoggable(TRACE)) {
       beanLog.log(TRACE, "   MGET {0}({1}) - hits:{2}", cacheName, ids, beanDataMap.keySet());
     }
@@ -388,8 +387,7 @@ abstract class BeanDescriptorCacheHelp<T> {
     for (Map.Entry<Object, Object> entry : beanDataMap.entrySet()) {
       CachedBeanData cachedBeanData = (CachedBeanData) entry.getValue();
       T bean = convertToBean(entry.getKey(), unmodifiable, context, cachedBeanData);
-      Object originalId = keyToOriginalId.get(entry.getKey());
-      result.add(bean, originalId != null ? originalId : desc.id(bean));
+      result.add(bean, desc.id(bean));
     }
     return result;
   }

ebean-core/src/main/java/io/ebeaninternal/server/deploy/BeanDescriptorManager.java

@@ -907,18 +907,8 @@ public final class BeanDescriptorManager implements BeanDescriptorMap, SpiBeanTy
   }
 
   private void makeOrderColumn(DeployBeanPropertyAssocMany<?> oneToMany) {
-    makeOrderColumn(oneToMany, targetDescriptor(oneToMany));
-  }
-
-  /**
-   * Create and assign the synthetic order column property onto the given target descriptor.
-   * <p>
-   * Used for both {@code @OneToMany} (targetDesc looked up via the target entity type) and
-   * {@code @ElementCollection} (targetDesc is the synthetic element descriptor which is not
-   * registered in {@code deployInfoMap} and so must be passed in directly).
-   */
-  public void makeOrderColumn(DeployBeanPropertyAssocMany<?> many, DeployBeanDescriptor<?> targetDesc) {
-    DeployOrderColumn orderColumn = many.getOrderColumn();
+    DeployBeanDescriptor<?> targetDesc = targetDescriptor(oneToMany);
+    DeployOrderColumn orderColumn = oneToMany.getOrderColumn();
     final ScalarType<?> scalarType = typeManager.type(Integer.class);
     DeployBeanProperty orderProperty = new DeployBeanProperty(targetDesc, Integer.class, scalarType, null);
     orderProperty.setName(DeployOrderColumn.LOGICAL_NAME);

ebean-core/src/main/java/io/ebeaninternal/server/deploy/BeanProperty.java

@@ -671,35 +671,6 @@ public class BeanProperty implements ElPropertyValue, Property, STreeProperty {
     setValue(entityBean, tenantId);
   }
 
-  /**
-   * By default, getIntercept and setIntercept will check if the passed bean is an instance of the descriptor type.
-   * <p>
-   * If the property is not part of the type hierarchy (i.e. is not this property from this descriptor) an
-   * IllegalArgumentException is thrown.
-   * <p>
-   * If inheritance is involved, this method returns false instead of throwing an exception, if the property might
-   * exist on one of the sibling child beans. This is necessary for getIntercept, as it returns <code>null</code>
-   * in this case.
-   *
-   * @return true if the property can be accessed on the given bean, false if it should be treated as unloaded.
-   */
-  private boolean checkPropertyAccess(EntityBean bean) {
-    if (bean == null || descriptor.type().isInstance(bean)) { // null = fall through - NPE is caught later.
-      return true;
-    }
-    InheritInfo inheritInfo = descriptor.inheritInfo();
-    if (inheritInfo == null || inheritInfo.isRoot() || !inheritInfo.getRoot().getType().isInstance(bean)) {
-      throw new IllegalArgumentException(propertyIncompatibleMsg(bean));
-    } else {
-      return false;
-    }
-  }
-
-  private String propertyIncompatibleMsg(EntityBean bean) {
-    String beanType = bean == null ? "null" : bean.getClass().getName();
-    return "Property " + name + " on [" + descriptor + "] is incompatible with type[" + beanType + "]";
-  }
-
   /**
    * Set the value of the property without interception or
    * PropertyChangeSupport.
@@ -716,9 +687,6 @@ public class BeanProperty implements ElPropertyValue, Property, STreeProperty {
    * Set the value of the property.
    */
   public void setValueIntercept(EntityBean bean, Object value) {
-    if (!checkPropertyAccess(bean)) {
-      throw new IllegalArgumentException(propertyIncompatibleMsg(bean));
-    }
     try {
       setter.setIntercept(bean, value);
     } catch (Exception ex) {
@@ -830,9 +798,6 @@ public class BeanProperty implements ElPropertyValue, Property, STreeProperty {
   }
 
   public Object getValueIntercept(EntityBean bean) {
-    if (!checkPropertyAccess(bean)) {
-      return null;
-    }
     try {
       return getter.getIntercept(bean);
     } catch (Exception ex) {

ebean-core/src/main/java/io/ebeaninternal/server/deploy/BeanPropertyAssocMany.java

@@ -57,12 +57,6 @@ public class BeanPropertyAssocMany<T> extends BeanPropertyAssoc<T> implements ST
    * Flag to indicate that the target has a order column to auto populate.
    */
   private final boolean hasOrderColumn;
-  /**
-   * For ManyToMany, the db column name of the order column stored on the intersection
-   * table (null for OneToMany/ElementCollection which use a target descriptor property instead).
-   */
-  private final String intersectionOrderColumn;
-  private final boolean intersectionOrderColumnNullable;
   /**
    * Flag to indicate manyToMany relationship.
    */
@@ -101,8 +95,6 @@ public class BeanPropertyAssocMany<T> extends BeanPropertyAssoc<T> implements ST
     this.o2mJoinTable = deploy.isO2mJoinTable();
     this.hasOrderColumn = deploy.hasOrderColumn();
     this.manyToMany = deploy.isManyToMany();
-    this.intersectionOrderColumn = (manyToMany && hasOrderColumn) ? deploy.getOrderColumn().getName() : null;
-    this.intersectionOrderColumnNullable = (manyToMany && hasOrderColumn) && deploy.getOrderColumn().isNullable();
     this.elementCollection = deploy.isElementCollection();
     this.elementDescriptor = deploy.getElementDescriptor();
     this.manyType = deploy.getManyType();
@@ -162,9 +154,6 @@ public class BeanPropertyAssocMany<T> extends BeanPropertyAssoc<T> implements ST
         embeddedExportedProperties = exportedProperties[0].isEmbedded();
         if (fetchOrderBy != null) {
           lazyFetchOrderBy = sqlHelp.lazyFetchOrderBy(fetchOrderBy);
-        } else if (intersectionOrderColumn != null) {
-          // ManyToMany @OrderColumn - the intersection table is always aliased "int_"
-          lazyFetchOrderBy = sqlHelp.lazyFetchOrderBy("int_." + intersectionOrderColumn);
         }
       }
     }
@@ -522,29 +511,6 @@ public class BeanPropertyAssocMany<T> extends BeanPropertyAssoc<T> implements ST
     return hasOrderColumn;
   }
 
-  /**
-   * Return true if this is a ManyToMany with an order column stored on the intersection table.
-   */
-  @Override
-  public boolean hasIntersectionOrderColumn() {
-    return intersectionOrderColumn != null;
-  }
-
-  /**
-   * Return the db column name of the ManyToMany intersection table order column (or null).
-   */
-  @Override
-  public String intersectionOrderColumn() {
-    return intersectionOrderColumn;
-  }
-
-  /**
-   * Return true if the intersection table order column is nullable.
-   */
-  public boolean isIntersectionOrderColumnNullable() {
-    return intersectionOrderColumnNullable;
-  }
-
   public boolean isOrphanRemoval() {
     return orphanRemoval;
   }

ebean-core/src/main/java/io/ebeaninternal/server/deploy/DbSqlContext.java

@@ -181,11 +181,4 @@ public interface DbSqlContext {
    * Include the filter many predicates if specified into the JOIN clause.
    */
   void includeFilterMany();
-
-  /**
-   * Return true if the given fetch path (relative to the query root) is the exact join clause
-   * that the pending filterMany predicate must be attached to - i.e. the deepest path the
-   * filterMany expression itself references.
-   */
-  boolean isFilterManyAttachPoint(String prefix);
 }

ebean-core/src/main/java/io/ebeaninternal/server/deploy/id/IdBinderSimple.java

@@ -234,10 +234,6 @@ public final class IdBinderSimple implements IdBinder {
   @Override
   public Object convertId(Object idValue) {
     if (!idValue.getClass().equals(expectedType)) {
-      if (idValue instanceof String) {
-        // for cacheKey() formatted values
-        return scalarType.parse((String) idValue);
-      }
       return scalarType.toBeanType(idValue);
     }
     return idValue;

ebean-core/src/main/java/io/ebeaninternal/server/deploy/parse/AnnotationAssocManys.java

@@ -89,11 +89,6 @@ final class AnnotationAssocManys extends AnnotationAssoc {
     ManyToMany manyToMany = get(prop, ManyToMany.class);
     if (manyToMany != null) {
       readToMany(manyToMany, prop);
-      OrderColumn orderColumn = get(prop, OrderColumn.class);
-      if (orderColumn != null) {
-        // ManyToMany order value is stored on the intersection table (not the target bean)
-        prop.setOrderColumn(new DeployOrderColumn(orderColumn));
-      }
     }
     ElementCollection elementCollection = get(prop, ElementCollection.class);
     if (elementCollection != null) {
@@ -182,11 +177,6 @@ final class AnnotationAssocManys extends AnnotationAssoc {
     if (!elementCollection.targetClass().equals(void.class)) {
       prop.setTargetType(elementCollection.targetClass());
     }
-    OrderColumn orderColumn = get(prop, OrderColumn.class);
-    if (orderColumn != null) {
-      prop.setOrderColumn(new DeployOrderColumn(orderColumn));
-      prop.setFetchOrderBy(DeployOrderColumn.LOGICAL_NAME);
-    }
     Column column = prop.getMetaAnnotation(Column.class);
     if (column != null) {
       prop.setDbColumn(column.name());
@@ -278,11 +268,6 @@ final class AnnotationAssocManys extends AnnotationAssoc {
 
     elementDescriptor.setName(prop.toString());
     factory.createUnidirectional(elementDescriptor, prop.getOwningType(), beanTable, prop.getTableJoin());
-    if (prop.hasOrderColumn()) {
-      // create the synthetic order property on the element descriptor - the element descriptor
-      // is not registered in deployInfoMap so this can't go through the usual OneToMany path
-      factory.makeOrderColumn(prop, elementDescriptor);
-    }
     prop.setElementDescriptor(factory.createElementDescriptor(elementDescriptor, prop.getManyType(), scalar));
   }
 

ebean-core/src/main/java/io/ebeaninternal/server/el/ElPropertyDeploy.java

@@ -91,16 +91,4 @@ public interface ElPropertyDeploy extends SpiQueryManyJoin {
   default String fetchOrderBy() {
     return beanProperty().fetchOrderBy();
   }
-
-  @Override
-  default boolean hasIntersectionOrderColumn() {
-    BeanProperty prop = beanProperty();
-    return prop instanceof io.ebeaninternal.server.deploy.BeanPropertyAssocMany
-      && prop.hasIntersectionOrderColumn();
-  }
-
-  @Override
-  default String intersectionOrderColumn() {
-    return beanProperty().intersectionOrderColumn();
-  }
 }

ebean-core/src/main/java/io/ebeaninternal/server/expression/DefaultExpressionList.java

@@ -254,27 +254,17 @@ public class DefaultExpressionList<T> implements SpiExpressionList<T> {
 
   @Override
   public Query<T> asOf(Timestamp asOf) {
-    return query().asOf(asOf);
+    return query.asOf(asOf);
   }
 
   @Override
   public Query<T> asDraft() {
-    return query().asDraft();
+    return query.asDraft();
   }
 
   @Override
   public <D> DtoQuery<D> asDto(Class<D> dtoClass) {
-    return query().asDto(dtoClass);
-  }
-
-  @Override
-  public <D> MappedQuery<D> mapTo(Class<D> dtoType) {
-    return query().mapTo(dtoType);
-  }
-
-  @Override
-  public <D> MappedQuery<D> mapTo(Class<D> dtoType, DtoMapper<T, D> mapper) {
-    return query().mapTo(dtoType, mapper);
+    return query.asDto(dtoClass);
   }
 
   @Override
@@ -1335,24 +1325,6 @@ public class DefaultExpressionList<T> implements SpiExpressionList<T> {
     return null;
   }
 
-  /**
-   * Return a "propertyName: value" description when this expression list is a single
-   * simple equality predicate (a candidate natural/unique key), otherwise null.
-   * <p>
-   * Used to build a decent default message for {@code findOneOrThrow()} when the query
-   * isn't a simple find-by-id.
-   */
-  @Nullable
-  public String singleEqDescription() {
-    if (list.size() == 1 && list.get(0) instanceof SimpleExpression) {
-      SimpleExpression simple = (SimpleExpression) list.get(0);
-      if (simple.isOpEquals()) {
-        return simple.getPropName() + ": " + simple.getValue();
-      }
-    }
-    return null;
-  }
-
   @Override
   public ExpressionList<T> clear() {
     list.clear();

ebean-core/src/main/java/io/ebeaninternal/server/expression/JunctionExpression.java

@@ -367,16 +367,6 @@ final class JunctionExpression<T> implements SpiJunction<T>, SpiExpression, Expr
     return exprList.asDto(dtoClass);
   }
 
-  @Override
-  public <D> MappedQuery<D> mapTo(Class<D> dtoType) {
-    return exprList.mapTo(dtoType);
-  }
-
-  @Override
-  public <D> MappedQuery<D> mapTo(Class<D> dtoType, DtoMapper<T, D> mapper) {
-    return exprList.mapTo(dtoType, mapper);
-  }
-
   @Override
   public UpdateQuery<T> asUpdate() {
     return exprList.asUpdate();

ebean-core/src/main/java/io/ebeaninternal/server/persist/SaveManyBeans.java

@@ -256,12 +256,6 @@ final class SaveManyBeans extends SaveManyBase {
   }
 
   private void saveAssocManyIntersection(boolean queue) {
-    if (many.hasIntersectionOrderColumn()) {
-      // With @OrderColumn the position of every row can change on any add/remove/reorder so
-      // we always delete all intersection rows and reinsert them in the current list order.
-      saveAssocManyIntersectionOrdered(queue);
-      return;
-    }
     final boolean vanillaCollection = !(value instanceof BeanCollection<?>);
     if (vanillaCollection || forcedUpdate) {
       // delete all intersection rows and then treat all
@@ -346,53 +340,6 @@ final class SaveManyBeans extends SaveManyBase {
     transaction.depth(-1);
   }
 
-  /**
-   * Save the ManyToMany intersection rows for a property with an {@code @OrderColumn}.
-   * <p>
-   * Unlike the standard diff based save (additions/removals), this always deletes all existing
-   * intersection rows for the parent and reinserts every current entry in list order, binding
-   * the sequential order index. This is required because a pure reorder (no add/remove) would
-   * not otherwise be detected/persisted, and there is no per-row place (unlike OneToMany/
-   * ElementCollection) to compare an existing 'loaded' order against - the order value lives on
-   * the intersection row, not on the target bean.
-   */
-  private void saveAssocManyIntersectionOrdered(boolean queue) {
-    if (value == null) {
-      return;
-    }
-    Collection<?> current;
-    if (value instanceof Map<?, ?>) {
-      current = ((Map<?, ?>) value).values();
-    } else if (value instanceof Collection<?>) {
-      current = (Collection<?>) value;
-    } else {
-      throw new PersistenceException("Unhandled ManyToMany type " + value.getClass().getName() + " for " + many.fullName());
-    }
-    if (value instanceof BeanCollection<?>) {
-      BeanCollection<?> manyValue = (BeanCollection<?>) value;
-      setListenMode(manyValue, many);
-      manyValue.modifyReset();
-    }
-    if (!insertedParent) {
-      request.preManyToManyUpdate();
-      persister.deleteManyIntersection(parentBean, many, transaction, publish, queue);
-    }
-    String orderColumn = many.intersectionOrderColumn();
-    transaction.depth(+1);
-    int position = 0;
-    for (Object other : current) {
-      EntityBean otherBean = (EntityBean) other;
-      if (!many.hasImportedId(otherBean)) {
-        throw new PersistenceException("ManyToMany bean does not have an Id value? " + otherBean);
-      }
-      IntersectionRow intRow = many.buildManyToManyMapBean(parentBean, otherBean, publish);
-      intRow.put(orderColumn, position++);
-      SpiSqlUpdate sqlInsert = intRow.createInsert(server);
-      persister.executeOrQueue(sqlInsert, transaction, queue, BatchControl.INSERT_QUEUE);
-    }
-    transaction.depth(-1);
-  }
-
   private boolean isChangedProperty() {
     return request.isChangedProperty(many.propertyIndex());
   }

ebean-core/src/main/java/io/ebeaninternal/server/persist/SaveManyElementCollection.java

@@ -44,15 +44,10 @@ final class SaveManyElementCollection extends SaveManyBase {
   private void saveCollection() {
     SpiSqlUpdate proto = many.insertElementCollection();
     Object parentId = request.beanId();
-    boolean hasOrderColumn = many.hasOrderColumn();
-    int position = 0;
     for (Object value : collection) {
       final SpiSqlUpdate sqlInsert = proto.copy();
       sqlInsert.setParameter(parentId);
       many.bindElementValue(sqlInsert, value);
-      if (hasOrderColumn) {
-        sqlInsert.setParameter(position++);
-      }
       persister.addToFlushQueue(sqlInsert, transaction, BatchControl.INSERT_QUEUE);
     }
     resetModifyState();

ebean-core/src/main/java/io/ebeaninternal/server/persist/dml/InsertMetaOptionsPostgres.java

@@ -4,9 +4,11 @@ import io.ebean.InsertOptions;
 import io.ebeaninternal.server.deploy.BeanDescriptor;
 import io.ebeaninternal.server.deploy.BeanProperty;
 
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.stream.Collectors;
 
 /**
  * Postgres specific generation of insert on conflict.
@@ -16,14 +18,12 @@ final class InsertMetaOptionsPostgres implements InsertMetaOptions {
   private final InsertMeta meta;
   private final BeanDescriptor<?> desc;
   private final String baseTable;
-  private final List<String> nonUpdatableColumns;
   private final Map<String, String> sqlCache = new ConcurrentHashMap<>();
 
   InsertMetaOptionsPostgres(InsertMeta meta, BeanDescriptor<?> desc) {
     this.meta = meta;
     this.desc = desc;
     this.baseTable = desc.baseTable();
-    this.nonUpdatableColumns = InsertMetaOptionsSupport.nonUpdatableColumns(desc);
   }
 
   @Override
@@ -49,7 +49,10 @@ final class InsertMetaOptionsPostgres implements InsertMetaOptions {
     meta.sql(request, !withId, baseTable, false);
     request.append(" on conflict ");
 
-    List<String> uniqueColumns = InsertMetaOptionsSupport.uniqueColumns(desc, withId);
+    List<String> uniqueColumns = desc.uniqueProps().stream()
+      .flatMap(Arrays::stream)
+      .map(BeanProperty::dbColumn)
+      .collect(Collectors.toList());
 
     String constraintName = options.constraint();
     if (constraintName != null) {
@@ -81,7 +84,6 @@ final class InsertMetaOptionsPostgres implements InsertMetaOptions {
   private void setColumns(boolean withId, GenerateDmlRequest request, List<String> uniqueColumns) {
     List<String> columns = request.columns();
     columns.removeAll(uniqueColumns);
-    columns.removeAll(nonUpdatableColumns);
     if (withId) {
       BeanProperty idProperty = desc.idProperty();
       if (idProperty != null && !idProperty.isEmbedded()) {

ebean-core/src/main/java/io/ebeaninternal/server/persist/dml/InsertMetaOptionsSqlite.java

@@ -4,9 +4,11 @@ import io.ebean.InsertOptions;
 import io.ebeaninternal.server.deploy.BeanDescriptor;
 import io.ebeaninternal.server.deploy.BeanProperty;
 
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.stream.Collectors;
 
 /**
  * SQLite specific generation of insert on conflict.
@@ -19,14 +21,12 @@ final class InsertMetaOptionsSqlite implements InsertMetaOptions {
   private final InsertMeta meta;
   private final BeanDescriptor<?> desc;
   private final String baseTable;
-  private final List<String> nonUpdatableColumns;
   private final Map<String, String> sqlCache = new ConcurrentHashMap<>();
 
   InsertMetaOptionsSqlite(InsertMeta meta, BeanDescriptor<?> desc) {
     this.meta = meta;
     this.desc = desc;
     this.baseTable = desc.baseTable();
-    this.nonUpdatableColumns = InsertMetaOptionsSupport.nonUpdatableColumns(desc);
   }
 
   @Override
@@ -55,7 +55,10 @@ final class InsertMetaOptionsSqlite implements InsertMetaOptions {
     meta.sql(request, !withId, baseTable, false);
     request.append(" on conflict (");
 
-    List<String> uniqueColumns = InsertMetaOptionsSupport.uniqueColumns(desc, withId);
+    List<String> uniqueColumns = desc.uniqueProps().stream()
+      .flatMap(Arrays::stream)
+      .map(BeanProperty::dbColumn)
+      .collect(Collectors.toList());
 
     String cols = options.uniqueColumns();
     if (cols != null) {
@@ -82,7 +85,6 @@ final class InsertMetaOptionsSqlite implements InsertMetaOptions {
   private void setColumns(boolean withId, GenerateDmlRequest request, List<String> uniqueColumns) {
     List<String> columns = request.columns();
     columns.removeAll(uniqueColumns);
-    columns.removeAll(nonUpdatableColumns);
     if (withId) {
       BeanProperty idProperty = desc.idProperty();
       if (idProperty != null && !idProperty.isEmbedded()) {

ebean-core/src/main/java/io/ebeaninternal/server/persist/dml/InsertMetaOptionsSupport.java

@@ -1,75 +0,0 @@
-package io.ebeaninternal.server.persist.dml;
-
-import io.ebeaninternal.server.deploy.BeanDescriptor;
-import io.ebeaninternal.server.deploy.BeanProperty;
-import io.ebeaninternal.server.deploy.BeanPropertyAssocOne;
-import io.ebeaninternal.server.deploy.generatedproperty.GeneratedProperty;
-
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.List;
-import java.util.stream.Collectors;
-
-/**
- * Shared support for the platform specific insert on conflict do update generation.
- */
-final class InsertMetaOptionsSupport {
-
-  private InsertMetaOptionsSupport() {
-  }
-
-  /**
-   * Return the columns to use as the on conflict target.
-   * <p>
-   * Uses columns explicitly mapped as unique via {@code @Column(unique=true)} or
-   * {@code @Index(unique=true)}. When there are none of those, falls back to the primary
-   * key column(s) given the primary key constraint is inherently unique. This fallback only
-   * applies when the id value is included in the insert (withId) as an insert relying on a
-   * database generated id (identity/sequence) is never going to naturally conflict on that id.
-   */
-  static List<String> uniqueColumns(BeanDescriptor<?> desc, boolean withId) {
-    List<String> uniqueColumns = desc.uniqueProps().stream()
-      .flatMap(Arrays::stream)
-      .map(BeanProperty::dbColumn)
-      .collect(Collectors.toList());
-    if (uniqueColumns.isEmpty() && withId) {
-      uniqueColumns = idColumns(desc);
-    }
-    return uniqueColumns;
-  }
-
-  private static List<String> idColumns(BeanDescriptor<?> desc) {
-    BeanProperty idProperty = desc.idProperty();
-    if (idProperty == null) {
-      return List.of();
-    }
-    if (idProperty.isEmbedded() && idProperty instanceof BeanPropertyAssocOne) {
-      List<String> columns = new ArrayList<>();
-      for (BeanProperty embedded : ((BeanPropertyAssocOne<?>) idProperty).properties()) {
-        columns.add(embedded.dbColumn());
-      }
-      return columns;
-    }
-    return List.of(idProperty.dbColumn());
-  }
-
-  /**
-   * Return the columns that should be excluded from the generated "do update set" clause
-   * as they are not updatable, e.g. {@code @Column(updatable=false)} or a generated property
-   * that is insert only such as {@code @WhenCreated}/{@code @WhoCreated}.
-   */
-  static List<String> nonUpdatableColumns(BeanDescriptor<?> desc) {
-    List<String> columns = new ArrayList<>();
-    for (BeanProperty prop : desc.propertiesNonTransient()) {
-      if (!prop.isDbUpdatable() || isInsertOnlyGenerated(prop)) {
-        columns.add(prop.dbColumn());
-      }
-    }
-    return columns;
-  }
-
-  private static boolean isInsertOnlyGenerated(BeanProperty prop) {
-    GeneratedProperty gen = prop.generatedProperty();
-    return gen != null && gen.includeInInsert() && !gen.includeInUpdate();
-  }
-}

ebean-core/src/main/java/io/ebeaninternal/server/persist/dmlbind/BindableIdEmbedded.java

@@ -60,10 +60,6 @@ final class BindableIdEmbedded implements BindableId {
   @Override
   public void dmlBind(BindableRequest request, EntityBean bean) throws SQLException {
     EntityBean idValue = (EntityBean) embId.getValue(bean);
-    if (idValue == null && matches != null) {
-      // The id (e.g. IdClass) hasn't been derived/cached on this bean yet
-      idValue = deriveId(bean);
-    }
     for (BeanProperty prop : props) {
       Object value = prop.getValue(idValue);
       request.bind(value, prop);
@@ -87,21 +83,13 @@ final class BindableIdEmbedded implements BindableId {
 
   @Override
   public boolean deriveConcatenatedId(PersistRequestBean<?> persist) {
-    deriveId(persist.entityBean());
-    return true;
-  }
-
-  /**
-   * Derive/build the concatenated id (e.g. IdClass) from the entity's own matching id
-   * properties, caching it on the bean (via setValueIntercept) for subsequent use.
-   */
-  private EntityBean deriveId(EntityBean bean) {
     if (matches == null) {
       String m = "No matches for " + embId.fullName() + " the concatenated key columns where not found?"
         + " I expect that the concatenated key was null, and this bean does"
         + " not have ManyToOne assoc beans matching the primary key columns?";
       throw new PersistenceException(m);
     }
+    EntityBean bean = persist.entityBean();
     // create the new id
     EntityBean newId = (EntityBean) embId.createEmbeddedId();
     // populate it from the assoc one id values...
@@ -109,7 +97,7 @@ final class BindableIdEmbedded implements BindableId {
       match.populate(bean, newId);
     }
     embId.setValueIntercept(bean, newId);
-    return newId;
+    return true;
   }
 
 }

ebean-core/src/main/java/io/ebeaninternal/server/query/CQueryBuilder.java

@@ -321,46 +321,6 @@ final class CQueryBuilder {
     return lastFound;
   }
 
-  /**
-   * Find the index of the top-level (non-nested) "select" keyword in sql. Used to detect if sql
-   * starts with a WITH clause (CTE) header - SQL Server does not support a WITH clause nested
-   * inside a subquery/derived table, so it must be hoisted in front of a wrapping SELECT
-   * (count/exists) rather than wrapped along with the rest of the query.
-   * <p>
-   * Returns 0 if there is no leading WITH clause (sql starts directly with SELECT), or -1 if no
-   * top-level SELECT is found at all.
-   */
-  static int topLevelSelectStart(String sql) {
-    int depth = 0;
-    int len = sql.length();
-    for (int i = 0; i < len; i++) {
-      char c = sql.charAt(i);
-      if (c == '(') {
-        depth++;
-      } else if (c == ')') {
-        depth--;
-      } else if (depth == 0 && sql.regionMatches(true, i, "select", 0, 6)
-        && (i == 0 || !Character.isLetterOrDigit(sql.charAt(i - 1)))
-        && (i + 6 == len || !Character.isLetterOrDigit(sql.charAt(i + 6)))) {
-        return i;
-      }
-    }
-    return -1;
-  }
-
-  /**
-   * Split off a leading WITH clause (CTE header) from sql, returning {@code {header, body}} so the
-   * header can be hoisted in front of a wrapping SELECT. Returns an empty header (unchanged sql as
-   * the body) when there is no leading WITH clause.
-   */
-  static String[] splitCteHeader(String sql) {
-    int pos = topLevelSelectStart(sql);
-    if (pos <= 0) {
-      return new String[]{"", sql};
-    }
-    return new String[]{sql.substring(0, pos), sql.substring(pos)};
-  }
-
   static String inlineSqlCommentLabel(String label, ProfileLocation profileLocation, boolean secondary, String simpleName) {
     if (label != null) {
       return secondary ? label : CQueryPlan.planLabelWithType(label, simpleName);
@@ -369,22 +329,15 @@ final class CQueryBuilder {
   }
 
   private String wrapSelectCount(String sql) {
-    String[] parts = splitCteHeader(sql);
-    sql = parts[0] + "select count(*) from ( " + parts[1] + ")";
+    sql = "select count(*) from ( " + sql + ")";
     if (selectCountWithAlias) {
       sql += " as c";
     }
     return sql;
   }
 
-  static String wrapSelectExists(String sql, boolean existsWithCaseWhen, String existsFromClause) {
-    String[] parts = splitCteHeader(sql);
-    String header = parts[0];
-    String body = parts[1];
-    if (existsWithCaseWhen) {
-      return header + "select case when exists(" + body + ") then 1 else 0 end" + existsFromClause;
-    }
-    return header + "select exists(" + body + ")";
+  private String wrapSelectExists(String sql) {
+    return "select exists(" + sql + ")";
   }
 
   /**
@@ -413,7 +366,7 @@ final class CQueryBuilder {
     }
 
     SqlLimitResponse s = buildSql("select 1", request, predicates, sqlTree);
-    String sql = wrapSelectExists(s.getSql(), dbPlatform.existsWithCaseWhen(), dbPlatform.existsFromClause());
+    String sql = wrapSelectExists(s.getSql());
 
     queryPlan = new CQueryPlan(request, sql, sqlTree.plan(), predicates.logWhereSql());
     request.putQueryPlan(queryPlan);

ebean-core/src/main/java/io/ebeaninternal/server/query/CQueryPredicates.java

@@ -33,13 +33,6 @@ import static java.lang.System.Logger.Level.WARNING;
  */
 public final class CQueryPredicates {
 
-  /**
-   * Default lower bound used for findVersions() (no explicit start/end) on sql2011
-   * standards based platforms that require actual bind values for the root table's
-   * 'for system_time between ? and ?' clause.
-   */
-  private static final Timestamp EPOCH = Timestamp.valueOf("1970-01-01 00:00:00");
-
   private final Binder binder;
   private final OrmQueryRequest<?> request;
   private final SpiQuery<?> query;
@@ -67,22 +60,11 @@ public final class CQueryPredicates {
   private String dbOrderBy;
   private String dbDistinctOn;
   private String dbUpdateClause;
-  /**
-   * Set when the many join is a ManyToMany with an intersection table order column - used to
-   * resolve the literal "${path}dbColumn" marker appended to dbOrderBy in parseTableAlias().
-   */
-  private String intersectionOrderPath;
-  private String intersectionOrderColumn;
   /**
    * Includes from where and order by clauses.
    */
   private Set<String> predicateIncludes;
   private Set<String> orderByIncludes;
-  /**
-   * The fetch path (relative to the query root) of the many-root whose own join clause the
-   * filterMany-in-JOIN predicate is attached to
-   */
-  private String filterManyAttachPath;
 
   CQueryPredicates(Binder binder, OrmQueryRequest<?> request) {
     this.binder = binder;
@@ -102,16 +84,10 @@ public final class CQueryPredicates {
       // bind the update set clause
       updateProperties.bind(binder, dataBind);
     }
-    if (binder.isAsOfStandardsBased() && query.temporalMode() == SpiQuery.TemporalMode.VERSIONS) {
+    if (query.isVersionsBetween() && binder.isAsOfStandardsBased()) {
       // sql2011 based versions between timestamp syntax
       Timestamp start = query.versionStart();
       Timestamp end = query.versionEnd();
-      if (start == null) {
-        start = EPOCH;
-      }
-      if (end == null) {
-        end = new Timestamp(System.currentTimeMillis());
-      }
       dataBind.append("between ").append(start).append(" and ").append(end);
       binder.bindObject(dataBind, start);
       binder.bindObject(dataBind, end);
@@ -227,8 +203,6 @@ public final class CQueryPredicates {
           filterMany = new DefaultExpressionRequest(request, deployParser, binder, filterManyExpr);
           if (buildSql) {
             dbFilterMany = filterMany.buildSql();
-            // safe as filterManyJoin only holds when the expression is root-property only -
-            filterManyAttachPath = manyProperty.path();
           }
         }
       }
@@ -265,14 +239,6 @@ public final class CQueryPredicates {
       dbHaving = alias.parseWhere(dbHaving);
     }
     if (dbOrderBy != null) {
-      if (intersectionOrderColumn != null) {
-        // resolve the ManyToMany intersection table order column BEFORE the generic
-        // alias substitution runs, as it needs the "z_" suffixed intersection alias
-        // rather than the plain target table alias.
-        String marker = "${" + intersectionOrderPath + "}" + intersectionOrderColumn;
-        String targetAlias = alias.tableAlias(intersectionOrderPath);
-        dbOrderBy = dbOrderBy.replace(marker, targetAlias + "z_." + intersectionOrderColumn);
-      }
       dbOrderBy = alias.parse(dbOrderBy);
     }
     if (dbDistinctOn != null) {
@@ -302,18 +268,9 @@ public final class CQueryPredicates {
     }
     // check for default ordering on the many property...
     SpiQueryManyJoin manyProp = request.manyJoin();
-    if (manyProp.hasIntersectionOrderColumn()) {
-      // ManyToMany with @OrderColumn on the intersection table - the column lives on the
-      // intersection table (alias "<targetAlias>z_") rather than a normal property path,
-      // so we append a literal marker that parseTableAlias() resolves directly.
-      intersectionOrderPath = manyProp.path();
-      intersectionOrderColumn = manyProp.intersectionOrderColumn();
-      orderBy = orderBy + ", ${" + intersectionOrderPath + "}" + intersectionOrderColumn;
-    } else {
-      String manyOrderBy = manyProp.fetchOrderBy();
-      if (manyOrderBy != null) {
-        orderBy = orderBy + ", " + parser.parse(CQueryBuilder.prefixOrderByFields(manyProp.path(), manyOrderBy));
-      }
+    String manyOrderBy = manyProp.fetchOrderBy();
+    if (manyOrderBy != null) {
+      orderBy = orderBy + ", " + parser.parse(CQueryBuilder.prefixOrderByFields(manyProp.path(), manyOrderBy));
     }
     if (request.isFindById()) {
       // only one master bean so should be fine...
@@ -406,14 +363,6 @@ public final class CQueryPredicates {
     return filterManyJoin ? dbFilterMany : null;
   }
 
-  /**
-   * Return the fetch path of the filterMany-in-JOIN predicate - the path whose own join clause
-   * the predicate must be appended to (or null if there is no filterMany-in-JOIN predicate at all).
-   */
-  String filterManyAttachPath() {
-    return filterManyJoin ? filterManyAttachPath : null;
-  }
-
   /**
    * Return the db column version of the order by clause.
    */

ebean-core/src/main/java/io/ebeaninternal/server/query/DefaultDbSqlContext.java

@@ -23,7 +23,6 @@ final class DefaultDbSqlContext implements DbSqlContext {
   private final ArrayStack<String> prefixStack = new ArrayStack<>();
   private final String fromForUpdate;
   private final String dbFilterManyJoin;
-  private final String filterManyAttachPath;
   private boolean useColumnAlias;
   private int columnIndex;
   private int asOfTableCount;
@@ -43,8 +42,7 @@ final class DefaultDbSqlContext implements DbSqlContext {
   private boolean joinSuppressed;
 
   DefaultDbSqlContext(SqlTreeAlias alias, String columnAliasPrefix, CQueryHistorySupport historySupport,
-                      CQueryDraftSupport draftSupport, String fromForUpdate, String dbFilterManyJoin,
-                      String filterManyAttachPath) {
+                      CQueryDraftSupport draftSupport, String fromForUpdate, String dbFilterManyJoin) {
     this.alias = alias;
     this.columnAliasPrefix = columnAliasPrefix;
     this.useColumnAlias = columnAliasPrefix != null;
@@ -53,12 +51,6 @@ final class DefaultDbSqlContext implements DbSqlContext {
     this.historyQuery = (historySupport != null);
     this.fromForUpdate = fromForUpdate;
     this.dbFilterManyJoin = dbFilterManyJoin;
-    this.filterManyAttachPath = filterManyAttachPath;
-  }
-
-  @Override
-  public boolean isFilterManyAttachPoint(String prefix) {
-    return dbFilterManyJoin != null && filterManyAttachPath != null && filterManyAttachPath.equals(prefix);
   }
 
   @Override

ebean-core/src/main/java/io/ebeaninternal/server/query/DefaultFetchGroupQuery.java

@@ -149,16 +149,6 @@ final class DefaultFetchGroupQuery<T> implements SpiFetchGroupQuery<T>, SpiQuery
     throw new RuntimeException("EB102: Only select() and fetch() clause is allowed on FetchGroup");
   }
 
-  @Override
-  public <D> MappedQuery<D> mapTo(Class<D> dtoType) {
-    throw new RuntimeException("EB102: Only select() and fetch() clause is allowed on FetchGroup");
-  }
-
-  @Override
-  public <D> MappedQuery<D> mapTo(Class<D> dtoType, DtoMapper<T, D> mapper) {
-    throw new RuntimeException("EB102: Only select() and fetch() clause is allowed on FetchGroup");
-  }
-
   @Override
   public UpdateQuery<T> asUpdate() {
     throw new RuntimeException("EB102: Only select() and fetch() clause is allowed on FetchGroup");

ebean-core/src/main/java/io/ebeaninternal/server/query/STreePropertyAssocMany.java

@@ -43,16 +43,6 @@ public interface STreePropertyAssocMany extends STreePropertyAssoc {
    */
   boolean hasJoinTable();
 
-  /**
-   * Return true if this is a ManyToMany with an order column stored on the intersection table.
-   */
-  boolean hasIntersectionOrderColumn();
-
-  /**
-   * Return the db column name of the ManyToMany intersection table order column (or null).
-   */
-  String intersectionOrderColumn();
-
   /**
    * Return the intersection table join.
    */

ebean-core/src/main/java/io/ebeaninternal/server/query/SqlTreeBuilder.java

@@ -108,7 +108,7 @@ public final class SqlTreeBuilder {
     CQueryHistorySupport historySupport = builder.historySupport(query);
     CQueryDraftSupport draftSupport = builder.draftSupport(query);
     String colAlias = subQuery || rootNode.isSingleProperty() ? null : columnAliasPrefix;
-    this.ctx = new DefaultDbSqlContext(alias, colAlias, historySupport, draftSupport, fromForUpdate, predicates.dbFilterManyJoin(), predicates.filterManyAttachPath());
+    this.ctx = new DefaultDbSqlContext(alias, colAlias, historySupport, draftSupport, fromForUpdate, predicates.dbFilterManyJoin());
   }
 
   /**

ebean-core/src/main/java/io/ebeaninternal/server/query/SqlTreeNodeBean.java

@@ -342,10 +342,6 @@ class SqlTreeNodeBean implements SqlTreeNode {
     if (desc.isSoftDelete() && temporalMode != SpiQuery.TemporalMode.SOFT_DELETED) {
       ctx.append(" and ").append(desc.softDeletePredicate(ctx.tableAlias(prefix)));
     }
-    if (prefix != null && ctx.isFilterManyAttachPoint(prefix)) {
-      // this node is where we inline the filterMany predicate
-      ctx.includeFilterMany();
-    }
     return sqlJoinType;
   }
 

ebean-core/src/main/java/io/ebeaninternal/server/query/SqlTreeNodeManyRoot.java

@@ -45,5 +45,6 @@ final class SqlTreeNodeManyRoot extends SqlTreeNodeBean {
   @Override
   public void appendFrom(DbSqlContext ctx, SqlJoinType joinType) {
     super.appendFrom(ctx, joinType.autoToOuter());
+    ctx.includeFilterMany();
   }
 }

ebean-core/src/main/java/io/ebeaninternal/server/querydefn/DefaultDtoQuery.java

@@ -2,7 +2,6 @@ package io.ebeaninternal.server.querydefn;
 
 import org.jspecify.annotations.NullMarked;
 import io.ebean.DtoQuery;
-import io.ebean.PagedList;
 import io.ebean.ProfileLocation;
 import io.ebean.QueryIterator;
 import io.ebean.Transaction;
@@ -12,7 +11,6 @@ import io.ebeaninternal.server.dto.DtoMappingRequest;
 import io.ebeaninternal.server.dto.DtoQueryPlan;
 import io.ebeaninternal.server.transaction.ExternalJdbcTransaction;
 
-import jakarta.persistence.PersistenceException;
 import javax.annotation.Nullable;
 import java.sql.Connection;
 import java.util.Collection;
@@ -52,8 +50,6 @@ public final class DefaultDtoQuery<T> extends AbstractQuery implements SpiDtoQue
     this.useMaster = ormQuery.isUseMaster();
     this.label = ormQuery.label();
     this.profileLocation = ormQuery.profileLocation();
-    this.firstRow = ormQuery.getFirstRow();
-    this.maxRows = ormQuery.getMaxRows();
   }
 
   /**
@@ -139,24 +135,6 @@ public final class DefaultDtoQuery<T> extends AbstractQuery implements SpiDtoQue
     return server.findDtoList(this);
   }
 
-  @Override
-  public PagedList<T> findPagedList() {
-    if (ormQuery == null) {
-      throw new PersistenceException("findPagedList() is only supported for a DtoQuery derived from an ORM query");
-    }
-    if (maxRows == 0) {
-      throw new PersistenceException("maxRows must be specified for findPagedList()");
-    }
-    // Use an independent copy for the row count query. The ormQuery instance is mutated with
-    // a (potentially since ended/inactive) implicit transaction when the DTO list is executed,
-    // so the count query must not share that transaction reference - instead it uses the
-    // transaction explicitly bound to this DtoQuery (if any), consistent with a plain
-    // Query.findPagedList().
-    SpiQuery<?> countQuery = ormQuery.copy();
-    countQuery.usingTransaction(transaction);
-    return new DtoPagedList<>(server, this, countQuery);
-  }
-
   @Nullable
   @Override
   public T findOne() {

ebean-core/src/main/java/io/ebeaninternal/server/querydefn/DefaultMappedQuery.java

@@ -1,156 +0,0 @@
-package io.ebeaninternal.server.querydefn;
-
-import io.ebean.DtoMapContext;
-import io.ebean.DtoMapper;
-import io.ebean.MappedQuery;
-import io.ebean.PagedList;
-import io.ebean.Transaction;
-import io.ebeaninternal.api.SpiEbeanServer;
-import io.ebeaninternal.api.SpiQuery;
-
-import java.sql.Connection;
-import java.util.List;
-import java.util.Optional;
-import java.util.function.Consumer;
-import java.util.function.Predicate;
-import java.util.stream.Stream;
-
-/**
- * Default implementation of {@link MappedQuery} backing {@code query.mapTo(dtoType)}.
- * <p>
- * Resolves the generated {@link DtoMapper} for the query's (entity, dto) pair, applies its
- * {@link DtoMapper#fetchGroup()} (derived from the target DTO's declared shape) - unless the
- * caller has already specified their own {@code select()}/{@code fetch()} spec, in which case
- * that manual spec is left untouched - and forces {@code setUnmodifiable(true)} on the
- * underlying query before it is executed, then maps the resulting entity graph into the
- * target DTO graph.
- */
-public final class DefaultMappedQuery<T, D> implements MappedQuery<D> {
-
-  private final SpiEbeanServer server;
-  private final SpiQuery<T> query;
-  private final Class<D> dtoType;
-  private DtoMapper<T, D> mapper;
-  private boolean applied;
-
-  public DefaultMappedQuery(SpiEbeanServer server, SpiQuery<T> query, Class<D> dtoType) {
-    this.server = server;
-    this.query = query;
-    this.dtoType = dtoType;
-  }
-
-  /**
-   * Use an already-resolved mapper instance directly - e.g. a named variant accessor on a
-   * generated mapper, such as {@code query.mapTo(User.class, userMapper.noFleets())} - bypassing
-   * {@code server.dtoMapper(...)} lookup entirely.
-   */
-  public DefaultMappedQuery(SpiEbeanServer server, SpiQuery<T> query, Class<D> dtoType, DtoMapper<T, D> mapper) {
-    this.server = server;
-    this.query = query;
-    this.dtoType = dtoType;
-    this.mapper = mapper;
-  }
-
-  /**
-   * Apply the mapper's fetch spec + unmodifiable to the underlying query (once) - must happen
-   * before the query is executed. Uses an explicit {@code applied} flag rather than a
-   * {@code mapper == null} check since a pre-supplied mapper (see the constructor above) is
-   * already non-null before the fetch spec has been applied.
-   */
-  private DtoMapper<T, D> mapper() {
-    if (!applied) {
-      if (mapper == null) {
-        mapper = server.dtoMapper(query.getBeanType(), dtoType);
-      }
-      if (query.detail().isEmpty()) {
-        // only apply the mapper's derived fetch spec if the caller hasn't already specified
-        // their own select()/fetch() - allowing manual query tuning/optimisation to take
-        // precedence over the DTO shape's default fetch spec when needed
-        query.select(mapper.fetchGroup());
-      }
-      query.setUnmodifiable(true);
-      applied = true;
-    }
-    return mapper;
-  }
-
-
-  @Override
-  public List<D> findList() {
-    DtoMapper<T, D> m = mapper();
-    return m.mapList(query.findList());
-  }
-
-  @Override
-  public D findOne() {
-    DtoMapper<T, D> m = mapper();
-    return m.map(query.findOne());
-  }
-
-  @Override
-  public Optional<D> findOneOrEmpty() {
-    return Optional.ofNullable(findOne());
-  }
-
-  @Override
-  public D findOneOrThrow() {
-    return mapper().map(query.findOneOrThrow());
-  }
-
-  @Override
-  public PagedList<D> findPagedList() {
-    DtoMapper<T, D> m = mapper();
-    return new MappedPagedList<>(query.findPagedList(), m);
-  }
-
-  @Override
-  public Stream<D> findStream() {
-    DtoMapper<T, D> m = mapper();
-    DtoMapContext context = new DtoMapContext();
-    return query.findStream().map(source -> m.map(source, context));
-  }
-
-  @Override
-  public void findEach(Consumer<D> consumer) {
-    DtoMapper<T, D> m = mapper();
-    DtoMapContext context = new DtoMapContext();
-    query.findEach(source -> consumer.accept(m.map(source, context)));
-  }
-
-  @Override
-  public void findEach(int batch, Consumer<List<D>> consumer) {
-    DtoMapper<T, D> m = mapper();
-    DtoMapContext context = new DtoMapContext();
-    query.findEach(batch, sourceBatch -> consumer.accept(m.mapList(sourceBatch, context)));
-  }
-
-  @Override
-  public void findEachWhile(Predicate<D> consumer) {
-    DtoMapper<T, D> m = mapper();
-    DtoMapContext context = new DtoMapContext();
-    query.findEachWhile(source -> consumer.test(m.map(source, context)));
-  }
-
-  @Override
-  public MappedQuery<D> usingMaster(boolean useMaster) {
-    query.usingMaster(useMaster);
-    return this;
-  }
-
-  @Override
-  public MappedQuery<D> usingTransaction(Transaction transaction) {
-    query.usingTransaction(transaction);
-    return this;
-  }
-
-  @Override
-  public MappedQuery<D> usingConnection(Connection connection) {
-    query.usingConnection(connection);
-    return this;
-  }
-
-  @Override
-  public void cancel() {
-    query.cancel();
-  }
-}

ebean-core/src/main/java/io/ebeaninternal/server/querydefn/DefaultOrmQuery.java

@@ -23,7 +23,6 @@ import io.ebeaninternal.server.query.NativeSqlQueryPlanKey;
 import io.ebeaninternal.server.rawsql.SpiRawSql;
 import io.ebeaninternal.server.transaction.ExternalJdbcTransaction;
 
-import jakarta.persistence.EntityNotFoundException;
 import jakarta.persistence.PersistenceException;
 import java.sql.Connection;
 import java.sql.Timestamp;
@@ -185,16 +184,6 @@ public class DefaultOrmQuery<T> extends AbstractQuery implements SpiQuery<T> {
     return server.findDto(dtoClass, this);
   }
 
-  @Override
-  public final <D> MappedQuery<D> mapTo(Class<D> dtoType) {
-    return new DefaultMappedQuery<>(server, this, dtoType);
-  }
-
-  @Override
-  public final <D> MappedQuery<D> mapTo(Class<D> dtoType, DtoMapper<T, D> mapper) {
-    return new DefaultMappedQuery<>(server, this, dtoType, mapper);
-  }
-
   @Override
   public final UpdateQuery<T> asUpdate() {
     return new DefaultUpdateQuery<>(this);
@@ -1657,30 +1646,6 @@ public class DefaultOrmQuery<T> extends AbstractQuery implements SpiQuery<T> {
     return server.findOneOrEmpty(this);
   }
 
-  @Override
-  public final T findOneOrThrow() {
-    return findOneOrEmpty().orElseThrow(() -> new EntityNotFoundException(notFoundMessage()));
-  }
-
-  /**
-   * Build a decent default "not found" message using the id (if this is effectively a
-   * find-by-id query) or, failing that, a single simple equality predicate (a likely
-   * natural/unique key). Falls back to a generic message for anything more complex.
-   */
-  private String notFoundMessage() {
-    String type = beanDescriptor.type().getSimpleName();
-    if (isFindById()) {
-      return type + " not found for id: " + id;
-    }
-    if (whereExpressions != null) {
-      String desc = whereExpressions.singleEqDescription();
-      if (desc != null) {
-        return type + " not found for " + desc;
-      }
-    }
-    return type + " not found";
-  }
-
   @Override
   public final FutureIds<T> findFutureIds() {
     return server.findFutureIds(this);

ebean-core/src/main/java/io/ebeaninternal/server/querydefn/DefaultOrmUpdate.java

@@ -1,7 +1,6 @@
 package io.ebeaninternal.server.querydefn;
 
 import io.ebean.Database;
-import io.ebean.Transaction;
 import io.ebean.Update;
 import io.ebeaninternal.api.BindParams;
 import io.ebeaninternal.api.SpiUpdate;
@@ -31,7 +30,6 @@ public final class DefaultOrmUpdate<T> implements SpiUpdate<T>, Serializable {
   private String generatedSql;
   private final String baseTable;
   private final OrmUpdateType type;
-  private transient Transaction transaction;
 
   /**
    * Create with a specific server. This means you can use the
@@ -90,13 +88,7 @@ public final class DefaultOrmUpdate<T> implements SpiUpdate<T>, Serializable {
 
   @Override
   public int execute() {
-    return server.execute(this, transaction);
-  }
-
-  @Override
-  public DefaultOrmUpdate<T> usingTransaction(Transaction transaction) {
-    this.transaction = transaction;
-    return this;
+    return server.execute(this);
   }
 
   /**

ebean-core/src/main/java/io/ebeaninternal/server/querydefn/DefaultRelationalQuery.java

@@ -281,17 +281,6 @@ public final class DefaultRelationalQuery extends AbstractQuery implements SpiSq
       return this;
     }
 
-    @Override
-    public TypeQuery<T> usingConnection(Connection connection) {
-      DefaultRelationalQuery.this.usingConnection(connection);
-      return this;
-    }
-
-    @Override
-    public void cancel() {
-      DefaultRelationalQuery.this.cancel();
-    }
-
     @Override
     public T findOne() {
       return findSingleAttribute(type);
@@ -337,17 +326,6 @@ public final class DefaultRelationalQuery extends AbstractQuery implements SpiSq
       return this;
     }
 
-    @Override
-    public TypeQuery<T> usingConnection(Connection connection) {
-      DefaultRelationalQuery.this.usingConnection(connection);
-      return this;
-    }
-
-    @Override
-    public void cancel() {
-      DefaultRelationalQuery.this.cancel();
-    }
-
     @Nullable
     @Override
     public T findOne() {

ebean-core/src/main/java/io/ebeaninternal/server/querydefn/DtoPagedList.java

@@ -1,146 +0,0 @@
-package io.ebeaninternal.server.querydefn;
-
-import io.ebean.PagedList;
-import io.ebeaninternal.api.SpiDtoQuery;
-import io.ebeaninternal.api.SpiEbeanServer;
-import io.ebeaninternal.api.SpiQuery;
-import jakarta.persistence.PersistenceException;
-
-import java.util.Collections;
-import java.util.List;
-import java.util.concurrent.Future;
-import java.util.concurrent.locks.ReentrantLock;
-
-/**
- * PagedList implementation for a DtoQuery that is derived from an underlying ORM query
- * (created via {@code Query.asDto()}).
- * <p>
- * The page of DTO beans is fetched via the DtoQuery while the total row count is derived
- * from the underlying ORM query (which has the matching where clause, joins etc).
- */
-final class DtoPagedList<T> implements PagedList<T> {
-
-  private final transient SpiEbeanServer server;
-  private final transient ReentrantLock lock = new ReentrantLock();
-  private final SpiDtoQuery<T> dtoQuery;
-  private final SpiQuery<?> countQuery;
-  private final int firstRow;
-  private final int maxRows;
-
-  private int totalRowCount = -1;
-  private Future<Integer> futureRowCount;
-  private List<T> list;
-
-  /**
-   * Construct with the dto query and the underlying ORM query used to derive the row count.
-   */
-  DtoPagedList(SpiEbeanServer server, SpiDtoQuery<T> dtoQuery, SpiQuery<?> countQuery) {
-    this.server = server;
-    this.dtoQuery = dtoQuery;
-    this.countQuery = countQuery;
-    this.maxRows = countQuery.getMaxRows();
-    this.firstRow = countQuery.getFirstRow();
-  }
-
-  @Override
-  public void loadCount() {
-    getFutureCount();
-  }
-
-  @Override
-  public Future<Integer> getFutureCount() {
-    lock.lock();
-    try {
-      if (futureRowCount == null) {
-        futureRowCount = server.findFutureCount(countQuery);
-      }
-      return futureRowCount;
-    } finally {
-      lock.unlock();
-    }
-  }
-
-  @Override
-  public List<T> getList() {
-    lock.lock();
-    try {
-      if (list == null) {
-        if (totalRowCount == 0) {
-          // already count and no rows
-          list = Collections.emptyList();
-        } else {
-          list = server.findDtoList(dtoQuery);
-        }
-      }
-      return list;
-    } finally {
-      lock.unlock();
-    }
-  }
-
-  @Override
-  public int getPageIndex() {
-    if (firstRow == 0) {
-      return 0;
-    }
-    return ((firstRow - 1) / maxRows) + 1;
-  }
-
-  @Override
-  public int getTotalPageCount() {
-    int rowCount = getTotalCount();
-    if (rowCount == 0) {
-      return 0;
-    } else {
-      return ((rowCount - 1) / maxRows) + 1;
-    }
-  }
-
-  @Override
-  public int getTotalCount() {
-    lock.lock();
-    try {
-      if (totalRowCount > -1) {
-        return totalRowCount;
-      }
-      if (futureRowCount != null) {
-        try {
-          // background query already initiated so get it with a wait
-          totalRowCount = futureRowCount.get();
-          return totalRowCount;
-        } catch (Exception e) {
-          throw new PersistenceException(e);
-        }
-      }
-      // just using foreground thread
-      totalRowCount = server.findCount(countQuery);
-      return totalRowCount;
-    } finally {
-      lock.unlock();
-    }
-  }
-
-  @Override
-  public boolean hasNext() {
-    return (firstRow + maxRows) < getTotalCount();
-  }
-
-  @Override
-  public boolean hasPrev() {
-    return firstRow > 0;
-  }
-
-  @Override
-  public int getPageSize() {
-    return maxRows;
-  }
-
-  @Override
-  public String getDisplayXtoYofZ(String to, String of) {
-    int first = firstRow + 1;
-    int last = firstRow + getList().size();
-    int total = getTotalCount();
-    return first + to + last + of + total;
-  }
-
-}

ebean-core/src/main/java/io/ebeaninternal/server/querydefn/MappedPagedList.java

@@ -1,87 +0,0 @@
-package io.ebeaninternal.server.querydefn;
-
-import io.ebean.DtoMapper;
-import io.ebean.PagedList;
-
-import java.util.List;
-import java.util.concurrent.Future;
-import java.util.concurrent.locks.ReentrantLock;
-
-/**
- * {@link PagedList} adapter backing {@code query.mapTo(dtoType).findPagedList()}.
- * <p>
- * Delegates all page metadata (total count, page index, {@code hasNext()}/{@code hasPrev()}, ...)
- * straight through to the underlying entity-typed {@link PagedList} unchanged - paging is a
- * property of the query, not of the DTO shape. Only {@link #getList()} differs: it maps the
- * delegate's entity list to the target DTO list (once, cached) via the given {@link DtoMapper}.
- */
-public final class MappedPagedList<T, D> implements PagedList<D> {
-
-  private final ReentrantLock lock = new ReentrantLock();
-  private final PagedList<T> delegate;
-  private final DtoMapper<T, D> mapper;
-  private List<D> mappedList;
-
-  public MappedPagedList(PagedList<T> delegate, DtoMapper<T, D> mapper) {
-    this.delegate = delegate;
-    this.mapper = mapper;
-  }
-
-  @Override
-  public void loadCount() {
-    delegate.loadCount();
-  }
-
-  @Override
-  public Future<Integer> getFutureCount() {
-    return delegate.getFutureCount();
-  }
-
-  @Override
-  public List<D> getList() {
-    lock.lock();
-    try {
-      if (mappedList == null) {
-        mappedList = mapper.mapList(delegate.getList());
-      }
-      return mappedList;
-    } finally {
-      lock.unlock();
-    }
-  }
-
-  @Override
-  public int getTotalCount() {
-    return delegate.getTotalCount();
-  }
-
-  @Override
-  public int getTotalPageCount() {
-    return delegate.getTotalPageCount();
-  }
-
-  @Override
-  public int getPageSize() {
-    return delegate.getPageSize();
-  }
-
-  @Override
-  public int getPageIndex() {
-    return delegate.getPageIndex();
-  }
-
-  @Override
-  public boolean hasNext() {
-    return delegate.hasNext();
-  }
-
-  @Override
-  public boolean hasPrev() {
-    return delegate.hasPrev();
-  }
-
-  @Override
-  public String getDisplayXtoYofZ(String to, String of) {
-    return delegate.getDisplayXtoYofZ(to, of);
-  }
-}

ebean-core/src/main/java/io/ebeaninternal/server/querydefn/OrmQueryDetail.java

@@ -7,7 +7,6 @@ import io.ebeaninternal.api.SpiExpressionList;
 import io.ebeaninternal.api.SpiQueryManyJoin;
 import io.ebeaninternal.server.deploy.BeanDescriptor;
 import io.ebeaninternal.server.deploy.BeanPropertyAssoc;
-import io.ebeaninternal.server.deploy.BeanPropertyAssocOne;
 import io.ebeaninternal.server.el.ElPropertyDeploy;
 import io.ebeaninternal.server.el.ElPropertyValue;
 
@@ -359,54 +358,6 @@ public final class OrmQueryDetail implements Serializable {
     }
   }
 
-  /**
-   * After sorting, fold any fetch path that only fetches a *ToOne association's id
-   * into a plain select of the parent path instead - the foreign key column is already
-   * present on the owning table so the join can be avoided entirely.
-   * <p>
-   * Iterates the fetch paths backwards (deepest first) so that a path already folded
-   * away does not stop a shallower ancestor also being folded, while a path that must
-   * remain a real join protects its own parent (added to {@code nonRemovable}) from
-   * being folded, as the parent's join is required to reach it.
-   */
-  private void convertIdFetches(BeanDescriptor<?> desc) {
-    Set<String> nonRemovable = new HashSet<>();
-    String[] paths = fetchPaths.keySet().toArray(new String[0]);
-    int i = paths.length;
-    while (i-- > 0) {
-      String path = paths[i];
-      ElPropertyDeploy el = desc.elPropertyDeploy(path);
-      OrmQueryProperties prop = fetchPaths.get(path);
-      if (nonRemovable.contains(path)) {
-        // a still-existing child fetch depends on this join, don't remove
-      } else if (el == null) {
-        throw new PersistenceException("Invalid fetch path " + path + " from " + desc.fullName());
-      } else if (el.beanProperty() instanceof BeanPropertyAssocOne) {
-        BeanPropertyAssocOne<?> assoc = (BeanPropertyAssocOne<?>) el.beanProperty();
-        // exported (mappedBy) one-to-one has no local foreign key column - it always needs the join
-        if (assoc.hasForeignKeyConstraint() && !assoc.isOneToOneExported()) {
-          if (prop.includesExactly(assoc.targetDescriptor().idName())) {
-            String parentPath = prop.getParentPath();
-            OrmQueryProperties parentProp = parentPath == null ? baseProps : fetchPaths.get(parentPath);
-            if (parentProp != null && parentProp.hasProperties()) {
-              OrmQueryProperties newParentProp = parentProp.withAddedInclude(assoc.name());
-              if (parentPath == null) {
-                baseProps = newParentProp;
-              } else {
-                fetchPaths.put(parentPath, newParentProp);
-              }
-              fetchPaths.remove(path);
-              prop = null;
-            }
-          }
-        }
-      }
-      if (prop != null && prop.getParentPath() != null) {
-        nonRemovable.add(prop.getParentPath());
-      }
-    }
-  }
-
   /**
    * Mark 'fetch joins' to 'many' properties over to 'query joins' where needed.
    *
@@ -424,7 +375,6 @@ public final class OrmQueryDetail implements Serializable {
     boolean fetchJoinFirstMany = allowOne;
 
     sortFetchPaths(beanDescriptor, addIds);
-    convertIdFetches(beanDescriptor);
     List<FetchEntry> pairs = sortByFetchPreference(beanDescriptor);
 
     for (FetchEntry pair : pairs) {
@@ -434,18 +384,14 @@ public final class OrmQueryDetail implements Serializable {
         OrmQueryProperties chunk = pair.getProperties();
         if (isQueryJoinCandidate(lazyLoadManyPath, chunk)) {
           // this is a 'fetch join' (included in main query)
-          BeanDescriptor<?> targetDescriptor = ((BeanPropertyAssoc<?>) elProp.beanProperty()).targetDescriptor();
-          if (fetchJoinFirstMany && !chunk.filterManyHasNestedProperty(targetDescriptor)) {
+          if (fetchJoinFirstMany) {
             // letting the first one remain a 'fetch join'
             fetchJoinFirstMany = false;
             manyFetchProperty = pair.getPath();
             chunk.filterManyInline();
             many = elProp;
           } else {
-            // convert this one over to a 'query join' - either because another many has already claimed the
-            // 'fetch join' slot, or because its filterMany references a property that requires crossing into
-            // an associated bean and can't safely be included as a JOIN predicate (see
-            // OrmQueryProperties.filterManyHasNestedProperty)
+            // convert this one over to a 'query join'
             chunk.markForQueryJoin();
           }
         }

ebean-core/src/main/java/io/ebeaninternal/server/querydefn/OrmQueryProperties.java

@@ -9,10 +9,7 @@ import io.ebean.util.SplitName;
 import io.ebeaninternal.api.SpiExpression;
 import io.ebeaninternal.api.SpiExpressionFactory;
 import io.ebeaninternal.api.SpiExpressionList;
-import io.ebeaninternal.api.SpiExpressionValidation;
 import io.ebeaninternal.api.SpiQuery;
-import io.ebeaninternal.server.deploy.BeanDescriptor;
-import io.ebeaninternal.server.el.ElPropertyValue;
 import io.ebeaninternal.server.expression.FilterExprPath;
 import io.ebeaninternal.server.expression.FilterExpressionList;
 
@@ -151,22 +148,6 @@ public final class OrmQueryProperties implements Serializable {
       : buildImmutableQueryPlanHashSuffix(sourceFetchConfig);
   }
 
-  /**
-   * Copy constructor with a replacement included set (used by {@link #withAddedInclude(String)}).
-   */
-  private OrmQueryProperties(OrmQueryProperties source, Set<String> replacementIncluded) {
-    this.fetchConfig = source.fetchConfig;
-    this.parentPath = source.parentPath;
-    this.path = source.path;
-    this.allProperties = source.allProperties;
-    this.cache = source.cache;
-    this.filterMany = source.filterMany;
-    this.markForQueryJoin = source.markForQueryJoin;
-    this.included = immutableIncluded(replacementIncluded);
-    this.immutableHashPrefix = buildImmutableQueryPlanHashPrefix(path, this.included);
-    this.immutableHashSuffix = source.immutableHashSuffix;
-  }
-
   private static Set<String> immutableIncluded(Set<String> included) {
     if (included == null) {
       return null;
@@ -253,26 +234,6 @@ public final class OrmQueryProperties implements Serializable {
     return filterMany != null && !markForQueryJoin;
   }
 
-  /**
-   * Return true if the filterMany expression (if any) references a property that requires
-   * crossing into an associated bean/join - e.g. {@code "group.name"} - rather than only
-   * plain/embedded properties resolving to columns on the many bean's own base table.
-   */
-  boolean filterManyHasNestedProperty(BeanDescriptor<?> targetDescriptor) {
-    if (filterMany == null) {
-      return false;
-    }
-    SpiExpressionValidation validation = new SpiExpressionValidation(targetDescriptor);
-    filterMany.validate(validation);
-    for (String property : validation.allProperties()) {
-      ElPropertyValue elProp = targetDescriptor.elGetValue(property);
-      if (elProp != null && elProp.isAssocProperty()) {
-        return true;
-      }
-    }
-    return false;
-  }
-
   /**
    * Adjust filterMany expressions for inclusion in main query.
    */
@@ -428,37 +389,6 @@ public final class OrmQueryProperties implements Serializable {
     return included == null || included.contains(propName);
   }
 
-  /**
-   * Return true if the included properties are exactly the single given property.
-   * <p>
-   * Used to detect a fetch/select of a *ToOne association that only includes the
-   * target's id property - a candidate for folding into the parent select as a plain
-   * foreign key property (avoiding an unnecessary join).
-   */
-  boolean includesExactly(String property) {
-    return included != null && included.size() == 1 && included.contains(property);
-  }
-
-  /**
-   * Return a new instance with the given property added to the included set.
-   * <p>
-   * Used to fold an id-only *ToOne fetch into this select as a plain foreign key
-   * property. A new instance is returned (rather than mutating {@link #included} in
-   * place) as this instance's included set is immutable and may be shared/cached
-   * (e.g. via FetchGroup reuse).
-   */
-  OrmQueryProperties withAddedInclude(String property) {
-    if (allProperties) {
-      return this;
-    }
-    Set<String> newIncluded = new LinkedHashSet<>();
-    if (included != null) {
-      newIncluded.addAll(included);
-    }
-    newIncluded.add(property);
-    return new OrmQueryProperties(this, newIncluded);
-  }
-
   /**
    * Mark this path as needing to be a query join.
    */

ebean-core/src/main/java/io/ebeaninternal/server/type/DefaultTypeManager.java

@@ -265,7 +265,7 @@ public final class DefaultTypeManager implements TypeManager {
 
   @Override
   public ScalarType<?> dbMapType() {
-    return hstoreSupport() ? hstoreType : ScalarTypeJsonMap.typeFor(false, Types.VARCHAR, MutationDetection.DEFAULT);
+    return hstoreSupport() ? hstoreType : ScalarTypeJsonMap.typeFor(false, Types.VARCHAR, false);
   }
 
   @Override
@@ -322,17 +322,17 @@ public final class DefaultTypeManager implements TypeManager {
     }
     Type genericType = prop.genericType();
     if (type.equals(List.class) && isValueTypeSimple(genericType)) {
-      return ScalarTypeJsonList.typeFor(postgres, dbType, docType(genericType), prop.isNullable(), collectionMutationDetection(prop));
+      return ScalarTypeJsonList.typeFor(postgres, dbType, docType(genericType), prop.isNullable(), keepSource(prop));
     }
     if (type.equals(Set.class) && isValueTypeSimple(genericType)) {
-      return ScalarTypeJsonSet.typeFor(postgres, dbType, docType(genericType), prop.isNullable(), collectionMutationDetection(prop));
+      return ScalarTypeJsonSet.typeFor(postgres, dbType, docType(genericType), prop.isNullable(), keepSource(prop));
     }
     if (type.equals(Map.class) && isBuiltinJsonMap(genericType)) {
       Type keyType = TypeReflectHelper.getMapKeyTypeRaw(genericType);
       if (isEnumType(keyType)) {
-        return enumJsonMapType(postgres, dbType, keyType, collectionMutationDetection(prop));
+        return enumJsonMapType(postgres, dbType, keyType, keepSource(prop));
       }
-      return ScalarTypeJsonMap.typeFor(postgres, dbType, collectionMutationDetection(prop));
+      return ScalarTypeJsonMap.typeFor(postgres, dbType, keepSource(prop));
     }
     if (objectMapperPresent && prop.mutationDetection() == MutationDetection.DEFAULT) {
       ScalarTypeSet<?> typeSet = typeSets.get(type);
@@ -343,25 +343,18 @@ public final class DefaultTypeManager implements TypeManager {
     return createJsonObjectMapperType(prop, dbType, DocPropertyType.OBJECT);
   }
 
-  /**
-   * Return the mutation detection mode to use for the built-in JSON collection types
-   * (Map, List, Set).
-   * <p>
-   * Unlike {@code @DbJson} properties handled via the Jackson ObjectMapper, {@code DEFAULT}
-   * on these collection types is <em>not</em> resolved against the DatabaseConfig wide
-   * default - it always uses the legacy ModifyAware wrapper based dirty checking. Only an
-   * explicit {@code NONE}, {@code HASH} or {@code SOURCE} on the property itself switches
-   * these types away from ModifyAware based checking.
-   */
-  private MutationDetection collectionMutationDetection(DeployProperty prop) {
-    return prop.mutationDetection();
+  private boolean keepSource(DeployProperty prop) {
+    if (prop.mutationDetection() == MutationDetection.DEFAULT) {
+      prop.setMutationDetection(jsonManager != null ? jsonManager.mutationDetection() : MutationDetection.NONE);
+    }
+    return prop.mutationDetection() == MutationDetection.SOURCE;
   }
 
   @SuppressWarnings("unchecked")
-  private ScalarType<?> enumJsonMapType(boolean postgres, int dbType, Type keyType, MutationDetection mutationDetection) {
+  private ScalarType<?> enumJsonMapType(boolean postgres, int dbType, Type keyType, boolean keepSource) {
     Class<? extends Enum<?>> enumClass = asEnumClass(keyType);
     ScalarType<? extends Enum<?>> enumScalarType = (ScalarType<? extends Enum<?>>) enumType(enumClass, null);
-    return ScalarTypeJsonMapEnum.typeFor(postgres, dbType, enumScalarType, mutationDetection);
+    return ScalarTypeJsonMapEnum.typeFor(postgres, dbType, enumScalarType, keepSource);
   }
 
   private DocPropertyType docPropertyType(DeployProperty prop, Class<?> type) {

ebean-core/src/main/java/io/ebeaninternal/server/type/PlatformArrayTypeJsonList.java

@@ -1,6 +1,5 @@
 package io.ebeaninternal.server.type;
 
-import io.ebean.annotation.MutationDetection;
 import io.ebean.core.type.DocPropertyType;
 import io.ebean.core.type.ScalarType;
 
@@ -28,14 +27,15 @@ class PlatformArrayTypeJsonList implements PlatformArrayTypeFactory {
   @Override
   public ScalarType<?> typeFor(Type valueType, boolean nullable) {
     if (valueType.equals(UUID.class)) {
-      return new ScalarTypeJsonList.VarcharWithConverter(DocPropertyType.UUID, nullable, ArrayElementConverter.UUID);
+      // TODO: keepSource for @DbArray?
+      return new ScalarTypeJsonList.VarcharWithConverter(DocPropertyType.UUID, nullable, false, ArrayElementConverter.UUID);
     }
-    return new ScalarTypeJsonList(java.sql.Types.VARCHAR, JsonStorage.VARCHAR, docType(valueType), nullable, MutationDetection.DEFAULT);
+    return new ScalarTypeJsonList(java.sql.Types.VARCHAR, JsonStorage.VARCHAR, docType(valueType), nullable, false);
   }
 
   @Override
   public ScalarType<?> typeForEnum(ScalarType<?> scalarType, boolean nullable) {
     final ArrayElementConverter.EnumConverter converter = new ArrayElementConverter.EnumConverter(scalarType);
-    return new ScalarTypeJsonList.VarcharWithConverter(scalarType.docType(), nullable, converter);
+    return new ScalarTypeJsonList.VarcharWithConverter(scalarType.docType(), nullable, false, converter);
   }
 }

ebean-core/src/main/java/io/ebeaninternal/server/type/PlatformArrayTypeJsonSet.java

@@ -1,6 +1,5 @@
 package io.ebeaninternal.server.type;
 
-import io.ebean.annotation.MutationDetection;
 import io.ebean.core.type.DocPropertyType;
 import io.ebean.core.type.ScalarType;
 
@@ -28,14 +27,15 @@ class PlatformArrayTypeJsonSet implements PlatformArrayTypeFactory {
   @Override
   public ScalarType<?> typeFor(Type valueType, boolean nullable) {
     if (valueType.equals(UUID.class)) {
-      return new ScalarTypeJsonSet.VarcharWithConverter(DocPropertyType.UUID, nullable, ArrayElementConverter.UUID);
+      // TODO: keepSource for @DbArray?
+      return new ScalarTypeJsonSet.VarcharWithConverter(DocPropertyType.UUID, nullable, false, ArrayElementConverter.UUID);
     }
-    return new ScalarTypeJsonSet(java.sql.Types.VARCHAR, JsonStorage.VARCHAR, docType(valueType), nullable, MutationDetection.DEFAULT);
+    return new ScalarTypeJsonSet(java.sql.Types.VARCHAR, JsonStorage.VARCHAR, docType(valueType), nullable, false);
   }
 
   @Override
   public ScalarType<?> typeForEnum(ScalarType<?> scalarType, boolean nullable) {
     final ArrayElementConverter.EnumConverter converter = new ArrayElementConverter.EnumConverter(scalarType);
-    return new ScalarTypeJsonSet.VarcharWithConverter(scalarType.docType(), nullable, converter);
+    return new ScalarTypeJsonSet.VarcharWithConverter(scalarType.docType(), nullable, false, converter);
   }
 }

ebean-core/src/main/java/io/ebeaninternal/server/type/ScalarTypeArray.java

@@ -10,12 +10,4 @@ public interface ScalarTypeArray {
    */
   String getDbColumnDefn();
 
-  /**
-   * Return the Java type of the individual array elements.
-   * <p>
-   * Used to bind the array correctly when the collection value is empty
-   * and so the element type can't be determined from the collection content.
-   */
-  Class<?> elementType();
-
 }

ebean-core/src/main/java/io/ebeaninternal/server/type/ScalarTypeArrayList.java

@@ -45,31 +45,31 @@ class ScalarTypeArrayList extends ScalarTypeArrayBase<List> implements ScalarTyp
       try {
         String key = valueType + ":" + nullable;
         if (valueType.equals(UUID.class)) {
-          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "uuid", DocPropertyType.UUID, ArrayElementConverter.UUID, UUID.class));
+          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "uuid", DocPropertyType.UUID, ArrayElementConverter.UUID));
         }
         if (valueType.equals(Long.class)) {
-          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "bigint", DocPropertyType.LONG, ArrayElementConverter.LONG, Long.class));
+          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "bigint", DocPropertyType.LONG, ArrayElementConverter.LONG));
         }
         if (valueType.equals(Integer.class)) {
-          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "integer", DocPropertyType.INTEGER, ArrayElementConverter.INTEGER, Integer.class));
+          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "integer", DocPropertyType.INTEGER, ArrayElementConverter.INTEGER));
         }
         if (valueType.equals(Float.class)) {
-          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "float4", DocPropertyType.DOUBLE, ArrayElementConverter.FLOAT, Float.class));
+          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "float4", DocPropertyType.DOUBLE, ArrayElementConverter.FLOAT));
         }
         if (valueType.equals(Double.class)) {
-          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "float", DocPropertyType.DOUBLE, ArrayElementConverter.DOUBLE, Double.class));
+          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "float", DocPropertyType.DOUBLE, ArrayElementConverter.DOUBLE));
         }
         if (valueType.equals(BigDecimal.class)) {
-          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "decimal", DocPropertyType.DOUBLE, ArrayElementConverter.BIG_DECIMAL, BigDecimal.class));
+          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "decimal", DocPropertyType.DOUBLE, ArrayElementConverter.BIG_DECIMAL));
         }
         if (valueType.equals(String.class)) {
-          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "varchar", DocPropertyType.TEXT, ArrayElementConverter.STRING, String.class));
+          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "varchar", DocPropertyType.TEXT, ArrayElementConverter.STRING));
         }
         if (valueType.equals(Instant.class)) {
-          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "timestamptz", DocPropertyType.TEXT, ArrayElementConverter.INSTANT, Instant.class));
+          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "timestamptz", DocPropertyType.TEXT, ArrayElementConverter.INSTANT));
         }
         if (valueType.equals(LocalDate.class)) {
-          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "date", DocPropertyType.TEXT, ArrayElementConverter.LOCAL_DATE, LocalDate.class));
+          return cache.computeIfAbsent(key, s -> new ScalarTypeArrayList(nullable, "date", DocPropertyType.TEXT, ArrayElementConverter.LOCAL_DATE));
         }
         throw new IllegalArgumentException("Type [" + valueType + "] not supported for @DbArray mapping");
       } finally {
@@ -79,24 +79,18 @@ class ScalarTypeArrayList extends ScalarTypeArrayBase<List> implements ScalarTyp
 
     @Override
     public ScalarTypeArrayList typeForEnum(ScalarType<?> scalarType, boolean nullable) {
-      return new ScalarTypeArrayList(nullable, arrayTypeFor(scalarType), scalarType.docType(), new ArrayElementConverter.EnumConverter(scalarType), scalarType.type());
+      return new ScalarTypeArrayList(nullable, arrayTypeFor(scalarType), scalarType.docType(), new ArrayElementConverter.EnumConverter(scalarType));
     }
   }
 
   private final String arrayType;
-  private final ArrayElementConverter converter;
-  private final Class<?> elementType;
 
-  public ScalarTypeArrayList(boolean nullable, String arrayType, DocPropertyType docPropertyType, ArrayElementConverter converter, Class<?> elementType) {
+  private final ArrayElementConverter converter;
+
+  public ScalarTypeArrayList(boolean nullable, String arrayType, DocPropertyType docPropertyType, ArrayElementConverter converter) {
     super(List.class, Types.ARRAY, docPropertyType, nullable);
     this.arrayType = arrayType;
     this.converter = converter;
-    this.elementType = elementType;
-  }
-
-  @Override
-  public Class<?> elementType() {
-    return elementType;
   }
 
   @Override