Package dev.relism.flash.extension

Class FlashApp

java.lang.Object

dev.relism.flash.extension.FlashRegistrar<FlashApp>

dev.relism.flash.extension.FlashApp

public final class FlashApp
extends FlashRegistrar<FlashApp>

Single entry point for Flash. Owns one flat FastPathRouterImpl — all routes (app-level and scoped) compile into a single FSM at startup.

 FlashApp.create(8080)
     .install(new JacksonExtension())
     .use(cors)
     .get("/ping",    (req, res) -> "pong")
     .get("/secured", (req, res) -> user(), oidc.protect())
     .scan("dev.example.handlers")
     .mount("/api", scope -> scope.get("/health", (req, res) -> "ok"))
     .startAndBlock();   // blocks main thread
 

Startup sequence (both start() and startAndBlock())

1. Extensions sorted by FlashExtension.priority() — lower first.
2. All FlashExtension.provide(dev.relism.flash.extension.FlashContext) — register services, processors, listeners.
3. FlashContext.resolveAll() — topo-sort, cycle detection.
4. All FlashExtension.routes(dev.relism.flash.extension.FlashRegistrar<?>, dev.relism.flash.extension.FlashContext) — routes registered, services available.
5. Compile all routes into one flat FSM — zero prefix scanning at runtime.
6. Accept loop started.

Default error handlers

Dev mode (-Dflash.env=dev): rich HTML with stack traces. Prod mode (default): generic JSON — no internal details leaked. Override via onException(dev.relism.flash.routing.AbstractRouter.ExceptionHandler) / onNotFound(dev.relism.flash.models.SimpleHandler.FunctionalHandler).

Method Summary

Modifier and Type	Method	Description
protected void	addMiddleware(Middleware mw)	Registers a middleware in this registrar's own scope (global or scope-level).
protected void	addRoute(HttpMethod method, String path, RequestHandler handler, List<Middleware> mw)	Adds a route immediately to this registrar's deferred compilation list.
protected void	addWsRoute(String path, WebSocketEndpoint endpoint)
static FlashApp	create(int port)
static FlashApp	create(FlashConfiguration cfg)
FlashContext	ctx()	Returns the FlashContext for this registrar.
FlashApp	install(FlashExtension ext)	Registers an extension for two-phase installation at startup.
FlashApp	mount(String namespace, Consumer<FlashScope> configure)	Mounts a scoped group of routes under namespace.
FlashApp	onException(AbstractRouter.ExceptionHandler handler)
FlashApp	onNotFound(SimpleHandler.FunctionalHandler handler)
FlashApp	start()	Boots the server and starts accepting connections.
void	startAndBlock()	Boots the server and blocks the calling thread until the server is stopped.
CompletableFuture<Void>	stop()
FlashApp	ws(String path, WebSocketHandler handler)	Registers a WebSocket endpoint at path.

Methods inherited from class dev.relism.flash.extension.FlashRegistrar

connect, delete, get, head, instantiate, instantiateWs, options, patch, post, purge, put, scan, trace, use

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

create

public static FlashApp create(int port)

create

public static FlashApp create(FlashConfiguration cfg)

mount

public FlashApp mount(String namespace,
 Consumer<FlashScope> configure)

Mounts a scoped group of routes under namespace. Routes accumulate in a FlashScope builder and merge into this app's single flat router at startup — pure syntactic sugar, no extra router involved.

ws

public FlashApp ws(String path,
 WebSocketHandler handler)

Registers a WebSocket endpoint at path. Runs on the same virtual-thread model as HTTP handlers. A path may have both an HTTP handler and a WS endpoint simultaneously.

onException

public FlashApp onException(AbstractRouter.ExceptionHandler handler)

onNotFound

public FlashApp onNotFound(SimpleHandler.FunctionalHandler handler)

ctx

public FlashContext ctx()

Description copied from class: FlashRegistrar

Returns the FlashContext for this registrar.

Specified by:

ctx in class FlashRegistrar<FlashApp>

install

public FlashApp install(FlashExtension ext)

Registers an extension for two-phase installation at startup. Install order is irrelevant — all FlashExtension.provide(dev.relism.flash.extension.FlashContext) calls complete before any FlashExtension.routes(dev.relism.flash.extension.FlashRegistrar<?>, dev.relism.flash.extension.FlashContext) call begins. Extensions are sorted by FlashExtension.priority() before execution.

start

public FlashApp start()

Boots the server and starts accepting connections. Returns immediately — the accept loop runs on a background platform thread.

Use startAndBlock() in main() if you have no other work to do after startup.

Returns:

this for storing or chaining (e.g. .start().ctx().require(...))

startAndBlock

public void startAndBlock()

Boots the server and blocks the calling thread until the server is stopped. Suitable for the end of main() — no need to keep the JVM alive manually.

stop

public CompletableFuture<Void> stop()

addRoute

protected void addRoute(HttpMethod method,
 String path,
 RequestHandler handler,
 List<Middleware> mw)

Description copied from class: FlashRegistrar

Adds a route immediately to this registrar's deferred compilation list. Subclasses may prepend a namespace prefix and inject scope middlewares before storing.

Specified by:

addRoute in class FlashRegistrar<FlashApp>

addWsRoute

protected void addWsRoute(String path,
 WebSocketEndpoint endpoint)

Specified by:

addWsRoute in class FlashRegistrar<FlashApp>

addMiddleware

protected void addMiddleware(Middleware mw)

Description copied from class: FlashRegistrar

Registers a middleware in this registrar's own scope (global or scope-level).

Specified by:

addMiddleware in class FlashRegistrar<FlashApp>