Package dev.relism.flash.extension

Class FlashContext

java.lang.Object

dev.relism.flash.extension.FlashContext

public class FlashContext
extends Object

Central service registry and boot-time hook coordinator.

Every handler, extension, and scope shares one (or a child of one) FlashContext. Three capabilities:

1. Service registry — provide(java.lang.Class<T>, T)/supply(java.lang.Class<T>, java.util.function.Supplier<T>)/require(java.lang.Class<T>)/find(java.lang.Class<T>).
2. Annotation processors — middleware injection from handler annotations at boot.
3. Route listeners — boot-time observation of the route graph.

Eager vs lazy registration

• provide(Class, Object) — instance is already constructed, registered immediately.
• supply(Class, Supplier) — factory is registered; it runs once, at resolveAll() time (called by FlashApp.start()) after all FlashExtension.provide(dev.relism.flash.extension.FlashContext) phases complete. The factory may call require(java.lang.Class<T>) for its own dependencies — the runtime resolves in topological order automatically and reports circular dependencies with the full cycle path.

A child context (via child()) inherits parent services and processors. Services provided on the child are scoped and invisible to the parent.

Constructor Summary

Constructors

Constructor	Description
FlashContext()

Method Summary

Modifier and Type	Method	Description
void	addAnnotationProcessor(AnnotationProcessor processor)	Registers an AnnotationProcessor.
void	addRouteListener(RouteListener listener)	Registers a boot-time RouteListener.
FlashContext	child()	Creates a child context that inherits this context's services and processors.
<T> Optional<T>	find(Class<T> type)	Returns the service for type, or empty if not found in this scope or any parent.
<T> Optional<T>	optional(Class<T> type)	Alias for find(java.lang.Class<T>) — prefer when semantics are "this may or may not exist".
<T> void	provide(Class<T> type, T instance)	Registers an already-constructed instance under type.
<T> T	require(Class<T> type)	Returns the service for type.
<T> void	supply(Class<T> type, Supplier<T> factory)	Registers a lazy factory for type.

Methods inherited from class java.lang.Object

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

Constructor Details

FlashContext

public FlashContext()

Method Details

child

public FlashContext child()

Creates a child context that inherits this context's services and processors.

provide

public <T> void provide(Class<T> type,
 T instance)

Registers an already-constructed instance under type.

supply

public <T> void supply(Class<T> type,
 Supplier<T> factory)

Registers a lazy factory for type. The factory runs once at resolveAll() time (or on the first require(java.lang.Class<T>) call for this type) and may call require(java.lang.Class<T>) for its own dependencies — topological order is resolved automatically.

 ctx.supply(JwtValidator.class, () ->
     new JwtValidator(ctx.require(OidcProviderMetadata.class).jwksUri()));
 

require

public <T> T require(Class<T> type)

Returns the service for type. Checks own scope first, then parent chain. Lazy-registered types are resolved on first access. Circular dependencies throw IllegalStateException with the full cycle path.

Throws:

IllegalStateException - if the service is not found anywhere in the context chain

find

public <T> Optional<T> find(Class<T> type)

Returns the service for type, or empty if not found in this scope or any parent.

optional

public <T> Optional<T> optional(Class<T> type)

Alias for find(java.lang.Class<T>) — prefer when semantics are "this may or may not exist".

addAnnotationProcessor

public void addAnnotationProcessor(AnnotationProcessor processor)

Registers an AnnotationProcessor. Processors run once per class-based handler at boot.

addRouteListener

public void addRouteListener(RouteListener listener)

Registers a boot-time RouteListener. Zero overhead on the request hot-path.