Class SpaNotFoundHandlerRegistry

java.lang.Object
com.kingsrook.qqq.middleware.javalin.routeproviders.SpaNotFoundHandlerRegistry
public class SpaNotFoundHandlerRegistry extends Object
Global registry for SPA 404 handlers. PROBLEM: Javalin's error() handlers are GLOBAL - you can only register one 404 handler per Javalin instance. When multiple IsolatedSpaRouteProviders try to register 404 handlers, they conflict, and only the last one wins. SOLUTION: This registry maintains a list of path-scoped 404 handlers. Each IsolatedSpaRouteProvider registers its scope and handler function. The global 404 handler (registered once with Javalin) delegates to the appropriate provider based on path matching. DESIGN: 1. IsolatedSpaRouteProvider registers: registerHandler("/admin", handler) 2. Global 404 occurs at /admin/Content/site 3. Registry finds handler for "/admin" (longest prefix match) 4. Calls the handler's callback 5. Handler decides whether to serve SPA index or let it 404 PRIORITY: Handlers are matched by LONGEST PATH PREFIX first - More specific paths (e.g., /admin/api) take precedence over /admin - Root path ("/") is always last resort

  • Method Details

    • getInstance

      public static SpaNotFoundHandlerRegistry getInstance()
      Get the singleton instance of the registry.
      Returns:
      The singleton SpaNotFoundHandlerRegistry instance

    • registerGlobalHandler

      public void registerGlobalHandler(io.javalin.Javalin service)
      Register the global 404 handler with Javalin (call once per Javalin instance). This method is idempotent per Javalin instance - calling it multiple times with the same instance has no effect. However, if a NEW Javalin instance is passed, the handler is registered with that instance. This is important for test isolation where each test may create its own Javalin server.
      Parameters:
      service - The Javalin instance to register the global 404 handler with

    • registerSpaHandler

      public void registerSpaHandler(String spaPath, Consumer<io.javalin.http.Context> handler)
      Register a path-scoped 404 handler
      Parameters:
      spaPath - The base path for this SPA (e.g., "/admin", "/")
      handler - The handler function to call when a 404 occurs under this path

    • clear

      public void clear()
      Clear all registered handlers (useful for testing) This resets the registry to its initial state, allowing a new Javalin instance to register handlers. Call this in test cleanup (@AfterEach) to ensure test isolation.