Enhance router usability (#124)

* refactor(framework): Enhance router usability
* docs: Update ERROR_CODES.md

---------

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

ERROR_CODES.md

@@ -341,7 +341,7 @@ This error is thrown if the framework tries to register a field as a route provi
 with `@Route`.
 This should never happen if the framework is used correctly.
 
-### 3002: `Route '*' already leads to '*' but was tried to be registered for '*'.`
+### 3002: `Route '*' already leads to a controller/component of type '*'.`
 
 - Runtime: ✅
 - Annotation Processor: ❌
@@ -376,7 +376,7 @@ public class Routes {
 
 ### 3004: `Field '*' in class '*' is not a valid provider field.`
 
-- Runtime: ✅
+- Runtime: ❌
 - Annotation Processor: ✅
 
 This error is thrown when a field annotated with `@Route` is not a `Provider`.

framework/src/main/java/org/fulib/fx/FulibFxApp.java

@@ -147,7 +147,7 @@ public static void setResourcesPath(@NotNull Path path) {
  */
  @SuppressWarnings("unchecked")
  public @NotNull <T extends Node> T initAndRender(@NotNull String route, @NotNull Map<@NotNull String, @Nullable Object> params, @Nullable DisposableContainer onDestroy) {
- Object component = this.frameworkComponent.router().getController(route);
+ Object component = this.frameworkComponent.router().getRoute(route);
  if (!ControllerUtil.isComponent(component)) {
  throw new IllegalArgumentException(error(1000).formatted(component.getClass().getName()));
  }

framework/src/main/java/org/fulib/fx/controller/ControllerManager.java

@@ -15,7 +15,6 @@
 import org.fulib.fx.annotation.event.OnKey;
 import org.fulib.fx.annotation.event.OnRender;
 import org.fulib.fx.controller.building.ControllerBuildFactory;
-import org.fulib.fx.controller.exception.IllegalControllerException;
 import org.fulib.fx.controller.internal.FxSidecar;
 import org.fulib.fx.controller.internal.ReflectionSidecar;
 import org.fulib.fx.data.disposable.RefreshableCompositeDisposable;
@@ -117,7 +116,7 @@ public void init(@NotNull Object instance, @NotNull Map<@NotNull String, @Nullab
 
  // Check if the instance is a controller
  if (!ControllerUtil.isControllerOrComponent(instance)) {
- throw new IllegalControllerException(error(1001).formatted(instance.getClass().getName()));
+ throw new RuntimeException(error(1001).formatted(instance.getClass().getName()));
  }
 
  getSidecar(instance).init(instance, parameters);

framework/src/main/java/org/fulib/fx/controller/Router.java

@@ -4,16 +4,9 @@
 import javafx.scene.Node;
 import javafx.scene.Parent;
 import javafx.util.Pair;
-import org.fulib.fx.FulibFxApp;
 import org.fulib.fx.annotation.Route;
-import org.fulib.fx.annotation.controller.Component;
-import org.fulib.fx.annotation.controller.Controller;
-import org.fulib.fx.controller.exception.ControllerDuplicatedRouteException;
-import org.fulib.fx.controller.exception.ControllerInvalidRouteException;
 import org.fulib.fx.data.*;
 import org.fulib.fx.util.ControllerUtil;
-import org.fulib.fx.util.FrameworkUtil;
-import org.fulib.fx.util.ReflectionUtil;
 import org.fulib.fx.util.reflection.Reflection;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -31,8 +24,8 @@
 @Singleton
 public class Router {
 
- private final TraversableTree<Field> routes;
- private final SizeableTraversableQueue<Pair<Either<TraversableNodeTree.Node<Field>, Object>, Map<String, Object>>> history;
+ private final TraversableTree<Provider<?>> routes;
+ private final SizeableTraversableQueue<Pair<Either<TraversableNodeTree.Node<Provider<?>>, Object>, Map<String, Object>>> history;
 
  @Inject
  Lazy<ControllerManager> manager;
@@ -60,6 +53,15 @@ public void registerRoutes(@NotNull Object routes) {
  Reflection.getFieldsWithAnnotation(routes.getClass(), Route.class).forEach(this::registerRoute);
  }
 
+ /**
+ * Checks if a router class has been registered already.
+ *
+ * @return True if a router class has been registered already.
+ */
+ public boolean routesRegistered() {
+ return this.routerObject != null;
+ }
+
 
  /**
  * Registers a field as a route.
@@ -79,13 +81,53 @@ private void registerRoute(@NotNull Field field) {
  Route annotation = field.getAnnotation(Route.class);
  String route = annotation.value().equals("$name") ? "/" + field.getName() : annotation.value();
 
+ try {
+ field.setAccessible(true);
+ Provider<?> provider = (Provider<?>) field.get(routerObject);
+ registerRoute(route, provider);
+ } catch (IllegalAccessException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+
+ /**
+ * Registers a route with the given provider.
+ * When adding a route, the route has to be unique, otherwise an exception will be thrown.
+ * <p>
+ * The route has to start with a slash, otherwise it will be added automatically.
+ * <p>
+ * This method doesn't check if the provider provides a valid controller or component.
+ *
+ * @param route The route to register
+ * @param provider The provider to register
+ * @throws RuntimeException If the route is already registered
+ */
+ public void registerRoute(@NotNull String route, @NotNull Provider<?> provider) {
  // Make sure the route starts with a slash to prevent issues with the traversal
  route = route.startsWith("/") ? route : "/" + route;
 
+ checkDuplicatedRoute(route, provider);
+
+ this.routes.insert(route, provider);
+
+ }
+
+ private void checkDuplicatedRoute(String route, Provider<?> provider) {
  if (this.routes.containsPath(route)) {
- throw new ControllerDuplicatedRouteException(route, field.getType(), this.routes.get(route).getType());
+ Object oldController = this.routes.get(route).get();
+ throw new RuntimeException(error(3002).formatted(route, oldController == null ? "null" : oldController.getClass().getName()));
+ }
+ }
+
+ private void checkContainsRoute(String route) {
+ if (!this.routes.containsPath(route)) {
+ String message = error(3005).formatted(route);
+ if (this.routes.containsPath("/" + route)) {
+ message += " " + note(3005).formatted("/" + route);
+ }
+ throw new RuntimeException(message);
  }
- this.routes.insert(route, field);
  }
 
  /**
@@ -95,35 +137,27 @@ private void registerRoute(@NotNull Field field) {
  * @param route The route of the controller
  * @param parameters The parameters to pass to the controller
  * @return A pair containing the controller instance and the rendered parent (will be the same if the controller is a component)
- * @throws ControllerInvalidRouteException If the route couldn't be found
+ * @throws RuntimeException If the route couldn't be found
  */
  public @NotNull Pair<Object, Parent> renderRoute(@NotNull String route, @NotNull Map<@NotNull String, @Nullable Object> parameters) {
  // Check if the route exists and has a valid controller
- if (!this.routes.containsPath(route)) {
- String message = error(3005).formatted(route);
- if (this.routes.containsPath("/" + route)) {
- message += " " + note(3005).formatted("/" + route);
- }
- throw new ControllerInvalidRouteException(message);
- }
+ checkContainsRoute(route);
 
  // Get the provider and the controller class
- Field provider = this.routes.traverse(route);
- TraversableNodeTree.Node<Field> node = ((TraversableNodeTree<Field>) this.routes).currentNode();
+ Provider<?> provider = this.routes.traverse(route);
+ TraversableNodeTree.Node<Provider<?>> node = ((TraversableNodeTree<Provider<?>>) this.routes).currentNode();
 
  // Since we visited this route with the given parameters, we can add it to the history
  this.addToHistory(new Pair<>(Either.left(node), parameters));
- Class<?> controllerClass = ReflectionUtil.getProvidedClass(Objects.requireNonNull(provider));
 
- // Check if the provider is providing a valid controller/component
- if (controllerClass == null) {
-  throw new RuntimeException(error(3004).formatted(provider.getName(), routerObject.getClass().getName()));
- }
- if (!controllerClass.isAnnotationPresent(Controller.class) && !controllerClass.isAnnotationPresent(Component.class)) {
+ // Get the instance of the controller
+ Object controllerInstance = provider.get();
+ Class<?> controllerClass = controllerInstance.getClass();
+
+ if (!ControllerUtil.isControllerOrComponent(controllerClass)) {
  throw new RuntimeException(error(1001).formatted(controllerClass.getName()));
  }
- // Get the instance of the controller
- Object controllerInstance = ReflectionUtil.getInstanceOfProviderField(provider, this.routerObject);
+
  Node renderedNode = this.manager.get().initAndRender(controllerInstance, parameters);
 
  if (renderedNode instanceof Parent parent) {
@@ -134,18 +168,35 @@ private void registerRoute(@NotNull Field field) {
  }
 
  /**
- * Returns the controller with the given route without initializing and rendering it.
+ * Returns the controller or component with the given route without initializing and rendering it.
  * The route will be seen as absolute, meaning it will be treated as a full path.
  *
  * @param route The route of the controller
  * @return The controller instance
  */
- public Object getController(String route) {
- Field provider = this.routes.get(route.startsWith("/") ? route : "/" + route);
- return ReflectionUtil.getInstanceOfProviderField(provider, this.routerObject);
+ public Object getRoute(String route) {
+ String absoluteRoute = absolute(route);
+ checkContainsRoute(absoluteRoute);
+ Provider<?> provider = this.routes.get(absoluteRoute);
+ return provider.get();
+ }
+
+ private String absolute(String route) {
+ return route.startsWith("/") ? route : "/" + route;
+ }
+
+ /**
+ * Returns whether the router contains the given route.
+ * The route will be seen as absolute, meaning it will be treated as a full path.
+ *
+ * @param route The route to check
+ * @return True if the route exists
+ */
+ public boolean containsRoute(String route) {
+ return this.routes.containsPath(absolute(route));
  }
 
- public void addToHistory(Pair<Either<TraversableNodeTree.Node<Field>, Object>, Map<String, Object>> pair) {
+ public void addToHistory(Pair<Either<TraversableNodeTree.Node<Provider<?>>, Object>, Map<String, Object>> pair) {
  this.history.insert(pair);
  }
 
@@ -177,12 +228,12 @@ public Pair<Object, Node> forward() {
  }
  }
 
- private Pair<Object, Node> navigate(Pair<Either<TraversableNodeTree.Node<Field>, Object>, Map<String, Object>> pair) {
+ private Pair<Object, Node> navigate(Pair<Either<TraversableNodeTree.Node<Provider<?>>, Object>, Map<String, Object>> pair) {
  var either = pair.getKey();
- either.getLeft().ifPresent(node -> ((TraversableNodeTree<Field>) routes).setCurrentNode(node)); // If the history contains a route, set it as the current node
+ either.getLeft().ifPresent(node -> ((TraversableNodeTree<Provider<?>>) routes).setCurrentNode(node)); // If the history contains a route, set it as the current node
 
  Object controller = either.isLeft() ?
- ReflectionUtil.getInstanceOfProviderField(either.getLeft().orElseThrow().value(), this.routerObject) : // Get the controller instance from the provider
+ Objects.requireNonNull(either.getLeft().orElseThrow().value()).get() : // Get the controller instance from the provider
  either.getRight().orElseThrow(); // Get the controller instance from the history
 
  this.manager.get().cleanup(); // Cleanup the current controller
@@ -201,17 +252,10 @@ private Pair<Object, Node> navigate(Pair<Either<TraversableNodeTree.Node<Field>,
  * @return The current controller object and its parameters
  */
  public Pair<Object, Map<String, Object>> current() {
- Either<TraversableNodeTree.Node<Field>, Object> either = this.history.current().getKey();
+ Either<TraversableNodeTree.Node<Provider<?>>, Object> either = this.history.current().getKey();
  return new Pair<>(
  either.isLeft() ?
- either.getLeft().map(node -> {
- try {
- Objects.requireNonNull(node.value()).setAccessible(true);
- return ((Provider<?>) Objects.requireNonNull(node.value()).get(routerObject)).get();
- } catch (IllegalAccessException e) {
- throw new RuntimeException(e);
- }
- }).orElseThrow() :
+ either.getLeft().map(node -> ((Provider<?>) Objects.requireNonNull(node.value()).get())).orElseThrow() :
  either.getRight().orElseThrow(),
  this.history.current().getValue()
  );
@@ -226,4 +270,10 @@ public Pair<Object, Map<String, Object>> current() {
  public void setHistorySize(int size) {
  this.history.setSize(size);
  }
+
+
+ @Override
+ public String toString() {
+ return "Router(\n" + this.routes + "\n)";
+ }
 }

framework/src/main/java/org/fulib/fx/data/TraversableNodeTree.java

@@ -198,4 +198,19 @@ public void removeChild(Node<E> child) {
 
  }
 
+ @Override
+ public String toString() {
+ return this.toString(this.root, 0);
+ }
+
+ private String toString(Node<E> node, int depth) {
+ StringBuilder builder = new StringBuilder();
+ builder.append("\t".repeat(Math.max(0, depth)));
+ builder.append(node.id.isBlank() ? "[empty]" : node.id).append(" ").append(node.value()).append("\n");
+ for (Node<E> child : node.children()) {
+ builder.append(toString(child, depth + 1));
+ }
+ return builder.delete(builder.length() - 2, builder.length()).toString();
+ }
+
 }

framework/src/main/java/org/fulib/fx/util/ControllerUtil.java

@@ -8,7 +8,6 @@
 import org.fulib.fx.annotation.event.OnInit;
 import org.fulib.fx.annotation.event.OnKey;
 import org.fulib.fx.annotation.event.OnRender;
-import org.fulib.fx.controller.exception.InvalidRouteFieldException;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -98,6 +97,16 @@ public static boolean isController(@Nullable Class<?> clazz) {
  return clazz != null && clazz.isAnnotationPresent(Controller.class) && !clazz.isAnnotationPresent(Component.class);
  }
 
+ /**
+ * Checks if a class is a controller or a component.
+ *
+ * @param clazz The class to check
+ * @return True if the class is a controller or a component
+ */
+ public static boolean isControllerOrComponent(@Nullable Class<?> clazz) {
+ return isController(clazz) || isComponent(clazz);
+ }
+
  /**
  * Checks if the given field is a field that can provide a component.
  *
@@ -128,11 +137,11 @@ public static boolean canProvideSubComponent(Field field) {
  * A valid route field is a field that is annotated with {@link Route} and is of type {@link Provider} where the generic type is a class annotated with {@link Controller} or {@link Component}.
  *
  * @param field The field to check
- * @throws InvalidRouteFieldException If the field is not a valid route field
+ * @throws RuntimeException If the field is not a valid route field
  */
  public static void requireControllerProvider(@NotNull Field field) {
- if (isControllerOrComponent(getProvidedClass(field))) {
- throw new InvalidRouteFieldException(field);
+ if (!isControllerOrComponent(getProvidedClass(field))) {
+ throw new RuntimeException(error(3003).formatted(field.getName(), field.getDeclaringClass().getName()));
  }
  }
 
@@ -157,7 +166,7 @@ public static boolean isEventMethod(@NotNull Method method) {
  * If a method overrides another method and the overridden method is an event method, calling the superclass method
  * results in the subclass method being called twice due to how java handles method overrides.
  *
- * @param method  The method to check
+ * @param method The method to check
  */
  public static void checkOverrides(Method method) {
  Method overridden = ReflectionUtil.getOverriding(method);