Interface FluxzeroBuilder

All Superinterfaces:
FluxzeroConfiguration
All Known Implementing Classes:
DefaultFluxzero.Builder
public interface FluxzeroBuilder extends FluxzeroConfiguration
Builder interface for constructing a Fluxzero instance.

This interface exposes advanced configuration hooks for customizing message handling, dispatch behavior, serialization, user resolution, correlation tracking, and many other aspects of a Fluxzero client. It is primarily used via DefaultFluxzero but can be extended or wrapped for deeper integrations.

  • Field Details

    • TYPE_ALIASES_PROPERTY

      static final String TYPE_ALIASES_PROPERTY
      Property containing comma-, semicolon-, or newline-separated type aliases in source=target form. Package aliases use a trailing .* on both sides. The conventional environment-variable name is FLUXZERO_SERIALIZATION_TYPE_ALIASES.
      See Also:

  • Method Details

    • configureDefaultConsumer

      FluxzeroBuilder configureDefaultConsumer(io.fluxzero.common.MessageType messageType, UnaryOperator<ConsumerConfiguration> updateFunction)
      Update the default consumer configuration for the specified message type.

      When unconfigured handlers use ConsumerConfiguration.PER_HANDLER_CONSUMER_MODE or ConsumerConfiguration.PER_PACKAGE_CONSUMER_MODE, this configuration is used as the template for the generated consumers.

    • configureDefaultConsumerHandlingMode

      default FluxzeroBuilder configureDefaultConsumerHandlingMode(ConsumerHandlingMode handlingMode)
      Configures the app-wide default handler execution mode for consumers whose own mode and message-type default consumer mode are both ConsumerHandlingMode.DEFAULT.

      Message-type defaults configured through configureDefaultConsumerHandlingMode(ConsumerHandlingMode, MessageType...) or configureDefaultConsumer(MessageType, UnaryOperator) take precedence over this app-wide default.

    • configureDefaultConsumerHandlingMode

      default FluxzeroBuilder configureDefaultConsumerHandlingMode(ConsumerHandlingMode handlingMode, io.fluxzero.common.MessageType... messageTypes)
      Configures the default handler execution mode for specific message types, or the whole app when no message types are supplied.

      Explicit @Consumer and custom ConsumerConfiguration handling modes still take precedence over these defaults.

    • addConsumerConfiguration

      FluxzeroBuilder addConsumerConfiguration(ConsumerConfiguration consumerConfiguration, io.fluxzero.common.MessageType... messageTypes)
      Adds a specific consumer configuration for one or more message types.

    • addBatchInterceptor

      FluxzeroBuilder addBatchInterceptor(BatchInterceptor interceptor, io.fluxzero.common.MessageType... forTypes)
      Registers a BatchInterceptor that applies to the given message types.

      You can use @Order on the interceptor class to influence ordering. Lower values have higher priority. Interceptors with a negative order value run before Fluxzero's built-in batch interceptors, while zero, positive, or missing values run after them. Interceptors registered via Java's ServiceLoader are also picked up automatically and participate in the same ordering.

    • addDispatchInterceptor

      FluxzeroBuilder addDispatchInterceptor(DispatchInterceptor interceptor, io.fluxzero.common.MessageType... forTypes)
      Adds a DispatchInterceptor that modifies or monitors message dispatch.

      You can use @Order on the interceptor class to influence ordering. Lower values have higher priority. Interceptors with a negative order value run in the high-priority slot, while zero, positive, or missing values run in the regular slot. Interceptors registered via Java's ServiceLoader are also picked up automatically and participate in the same ordering.

    • addHandlerInterceptor

      default FluxzeroBuilder addHandlerInterceptor(HandlerInterceptor interceptor, io.fluxzero.common.MessageType... forTypes)
      Adds a HandlerInterceptor for given message types.

      You can use @Order on the interceptor class to influence ordering. Lower values have higher priority. Interceptors with a negative order value run in the high-priority slot, while zero, positive, or missing values run in the regular slot. Interceptors registered via Java's ServiceLoader are also picked up automatically and participate in the same ordering.

    • addHandlerDecorator

      FluxzeroBuilder addHandlerDecorator(HandlerDecorator decorator, io.fluxzero.common.MessageType... forTypes)
      Adds a HandlerDecorator for the given message types.

      You can use @Order on the decorator class to influence ordering. Lower values have higher priority. Decorators with a negative order value run in the high-priority slot, while zero, positive, or missing values run in the regular slot. Decorators registered via Java's ServiceLoader are not discovered automatically; automatic service loading applies to interceptor interfaces.

    • replaceMessageRoutingInterceptor

      FluxzeroBuilder replaceMessageRoutingInterceptor(DispatchInterceptor messageRoutingInterceptor)
      Replaces the default routing interceptor used for message dispatch.

    • replaceCache

      FluxzeroBuilder replaceCache(io.fluxzero.common.caching.Cache cache)
      Replaces the default cache implementation.

    • withAggregateCache

      FluxzeroBuilder withAggregateCache(Class<?> aggregateType, io.fluxzero.common.caching.Cache cache)
      Configures a dedicated cache for a specific aggregate type.

    • withModelCache

      default FluxzeroBuilder withModelCache(io.fluxzero.common.caching.Cache cache)
      Configures the cache used by independently stored models.

      This overrides the shared cache for model state only; aggregate and relationship caches are unaffected.

    • replaceRelationshipsCache

      FluxzeroBuilder replaceRelationshipsCache(UnaryOperator<io.fluxzero.common.caching.Cache> replaceFunction)
      Replaces the internal relationships cache with a new implementation.

    • configureModelConflictHandling

      default FluxzeroBuilder configureModelConflictHandling(io.fluxzero.common.api.modeling.ModelConflictPolicy policy, ModelConflictResolver resolver, int maxRetries)
      Configures the optional policy used when an independent-model commit was evaluated against an older model state.

      ModelConflictPolicy.ACCEPT preserves the original event and internally rebases stale apply state without rerunning assertions or interceptors. Scoped @Model and @Apply settings may override this policy. Rejecting policies roll back the complete runtime action before invoking resolver. A resolver-requested retry performs a fresh pinned model load and is bounded by maxRetries. If this method is not called, properties fluxzero.model.conflictPolicy and fluxzero.model.maxConflictRetries are consulted. The policy defaults to RETRY from fluxzero.defaults.version = 2026.09.09, or ACCEPT in compatibility mode, with three retries. Under these implicit defaults, first creations fail on conflict rather than becoming upserts. An explicitly selected RETRY also applies to creation and therefore requires create-only assertions where appropriate.

      Parameters:
      policy - conflict policy sent with model commits
      resolver - client-side decision after a rolled-back conflict
      maxRetries - maximum number of complete action reevaluations
      Returns:
      this builder

    • configureAutomaticModelHandling

      default FluxzeroBuilder configureAutomaticModelHandling(AutomaticModelHandling handling)
      Configures whether model applies are exposed as automatic command handlers by default. Scoped @Model and @Apply settings take precedence. If this method is not called, fluxzero.model.automaticHandling is consulted before falling back to AutomaticModelHandling.ENABLED.

    • configureGraphProjectionCompletion

      default FluxzeroBuilder configureGraphProjectionCompletion(GraphProjectionCompletion completion)
      Configures the application default for materialized graph-projection result completion. Properties fall back through fluxzero.model.graphProjectionCompletion, then GraphProjectionCompletion.ASYNC.

    • forwardWebRequestsToLocalServer

      default FluxzeroBuilder forwardWebRequestsToLocalServer(int port)
      Forwards incoming MessageType.WEBREQUEST messages to a locally running HTTP server on the specified port.

      This allows applications to handle web requests using their own HTTP server rather than Fluxzero’s message-based @HandleWeb infrastructure.

      Note: This feature pushes requests to the local server and bypasses Fluxzero's pull-based dispatch model. Its use is discouraged unless integration with an existing HTTP stack is required.

      Parameters:
      port - the port on which the local HTTP server is listening
      Returns:
      this builder instance
      See Also:

    • forwardWebRequestsToLocalServer

      FluxzeroBuilder forwardWebRequestsToLocalServer(LocalServerConfig localServerConfig, UnaryOperator<ConsumerConfiguration> consumerConfigurator)
      Configures forwarding of MessageType.WEBREQUEST messages to a local HTTP server using the specified LocalServerConfig and custom consumer configuration.

      This mechanism is useful for advanced integration scenarios but bypasses Fluxzero's pull-based message tracking. Prefer native @HandleWeb handlers when possible.

      Parameters:
      localServerConfig - configuration for the local server (e.g., port, error behavior)
      consumerConfigurator - function to customize the underlying ConsumerConfiguration
      Returns:
      this builder instance
      See Also:

    • replaceDefaultResponseMapper

      FluxzeroBuilder replaceDefaultResponseMapper(ResponseMapper responseMapper)
      Replaces the default response mapper used for generic result mapping.

    • replaceWebResponseMapper

      FluxzeroBuilder replaceWebResponseMapper(WebResponseMapper webResponseMapper)
      Replaces the WebResponseMapper used for handling web responses.

    • replaceTaskScheduler

      FluxzeroBuilder replaceTaskScheduler(Function<Clock, io.fluxzero.common.TaskScheduler> function)
      Replaces the default TaskScheduler implementation.

    • replaceValidator

      default FluxzeroBuilder replaceValidator(UnaryOperator<Validator> replaceFunction)
      Replaces the validator used for payload validation, web parameter validation, and ValidationUtils convenience methods executed in this Fluxzero instance's context.
      Parameters:
      replaceFunction - function that receives the current validator and returns the replacement
      Returns:
      this builder instance

    • replaceIdentityProvider

      FluxzeroBuilder replaceIdentityProvider(UnaryOperator<IdentityProvider> replaceFunction)
      Replaces the identity provider used to generate message and entity identifiers.

    • addParameterResolver

      FluxzeroBuilder addParameterResolver(io.fluxzero.common.handling.ParameterResolver<? super DeserializingMessage> parameterResolver)
      Registers a ParameterResolver to support injection of method arguments in handlers.

    • replaceSerializer

      FluxzeroBuilder replaceSerializer(Serializer serializer)
      Replaces the default serializer used for events, commands, snapshots, and documents.

    • addTypeAlias

      default FluxzeroBuilder addTypeAlias(String oldType, String newType)
      Adds an exact alias from a legacy serialized type name to its current type name.

      Multiple aliases may be added. Programmatic aliases take precedence over aliases for the same source configured through TYPE_ALIASES_PROPERTY.

    • addTypeAliases

      default FluxzeroBuilder addTypeAliases(Map<String,String> aliases)
      Adds multiple exact aliases from legacy serialized type names to their current type names.

    • addPackageAlias

      default FluxzeroBuilder addPackageAlias(String oldPackage, String newPackage)
      Adds an alias from a legacy package and all its subpackages to a current package.

      Package names are supplied without a trailing wildcard. When aliases overlap, the longest matching package prefix wins; an exact type alias always takes precedence.

    • addPackageAliases

      default FluxzeroBuilder addPackageAliases(Map<String,String> aliases)
      Adds multiple package-prefix aliases.

    • replaceCorrelationDataProvider

      FluxzeroBuilder replaceCorrelationDataProvider(UnaryOperator<CorrelationDataProvider> correlationDataProvider)
      Replaces the CorrelationDataProvider used to attach correlation data to messages.

    • replaceSnapshotSerializer

      FluxzeroBuilder replaceSnapshotSerializer(Serializer serializer)
      Overrides the serializer used specifically for snapshot serialization.

    • replaceDocumentSerializer

      FluxzeroBuilder replaceDocumentSerializer(DocumentSerializer documentSerializer)
      Replaces the document serializer for search indexing.

    • registerUserProvider

      FluxzeroBuilder registerUserProvider(UserProvider userProvider)
      Registers a user provider used for resolving and authenticating User instances.

    • addPropertySource

      default FluxzeroBuilder addPropertySource(io.fluxzero.common.application.PropertySource propertySource)
      Adds a PropertySource to the configuration chain.

    • replacePropertySource

      FluxzeroBuilder replacePropertySource(UnaryOperator<io.fluxzero.common.application.PropertySource> replacer)
      Replaces the existing property source.

    • disableErrorReporting

      FluxzeroBuilder disableErrorReporting()
      Disables automatic error reporting (e.g., via ErrorGateway).

    • disableShutdownHook

      FluxzeroBuilder disableShutdownHook()
      Prevents registration of a shutdown hook.

    • disableMessageCorrelation

      FluxzeroBuilder disableMessageCorrelation()
      Disables automatic message correlation.

    • disablePayloadValidation

      FluxzeroBuilder disablePayloadValidation()
      Disables payload validation.

    • disableWebParameterValidation

      FluxzeroBuilder disableWebParameterValidation()
      Disables validation of injected web parameters (e.g. @PathParam, @QueryParam).

    • disableDataProtection

      FluxzeroBuilder disableDataProtection()
      Disables security filtering based on @FilterContent.

    • onMissingProtectedData

      FluxzeroBuilder onMissingProtectedData(MissingProtectedDataPolicy policy)
      Configures the application-wide response when referenced protected data is no longer available. Handler and consumer settings take precedence. If not configured, Fluxzero uses the "fluxzero.dataProtection.onMissingProtectedData" property and finally defaults to MissingProtectedDataPolicy.HANDLE.
      Parameters:
      policy - concrete application-wide policy; MissingProtectedDataPolicy.DEFAULT restores property and SDK-default resolution

    • disableAutomaticAggregateCaching

      FluxzeroBuilder disableAutomaticAggregateCaching()
      Disables automatic caching of aggregates.

    • disableAutomaticModelCaching

      default FluxzeroBuilder disableAutomaticModelCaching()
      Disables shared caching and cache tracking for independently stored models.

    • disableScheduledCommandHandler

      FluxzeroBuilder disableScheduledCommandHandler()
      Prevents installation of the default scheduled command handler.

    • disableAutomaticTracking

      default FluxzeroBuilder disableAutomaticTracking()
      Helper method that disables all processes that contain automatic trackers. Useful for low-level applications that want to run as lean as possible.

      E.g., this disables the scheduled command handler and automatic entity caching.

    • disableTrackingMetrics

      FluxzeroBuilder disableTrackingMetrics()
      Disables tracking of processing metrics.

    • disableCacheEvictionMetrics

      FluxzeroBuilder disableCacheEvictionMetrics()
      Disables metrics related to cache eviction.

    • disableApplicationLifecycleMetrics

      default FluxzeroBuilder disableApplicationLifecycleMetrics()
      Disables automatic application lifecycle metrics.

      By default, a fully constructed Fluxzero application asynchronously publishes a startup metric that confirms it can reach a Fluxzero Runtime metrics endpoint. A matching stopping metric is attempted during controlled shutdown. Test fixtures disable these infrastructure metrics automatically.

    • disableWebResponseCompression

      FluxzeroBuilder disableWebResponseCompression()
      Disables compression for web responses.

    • disableAdhocDispatchInterceptor

      FluxzeroBuilder disableAdhocDispatchInterceptor()
      Disables support for dynamically injected dispatch interceptors.

    • setMaxPublicationDepth

      FluxzeroBuilder setMaxPublicationDepth(int maxDepth)
      Sets the maximum publication-chain depth.

      The default is 100. A new external dispatch or scheduled branch starts at depth 0; messages published while handling another message use the current depth plus one. Set this to a negative value to disable the guard.

    • makeApplicationInstance

      FluxzeroBuilder makeApplicationInstance(boolean makeApplicationInstance)
      Marks the built instance as the global (application-level) Fluxzero.

    • disableKeepalive

      FluxzeroBuilder disableKeepalive()
      Disables Fluxzero’s built-in keepalive mechanism.

      By default, a Fluxzero instance keeps the JVM running after it is built by maintaining a single non-daemon thread. Calling this method disables that behavior, allowing the application to terminate normally once the main thread finishes.

    • enableHostMetrics

      default FluxzeroBuilder enableHostMetrics()
      Enables host metrics collection with default configuration.

      Host metrics include JVM memory, GC, threads, CPU usage, file descriptors, and more. Metrics are collected periodically (default: every 30 seconds) and published via MetricsGateway.

      Returns:
      this builder instance
      See Also:

    • enableHostMetrics

      default FluxzeroBuilder enableHostMetrics(UnaryOperator<HostMetricsConfiguration.HostMetricsConfigurationBuilder> configurer)
      Enables host metrics collection with a configuration customizer.

      Example usage: 

      builder.enableHostMetrics(config -> config
    .collectionInterval(Duration.ofSeconds(60))
    .applicationName("my-app")
    .collectDisk(true));
      Parameters:
      configurer - a function to customize the configuration builder
      Returns:
      this builder instance
      See Also:

    • enableHostMetrics

      FluxzeroBuilder enableHostMetrics(HostMetricsConfiguration configuration)
      Enables host metrics collection with a custom configuration.
      Parameters:
      configuration - the host metrics configuration
      Returns:
      this builder instance
      See Also:

    • build

      Fluxzero build(Client client)
      Builds the Fluxzero instance using the provided low-level Client.