Configuring Fluxzero

The FluxzeroBuilder interface is the primary entry point for configuring a Fluxzero instance. It allows fine-grained customization of all core behaviors, including message consumers, dispatch logic, interceptors, caching, serialization, metrics, and much more.

Most applications use the default builder via:

Java

FluxzeroBuilder builder = DefaultFluxzero.builder();

Kotlin

val builder = DefaultFluxzero.builder()

In Spring environments, it can be customized by implementing the FluxzeroCustomizer interface:

Java

@Component
public class MyCustomizer implements FluxzeroCustomizer {
    @Override
    public FluxzeroBuilder customize(FluxzeroBuilder builder) {
        return builder.addParameterResolver(new CustomResolver());
    }
}

Kotlin

@Component
class MyCustomizer : FluxzeroCustomizer {
    override fun customize(builder: FluxzeroBuilder): FluxzeroBuilder {
        return builder.addParameterResolver(CustomResolver())
    }
}

---

Key capabilities

Consumer and tracking configuration

• configureDefaultConsumer(MessageType, UnaryOperator<ConsumerConfiguration>) to adjust the default consumer template per message type. In perHandler mode this template is copied for generated handler consumers; in defaultAppConsumer mode it is the shared fallback consumer.
• addConsumerConfiguration(...) to register additional consumers for selected message types.
• forwardWebRequestsToLocalServer(...) to redirect incoming @HandleWeb calls to an existing local HTTP server.

Interceptors and decorators

• addHandlerInterceptor(...), addBatchInterceptor(...), and addDispatchInterceptor(...) to apply interceptors by message type.
• Interceptors may be prioritized (highPriority = true) or restricted to specific message types.
• replaceMessageRoutingInterceptor(...) overrides the routing logic for outbound messages.
• addHandlerDecorator(...) adds more generic handler-level logic.

Data, identity, and correlation

• replaceIdentityProvider(...) to control ID generation for messages or functional identifiers.
• replaceCorrelationDataProvider(...) to define how correlation metadata is attached to outbound messages.
• registerUserProvider(...) to integrate custom user authentication and inject User into handlers.

Caching and snapshotting

• replaceCache(...) and withAggregateCache(...) to plug in custom caching backends.
• replaceRelationshipsCache(...) for customizing the cache used in association-based message routing.
• replaceSnapshotSerializer(...) if you want to store snapshots differently from events.

Message serialization

• replaceSerializer(...) changes the default JSON serializer (e.g., for Jackson customizations).
• replaceDocumentSerializer(...) lets you influence how document fields are indexed and stored for search.
• Prefer fluxzero.serialization.typeAliases or FLUXZERO_SERIALIZATION_TYPE_ALIASES to configure the complete list of exact and package aliases per deployment.
• addTypeAlias(...), addTypeAliases(...), addPackageAlias(...), and addPackageAliases(...) provide programmatic configuration when aliases are intentionally owned by application code. These aliases take precedence over property configuration for the same source.

See Upcasting and downcasting for the alias syntax, resolution order, and TestFixture behavior.

Parameter injection and handler behavior

• addParameterResolver(...) registers a ParameterResolver to inject custom arguments into handler methods.
• replaceValidator(...) replaces the validator used by payload validation, web parameter validation, and ValidationUtils convenience methods.
• replaceDefaultResponseMapper(...) and replaceWebResponseMapper(...) to change how handler return values are mapped into responses.

Application configuration

• addPropertySource(...) and replacePropertySource(...) control the configuration hierarchy (e.g., ENV > system props > application.properties).
• Integrates with ApplicationProperties for encrypted or templated config values.

ApplicationProperties merges every application.properties resource visible as a separate classpath resource, including resources in Spring Boot nested JARs. A custom uber-JAR build that collapses equal resource names must merge those files in its own packaging configuration.

Task scheduling and execution

• replaceTaskScheduler(...) to inject a custom scheduler for async or delayed task execution.

---

Optional behavior toggles

These methods disable internal features as needed:

Method	Disables
disableErrorReporting()	Suppresses error publishing to ErrorGateway
disableShutdownHook()	Prevents the JVM shutdown hook
disableMessageCorrelation()	Skips automatic correlation ID injection
disablePayloadValidation()	Turns off payload type validation
disableDataProtection()	Disables @ProtectData and @DropProtectedData filtering
disableAutomaticAggregateCaching()	Skips aggregate cache setup
disableScheduledCommandHandler()	Removes default handler for scheduled commands
disableTrackingMetrics()	Prevents emitting metrics during message tracking
disableCacheEvictionMetrics()	Disables cache eviction telemetry
disableWebResponseCompression()	Prevents gzip compression for web responses
disableAdhocDispatchInterceptor()	Disallows use of AdhocDispatchInterceptor.runWith...() utilities

Use onMissingProtectedData(...) to configure the application-wide response when a message references protected data that has already been dropped. The same setting is available as fluxzero.dataProtection.onMissingProtectedData; an explicit builder setting takes precedence. Environment variables may use FLUXZERO_DATA_PROTECTION_ON_MISSING_PROTECTED_DATA or FLUXZERO_DATAPROTECTION_ONMISSINGPROTECTEDDATA.

---

Final assembly

Once the builder is configured, construct the Fluxzero instance by passing in a Client (usually a WebSocketClient or LocalClient):

Java

Fluxzero flux = builder.build(myClient);

Kotlin

val flux = builder.build(myClient)

To mark it as the global application-wide instance (i.e., accessible via Fluxzero.get()):

Java

builder.makeApplicationInstance(true).build(myClient);

Kotlin

builder.makeApplicationInstance(true).build(myClient)

This is the central instance that orchestrates message gateways, tracking, scheduling, and storage across your application. If Spring is used, the application instance is automatically set by Spring and unset when the Spring context is closed.

---

Spring auto-configuration

Fluxzero integrates well with Spring. If you’re using Spring (or Spring Boot), many components are auto-configured for you:

• If you provide a bean of type Serializer, Cache, Client, UserProvider, or WebResponseMapper, it will be automatically picked up by the builder.
• Upcasters and Downcasters are auto-registered if detected on Spring beans.
• Handlers (@Handle...) are automatically registered after the context is refreshed.
• @TrackSelf, @Stateful, and @SocketEndpoint beans are auto-detected and wired via post-processors.
• If no Client is configured explicitly, Fluxzero tries to create a WebSocketClient (based on available properties), or falls back to a LocalClient.

Caution

If you’re using Spring without Spring Boot, be sure to add @Import(FluxzeroSpringConfig.class) to enable auto-configuration.

You can always override or customize behavior via a FluxzeroCustomizer.

Injectable beans

Fluxzero exposes several core components as Spring beans, making them easy to inject into your application:

Bean type	Purpose
Fluxzero	Access to the full runtime and configuration
CommandGateway	Dispatch commands and receive results
EventGateway	Publish events to the global log
QueryGateway	Send queries and await answers
MetricsGateway	Emit custom metrics messages
ErrorGateway	Report errors manually
ResultGateway	Manually publish results from async flows
MessageScheduler	Schedule commands or other messages
AggregateRepository	Load and store aggregates
DocumentStore	Search, filter, and persist document models
KeyValueStore	Access key-value persisted state

You can simply inject any of these into your Spring-managed components:

Java

@Component
@AllArgsConstructor
public class MyService {
    private final CommandGateway commandGateway;

    public void doSomething() {
        commandGateway.sendAndForget(new MyCommand(...));
    }
}

Kotlin

@Component
class MyService(private val commandGateway: CommandGateway) {

    fun doSomething() {
        commandGateway.sendAndForget(MyCommand(...))
    }
}

Caution

While dependency injection is supported, it is not the recommended approach in most cases.

Instead, prefer using the static methods on the Fluxzero class:

Java

Fluxzero.sendCommand(new MyCommand(...));
Fluxzero.query(new GetUserProfile(userId));
Fluxzero.publishEvent(new UserLoggedIn(...));

Kotlin

Fluxzero.sendCommand(MyCommand(...))
Fluxzero.query(GetUserProfile(userId))
Fluxzero.publishEvent(UserLoggedIn(...))

This avoids boilerplate, reduces coupling to Spring, and works equally well in non-Spring contexts like tests or lightweight setups.