Package io.fluxcapacitor.javaclient.web

Annotation Interface ServeStatic

@Documented @Retention(RUNTIME) @Target({TYPE,PACKAGE}) public @interface ServeStatic
Declares a static file handler that serves files from a resource or file system location at the specified web path(s).

This annotation can be placed on a class or package that configures or instantiates a StaticFileHandler. At runtime, it may be discovered and used to register routes that serve static assets such as HTML, JavaScript, CSS, or images.

Files are served from either the file system or the classpath. If a file exists in both locations, the file system version takes precedence. If the resourcePath starts with classpath:, it is only loaded from the classpath. If it starts with file:, it is only loaded from the file system.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    fallbackFile
    Optional fallback file to serve if a requested resource is not found.
    String[]
    immutableCandidateExtensions
    File extensions considered candidates for immutable caching when their filenames are fingerprinted.
    int
    maxAgeSeconds
    Default max-age (in seconds) for non-immutable static files.
    String
    resourcePath
    The base resource path from which to serve static files.
    String[]
    value
    One or more web path patterns this handler applies to (e.g.

  • Element Details

    • value

      String[] value
      One or more web path patterns this handler applies to (e.g. "static", "/web/public").

      If a path starts with /, it is interpreted as an absolute path and not influenced by outer Path annotations. Otherwise, it is considered relative and will be prefixed with any outer @Path values.

      If left empty, the path will be inferred from outer @Path annotations or defaults.

      Returns:
      Web path patterns for serving static content.
      Default:
      {}

    • resourcePath

      String resourcePath
      The base resource path from which to serve static files.

      May point to a classpath directory (e.g., /static, assets/) or a file system path (e.g., /opt/myapp/public). If both classpath and file system contain the same file, the file system version takes precedence.

      Prefixing the path with classpath: or file: restricts loading to that source only.

      Returns:
      Path to the directory containing static resources.
      Default:
      "/static"

    • fallbackFile

      String fallbackFile
      Optional fallback file to serve if a requested resource is not found.

      This is useful for single-page applications (SPAs) where all unknown routes should fall back to index.html.

      To disable this behavior, return an empty string.

      Returns:
      Relative path to the fallback file, e.g., index.html.
      Default:
      "index.html"

    • immutableCandidateExtensions

      String[] immutableCandidateExtensions
      File extensions considered candidates for immutable caching when their filenames are fingerprinted.

      Fingerprinted files (e.g., app.abc123.js) with one of these extensions will receive Cache-Control: public, max-age=31536000, immutable.

      Returns:
      Extensions (without leading dots) eligible for immutable cache headers.
      Default:
      {"html", "js", "css", "json", "svg"}

    • maxAgeSeconds

      int maxAgeSeconds
      Default max-age (in seconds) for non-immutable static files.

      Files that are not fingerprinted will receive a cache-control header such as Cache-Control: public, max-age=86400. HTML files may override this with must-revalidate.

      Returns:
      Number of seconds the file is allowed to be cached.
      Default:
      86400