preparing for a conceptual refactoring...

2026-03-28 14:11:12 +01:00
parent 7b996b552b
commit 2edd68b0aa
60 changed files with 3432 additions and 518 deletions
@@ -0,0 +1,44 @@
+package dev.relism.extension;
+
+import dev.relism.http.HttpMethod;
+import dev.relism.routing.Middleware;
+
+import java.util.List;
+
+/**
+ * Immutable snapshot of a route captured at registration time.
+ *
+ * <p>Emitted by {@link FlashApp} and {@link FlashScope} to every registered
+ * {@link RouteListener} before the route is compiled into the routing engine.
+ * All information is derived automatically — no annotations or declarations
+ * are required from the developer.
+ *
+ * <h3>Middleware chain</h3>
+ * {@link #middlewareChain} lists the {@link Middleware} classes outermost-first:
+ * <ol>
+ *   <li>Router-level middlewares (set on the router constructor)</li>
+ *   <li>Annotation-injected middlewares (e.g. from {@code @Authenticated})</li>
+ *   <li>Handler-level explicit middlewares (passed via {@code .with(...)})</li>
+ * </ol>
+ *
+ * <h3>Handler abstraction chain</h3>
+ * Walk {@link #handlerClass} upward via {@link Class#getSuperclass()} to reconstruct
+ * the full inheritance chain (e.g. {@code EditPostPageHandler → HtmlHandler → RequestHandler}).
+ * Read {@link Class#getAnnotations()} on each level to discover declared pointcuts
+ * ({@code @Authenticated}, {@code @RolesAllowed}, {@code @Route}, etc.).
+ *
+ * @param method          HTTP method for this route
+ * @param path            full path as declared (including namespace prefix for scoped routes)
+ * @param namespace       namespace prefix of the router that owns this route ({@code "/"} for root)
+ * @param routerType      simple class name of the owning router implementation
+ * @param handlerClass    concrete handler class, or {@code null} for anonymous lambda handlers
+ * @param middlewareChain ordered middleware classes, outermost first
+ */
+public record RouteEvent(
+        HttpMethod      method,
+        String          path,
+        String          namespace,
+        String          routerType,
+        Class<?>        handlerClass,
+        List<Class<? extends Middleware>> middlewareChain
+) {}