Class IsolatedSpaRouteProvider

java.lang.Object
com.kingsrook.qqq.middleware.javalin.routeproviders.IsolatedSpaRouteProvider
All Implemented Interfaces:
QJavalinRouteProviderInterface
public class IsolatedSpaRouteProvider extends Object implements QJavalinRouteProviderInterface
Complete isolated SPA route provider with deep linking support. This provider offers full SPA functionality including: - Static file serving from classpath or filesystem - Deep linking support (404 -> index.html fallback) - Path-scoped before/after handlers - Complete isolation from other SPAs - Support for root path ("/") with exclusions for other SPAs Usage Examples: // Admin SPA at /admin new IsolatedSpaRouteProvider("/admin", "admin-spa/dist/") .withSpaIndexFile("admin-spa/dist/index.html") .withAuthenticator(new QCodeReference(AdminAuthenticator.class)) // Root SPA at / (excluding other SPAs) new IsolatedSpaRouteProvider("/", "public-site/") .withSpaIndexFile("public-site/index.html") .withExcludedPaths(List.of("/admin", "/api"))

  • Constructor Details

    • IsolatedSpaRouteProvider

      public IsolatedSpaRouteProvider(String spaPath, String staticFilesPath)
      Constructor
      Parameters:
      spaPath - Path where the SPA is hosted (e.g., "/", "/admin", "/customer")
      staticFilesPath - Path to static files (classpath or filesystem)

  • Method Details

    • setQInstance

      public void setQInstance(QInstance qInstance)
      Set the QInstance (required by interface). The QInstance is needed for authentication when an authenticator is configured.
      Specified by:
      setQInstance in interface QJavalinRouteProviderInterface
      Parameters:
      qInstance - The QInstance containing metadata and configuration

    • acceptJavalinConfig

      public void acceptJavalinConfig(io.javalin.config.JavalinConfig config)
      Configure static file serving during Javalin config phase. Called by Javalin during server initialization to set up static file serving.
      Specified by:
      acceptJavalinConfig in interface QJavalinRouteProviderInterface
      Parameters:
      config - The Javalin configuration to add static file settings to

    • acceptJavalinService

      public void acceptJavalinService(io.javalin.Javalin service)
      Register path-scoped handlers after Javalin service is created. Called after Javalin is created to register before/after handlers and the 404 handler for deep linking support.
      Specified by:
      acceptJavalinService in interface QJavalinRouteProviderInterface
      Parameters:
      service - The Javalin service instance to register handlers with

    • withSpaIndexFile

      public IsolatedSpaRouteProvider withSpaIndexFile(String spaIndexFile)
      Fluent setter: Set the SPA index file path.
      Parameters:
      spaIndexFile - The classpath path to the index.html file (e.g., "admin-spa/dist/index.html")
      Returns:
      this provider instance for method chaining

    • withAuthenticator

      public IsolatedSpaRouteProvider withAuthenticator(QCodeReference authenticator)
      Fluent setter: Set the authenticator.
      Parameters:
      authenticator - QCodeReference to a RouteAuthenticatorInterface implementation
      Returns:
      this provider instance for method chaining

    • withExcludedPaths

      public IsolatedSpaRouteProvider withExcludedPaths(List<String> paths)
      Fluent setter: Add paths to exclude (for root SPA only). Excluded paths will not be handled by this SPA, allowing other route providers to handle them (e.g., exclude "/api" from a root SPA).
      Parameters:
      paths - List of paths to exclude (e.g., "/api", "/admin")
      Returns:
      this provider instance for method chaining

    • withExcludedPath

      public IsolatedSpaRouteProvider withExcludedPath(String path)
      Fluent setter: Add a single excluded path.
      Parameters:
      path - The path to exclude (e.g., "/api")
      Returns:
      this provider instance for method chaining

    • withBeforeHandler

      public IsolatedSpaRouteProvider withBeforeHandler(io.javalin.http.Handler handler)
      Fluent setter: Add a custom before handler. Before handlers run before request processing, useful for logging, custom authentication, or request modification.
      Parameters:
      handler - The Javalin Handler to run before request processing
      Returns:
      this provider instance for method chaining

    • withAfterHandler

      public IsolatedSpaRouteProvider withAfterHandler(io.javalin.http.Handler handler)
      Fluent setter: Add a custom after handler. After handlers run after request processing, useful for logging, response modification, or cleanup.
      Parameters:
      handler - The Javalin Handler to run after request processing
      Returns:
      this provider instance for method chaining

    • withDeepLinking

      public IsolatedSpaRouteProvider withDeepLinking(boolean enable)
      Fluent setter: Enable/disable deep linking (default: true). When enabled, 404 errors for non-static-asset paths under this SPA's path will serve index.html, allowing client-side routing to handle the URL.
      Parameters:
      enable - true to enable deep linking, false to disable
      Returns:
      this provider instance for method chaining

    • withLoadFromJar

      public IsolatedSpaRouteProvider withLoadFromJar(boolean loadFromJar)
      Fluent setter: Set whether to load from JAR (overrides system property). When true, loads static files from classpath (for production JAR deployment). When false, loads from filesystem (for development with hot reload).
      Parameters:
      loadFromJar - true to load from classpath, false to load from filesystem
      Returns:
      this provider instance for method chaining

    • withCustomAssetExtensions

      public IsolatedSpaRouteProvider withCustomAssetExtensions(String... extensions)
      Fluent setter: Add custom file extensions to detect as static assets Use this when your SPA uses non-standard file extensions that should be treated as static assets rather than client-side routes. Example: .myext, .customdata
      Parameters:
      extensions - Custom extensions to add (e.g., ".myext", ".custom")
      Returns:
      this for method chaining

    • withCustomAssetPathPatterns

      public IsolatedSpaRouteProvider withCustomAssetPathPatterns(String... patterns)
      Fluent setter: Add custom path patterns to detect as static assets Use this when your SPA uses non-standard directory structures for assets. Example: /my-assets/, /resources/, /cdn/
      Parameters:
      patterns - Path patterns to add (should contain "/" to avoid false positives)
      Returns:
      this for method chaining

    • withCustomAssetDetector

      public IsolatedSpaRouteProvider withCustomAssetDetector(Predicate<String> detector)
      Fluent setter: Add custom detection logic for static assets Use this for complex cases where file extensions and path patterns aren't sufficient. The custom detector runs FIRST, before extension/path checks. Example: Detect all paths starting with /cdn/ as assets provider.withCustomAssetDetector(path -> path.startsWith("/cdn/"))
      Parameters:
      detector - Predicate that returns true if path is a static asset
      Returns:
      this for method chaining

    • getSpaPath

      public String getSpaPath()
      Getter for spaPath.
      Returns:
      The path where this SPA is hosted (e.g., "/admin", "/")

    • getStaticFilesPath

      public String getStaticFilesPath()
      Getter for staticFilesPath.
      Returns:
      The classpath or filesystem path to static files

    • getSpaIndexFile

      public String getSpaIndexFile()
      Getter for spaIndexFile.
      Returns:
      The path to the SPA's index.html file