feat: @Param method option (#120)

* feat(framework): Add @param method and type

* feat(framework): Implement @param method and type in ReflectionSidecar

* feat(processor): Implement @param method and type in FxClassGenerator

* test(processor): Update ParamController

* docs: Update parameters and data flow docs

* chore: Remove unused import

* docs: Clarify bind/unbind in data flow

* fix(framework): ReflectionSidecar error cases

* docs: Update ERROR_CODES.md

---------

Co-authored-by: Clashsoft <Clashsoft@users.noreply.github.com>

ERROR_CODES.md

@@ -413,7 +413,7 @@ This can happen if one uses `show("../")` whilst already being at the empty rout
 
 This error is thrown when the framework fails to put a parameter value into a field.
 
-### 4001: `Couldn't call setter method with parameter '*' for field '*' in class '*'.`
+### 4001: `Couldn't call setter method '*' with parameter '*' for field '*' in class '*'.`
 
 - Runtime: ✅
 - Annotation Processor: ❌

annotation-processor/src/main/java/org/fulib/fx/FxClassGenerator.java

@@ -12,10 +12,7 @@
 import org.fulib.fx.util.ControllerUtil;
 
 import javax.annotation.processing.ProcessingEnvironment;
-import javax.lang.model.element.ExecutableElement;
-import javax.lang.model.element.Modifier;
-import javax.lang.model.element.TypeElement;
-import javax.lang.model.element.VariableElement;
+import javax.lang.model.element.*;
 import javax.lang.model.type.DeclaredType;
 import javax.lang.model.type.ExecutableType;
 import javax.lang.model.type.TypeMirror;
@@ -30,16 +27,6 @@ public class FxClassGenerator {
     private final ProcessingEnvironment processingEnv;
     private final ProcessingHelper helper;
 
-    /**
-     * The (erased) `javafx.beans.value.WritableValue` type.
-     */
-    private final TypeMirror writableValue;
-
-    /**
-     * The `setValue` method of `javafx.beans.value.WritableValue`.
-     */
-    private final ExecutableElement genericSetValue;
-
     /**
      * The `javafx.scene.Parent` type.
      */
@@ -53,17 +40,6 @@ public FxClassGenerator(ProcessingHelper helper, ProcessingEnvironment processin
         this.helper = helper;
         this.processingEnv = processingEnv;
 
-        final TypeElement writableValue = processingEnv.getElementUtils().getTypeElement("javafx.beans.value.WritableValue");
-        this.writableValue = processingEnv.getTypeUtils().erasure(writableValue.asType());
-
-        genericSetValue = writableValue.getEnclosedElements()
-            .stream()
-            .filter(e -> e instanceof ExecutableElement)
-            .map(e -> (ExecutableElement) e)
-            .filter(e -> "setValue".equals(e.getSimpleName().toString()))
-            .findFirst()
-            .orElseThrow();
-
         parent = processingEnv.getElementUtils().getTypeElement("javafx.scene.Parent").asType();
         pane = processingEnv.getElementUtils().getTypeElement("javafx.scene.layout.Pane").asType();
     }
@@ -154,29 +130,20 @@ private void generateParametersIntoFields(PrintWriter out, TypeElement component
             out.printf("    if (params.containsKey(%s)) {%n", paramNameLiteral);
 
             // TODO field must be public, package-private or protected -- add a diagnostic if it's private
-            if (processingEnv.getTypeUtils().isAssignable(field.asType(), writableValue)) {
-                // We use the `setValue` method to infer the actual type of the field,
-                // E.g. if the field is a `StringProperty` which extends `WritableValue<String>`,
-                // we can infer that the actual type is `String`.
-                final ExecutableType asMemberOf = (ExecutableType) processingEnv.getTypeUtils().asMemberOf((DeclaredType) field.asType(), genericSetValue);
-                final TypeMirror typeArg = asMemberOf.getParameterTypes().get(0);
-                final String writableType = typeArg.toString();
-                if (field.getModifiers().contains(Modifier.FINAL)) {
-                    out.printf("      instance.%s.setValue((%s) params.get(%s));%n", fieldName, writableType, paramNameLiteral);
-                } else {
-                    // final Object param = params.get(<paramNameLiteral>);
-                    // if (param instanceof <writableValue>) {
-                    //   instance.<fieldName> = (<fieldType>) param);
-                    // } else {
-                    //   instance.<fieldName>.setValue((<writableType>) param);
-                    // }
-                    out.printf("      final Object param = params.get(%s);%n", paramNameLiteral);
-                    out.printf("      if (param instanceof %s) {%n", writableValue);
-                    out.printf("        instance.%s = (%s) param;%n", fieldName, fieldType);
-                    out.println("      } else {");
-                    out.printf("        instance.%s.setValue((%s) param);%n", fieldName, writableType);
-                    out.println("      }");
-                }
+            final String methodName = param.method();
+            if (methodName != null && !methodName.isEmpty()) {
+                // this is some hacky way to get the @Param().type().
+                // param.type() does not work because we cannot access the Class<?> instance at compile time.
+                // So we have to read the AnnotationMirror.
+                final AnnotationMirror paramMirror = field.getAnnotationMirrors().stream()
+                    .filter(a -> "org.fulib.fx.annotation.param.Param".equals(a.getAnnotationType().toString()))
+                    .findFirst().orElseThrow();
+                final String methodParamType = paramMirror.getElementValues().values().stream()
+                    .map(Object::toString)
+                    .filter(s -> s.endsWith(".class"))
+                    .map(s -> s.substring(0, s.length() - 6)) // remove ".class"
+                    .findFirst().orElse("Object"); // else case also happens when type is not specified in the annotation (default Object)
+                out.printf("      instance.%s.%s((%s) params.get(%s));%n", fieldName, methodName, methodParamType, paramNameLiteral);
             } else {
                 out.printf("      instance.%s = (%s) params.get(%s);%n", fieldName, fieldType, paramNameLiteral);
             }

docs/controller/4-parameters.md

@@ -4,15 +4,11 @@ To pass parameters to a controller, an additional argument can be provided to th
 strings and objects. The strings specify the argument's name and the objects are the value of the argument. For example,
 `show("/route/to/controller", Map.of("key", value, "key2", value2))` will pass the value `value` to the argument `key`.
 
-To use a passed argument in a field or method, you have to annotate it with `@Param("key")`. The name of the parameter
-will be used to match it to the map of parameters passed to the `show()` method. If the annotation is used on a field,
-the field will be injected with the value of the parameter before the controller is initialized. If the annotation is used
-on a method, the method will be called with the value of the parameter before the controller is initialized. If the
-annotation is used on a method parameter of a render/init method, the method will be called with the value of the parameter.
-
-If `@Param` is used on a field containing a `WriteableValue` (e.g. a `StringProperty`), its value will be set to the
-parameter's value if the parameter has the correct type (e.g. a `String` for a `StringProperty`). If the parameter is
-a `WritableValue` as well, the logic will be the same as for a normal field.
+To use a passed argument in a field or method, you have to annotate it with `@Param("key")`.
+The name of the parameter will be used to match it to the map of parameters passed to the `show()` method.
+If the annotation is used on a field, the field will be injected with the value of the parameter before the controller is initialized.
+If the annotation is used on a method, the method will be called with the value of the parameter before the controller is initialized.
+If the annotation is used on a method parameter of a render/init method, the method will be called with the value of the parameter.
 
 Instead of accessing the parameters one by one, you can also use the `@ParamsMap` annotation to inject a map of all parameters.
 This annotation can be used for fields and method parameters of type `Map<String, Object>`. If the annotated field is final,
@@ -34,9 +30,10 @@ public class FooController {
     @Param("baba")
     private Bar bar;
 
-    // The set method of the writable value will be called with the parameter 'fofo'
-    @Param("fofo")
-    private ObjectProperty<Foo> foo = new SimpleObjectProperty<>();
+    // The setValue(T) method of the ObjectProperty will be called with the parameter named 'fofo'
+    // Note that the erased parameter type of ObjectProperty.setValue is Object, so we specify that as the type.
+    @Param(value = "fofo", method = "setValue", type = Object.class)
+    private final ObjectProperty<Foo> foo = new SimpleObjectProperty<>();
 
     // This field will be injected with a map of all parameters before the controller is initialized
     @ParamsMap

docs/tutorial/data-flow.md

@@ -119,18 +119,36 @@ Instead of defining a Runnable or Consumer directly, you can create a Property a
 ```java
 @Component
 public class MyComponent {
-
-  @Param("colorChange")
+  // option 1: The subcomponent reuses the parent's property instance.
+  @Param("color")
   ObjectProperty<Color> color;
 
-  @Param("colorBind")
-  // As this field is final, bind() will be used instead
-  final ObjectProperty<Color> otherColor = new SimpleObjectProperty<>();
+  // Option 2: The subcomponent uses its own property instance and binds it to the parent's property.
+  // Writing to this property will NOT update the parent's property.
+  // We have to unbind using destroy.
+  @Param(value = "color", method = "bind", type = Object.class)
+  final ObjectProperty<Color> colorBind = new SimpleObjectProperty<>();
+
+  // Option 3: The subcomponent uses its own property instance and binds it to the parent's property bidirectionally.
+  // Writing to this property will update the parent's property.
+  // We have to manually bind using subscriber to allow for unbinding.
+  final ObjectProperty<Color> colorBindBidi = new SimpleObjectProperty<>();
+  Subscriber subscriber = ...;
+
+  @OnInit
+  void init(@Param("color") ObjectProperty<Color> color) {
+    subscriber.bindBidirectional(colorBindBidi, color);
+  }
 
   void onButtonClicked() {
     Color newColor = ...;
     color.set(newColor);
   }
+
+  @OnDestroy
+  void destroy() {
+    colorBind.unbind();
+  }
 }
 ```
 
@@ -143,8 +161,7 @@ public class MyController {
   @OnRender
   void createSubs() {
     ObjectProperty<Color> color = new SimpleObjectProperty(Color.WHITE);
-    ObjectProperty<Color> colorBind = new SimpleObjectProperty(Color.WHITE);
-    MyComponent component = app.initAndRender(new MyComponent(), Map.of("colorChange", color, "colorBind", colorBind));
+    MyComponent component = app.initAndRender(new MyComponent(), Map.of("color", color));
     subscriber.listen(color, (observable, oldValue, newValue) -> { // Use subscribers to prevent memory leaks
       System.out.println(newValue);
     });

framework/src/main/java/org/fulib/fx/annotation/param/Param.java

@@ -31,4 +31,16 @@
      */
     String value();
 
+    /**
+     * The method of the field's class that will be called with the parameter's value.
+     * Useful for {@code final} fields or {@link javafx.beans.property.Property} fields.
+     * @return the method name
+     */
+    String method() default "";
+
+    /**
+     * When using {@link #method()}, this specifies the type of the first (and only) parameter of that method.
+     * @return the type of the method parameter
+     */
+    Class<?> type() default Object.class;
 }

framework/src/main/java/org/fulib/fx/controller/internal/ReflectionSidecar.java

@@ -1,6 +1,5 @@
 package org.fulib.fx.controller.internal;
 
-import javafx.beans.value.WritableValue;
 import javafx.event.EventHandler;
 import javafx.event.EventType;
 import javafx.scene.Node;
@@ -146,18 +145,22 @@ private void fillParametersIntoFields(@NotNull Object instance, @NotNull Map<@No
                 Object value = parameters.get(param);
                 Object fieldValue = field.get(instance);
 
-                // If the field is a WriteableValue, use the setValue method
-                if (WritableValue.class.isAssignableFrom(fieldType) && !(value instanceof WritableValue)) {
+                String method = paramAnnotation.method();
+                if (method != null && !method.isEmpty()) {
 
-                    // We cannot call setValue on a non-existing property
+                    // We cannot call the method on a non-existing property
                     if (fieldValue == null) {
-                        throw new RuntimeException(error(4001).formatted(param, field.getName(), instance.getClass().getName()));
+                        throw new RuntimeException(error(4001).formatted(method, param, field.getName(), instance.getClass().getName()));
                     }
 
+                    final Class<?> methodParamType = paramAnnotation.type();
                     try {
-                        ((WritableValue<Object>) field.get(instance)).setValue(value);
-                    } catch (ClassCastException e) {
-                        throw new RuntimeException(error(4007).formatted(param, field.getName(), instance.getClass().getName(), fieldType.getName(), value == null ? "null" : value.getClass().getName()));
+                        final Method methodName = field.getType().getMethod(method, methodParamType);
+                        methodName.invoke(fieldValue, value);
+                    } catch (IllegalArgumentException iae) { // parameter types don't match
+                        throw new RuntimeException(error(4007).formatted(param, field.getName(), instance.getClass().getName(), methodParamType.getName(), value == null ? "null" : value.getClass().getName()), iae);
+                    } catch (ReflectiveOperationException roe) { // method not found
+                        throw new RuntimeException(error(4001).formatted(method, param, field.getName(), instance.getClass().getName()), roe);
                     }
                 }
 

framework/src/main/resources/org/fulib/fx/lang/error.properties

@@ -37,7 +37,7 @@
 
 # Parameters
 4000=Couldn't fill parameter '%s' into field '%s' in class '%s'.
-4001=Couldn't call setter method with parameter '%s' for field '%s' in class '%s'.
+4001=Couldn't call setter method '%s' with parameter '%s' for field '%s' in class '%s'.
 4002=Field '%s' annotated with @ParamsMap in class '%s' is not of type Map<String, Object>.
 4003=Method '%s' annotated with @ParamsMap in class '%s' must have exactly one parameter of type Map<String, Object>.
 4004=Parameter '%s' annotated with @ParamsMap in method '%s' in class '%s' is not of type Map<String, Object>.

framework/src/test/java/org/fulib/fx/app/controller/ParamController.java

@@ -21,7 +21,7 @@ public class ParamController {
     private String setterParam;
     @Param("integer")
     int fieldParam;
-    @Param("string")
+    @Param(value = "string", method = "set", type = String.class)
     final StringProperty fieldPropertyParam = new SimpleStringProperty();
 
     private Map<String, Object> onInitParamsMap;