refactor: promote SimpleDTOProjection to official NameBasedProjection feature

Author: Mouon

querydsl-libraries/querydsl-core/src/main/java/com/querydsl/core/types/NameBasedProjection.java

@@ -23,91 +23,88 @@ public NameBasedProjection(Class<? extends T> type, EntityPathBase<?>... entitie
   }
 
   private Map<String, Expression<?>> collectExpressions(EntityPathBase<?>... entities) {
-      Map<String, Expression<?>> map = new HashMap<>();
-      for (EntityPathBase<?> entity : entities) {
-          Class<?> clazz = entity.getClass();
-          for (Field f : clazz.getFields()){
-              String name = f.getName();
-              if(!map.containsKey(name)){
-                  try{
-                      Object val = f.get(entity);
-                      if(val instanceof Expression){
-                          map.put(name, (Expression<?>) val);
-                      }
-                  }catch (IllegalAccessException e){
-
-                  }
-              }
+    Map<String, Expression<?>> map = new HashMap<>();
+    for (EntityPathBase<?> entity : entities) {
+      Class<?> clazz = entity.getClass();
+      for (Field f : clazz.getFields()) {
+        String name = f.getName();
+        if (!map.containsKey(name)) {
+          try {
+            Object val = f.get(entity);
+            if (val instanceof Expression) {
+              map.put(name, (Expression<?>) val);
+            }
+          } catch (IllegalAccessException e) {
+
           }
+        }
       }
-      return map;
+    }
+    return map;
   }
 
-
-
   private Constructor<? extends T> findMatchingConstructor(
-            Class<? extends T> type,
-            Map<String, Expression<?>> exprByName
-    ) {
-        Constructor<?>[] ctors = type.getDeclaredConstructors();
-
-        for (Constructor<?> ctor : ctors) {
-            Parameter[] params = ctor.getParameters();
-            if (params.length == 0) continue;
-            boolean allMatch = true;
-            for (Parameter p : params) {
-                String paramName = p.getName();
-                if (!exprByName.containsKey(paramName)) {
-                    allMatch = false;
-                    break;
-                }
-            }
-            if (allMatch) {
-                ctor.setAccessible(true);
-                return (Constructor<? extends T>) ctor;
-            }
+      Class<? extends T> type, Map<String, Expression<?>> exprByName) {
+    Constructor<?>[] ctors = type.getDeclaredConstructors();
+
+    for (Constructor<?> ctor : ctors) {
+      Parameter[] params = ctor.getParameters();
+      if (params.length == 0) continue;
+      boolean allMatch = true;
+      for (Parameter p : params) {
+        String paramName = p.getName();
+        if (!exprByName.containsKey(paramName)) {
+          allMatch = false;
+          break;
         }
+      }
+      if (allMatch) {
+        ctor.setAccessible(true);
+        return (Constructor<? extends T>) ctor;
+      }
+    }
 
-        Constructor<?> fallback = null;
-        for (Constructor<?> ctor : ctors) {
-            int paramCount = ctor.getParameterCount();
-            if (paramCount > 0 && paramCount <= exprByName.size()) {
-                if(fallback == null || ctor.getParameterCount() > fallback.getParameterCount()){
-                    fallback = ctor;
-                }
-            }
+    Constructor<?> fallback = null;
+    for (Constructor<?> ctor : ctors) {
+      int paramCount = ctor.getParameterCount();
+      if (paramCount > 0 && paramCount <= exprByName.size()) {
+        if (fallback == null || ctor.getParameterCount() > fallback.getParameterCount()) {
+          fallback = ctor;
         }
+      }
+    }
 
-        if(fallback != null){
-            fallback.setAccessible(true);
-            return (Constructor<? extends T>) fallback;
-        }
+    if (fallback != null) {
+      fallback.setAccessible(true);
+      return (Constructor<? extends T>) fallback;
+    }
 
-        throw new RuntimeException("No constructor in " + type.getSimpleName()
-                + " can be satisfied by entities: " + exprByName.keySet());
+    throw new RuntimeException(
+        "No constructor in "
+            + type.getSimpleName()
+            + " can be satisfied by entities: "
+            + exprByName.keySet());
   }
 
   private List<Expression<?>> buildArgsForConstructor(
-            Constructor<? extends T> ctor,
-            Map<String, Expression<?>> exprByName
-    ) {
-        List<Expression<?>> list = new ArrayList<>();
+      Constructor<? extends T> ctor, Map<String, Expression<?>> exprByName) {
+    List<Expression<?>> list = new ArrayList<>();
 
-        Parameter[] params = ctor.getParameters();
+    Parameter[] params = ctor.getParameters();
 
-        boolean unnamed = params.length > 0 && params[0].getName().startsWith("arg");
-        Field[] fields = unnamed ? ctor.getDeclaringClass().getDeclaredFields() : new Field[0];
+    boolean unnamed = params.length > 0 && params[0].getName().startsWith("arg");
+    Field[] fields = unnamed ? ctor.getDeclaringClass().getDeclaredFields() : new Field[0];
 
-        for (int i = 0; i < params.length; i++) {
-            String name = unnamed ? fields[i].getName() : params[i].getName();
-            Expression<?> expr = exprByName.get(name);
-            if (expr == null) {
-                throw new RuntimeException("No expression for parameter: " + name);
-            }
-            list.add(expr);
-        }
-        return list;
+    for (int i = 0; i < params.length; i++) {
+      String name = unnamed ? fields[i].getName() : params[i].getName();
+      Expression<?> expr = exprByName.get(name);
+      if (expr == null) {
+        throw new RuntimeException("No expression for parameter: " + name);
+      }
+      list.add(expr);
     }
+    return list;
+  }
 
   @Override
   public T newInstance(Object... args) {
@@ -128,6 +125,73 @@ public <R, C> R accept(Visitor<R, C> v, C context) {
     return null;
   }
 
+  /**
+   * Creates a {@link NameBasedProjection} instance for the given DTO class and entity.
+   *
+   * <p>Author: <b>Mouon (munhyunjune)</b>
+   *
+   * <h3>Purpose</h3>
+   *
+   * Simplifies QueryDSL projection by automatically binding entity fields to DTO constructor or
+   * field names. This eliminates the need to manually specify every field in {@code
+   * Projections.fields()} or {@code Projections.constructor()}, significantly reducing boilerplate
+   * code.
+   *
+   * <h3>Usage Example</h3>
+   *
+   * <pre>{@code
+   * QAnimal animal = QAnimal.animal;
+   *
+   * // Instead of writing:
+   * Projections.fields(AnimalDTO.class, animal.id, animal.name, animal.weight)
+   *
+   * // You can simply write:
+   * AnimalDTO dto = NameBasedProjection.binder(AnimalDTO.class, animal)
+   *     .newInstance(1, "Lion", 120);
+   * }</pre>
+   *
+   * <h3>Parameters</h3>
+   *
+   * <ul>
+   *   <li><b>type</b> — The DTO class type to project into.
+   *   <li><b>entity</b> — The QueryDSL {@link EntityPathBase} whose fields will be automatically
+   *       mapped.
+   * </ul>
+   *
+   * <h3>Return</h3>
+   *
+   * A new {@link NameBasedProjection} instance capable of instantiating the given DTO type using
+   * the entity's expressions.
+   *
+   * <h3>Matching Logic</h3>
+   *
+   * <ul>
+   *   <li>DTO constructor parameters are matched by <b>name</b> (not by order).
+   *   <li>Internally, {@code Map<String, Expression<?>> exprByName} is used to pair entity field
+   *       names with corresponding constructor parameter names.
+   *   <li>If compiled without {@code -parameters}, parameter names default to {@code arg0, arg1,
+   *       ...}, so the class fields’ order will be used as a fallback.
+   * </ul>
+   *
+   * <h3>Caution</h3>
+   *
+   * <ul>
+   *   <li>The DTO must have either:
+   *       <ul>
+   *         <li>a constructor whose parameter names match entity field names, or
+   *         <li>accessible fields whose names match entity field names.
+   *       </ul>
+   *   <li>If there is no matching field or constructor parameter for an entity expression, a {@link
+   *       RuntimeException} will be thrown.
+   *   <li>When using multiple entities (e.g. {@code new NameBasedProjection<>(Dto.class, user,
+   *       order)}), duplicate field names are resolved by the <b>first</b> entity provided.
+   * </ul>
+   *
+   * @param type the DTO class type to bind expressions to
+   * @param entity the QueryDSL entity path whose field expressions are used
+   * @param <T> the generic DTO type
+   * @return a new {@link NameBasedProjection} ready to create DTO instances
+   */
   public static <T> NameBasedProjection<T> binder(
       Class<? extends T> type, EntityPathBase<?> entity) {
     return new NameBasedProjection<>(type, entity);

querydsl-libraries/querydsl-core/src/test/java/com/querydsl/core/NameBasedProjectionTest.java

@@ -3,8 +3,8 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import com.querydsl.core.domain.QAnimal;
-import com.querydsl.core.types.Projections;
 import com.querydsl.core.types.NameBasedProjection;
+import com.querydsl.core.types.Projections;
 import java.sql.Date;
 import org.junit.Test;
 
@@ -126,7 +126,7 @@ public void testSimpleDTOProjectionWithFields() {
                 150 // weight
                 );
 
-    // Create DTO using SimpleDTOProjection.fields()
+    // Create DTO using NameBasedProjection.binder
     AnimalDTO dtoFromSimpleDTOProjection =
         NameBasedProjection.binder(AnimalDTO.class, animal)
             .newInstance(
@@ -145,4 +145,138 @@ public void testSimpleDTOProjectionWithFields() {
         .usingRecursiveComparison()
         .isEqualTo(dtoFromProjections);
   }
+
+  /**
+   * DTO class that merges Animal and Cat entity fields. Used only for testing multi-entity
+   * NameBasedProjection behavior.
+   */
+  public static class AnimalCatDTO {
+    private boolean alive;
+    private double bodyWeight;
+    private Date dateField;
+    private int id;
+    private String name;
+    private int toes;
+    private int weight;
+    private int breed; // Field from Cat entity
+
+    // Constructor with all fields
+    public AnimalCatDTO(
+        boolean alive,
+        double bodyWeight,
+        Date dateField,
+        int id,
+        String name,
+        int toes,
+        int weight,
+        int breed) {
+      this.alive = alive;
+      this.bodyWeight = bodyWeight;
+      this.dateField = dateField;
+      this.id = id;
+      this.name = name;
+      this.toes = toes;
+      this.weight = weight;
+      this.breed = breed;
+    }
+
+    // Default constructor
+    public AnimalCatDTO() {}
+
+    // Getters
+    public boolean isAlive() {
+      return alive;
+    }
+
+    public double getBodyWeight() {
+      return bodyWeight;
+    }
+
+    public Date getDateField() {
+      return dateField;
+    }
+
+    public int getId() {
+      return id;
+    }
+
+    public String getName() {
+      return name;
+    }
+
+    public int getToes() {
+      return toes;
+    }
+
+    public int getWeight() {
+      return weight;
+    }
+
+    public int getBreed() {
+      return breed;
+    }
+
+    @Override
+    public String toString() {
+      return "AnimalCatDTO{"
+          + "alive="
+          + alive
+          + ", bodyWeight="
+          + bodyWeight
+          + ", dateField="
+          + dateField
+          + ", id="
+          + id
+          + ", name='"
+          + name
+          + '\''
+          + ", toes="
+          + toes
+          + ", weight="
+          + weight
+          + ", breed="
+          + breed
+          + '}';
+    }
+  }
+
+  /**
+   * Test combining multiple entities (QAnimal and QCat) into one DTO using NameBasedProjection.
+   * This verifies that: - Multiple EntityPathBase arguments are supported. - Fields from both
+   * entities are mapped correctly. - When duplicate field names exist, the first entity's field
+   * (QAnimal) takes precedence.
+   */
+  @Test
+  public void testMultiEntityProjectionWithAnimalAndCat() {
+    QAnimal animal = QAnimal.animal;
+    com.querydsl.core.domain.QCat cat = com.querydsl.core.domain.QCat.cat;
+
+    // Create a Date object for testing
+    Date testDate = new Date(System.currentTimeMillis());
+
+    // Create a DTO that combines fields from both Animal and Cat entities
+    AnimalCatDTO dto =
+        new NameBasedProjection<>(AnimalCatDTO.class, animal, cat)
+            .newInstance(
+                true, // alive (from Animal)
+                55.2, // bodyWeight (from Animal)
+                testDate, // dateField (from Animal)
+                10, // id (from Animal)
+                "Kitty", // name (from Animal)
+                4, // toes (from Animal)
+                7, // weight (from Animal)
+                2 // breed (from Cat)
+                );
+
+    // Verify that all fields are correctly mapped
+    assertThat(dto).isNotNull();
+    assertThat(dto.isAlive()).isTrue();
+    assertThat(dto.getBodyWeight()).isEqualTo(55.2);
+    assertThat(dto.getDateField()).isEqualTo(testDate);
+    assertThat(dto.getId()).isEqualTo(10);
+    assertThat(dto.getName()).isEqualTo("Kitty");
+    assertThat(dto.getToes()).isEqualTo(4);
+    assertThat(dto.getWeight()).isEqualTo(7);
+    assertThat(dto.getBreed()).isEqualTo(2);
+  }
 }