mvc: Add BindParam annotation for custom parsing/mapping

- Add extra lookup for mapping function
- Add some docs
- ref  #3472

Author: jknack

docs/asciidoc/mvc-api.adoc

@@ -383,6 +383,75 @@ class MyController {
 }
 ----
 
+==== Bind
+
+You can use the javadoc:annotation.BindParam[] annotation which allow custom mapping from HTTP request.
+
+.Use the annotation
+[source, java, role = "primary"]
+----
+public class Controller {
+
+  @GET("/{foo}")
+  public String bind(@BindParam MyBean bean) {
+    return "with custom mapping: " + bean;
+  }
+}
+----
+
+.Kotlin
+[source, kotlin, role = "secondary"]
+----
+class Controller {
+
+  @GET("/{foo}")
+  fun bind(@BindParam bean: MyBean) = "with custom mapping: $bean"
+}
+----
+
+.Write the mapping function
+[source, java, role = "primary"]
+----
+public record MyBean(String value) {
+
+  public static MyBean of(Context ctx) {
+    // build MyBean from HTTP request
+  }
+}
+----
+
+.Kotlin
+[source, kotlin, role = "secondary"]
+----
+class MyBean constructor(value: String) {
+
+  companion object {
+       @JvmStatic
+       fun of(ctx: Context) : Person {
+          // build MyBean from HTTP request
+       }
+  }
+}
+----
+
+It works as:
+
+- The javadoc:annotation.BindParam[] allow you to convert HTTP request to an Java Object in the way you wish
+- The annotation looks for public method/function that takes a javadoc:Context[] as parameter and returns the same type required as parameter.
+- It looks in the parameter type or fallback into the controller class
+
+Alternative you can specify the factory class:
+
+----
+   @BindParam(MyFactoryClass.class)
+----
+
+And/or function name:
+
+----
+   @BindParam(value = MyFactoryClass.class, fn = "fromContext")
+----
+
 ==== Flash
 
 Provisioning of flash attribute is available via javadoc:annotation.FlashParam[] annotation:

jooby/src/main/java/io/jooby/annotation/BindParam.java

@@ -20,9 +20,11 @@
 @Target({ElementType.PARAMETER, ElementType.ANNOTATION_TYPE})
 public @interface BindParam {
   /**
-   * Class containing the mapping function.
+   * Class containing the mapping function. If no class is specified it looks at:
    *
-   * @return Default to controller class.
+   * <p>- Parameter type for {@link #fn()} method. - Or fallback to controller class.
+   *
+   * @return Source of mapping function.
    */
   Class<?> value() default void.class;
 

modules/jooby-apt/src/main/java/io/jooby/internal/apt/ParameterGenerator.java

@@ -17,9 +17,7 @@
 import java.util.function.Predicate;
 import java.util.stream.Stream;
 
-import javax.lang.model.element.AnnotationMirror;
-import javax.lang.model.element.ExecutableElement;
-import javax.lang.model.element.Modifier;
+import javax.lang.model.element.*;
 
 public enum ParameterGenerator {
   ContextParam("getAttribute", "io.jooby.annotation.ContextParam", "jakarta.ws.rs.core.Context") {
@@ -116,32 +114,37 @@ public String toSourceCode(
         TypeDefinition type,
         String name,
         boolean nullable) {
+      List<Element> converters = new ArrayList<>();
       var typeNames = findAnnotationValue(annotation, AnnotationSupport.VALUE);
       var typeName = typeNames.isEmpty() ? null : typeNames.get(0);
       var router = route.getRouter();
       var targetType = router.getTargetType();
-      var converter =
-          typeName == null
-              ? targetType
-              : route
-                  .getContext()
-                  .getProcessingEnvironment()
-                  .getElementUtils()
-                  .getTypeElement(typeName);
+      var env = route.getContext().getProcessingEnvironment();
+      if (typeName != null) {
+        converters.add(env.getElementUtils().getTypeElement(typeName));
+      } else {
+        // Fallback bean class first
+        converters.add(env.getTypeUtils().asElement(type.getRawType()));
+        // Fallback controller class later
+        converters.add(targetType);
+      }
       var fns = findAnnotationValue(annotation, "fn"::equals);
       var fn = fns.isEmpty() ? null : fns.get(0);
       Predicate<ExecutableElement> contextAsParameter =
           it ->
               it.getParameters().size() == 1
                   && it.getParameters().get(0).asType().toString().equals("io.jooby.Context");
-      Predicate<ExecutableElement> matchesReturnType =
-          it ->
-              new TypeDefinition(
-                      route.getContext().getProcessingEnvironment().getTypeUtils(),
-                      it.getReturnType())
-                  .getRawType()
-                  .equals(type.getRawType());
-      var filter = contextAsParameter.and(matchesReturnType);
+      Predicate<ExecutableElement> matchesType =
+          it -> {
+            var returnType =
+                new TypeDefinition(
+                        route.getContext().getProcessingEnvironment().getTypeUtils(),
+                        it.getReturnType())
+                    .getRawType();
+            return returnType.equals(type.getRawType())
+                || (it.getSimpleName().toString().equals("<init>"));
+          };
+      var filter = contextAsParameter.and(matchesType);
       String methodErrorName;
       if (fn != null) {
         Predicate<ExecutableElement> matchesName = it -> it.getSimpleName().toString().equals(fn);
@@ -152,7 +155,8 @@ public String toSourceCode(
       }
       // find function by type
       ExecutableElement mapping =
-          converter.getEnclosedElements().stream()
+          converters.stream()
+              .flatMap(it -> it.getEnclosedElements().stream())
               .filter(ExecutableElement.class::isInstance)
               .map(ExecutableElement.class::cast)
               // filter by Context
@@ -161,21 +165,23 @@ public String toSourceCode(
               .orElseThrow(
                   () ->
                       new IllegalArgumentException(
-                          "Method not found: " + converter + ".[unnamed]" + methodErrorName));
+                          "Method not found: " + methodErrorName + " on " + converters));
       if (!mapping.getModifiers().contains(Modifier.PUBLIC)) {
-        throw new IllegalArgumentException("Method is not public: " + converter + "." + mapping);
+        throw new IllegalArgumentException(
+            "Method is not public: " + mapping.getEnclosingElement() + "." + mapping);
       }
       if (mapping.getModifiers().contains(Modifier.STATIC)) {
         return CodeBlock.of(
-            converter.equals(targetType)
-                ? mapping.getSimpleName()
-                : converter.getQualifiedName() + "." + mapping.getSimpleName(),
-            "(ctx)");
+            mapping.getEnclosingElement().asType() + "." + mapping.getSimpleName(), "(ctx)");
       } else {
-        if (converter.equals(targetType)) {
+        if (mapping.getEnclosingElement().equals(targetType)) {
           return CodeBlock.of("c." + mapping.getSimpleName(), "(ctx)");
         } else {
-          throw new IllegalArgumentException("Not a static method: " + converter + "." + mapping);
+          if (mapping.getKind() == ElementKind.CONSTRUCTOR) {
+            return CodeBlock.of(kt ? "" : "new ", type.getName(), "(ctx)");
+          }
+          throw new IllegalArgumentException(
+              "Not a static method: " + mapping.getEnclosingElement() + "." + mapping);
         }
       }
     }

modules/jooby-apt/src/test/java/tests/i3472/BeanMapping.java

@@ -9,6 +9,10 @@
 
 public class BeanMapping {
   public static BindBean map(Context ctx) {
-    return new BindBean("extends:" + ctx.query("value").value());
+    return new BindBean("mapping:" + ctx.query("value").value());
+  }
+
+  public static BindBean withName(Context ctx) {
+    return new BindBean("withName:" + ctx.query("value").value());
   }
 }

modules/jooby-apt/src/test/java/tests/i3472/BindBean.java

@@ -10,6 +10,6 @@
 public record BindBean(String value) {
 
   public static BindBean of(Context ctx) {
-    return new BindBean("static:" + ctx.query("value").value());
+    return new BindBean("bean-factory-method:" + ctx.query("value").value());
   }
 }

modules/jooby-apt/src/test/java/tests/i3472/BindBeanConstructor.java

@@ -0,0 +1,22 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package tests.i3472;
+
+import io.jooby.Context;
+
+public class BindBeanConstructor {
+
+  private final String value;
+
+  public BindBeanConstructor(Context ctx) {
+    this.value = "bean-constructor:" + ctx.query("value").value();
+  }
+
+  @Override
+  public String toString() {
+    return value;
+  }
+}

modules/jooby-apt/src/test/java/tests/i3472/BindController.java

@@ -0,0 +1,8 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package tests.i3472;
+
+public record BindController(String value) {}

modules/jooby-apt/src/test/java/tests/i3472/C3472.java

@@ -5,37 +5,19 @@
  */
 package tests.i3472;
 
-import io.jooby.Context;
 import io.jooby.annotation.BindParam;
 import io.jooby.annotation.GET;
 
 public class C3472 {
 
-  @GET("/3472")
-  public BindBean bind(@BindParam BindBean bean) {
+  @GET("/3472/mapping")
+  public BindBean bind(@BindParam(BeanMapping.class) BindBean bean) {
     return bean;
   }
 
-  @GET("/3472/named")
-  public BindBean bindName(@BindParam(fn = "bindWithName") BindBean bean) {
+  @GET("/3472/withName")
+  public BindBean bindWithName(
+      @BindParam(value = BeanMapping.class, fn = "withName") BindBean bean) {
     return bean;
   }
-
-  @GET("/3472/static")
-  public BindBean bindStatic(@BindParam(BindBean.class) BindBean bean) {
-    return bean;
-  }
-
-  @GET("/3472/extends")
-  public BindBean bindExtends(@SubAnnotation BindBean bean) {
-    return bean;
-  }
-
-  public BindBean convert(Context ctx) {
-    return new BindBean(ctx.query("value").value());
-  }
-
-  public BindBean bindWithName(Context ctx) {
-    return new BindBean("fn:" + ctx.query("value").value());
-  }
 }

modules/jooby-apt/src/test/java/tests/i3472/C3472b.java

@@ -0,0 +1,22 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package tests.i3472;
+
+import io.jooby.annotation.BindParam;
+import io.jooby.annotation.GET;
+
+public class C3472b {
+
+  @GET("/3472/bean-factory-method")
+  public BindBean bind(@BindParam BindBean bean) {
+    return bean;
+  }
+
+  @GET("/3472/bean-constructor")
+  public String bind(@BindParam BindBeanConstructor bean) {
+    return bean.toString();
+  }
+}

modules/jooby-apt/src/test/java/tests/i3472/C3472c.java

@@ -0,0 +1,22 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package tests.i3472;
+
+import io.jooby.Context;
+import io.jooby.annotation.BindParam;
+import io.jooby.annotation.GET;
+
+public class C3472c {
+
+  @GET("/3472/bean-controller")
+  public BindController bind(@BindParam BindController bean) {
+    return bean;
+  }
+
+  public BindController create(Context ctx) {
+    return new BindController("bean-controller:" + ctx.query("value").value());
+  }
+}