feat(@QueryProjection): support builder-based Q class generation (#1078)

* feature: add builder properties in QueryProjection annotation

* feature: add builder properties in Constructor class

* feature: add public static inner class write methods

* feature: add QueryProjection Builder feature on annotation processor

* feature: add inner builder class and factory method to generated QClass

* test: add QueryProjectionBuilderTestEntity for test

* feature, test: add QueryProjectionBuilderTestEntity for GenericExporter

* question: how can i resolve binary incompatible change without this commit

* feature: add duplicate builder name check in TypeElementHandler

* docs: update javadoc for QueryProjection

* feature: enhance builder name validation in TypeElementHandler

* test: add unit tests for QueryProjectionBuilder

* Skip API validation on tooling projects

Signed-off-by: Marvin Froeder <[email protected]>

* modify: remove inner class, methods binary compatibility validation bypass option

---------

Signed-off-by: Marvin Froeder <[email protected]>
Co-authored-by: Marvin Froeder <[email protected]>

Author: Cole-SJ

pom.xml

@@ -453,6 +453,9 @@
         <version>0.23.1</version>
         <configuration>
           <parameter>
+            <excludes>
+              <exclude>com.querydsl.core.annotations.QueryProjection</exclude>          
+            </excludes>
             <ignoreMissingOldVersion>true</ignoreMissingOldVersion>
             <onlyModified>true</onlyModified>
             <breakBuildOnBinaryIncompatibleModifications>true</breakBuildOnBinaryIncompatibleModifications>
@@ -466,14 +469,6 @@
             <accessModifier>public</accessModifier>
           </parameter>
         </configuration>
-        <executions>
-          <execution>
-            <goals>
-              <goal>cmp</goal>
-            </goals>
-            <phase>verify</phase>
-          </execution>
-        </executions>
       </plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>

querydsl-libraries/pom.xml

@@ -138,6 +138,18 @@
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>com.github.siom79.japicmp</groupId>
+        <artifactId>japicmp-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <goals>
+              <goal>cmp</goal>
+            </goals>
+            <phase>verify</phase>
+          </execution>
+        </executions>
+      </plugin>
     </plugins>
   </build>
 

querydsl-libraries/querydsl-core/src/main/java/com/querydsl/core/annotations/QueryProjection.java

@@ -30,7 +30,7 @@
  *
  *     private String firstName, lastName;
  *
- *     {@code @QueryProjection}
+ *     {@code @QueryProjection(useBuilder = true, builderName = "new")}
  *     public UserInfo(String firstName, String lastName) {
  *         this.firstName = firstName;
  *         this.lastName = lastName;
@@ -49,8 +49,27 @@
  *     .select(new QUserInfo(user.firstName, user.lastName))
  *     .fetch();
  * }</pre>
+ *
+ * or(with Builder)
+ *
+ * <pre>{@code
+ * QUser user = QUser.user;
+ * List <UserInfo> result = querydsl.from(user)
+ *     .where(user.valid.eq(true))
+ *     .select(QUserInfo.builderNew()
+ *            .firstName(user.firstName)
+ *            .lastName(user.lastName)
+ *            .build()
+ *     )
+ *     .fetch();
+ * }</pre>
  */
 @Documented
 @Target({ElementType.CONSTRUCTOR, ElementType.TYPE})
 @Retention(RUNTIME)
-public @interface QueryProjection {}
+public @interface QueryProjection {
+
+  boolean useBuilder() default false;
+
+  String builderName() default "";
+}

querydsl-tooling/querydsl-apt/src/main/java/com/querydsl/apt/AbstractQuerydslProcessor.java

@@ -57,6 +57,7 @@
 import java.util.Set;
 import java.util.stream.Stream;
 import javax.annotation.processing.AbstractProcessor;
+import javax.annotation.processing.Messager;
 import javax.annotation.processing.RoundEnvironment;
 import javax.lang.model.SourceVersion;
 import javax.lang.model.element.AnnotationMirror;
@@ -164,7 +165,7 @@ protected void processAnnotations() {
     var altEntityAnn = conf.getAlternativeEntityAnnotation() != null;
     var superAnn = conf.getSuperTypeAnnotation() != null;
     for (TypeElement element : elements) {
-      var entityType = elementHandler.handleEntityType(element);
+      var entityType = elementHandler.handleEntityType(element, processingEnv.getMessager());
       registerTypeElement(entityType.getFullName(), element);
       if (typeFactory.isSimpleTypeEntity(element, conf.getEntityAnnotation())) {
         context.entityTypes.put(entityType.getFullName(), entityType);
@@ -189,7 +190,7 @@ protected void processAnnotations() {
       if (!context.allTypes.containsKey(fullName)) {
         var element = processingEnv.getElementUtils().getTypeElement(fullName);
         if (element != null) {
-          elementHandler.handleEntityType(element);
+          elementHandler.handleEntityType(element, processingEnv.getMessager());
         }
       }
     }
@@ -206,7 +207,7 @@ protected void processAnnotations() {
       addSupertypeFields(entityType, handled);
     }
 
-    processProjectionTypes(elements);
+    processProjectionTypes(elements, processingEnv.getMessager());
 
     // extend entity types
     typeFactory.extendTypes();
@@ -231,7 +232,8 @@ private void addExternalParents(EntityType entityType) {
             && !TypeUtils.hasAnnotationOfType(typeElement, conf.getEntityAnnotations())) {
           continue;
         }
-        var superEntityType = elementHandler.handleEntityType(typeElement);
+        var superEntityType =
+            elementHandler.handleEntityType(typeElement, processingEnv.getMessager());
         if (superEntityType.getSuperType() != null) {
           superTypes.push(superEntityType.getSuperType().getType());
         }
@@ -306,7 +308,7 @@ protected Set<TypeElement> collectElements() {
       // register found elements
       for (TypeElement element : embeddedElements) {
         if (!elements.contains(element)) {
-          elementHandler.handleEntityType(element);
+          elementHandler.handleEntityType(element, processingEnv.getMessager());
         }
       }
     }
@@ -343,20 +345,20 @@ private void registerTypeElement(String entityName, TypeElement element) {
     elements.add(element);
   }
 
-  private void processProjectionTypes(Set<TypeElement> elements) {
+  private void processProjectionTypes(Set<TypeElement> elements, Messager messager) {
     Set<Element> visited = new HashSet<>();
     for (Element element : getElements(QueryProjection.class)) {
       if (element.getKind() == ElementKind.CONSTRUCTOR) {
         var parent = element.getEnclosingElement();
         if (!elements.contains(parent) && !visited.contains(parent)) {
-          var model = elementHandler.handleProjectionType((TypeElement) parent, true);
+          var model = elementHandler.handleProjectionType((TypeElement) parent, true, messager);
           registerTypeElement(model.getFullName(), (TypeElement) parent);
           context.projectionTypes.put(model.getFullName(), model);
           visited.add(parent);
         }
       }
       if (element.getKind().isClass() && !visited.contains(element)) {
-        var model = elementHandler.handleProjectionType((TypeElement) element, false);
+        var model = elementHandler.handleProjectionType((TypeElement) element, false, messager);
         registerTypeElement(model.getFullName(), (TypeElement) element);
         context.projectionTypes.put(model.getFullName(), model);
         visited.add(element);

querydsl-tooling/querydsl-apt/src/main/java/com/querydsl/apt/TypeElementHandler.java

@@ -23,6 +23,7 @@
 import com.querydsl.codegen.utils.model.TypeCategory;
 import com.querydsl.core.annotations.PropertyType;
 import com.querydsl.core.annotations.QueryInit;
+import com.querydsl.core.annotations.QueryProjection;
 import com.querydsl.core.annotations.QueryType;
 import com.querydsl.core.util.Annotations;
 import com.querydsl.core.util.BeanUtils;
@@ -34,12 +35,14 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import javax.annotation.processing.Messager;
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.element.VariableElement;
 import javax.lang.model.type.TypeMirror;
 import javax.lang.model.util.ElementFilter;
+import javax.tools.Diagnostic;
 
 /**
  * {@code TypeElementHandler} is an APT visitor for entity types
@@ -67,7 +70,7 @@ public TypeElementHandler(
     this.queryTypeFactory = queryTypeFactory;
   }
 
-  public EntityType handleEntityType(TypeElement element) {
+  public EntityType handleEntityType(TypeElement element, Messager messager) {
     EntityType entityType = typeFactory.getEntityType(element.asType(), true);
     List<? extends Element> elements = element.getEnclosedElements();
     var config = configuration.getConfig(element, elements);
@@ -78,7 +81,7 @@ public EntityType handleEntityType(TypeElement element) {
 
     // constructors
     if (config.visitConstructors()) {
-      handleConstructors(entityType, elements, true);
+      handleConstructors(entityType, elements, true, messager);
     }
 
     // fields
@@ -175,13 +178,14 @@ private Property toProperty(
     return new Property(entityType, name, propertyType, inits);
   }
 
-  public EntityType handleProjectionType(TypeElement e, boolean onlyAnnotatedConstructors) {
+  public EntityType handleProjectionType(
+      TypeElement e, boolean onlyAnnotatedConstructors, Messager messager) {
     Type c = typeFactory.getType(e.asType(), true);
     var entityType =
         new EntityType(c.as(TypeCategory.ENTITY), configuration.getVariableNameFunction());
     typeMappings.register(entityType, queryTypeFactory.create(entityType));
     List<? extends Element> elements = e.getEnclosedElements();
-    handleConstructors(entityType, elements, onlyAnnotatedConstructors);
+    handleConstructors(entityType, elements, onlyAnnotatedConstructors, messager);
     return entityType;
   }
 
@@ -198,11 +202,40 @@ private Type getType(VariableElement element) {
   }
 
   private void handleConstructors(
-      EntityType entityType, List<? extends Element> elements, boolean onlyAnnotatedConstructors) {
+      EntityType entityType,
+      List<? extends Element> elements,
+      boolean onlyAnnotatedConstructors,
+      Messager messager) {
+    var builderNameSet = new HashSet<String>();
     for (ExecutableElement constructor : ElementFilter.constructorsIn(elements)) {
       if (configuration.isValidConstructor(constructor, onlyAnnotatedConstructors)) {
         var parameters = transformParams(constructor.getParameters());
-        entityType.addConstructor(new Constructor(parameters));
+        QueryProjection projection = constructor.getAnnotation(QueryProjection.class);
+        if (projection != null
+            && projection.useBuilder()
+            && projection.builderName().trim().isEmpty()) {
+          messager.printMessage(
+              Diagnostic.Kind.ERROR,
+              "@QueryProjection with builder=true requires a non-empty builderName",
+              constructor);
+          return;
+        }
+
+        Constructor constructorModel = new Constructor(parameters);
+        constructorModel.setUseBuilder(projection != null && projection.useBuilder());
+        constructorModel.setBuilderName(projection != null ? projection.builderName() : "");
+
+        if (constructorModel.useBuilder()
+            && builderNameSet.contains(constructorModel.getBuilderName())) {
+          messager.printMessage(
+              Diagnostic.Kind.ERROR,
+              "Duplicate builderName found: " + constructorModel.getBuilderName(),
+              constructor);
+          return;
+        }
+
+        builderNameSet.add(constructorModel.getBuilderName());
+        entityType.addConstructor(constructorModel);
       }
     }
   }

querydsl-tooling/querydsl-apt/src/test/java/com/querydsl/apt/GenericExporterTest.java

@@ -50,6 +50,7 @@ public void execute() throws IOException {
     expected.add("QQueryProjectionTest_EntityWithProjection.java");
     expected.add("QEmbeddable3Test_EmbeddableClass.java");
     expected.add("QQueryEmbedded4Test_User.java");
+    expected.add("QQueryProjectionBuilderTestEntity.java");
 
     execute(expected, "GenericExporterTest", "QuerydslAnnotationProcessor");
   }
@@ -89,6 +90,7 @@ public void execute2() throws IOException {
     expected.add("QOneToOneTest_Person.java");
     expected.add("QGeneric16Test_HidaBez.java");
     expected.add("QGeneric16Test_HidaBezGruppe.java");
+    expected.add("QQueryProjectionBuilderTestEntity.java");
 
     execute(expected, "GenericExporterTest2", "HibernateAnnotationProcessor");
   }

querydsl-tooling/querydsl-apt/src/test/java/com/querydsl/apt/domain/QueryProjectionBuilderTest.java

@@ -0,0 +1,34 @@
+package com.querydsl.apt.domain;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+
+import com.querydsl.core.types.dsl.Expressions;
+import org.junit.Test;
+
+public class QueryProjectionBuilderTest {
+
+  @Test
+  public void builder_buildsQClassCorrectly() {
+    var property = Expressions.stringPath("x");
+    QQueryProjectionBuilderTestEntity dto =
+        QQueryProjectionBuilderTestEntity.builderTest1().setProperty(property).build();
+
+    assertNotNull(dto);
+    assertEquals(QueryProjectionBuilderTestEntity.class, dto.getType());
+  }
+
+  @Test
+  public void builder_buildsQClassCorrectly2() {
+    var property = Expressions.stringPath("x");
+    var intProperty = Expressions.numberPath(Integer.class, "y");
+    QQueryProjectionBuilderTestEntity dto =
+        QQueryProjectionBuilderTestEntity.builderTest2()
+            .setProperty(property)
+            .setIntProperty(intProperty)
+            .build();
+
+    assertNotNull(dto);
+    assertEquals(QueryProjectionBuilderTestEntity.class, dto.getType());
+  }
+}

querydsl-tooling/querydsl-apt/src/test/java/com/querydsl/apt/domain/QueryProjectionBuilderTestEntity.java

@@ -0,0 +1,32 @@
+package com.querydsl.apt.domain;
+
+import com.querydsl.core.annotations.QueryProjection;
+
+public class QueryProjectionBuilderTestEntity {
+  private String property;
+  private int intProperty;
+  private Test test;
+
+  @QueryProjection(useBuilder = true, builderName = "Test1")
+  public QueryProjectionBuilderTestEntity(String property) {
+    this.property = property;
+  }
+
+  @QueryProjection(useBuilder = true, builderName = "Test2")
+  public QueryProjectionBuilderTestEntity(String property, int intProperty) {
+    this.property = property;
+    this.intProperty = intProperty;
+  }
+
+  @QueryProjection(useBuilder = true, builderName = "Test3")
+  public QueryProjectionBuilderTestEntity(String property, int intProperty, Test test) {
+    this.property = property;
+    this.intProperty = intProperty;
+    this.test = test;
+  }
+
+  public static class Test {
+    private String property;
+    private int intProperty;
+  }
+}

querydsl-tooling/querydsl-codegen-utils/src/main/java/com/querydsl/codegen/utils/CodeWriter.java

@@ -41,6 +41,11 @@ public interface CodeWriter extends Appendable {
 
   CodeWriter beginClass(Type type, Type superClass, Type... interfaces) throws IOException;
 
+  CodeWriter beginInnerStaticClass(Type type) throws IOException;
+
+  CodeWriter beginInnerStaticClass(Type type, Type superClass, Type... interfaces)
+      throws IOException;
+
   <T> CodeWriter beginConstructor(Collection<T> params, Function<T, Parameter> transformer)
       throws IOException;
 

querydsl-tooling/querydsl-codegen-utils/src/main/java/com/querydsl/codegen/utils/JavaWriter.java

@@ -57,6 +57,8 @@ public final class JavaWriter extends AbstractCodeWriter<JavaWriter> {
 
   private static final String PUBLIC_CLASS = "public class ";
 
+  private static final String PUBLIC_STATIC_CLASS = "public static class ";
+
   private static final String PUBLIC_FINAL = "public final ";
 
   private static final String PUBLIC_INTERFACE = "public interface ";
@@ -202,6 +204,33 @@ public JavaWriter beginClass(Type type, Type superClass, Type... interfaces) thr
     return this;
   }
 
+  @Override
+  public CodeWriter beginInnerStaticClass(Type type) throws IOException {
+    return beginInnerStaticClass(type, null);
+  }
+
+  @Override
+  public CodeWriter beginInnerStaticClass(Type type, Type superClass, Type... interfaces)
+      throws IOException {
+    beginLine(PUBLIC_STATIC_CLASS, type.getGenericName(false, packages, classes));
+    if (superClass != null) {
+      append(EXTENDS).append(superClass.getGenericName(false, packages, classes));
+    }
+    if (interfaces.length > 0) {
+      append(IMPLEMENTS);
+      for (int i = 0; i < interfaces.length; i++) {
+        if (i > 0) {
+          append(Symbols.COMMA);
+        }
+        append(interfaces[i].getGenericName(false, packages, classes));
+      }
+    }
+    append(" {").nl().nl();
+    goIn();
+    types.push(type);
+    return this;
+  }
+
   @Override
   public <T> JavaWriter beginConstructor(
       Collection<T> parameters, Function<T, Parameter> transformer) throws IOException {